Pre-defined functions

A number of functions are pre-defined by the EDEN interpreter. These pre-defined functions cannot be re-defined by the users to prevent ruining their definition accidently. The following is a list of pre-defined functions.

I/O Functions

write(...), writeln(...)

write and writeln print the arguments on stdout (standard output file). writeln appends a newline \n at the end. For example,

for (i = 1; i <= 10; i++) write(i, ' ');

gives

1 2 3 4 5 6 7 8 9 10

writeln("sum of ", 1, '+', 2, " = ", 1 + 2);

gives

sum of 1+2 = 3

Type Conversion Functions

type(data)

It returns the type of data as a string:

Data Type	String Returned
`@` ``undefined''	"@"
integer	`"int"`
character	`"char"`
string	`"string"`
floating point	`"float"`
list	`"list"`
function	`"func"`
procedure	`"proc"`
pre-defined function	`"builtin"`
pre-bound C function	`"C-func"`

For example, type(1) gives "int".

int(data)

If data is an integer, the same value will be returned. If it is a character, the code of the character will be returned. If it is a string, the string will be assumed as a stream of digits, and these digits are converted into an integer which will be returned. If it is a floating point, it will be truncated into an integer before it is returned. If it is a pointer, the address is casted to an integer which will be returned. The function returns @ otherwise.

char(data)

If data is a character, the same character will be returned. If it is an integer, the character having the code equals to the integer will be returned. If it is a string, its first character will be returned. If it is a floating point, it will be truncated into an integer and then cast to a character before it is returned. The function returns @ otherwise.

str(data)

If data is a string, the same string will be returned. If it is @ the string "@" will be returned. If it is a character, the character will be converted into a string and returned. If it is an integer or a floating point, the string of digits corresponding to the value will be returned. The function returns @ otherwise.

float(data)

If data is a floating point, the same value will be returned. If it is an integer, the floating point having the same value will be returned. If it is a character, the floating point having the same value as the code of the character will be returned. If it is a string, the string will be assumed as a stream of digits, and these digits are converted into a floating point which will be returned. If it is a pointer, it will be casted into an integer and then converted to a floating point before it is returned. The function returns @ otherwise.

String Functions

substr(string string, int from, int to)

substr returns a substring of string. from and to are the starting and ending positions respectively; they are integer values. If from is greater than to, the null string will be returned. from must not be small than 1. If to is greater than the number of characters of string, spaces will be added. For example,

substr("1234567890", 4, 8)

evaluates to "45678".

Examples:

Example	Result
`substr("1234567890", 4, 8)`	`"45678"`
`substr("1234567890", 5, 3)`	`""`
`substr("1234567890", 7, 12)`	`"7890 "`

strcat(string string,...)

strcat returns the string of the concatenation of its arguments. All arguments must be of string or character types. Characters are considered as a string of length 1. If it is called with no arguments, the null string will be returned. For example,

s = strcat("Garden", " of ", "Eden", '.');

s has the value "Garden of Eden.".

nameof(pointer pointer)

nameof returns the name of object to which the first argument (of pointer type) points. The function returns a string. This function is an ad hoc function. Bugs: If the pointer points to a character of a string object or an item of a list object, the string or the list object name is returned. For example,

Example	Results
`nameof(&Object)`	`"Object"`
`nameof(&A_String[1])`	`"A_String"`
`nameof(&A_List[5])`	`"A_List"`

List Functions

sublist(list list, int from, int to)

sublist returns a sublist of list. from and to are the starting and ending item positions respectively; they are integer values. If from is greater than to, the null list [] will be returned. from must not be small than 1. If to is greater than the number of items in list, @ will be added. For example,

Example	Result
`sublist([1,2,3,4,5], 2, 4)`	`[2,3,4]`
`sublist([1,2,3,4,5], 5, 3)`	`[]`
`sublist([1,2,3,4,5], 4, 7)`	`[4,5,@,@]`

listcat(list list, ...)

listcat returns the list of the concatenation of its arguments. For example,

listcat([1,2,3],[4,5,6],[7,8,9])

gives

[1,2,3,4,5,6,7,8,9]

array(int n, data)

array returns a list consists of n items that each is data. If data is omitted, @ will be assumed. data can have any type. For example,

Example	Result
`array(3, 0)`	`[0,0,0]`
`array(4)`	`[@,@,@,@]`

Time Functions

time()

time returns the current time in seconds since Jan 1, 1970

ftime()

ftime returns the current time in terms of the time elapsed since Jan 1, 1970. ftime is accurate up to milli-seconds. The return value is a list [second, milli] where second = the number of seconds and milli = the number of milli-seconds in addition to the time elapsed since Jan 1, 1970.

gettime()

gettime returns the current time. The return value is a list of seven integers, the meaning of these integers are respectively:

second	0-59
minute	0-59
hour	0-23
day of month	1-31
month of year	1-12
year	year-1900
day of week	0-6 (0 = Sunday)

Script Functions

apply(func function, list list)

apply calls the function specified in the first argument with the second argument as its actual argument (i.e. $). Thus the first and second arguments must be of type function and list respectively. For example,

apply(writeln, [1,2,3]);

is equivalent to call

writeln(1,2,3);

execute(string string)

execute executes a string as Eden statements. It returns 0 if no errors occurred in the execution of the string, non-zero otherwise. The execution terminates as soon as it encounters a syntax error or run-time error. Note that it is not a macro; the string must be some valid and complete Eden statements. Also this function can be executed within a function body. For example,

proc reset_F { execute("F is A+B;"); }

Every time reset_F is called, F will be defined to be a formula variable contains the expression "A+B" unless there are run-time errors, such as the circular definition conflict.

eval(expr expression)

eval evaluates an Eden expression, returning the result. This can be used to grab the current value of a variable when forming a definition. For example,

c=3;
a is b+eval(c);

Now using the query command,

?a;
a is b+3;
a ~> [];

todo(string string)

There are inside EDEN two todo lists, one current one and the other is a store for statements to be executed when the current todo list exhausted. todo is similar to execute except that the todo-statements will only be executed after the current thread of control terminates. For example, in one session you enter:

todo("writeln(1);"); writeln("Hello world");

The result will be

Hello world
1

include(string filename)

include works in the same way as execute except it takes in a file instead of a string; the file is specified by the first argument which is a string expression. If the execution is successful, include returns 0. The execution terminates as soon as it encounters a syntax error or run-time error. The file name and line number where the error occurs will be reported by the interpreter. For example,

include("utility");

executes the file called utility.

exit(int status)

exit terminates the program and returns status, an integer, to the parent process or operating system. If status is omitted, 0 is assumed.

forget(string name)

forget remove the entry of variable whose name is indicated by the string name. forget returns 0 if success, 1 if it can't find the variable that matches the name, 2 if it refuses to remove the entry because there are some definitions or actions depends on this variable.
Note: it is very dangerous to remove a variable since there may be some references on the variable that cannot be detected (e.g. a reference within a function body). In such case, the system may produce unpredicable result. (This function may be removed or replaced in future releases).

eager()

eager eagerly evaluate/execute all queued definitions/actions despite of the status of autocalc.

touch(pointer vp1, vp2, vp3, ...)

vp1, ... are pointers to variables. touch puts the targets of variables, pointed to by vp1, vp2, vp3, ..., to the evaluation queue.

formula_list()

formula_list returns the current list of addresses of formula variables queued. This function is useful to inspect the internal queue of formulae when the autocalc is 0 (off). This function is implemented in the later versions of the EDEN interpreter.

action_list()

action_list returns the current list of addresses of action specifications queued. This function is useful to inspect the internal queue of actions when the autocalc is ``off''. This function is implemented in the later versions of the EDEN interpreter.

symboltable()

symboltable returns the current internal symbol table of the interpreter as a list. Each symbol entry is of the form:

[ name, type, text, targets, sources ]

where

name: the object name (a string)
type: a string indicates the type of the variable: "var", "formula", "proc", "procmacro", "func", "builtin", "Real-func", "C-func". Note that these types are different from the output from type.
text: if the object is a function definition, formula variable, or action specification, then text stores the definitions in textual form.
targets: a list of variable names (strings) by which this object is referenced directly.
sources: a list of variable names (strings) to which this object refers directly.

For example, if the following definitions are defined

...
a is b + c;
b = 3;
f is b * g;
...

and,

S = symboltable());

then, S is:

[ ... [ "a", "formula", "b + c;", [], ["b","c"] ],
    [ "b", "var", "", ["a"], [] ], ... ]

symbols(string type)

symbols returns a list of symbol names which are of the type required. The type may be:

"@", "int", "char", "string", "float", "list", "var": any read/write variable (defined by assignments),
"formula": any definitive variable (defined by definitions),
"func", "proc": user-defined functions and procedures,
"builtin": Eden functions or procedures,
"Real-func": Real C functions,
"C-func": other C functions,
"any": any symbols

symboldetail(string name), symboldetail(pointer symbol)

symboldetail returns the information of a particular symbol. The information is in the same format as that of symboltable.

Unix Functions

getenv(string env): getenv returns the string of the environment variable env. See getenv(3).
putenv(string env): putenv sets the environment variable. env should have the form: "name=value". See putenv(3).
error(string err_msg): error generates an EDEN error and prints the error message err_msg.
error_no(): error_no returns the last system (not EDEN) error number (an integer).
backgnd(string path, cmd, arg1, arg2, ...): backgnd executes a process at background named by path backgnd returns the process id (-1 if fail). Bug: backgnd may returns a +ve id even if it can't execute the command.
pipe(string path, cmd, arg1, arg2, ...): pipe pipes output (stdout) to process named by path. pipe returns the process id (-1 if fail). Bug: pipe may return a +ve id even if it can't execute the command.
get_msgq(int key, flag): get_msgq gets a message queue using key. flag denotes the permission and options (see msgget(2)). It returns the message queue id (integer), -1 if fail.
remove_msgq(msqid): remove_msgq removes a message queue whose id is msgid. It returns -1 if fail (see msgctl(2)).
send_msg(int msqid, [ msg_type, string msg_text ], flag): send_msg sends a message (text string) to message queue msqid. msg_type denotes the message type. msg_text is a string (terminated by \0, i.e. at least having length 1. flag is 0 (for wait) and 04000 (octal) for no wait (see msgsnd(2)). It returns -1 if fail.
receive_msg(int msqid, msg_type, flag): receive_msg receives message of msg_type from message queue msqid. flag: c.f. send_msg and msgsnd(2). It returns @ if fail, else [m_type, m_text] where m_type is the actual message type received and m_text is the text string received. The following functions are data type related functions. int, char, str, and float are type conversion functions.

Predefined C Procedures

The following list of functions are pre-bound C functions. Users should refer to their own reference manual.

Function	Description
`fclose`	close a file
`fgetc`	get a character from an opened file
`fgets`	get a string from a file
`fopen`	open a file
`fprintf`	print to a file
`fputc`	print a character to a file
`fscanf`	formated read data from a file
`gets`	get a string from stdin
`pclose`	close a pipe
`popen`	open a pipe
`putw`	put a machine word to a file
`setbuf`	set the buffer size of a file
`sprintf`	print to a string
`sscanf`	formated read data from a string
`system`	execute command in a sub-shell
`ungetc`	unget a character
`srand`	random number generator
`rand`	random number generator

Functions defined in ``math.h''

sin cos tan asin acos atan atan2 sqrt pow log log2 log10 exp exp2 exp10

Different releases of the EDEN interpreter support different C function packages, such as CURSES (standard UNIX windowing package) and SunCore (standard SUN workstation graphics package). The user should consult to the release notes and the packages' reference manuals for the descriptions of the functions.

Miscellaneous Functions

debug(int status)

If status is a non-zero integer, debug turns on the debugging mode. When the debugging mode is on the interpreter prints out some information showing the status of the machine. Default: off (0). For example,

debug(1);        /* turn on debugging mode */

It is a subroutine for developing the interpreter. It is available to the user only if the interpreter was compiled with the flag -DDEBUG.

pack(...)

pack allocates a continuous memory space on the heap and stores the data in this memory block. The values are packed in a machine-dependent fashion, so the function is not portable. Data is packed as C type:-

integer	int	(4 bytes)
real	float	(4)
character	char	(1)
string/pointer/function/etc	char *	(4)

pack returns the address of the beginning of memory block as an integer. Example:

x = [0.0, 100.0, 100.0, 0.0];        /* x-coordinates */
y = [0.0, 0.0, 100.0, 100.0];        /* y-coordinates */
polygon_abs_2(pack(x), pack(y), 4);
                     /* will draw a filled square */
/* in fact, you could do:
     polygon_abs_2(pack([0.0, 100.0, 100.0, 0.0]),
                   pack([0.0, 0.0, 100.0, 100.0]),
                   4);
*/
move_abs_2(0.0, 0.0);
polyline_abs_2(pack(x), pack(y), 4);
                    /* will draw a hollow square */
/* c.f. SunCore Reference Manual */

Bugs: It is very ad hoc, and not universal, i.e. cannot handle all struct. It converts real numbers into "float"s instead of "double"s (so we can call Suncore polyline and polygon primitives). There should be an "unpack" function.