---------- EDEN (Evaluator of DEfinitive Notations) QUICK REFERENCE ----------

Parts of syntax which are !@Ooptional are shown like this!@P


CONTENTS OF THIS QUICK REFERENCE:

1. C-like syntax
2. Data types
3. Operators
4. Procedural statements
5. User-defined functions, procedures, actions...
6. Pre-defined variables
7. Pre-defined functions and procedures
8. C-library functions and procedures
9. Writing a clock
10. More information


-- 1. C-LIKE SYNTAX ----------------------------------------------------------

Statements are followed by the semi-colon;

/* Multi-line C-style comments /* ...although note they may nest in Eden */ */
## one-line comments start with two hash characters

Assignment: v = 1;
Definition: a is f(b, c);

Function: func square { return $1*$1; }
Procedure: proc inc_a { a++; }
Action: proc print : q { writeln("q is ", q); }

Name space: can access Scout variables directly.
            to access Donald variables, prepend an underscore _

Variable declaration is not required or possible.
Redeclaration of type is automatic


-- 2. DATA TYPES -------------------------------------------------------------

Undefined: @
Integer: 123, 018 (octal), 0xAB (hex)
Character: 'A', '\n', '\009'
Floating point: 1.23e-15

String: s = "this is a string"
s[1] is the first character of the string s

Pointer: ip = &int_variable
* dereferences a pointer: *ip == int_variable

List: L = [ 100, 'a', "string", [1,2,3] ]
L[1] is the first item of L
L[4][2] is the second item in the fourth item of L
L# is the length of list L
L // M is the concatenation of L and M
See also append, insert, delete and shift


-- 3. OPERATORS --------------------------------------------------------------

Strict: Returns @ if an operand is @
Lazy: Leaves the second operand unevaluated if it is unnecessary
Eager: Always evaluates both operands

Arithmetic (strict): + - (difference and unary) * / % (remainder)

Relational: < > <= >=

Equality: == !=

Logical (lazy): && || !
Logical (eager): and or not
Bitwise (eager): bitand bitor

Conditional: cond ? iftrue : iffalseor@

Assignment: = += -=
Prefix assignment: ++lvalue --lvalue
Postfix assignment: lvalue++ lvalue--

Indirection: a=1; r="a"; v=`r`;  Now v == 1 (note: there are problems with
use of indirection on the RHS of a definition)

Type casting is implemented through functions: see int(), char() etc below


-- 4. PROCEDURAL STATEMENTS --------------------------------------------------

Compound statements: { statement; !@Ostatements...!@P }

insert list, position, value;  (note: - no brackets - these are not functions
append list, value;                   - they operate only only lists, not
delete list, position;                  strings)
shift !@Olist!@P; (shift with no argument deletes the first item from $)

if (expression) statement !@Oelse statement!@P

while (expression) statement

do statement while (expression);

for (!@Oinitialisation!@P; !@Opre-iteration-test!@P; !@Opost-statement!@P) statement

switch (expression) { case constant: statement; !@Odefault statement;!@P }

break; causes termination of the smallest enclosing while, do, for, switch

continue; causes continuation of smallest enclosing while, do, for

return !@Oexpression!@P;

Null statement: ;

Dependency link: identifier ~> [ !@Oidentifier_list!@P ];

Query: ?lvalue;

Value freezing: eval(sym): takes the value of sym at definition entry time
  (note this is at proc definition time if eval is used within a proc)


-- 5. USER-DEFINED FUNCTIONS, PROCEDURES, ACTIONS... -------------------------

func identifier { !@Opara id_list;!@P !@Oauto id_list;!@P !@Ostatements...!@P }
proc identifier !@O: id_list!@P { !@Opara id_list;!@P !@Oauto id_list;!@P !@Ostatements...!@P }
procmacro identifier { !@Opara id_list;!@P !@Oauto id_list;!@P !@Ostatements...!@P }

$ is the argument list of a function
$3 is the third argument
$[n] is the n-th argument

Function call: four = square(2);


-- 6. PRE-DEFINED VARIABLES --------------------------------------------------

stdin: standard input
stdout: standard output
stderr: standard error
autocalc: whether Eden automatically recalculates formula definitions
_tkeden_showxoutput: whether to show info sent to Tcl for debugging
  purposes (see also debug(128))
eden_error_index_range: whether to generate an error or @ when referencing
  outside an array
eden_notice_undef_reference: whether to give notices about references to
  undefined values
tkeden_vbfeatures: whether to implement "VB-like features" in Scout (eg
  mouseClick observables).  These features are not recommended for use in
  new models.
PI: ratio of circle circumference to diameter (note lower case pi in DoNaLD)


-- 7. PRE-DEFINED FUNCTIONS AND PROCEDURES -----------------------------------

write(args...): print arguments on stdout
writeln(args...): print arguments on stdout, appending a newline (\n)

type(data): returns the type of data as a string
int(data): returns data after cast to integer type
char(data): returns data after cast to character type
str(data): returns data after cast to character type
float(data): returns data after cast to floating point type

substr(string, from, to): returns a substring of string
strcat(strings...): returns the string concatenation of its arguments
nameof(pointer): returns the name of the symbol to which the pointer points

sublist(list, from, to): returns a sublist of list
listcat(lists...): returns the list concatenation of its arguments
array(size, data): returns a list constructed from data items, of length size

time(): returns the current time in seconds since Jan 1, 1970
ftime(): returns the current time in [second, milli] form
gettime(): returns the current time in
  [second, minute, hour, day of month, month of year, year, day of week] form

apply(function, list): calls function with list as argument
execute(string): executes string as Eden statements
todo(string): will execute string as Eden statements after current
  evaluation terminates
include(string!@O, string...!@P): executes the contents of the named file(s) as
  Eden statements
cd(string): changes the current working directory
cwd(): returns the current working directory
dirname(string): returns the containing directory of a given filepath
basename(string): returns the filename (leafname) of a given filepath
exit(status): terminates the program, returning status as exit status
forget(string): attempts to remove the named variable from the symbol
  table.  Returns 0 for OK, 1 for not found, 2 for failure
forget(pointer): attempts to remove the pointed-to variable from the symbol
  table.  Returns 0 for OK, 2 for failure (1 is not possible).
eager(): evaluate all out of date formula variables and actions now, update
  the screen, whatever the state of autocalc
touch(pointers...): put the targets of the pointed to variables on the
  evaluation queue
formula_list(): returns list of pointers to queued formula variables
action_list(): returns list of pointers to queued actions
symboltable(): returns the current symbol table as a list of lists
symbols(string): returns a list of symbols from the symbol table which are
  of the specified type
symboldetail(string): returns a list of information about the named symbol
symboldetail(pointer): returns a list of information about the named symbol
symboltext(string): returns the original text used when defining a symbol
symboltext(pointer): returns the original text used when defining a symbol
symboldefinition(string): returns a symbol in Eden-interpretable form
symboldefinition(pointer): returns a symbol in Eden-interpretable form

getenv(env): returns the string contents of the environment variable env
putenv(env): set environment variable: env should have the form "name=value"
error(message): generate an Eden error
error_no(): returns the last system (not Eden) error number
backgnd(path, cmd, arg1, arg2...): executes a process in the background
pipe(path, cmd, arg1, arg2...): pipes stdout to the process given by path
get_msgq(key flag): gets a message queue
remove_msgq(msgqid): removes a message from the message queue msgqid
send_msg(msgid, [msg_type, msg_text], flag): send a message on a message queue
receive_msg(msgqid, msg_type, flag): receive a message from a message queue

notation(name, agentname): install a new definitive notation
installeddi(): install the eddi notation

macro(s, para1, para2, ..., paraN): substitute ?1 in s with para1, ?2 with
  para2 etc and return the result
copyproc(oldname, newname): copy a proc to a new name
showpara(procname, showret): adjust the definition of a proc so that, when
  called, the parameters and, optionally, return result are printed
round(r): make a real value into an integer with rounding

max(number, ...) or max([list of numbers]) : returns the maximum of the 
  numbers
min(number, ...) or min([list of numbers]) : returns the minimum of the 
  numbers
sum(number, ...) or sum([list of numbers]) : returns the sum of the numbers
abs(number) : returns number if > 0, otherwise returns -number (e.g abs(-7)=7)
average(number, ...) or average([list of numbers]) : returns the average of 
  the numbers
nthroot(number, n) : returns the n'th root of the number given
factorial(number) : returns the factorial of the number given
product(number, ... ) : returns the numbers passed multiplied together
sign(number) : returns -1 if number is < 0, 0 if number = 0, 1 if number > 0
even(number) : returns the nearest even number to the number given
odd(number) : returns the nearest odd number to the number given
mround(number, multiple) : returns the number rounded to the nearest multiple
  of the given multiple (e.g mround(62,6)=60)
sumsq(number, .. ) or sumsq([list of numbers]) : returns the sum of the 
  squares of the numbers passed
trunc(number) : returns the integer part of the number given
combin(total, n) : returns the number of ways n numbers can be picked from 
  total number of items
ceiling(number, multiple) : returns the number rounded to the nearest multiple
  of the given multiple that is greater than the number
floor(number, multiple) : returns the number rounded to the nearest
  multiple of the given multiple that is lower than the number
degrees(angle) : returns an angle given in radians with its equivalent in 
  degrees in a range 0-360
radians(angle) : returns an angle given in degrees with its equivalent in 
  radians in a range 0-2*PI
rounddigits(number, digits) : returns the number rounded to the specified 
  number of digits (e.g rounddigits(123.45,2)=120)
gcd(number, ...) or gcd([list of numbers]) : returns the largest number which 
  will divide exactly into all the numbers passed
lcm(number, ...) or lcm([list of numbers]) : returns the smallest number that
  all the numbers passed will divide exactly into it
variance(number, ...) or variance([list of numbers]) : returns the variance of
  the numbers passed or the list of numbers passed to it
stdev(number, ...) or stdev([list of numbers]) : returns the standard 
  deviation of the numbers passed or the list of numbers passed to it
sort([list of numbers], direction) : returns the list of numbers sorted. the 
  direction parameter should be 1 to return an ascending list, 2 to return a 
  descending list
median([list of numbers]) : returns the median element of a list of elements,
  those elements do not need to be in any sorted order

randomise() : seeds the random number generator with a random number
rnd(number) : returns a random number between 0 and the number. Note
  that both 0 and number are included in the range.

rgb2color(r, g, b): takes values in range 0-255 and returns a colour
  reference (which should be treated as opaque) to be used in SCOUT/DoNaLD
rgb2colour(r, g, b): same as rgb2color


-- 8. C-LIBRARY FUNCTIONS AND PROCEDURES -------------------------------------
(see their man pages for more detail)

fopen(filename, mode): opens a file, returning the fileid
fclose(fileid): closes a file stream

fgetc(fileid): gets and returns a character from a file stream
fgets(n, fileid): returns a string (max n characters) read from a file stream
  and @ when end of file has been reached
fscanf(fileid, format, &out1, &out2...): formatted read from the input stream
gets(): returns a string read from stdin
ungetc(c, fileid): pushes the character back onto the input stream fileid

fprintf(fileid, format, args...): prints a formatted string to a file stream
fputc(char, fileid): prints a character to a file stream

pclose(fileid): close a pipe
popen(command, mode): open a pipe, returning fileid
putw(w, fileid): puts a machine word to a file stream
setbuf(fileid, buf): set the buffer size of a file

sprintf(&s, format, args...): formatted print to a string (warning: s must
  first be initialised to a string of appropriate length)
sscanf(&s, format, &out1, &out2...): formatted read from string s

system(string): execute command in a sub-shell
stat(filename): returns a list of information about the named file:
  UID, GID, size, times of last access, data modification, file status change
srand(seed): seed the random number generator
rand(): return a random number (range is system dependent)

sin(float): returns the sine of its (radians) argument
cos(float): returns the cosine of its (radians) argument
tan(float): returns the tangent of its (radians) argument
asin(float): returns the principle arcsine of its (radians) argument
acos(float): returns the principle arccosine of its (radians) argument
atan(float): returns the principle arctangent of its (radians) argument
atan2(y, x): returns the principle value of the arctangent of y/x (floats)
sqrt(float): returns the square root of its argument
pow(x, y): returns the value of x raised to the power y (floats)
log(float): returns the natural logarithm of its argument (which must be +ve)
log10(float): returns the logarithm to base 10 of its argument
exp(float): returns the exponential (pow(e,x)) of its argument
... the above always return a float, even if all arguments are ints

debug(status): sets the interpreter debugging mode.  Add these values to
  form the parameter:
    1:  various
    2:  RunSet debugging
    4:  Eden parser debugging (=yydebug)
    8:  Sasami
    16: Donald
    32: Scout parser debugging (=st_debug)
    64: malloc debugging (emalloc macro)
    128: Tcl_Eval debugging
    256: execute debugging
    512: func / proc / procmacro call debugging
    1024: VMWRIT debugging (in 1 also)
    2048: Donald parser debugging (=dd_debug)
    4096: Print errors on stderr as well as the error window

pack(data...): stores data in a newly allocated memory space on the heap

... there may be more built-in functions and procedures depending upon the
Eden variant you are using.


-- 9. WRITING A CLOCK --------------------------------------------------------

proc clocking : clock { /* a clocking process */
 todo("clock++;");  /* increment clock after current evaluation finishes */
}

proc device1 : clock {  /* action synchronised by the clock */
 ...                   /* action body */
}

proc device2 : clock {
 ...                   /* action body */
}


-- 10. MORE INFORMATION ------------------------------------------------------

See the full manual available at http://www.dcs.warwick.ac.uk/modelling/
for more detail.
