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

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


-- 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


-- 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


-- 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


-- 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)


-- 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);


-- 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)


-- 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


-- 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
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

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

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.


-- 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 */
}


-- MORE INFORMATION ----------------------------------------------------------

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