---------- 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. 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_vbfeatures: whether to implement "VB-like features" in Scout (eg
mouseClick observables). These features are not recommended for use in
new models.
eden_notice_undef_reference: whether to give notices about references to
undefined values.
eden_error_index_range: whether to generate an error or @ when referencing
outside an array.
_tkeden_showxoutput: whether to show info sent to Tcl for debugging
purposes (see also debug(128)).
eden_debug_notations: whether the notation-handling Eden code should give
debugging output
eden_debug_edenclocks: whether the edenclocks Eden code should give
debugging output
PI: ratio of circle circumference to diameter (note lower case pi in DoNaLD).
edenclocks: list of tuples describing integer variables that should be
automatically incremented at a given time interval. Each element in
the edenclocks list is itself a list, in the form [clockPtr, millis].
'clockPtr' should be a pointer to an integer variable which will then
be incremented every 'millis' milliseconds. There are two possible
special values for 'millis':
@ - "pause" this clock: don't increment. Enables a record of a clock
variable to be left in the edenclocks list but temporarily
disabled.
0 - increment this clock as fast as possible. This enables the commonly
used pattern 'proc p { foo(); todo("p();"); }' to become
'proc p : tick { foo(); }; startedenclock(&tick, 0);'.
Eg: 'edenclocks=[[&a, 1000], [&b, 2500], [&tick, 0]];' causes 'a' to be
incremented once per second, 'b' to be incremented every 2.5 seconds, and
'tick' to be incremented as fast as possible. The edenclocks list can be
changed manually or by using the startedenclock and stopedenclock helper
procs provided.
-- 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: one of "@", "int",
"char", "string", "float", "list", "func", "proc", "procmacro",
"builtin", "C-func", "Real-func".
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. Consider using a solution using edenclocks instead.
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 ("@", "int", "char", "string", "float", "list",
"var", "formula", "proc", "procmacro", "func", "builtin", "Real-func",
"C-func" or "any").
symboldetail(string): returns a list of information about the named symbol:
[name, type, text, targets, sources, master]
type is one of "var", "formula", "proc", "procmacro", "func", "builtin",
"Real-func", "C-func".
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.
installAOP(notation, agentname): install a new Agent-Oriented Parser
notation. notation string must include the initial % character. This
function replaces the old "notation" built-in: replace notation("eddi",
"eddi_notation"); with installAOP("%eddi", "eddi_notation");
newNotation(name, switchProcPtr, transProcPtr): install a new notation.
installIPTrans(name, path): install a new Interactive Process -based
translator.
removeNotationRadioButton(notation): removes a notation radio button from
the tkeden interface. Pass the name of a notation, including the initial
% character.
installeddi(): install the EDDI notation.
installarca(): install the ARCA notation.
installdenota(): install the DENOTA notation.
installedensl(): install the EdenSL 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.
(Superseded for most purposes by debug(512)).
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.
realrand() : returns a real random number between 0.0 and 1.0, including 0
but excluding 1.
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.
ipopen(path, cmd, arg1, arg2...): creates a concurrent interactive process,
returning a list [rfd, wfd, efd] of stdin, stdout, stderr file descriptors.
ipclose([rfd, wfd, efd]): terminates the process created with ipopen.
fdready(fd, type, [sec, milli]): returns non-zero if the file descriptor
can be read from, written to, or has an exception, depending on the
second argument, which should be 'r', 'w' or 'e'. Will block for the
time stated in third argument (which can be zero), or indefinately until
the necessary condition is achieved if the third argument is @.
rawread(fd, maxbytes): returns a string, maximum maxbytes long, read from
the file descriptor fd, with no file buffering.
rawwrite(fd, string): writes string to the file descriptor, with no file
buffering.
regmatch(pattern, subject): returns a list of subpatterns in the first
match found by the (Perl-compatible) regular expression pattern in
subject. The first subpattern is the entire match.
regreplace(pattern, replacement, subject!@O, limit!@P): replaces the matches
found by pattern in subject with replacement. The optional limit
sets the number of replacements that are made. replacement can
contain references to parenthesised subpatterns in pattern, in the
form "$n" (0<=n<=99). A literal $ can be achieved by escaping it:
"\\$" (note the need to escape the backslash in an Eden string).
usbhidopen(filename): opens a file (eg /dev/input/event0) as a Universal
Serial Bus Human Input Device (eg a joystick or steering wheel),
returning the fileid. Available on Linux only at present.
usbhidread(fileid): returns a packet of information read from the device in
the form [time, type, code, value]. time is returned in the same form as
the ftime() routine. If there were no packets to read, empty list is
returned.
usbhidclose(fileid): closes the fileid.
rawserialopen(filename): opens a file (eg /dev/ttyS0) and sets it in raw
mode, returning the fileid. This is intended to be used for communication
with hardware. Use with rawwrite() and rawserialread(). Available on Linux
only at present.
rawserialread(fd, maxbytes): returns a string, maximum maxbytes long, read
from the file descriptor fd, with no file buffering.
rawserialclose(fileid): closes the fileid.
inpdevlineno(): returns an integer -- the current line number in the
Eden (or other?) code.
inpdevname(): returns a string -- the name of the current input device.
(NB: for the above, use eg eval(inpdevlineno()) to evaluate and obtain
values from parse time rather than run time.)
debug(status): sets the interpreter debugging mode. Add these values to
form the parameter:
1: various
2: RunSet (inc todo()) 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.
8192: regular expression debugging
16384: notation debugging
32768: timers C code debugging
trace(): prints a stack trace of proc/func calls made on stderr.
pack(data...): stores data in a newly allocated memory space on the heap.
createtimer(cmdstring, millis): adds cmdstring to the todo() queue in
'millis' milliseconds (which must be an integer >= 1). The timing of
this event is only approximate and may be more (or less...?!) than
specified. Returns a token which can be passed to
deletetcltimerhandler(). This is a relatively low- level function:
recommend you write procedures triggered by 'edenclock' variables
instead if possible (see 'edenclocks' variable and 'setedenclock' and
other helper procedures).
deletetimer(token): must be passed a token previously returned from
createtcltimerhandler. Stops the particular timer from activating.
deletealltimers(): stops all timers from activating.
setedenclock(clockPtr, millis): cause the integer variable pointed to by
clockPtr to increment every 'millis' milliseconds. For details of '@'
and '0' special cases for 'millis', see description of 'edenclocks' list.
Eg: 'setedenclock(&a, 1000);' causes variable 'a' to increment every sec.
removeedenclock(clockPtr): removes edenclock variable from edenclocks list.
pauseedenclocks(): temporarily pause all edenclocks.
unpauseedenclocks(): continue after having paused edenclocks. (Note that
each clock will be restarted at roughly the same instant so the phase
relationships between each will not be the same as before the pause.)
edeninterruptedhook(): define this procedure to cause statements to happen
after the Interrupt button / ctrl-c are pressed.
... there may be more built-in functions and procedures, depending upon the
Eden variant you are using.
-- 8. C-LIBRARY FUNCTIONS AND PROCEDURES -------------------------------------
(see their man pages for more detail)
fopen(filename, mode): opens a file, returning the fileid or 0 on error.
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
-- 9. MORE INFORMATION -------------------------------------------------------
See the full manual available at http://go.warwick.ac.uk/EDEN/ for
more detail.