prev | next | contents


Part B: THEMATIC SUMMARY.

1 Arithmetics and maths.

   Here are the various operators supported by OpenEuphoria, arranged by the type of task they help perform. A short description is provided for each of them.

+ the ordinary addition.
- the ordinary substraction.
* the ordinary multiplication.
/ the division operator. Returns a floating poinnt number if it cannot return a fraction.
- (1 operand) changes the sign of the operand.
floor(x) the greatest integer not greater than x.
ceiling(x) the smallest integer not less than x.
remainder(x,y) equals x-y*floor(x/y)
abs(x) computes the absolute value of an atomic value.
sqrt(x) calculates the square root of an atomic value
rand(x) generates random numbers not greater than x.
set_rand(x) initializes the random number generator rand uses.
sin(x) calculates the sine of x.
arcsin(x) calculates the angle with a given sine.
cos(x) calculates the cosine of x.
arccos(x) calculates the angle with a given cosine
tan(x) calculates the tangent of x.
arctan(x) calculates the arc tangent of x.
log(x) calculates the natural logarithm.
exp(x) calculates the exponential of x.
power(base,exponent) calculates base raised to the power exponent.
Ethe base of the natural logarithm (2.7182818....)
PI the circle perimeter/diameter ratio (3.14159...)
[+|-]infThe infinity symbol, with an optional sign.
scale2(x) returns the exponent of the higher power of 2 not greater than the absolute value of x.
scale10(x) returns the exponent of the higher power of 10 not greater than the absolute value of x.
int_to_bits(some_int,size)Returns a sequence made of the size least significant bits of some_int.
bits_to_int(some_seq)Returns an integer made of the 0's and 1's of some_seq.

2 Binary operations.

&& bitwise and
|| bitwise or
~~ bitwise xor
^ bitwise not
<< left shift
>> right unsigned shift
>>> right signed shift
and_bits(x,y) perform logical AND on corresponding bits of operands
or_bits(x,y) perform logical OR on corresponding bits of operands
xor_bits(x,y) perform logical XOR on corresponding bits of operands
not_bits(x,y) perform logical NOT on all bits of operands
rotate(memory,field,number)
rotates the raw RAM structure area memory.field, by number positions to the right. This operation is forbidden on any other sort of data.


3 array/sequence building.

{x,y,..} a nonatom whose first element is x, the second one y,...
{} an empty nonatom
"" an empty string
"..." a string
$"..."$ a long string: any line ending characters in it are ignored, so it may span several lines in source files.
"""...""" verbatim string. No processing at all is performed on a verbatim string, so line breaks are treated as is, and there are no escape sequences.
\letter an escape sequence, see part A, 2.2 for the sequences recognized.
\(number) a character whose ASCII code is number.
& concatenation: lengths of both operands add up to the result's length. The second operand is considered to be of length 1 if it is an atom
i=length(s)
number of elements in the nonatom s.
r=repeat(x,n)
builds a nonatom of length n, each element of which is x.
repeat_pattern(x,n)
builds a nonatom of length n*length(x) obtained by concatenating n-1 times x to itself.
r=append(s,x)
adds x at the end of s, length(r)=1+length(s).
r=prepend(s,x)
adds x at the beginning of s, length(r)=1+length(s).
cut_paste(target,position,source,start,end)
Removes the slice [target..end] from source and copies it onto target, starting at position. An error occurs if the pasted slice extends past the end of target.
transfer(target,position,source,start,end)
Removes the slice [start..end] from source and inserts it into target, the first element of the cut slice appearing at position.
transfer_as_one(target,position,source,start,end)
Removes the slice [start..end] from source and inserts it into target at position as a new element.
swap_slices(target,t_start,t_end,source,s_start,s_end)
Swaps the slices source[s_start..s_end] and target[t_start..t_end]. The slices need not have the same length.


4 sequence/array/structure access

s[i] the i-th element of s
s[i..j] the sublist of s formed by its elements i through j. Empty if i=j+1 otherwise invalid.
s[i1,...,in] the nonatom formed by s[i1], ... and s[in].
s[i][j] the j-th element of the nonatom which is the i-th element of s
s.name the element of s with name name
.name the member in the host structure with name name. Allowed only in context type statements.
s[-i] the i-th element of the mirror copy of s. Thus, s[-1] is the last element of s, and so on backwards.
cast(identifier,expr1,expr2)
sets identifier@types[expr1] to expr2, or to the routine_id of expr2. This may be needed when the known type information is better than the standard assumption and needs to be kept. expr1 may be any slice specification.

5 Assignments.

=
assigns the value on the right side to the variable on the left side.
:=
same, only in side effects of conditions
x operator= y
short for x=x operator y, where operator is any infix listed in 1 or 2.
#(x1,x2,...xn)[operator]=y
short for: x1 operator=y, x2 operator= y,...,xn operator= y. There may be no operator, hence the brackets.
#(x1,...xn)#[operator]=expr
maps the expr on the right to the left hand side. It is short for x1 [operator]= expr[1], x2 [operator]= expr[2] and so on. Extra symbols on the left or the right are ignored. Use the _ special variable to discard the result at this place on the left.
x=get_var(expr)
gets the value of the variable of id expr.
set_var(expr1,expr2)
assigns the result of expr2 to the variable whose id is expr1.
fit(target,source,padding|_)
assigns source to target and takes appropriate action if the lengths don't match. Basically, extra elements of the left or right hand side are ignored. If target is longer than source, the remaining elements of target are set to padding, or left alone if the third eargument is _.


6 Accessing variables.

lock expr
makes the variable specified by expr (by name or by id) read-only.
unlock expr
makes a previously locked variable writeable again.
name general_identifier as identifier
creates an alias. Specially handy for accessing deeply nested subsequences.
rename general_identifier as identifier
changes an alias.
unname identifier
undefines an alias.
expr[{simpleindex}]
specifies a part or subpart of a nonatomic entity. A simpleindex is an atom or a slice in the form expr..expr.
expr[[expr]]
The inner expr must evaluate to a nonatomic type of nonatomic type specifying parts to be extracted from the first expr.
general_identifier@identifier
the metadata with identifier the right hand operand relative to the variable on the left hand side is returned. See 5.1 in part A for a list of available metadata.
[global ]scope [name] ... end scope
defines a code block that may have its own symbols. A named scope must be used for its global symbols to be visible. global allow the scope to be used from other files. See part A, chapter 7, for a more detailed account.

7 Relational operators.

= is equal to
!= is not equal to
<,<= is less than, is no greater than
>,>= is greater than, is not less than
x and y is true if and only if x and y are true.
x or y is true whenever x or y is true
not x true if x is false, false if x is true.
x=compare(expr1,expr2)
compares expr1 to expr2, and returns -1 (less), 0 (equal) or 1 (greater). For this porpose, an atom is always less than a nonatom.
x=equal(expr1,expr2)
equivalent to x=(compare(expr1,expr2)=0)

8 Declaring variables/types.

[global ]type {identifier[=expr]}
declares all identifiers in the nonempty list on the right to be variables of the type type. If the global keyword is used, they may be seen from other files. It is disallowed inside routines. The identifiers may get an initial value on declaration.
[static ]type {identifier[=expr]}
declares all identifiers in the nonempty list on the right to be variables of the type type. If the static keyword is used, they will persist between two invocations of the current routine. This form is allowed only in routines, and may not follow general code statements. Symbols may get an initial value on declaration.
[global ]constant {[type ]identifier=expr}
defines constants, which are symbols whose value does not change and is specified on declaration. Their types may be specified. If not, object is assumed. Using the keyword global may make the symbols to be seen from outside the file they are defined in; it cannot be used in routines.
new_var(type,name,value|_)
creates a new variable of the type type, with name name, and initial value the third argument. If this argument is '_', no initial value is assigned.
del_var(expr)
destroys a variable that was created using new_var().
id(expr)
if expr evaluates to a string, returns the id of the only visible variable with this name, or -1 if none.
var(expr)
if exppr evaluates to a string, returns the name of the variable with this id, or "" if none.
[check ][global ][forward ]type name(type identifier)
specifies a routine to be called whenever a variable of that type is being assigned and type is checked. This defines an user-defined type. Types must return a boolean, and take exactly one argument.
[check ][global ][forward ]reftype name(integer identifier,update type identifier)
specifies a routine to be called whenever a variable of that type is being assigned and type is checked. This defines an user-defined type. The first argument of this routine is a variable id, and the second is the value to be assigned. reftypes must return a boolean.
array(expr) [of type]
an ordered, indexed collection of expr elements passing the same type check. The object type is assumed if no type is provided.
sequence [of type]
an ordered, indexed collection of elemnts passing the same type check. The object type is assumed if no type is supplied.
structure identifier({type|_ identifier|_)} ... end structure
a collection of elements, each of them with a type and a name. The elements can be accessed by name or index (their rank in the order in which they were enumerated). An element may have no name; an unnamed type will be defined later as a contxt type (see part A, 1.4).
is
The construct type | reftype altname is aliased allows to define an alias for the type aliased. This is specially useful in order to call the type checking function for a compound type such as "sequence of integer".

9 Including abstract files.

include filename|(expr) [as namespace]
makes all global symbols from filename be seen in the default namespace as well as in the specified namespace if any. If filename is included or imported for the first time in a program, its top level statements are executed. Using parentheses allows to use an expression rather than an explicit filename.
import filename|(expr) as namespace
makes all global symbols from an abstract file visible in namespace. If filename is included or imported for the first time in a program, its top level statements are executed. The global symbols in filename do not appear in the default namespace. The filename may be computed, as for the include statement.
promote [but] symbol list from namespace
makes the specified symbols in namespace available in the default namespace. The list may be implicit or explicit, in which case it must appear between double quotes. You can define in this way the list of symbols not to be visible in default. Using '_' means all symbols.
demote [but] symbol list [from namespace]
makes the specified symbols unavailable in the default namespace. The list may be implicit or explicit, in which case it must appear between double quotes. You can define in this way the list of symbols not to be visible any longer in default. The from clause is mandatory if but is used. Using '_' means all symbols.
[global ]scope [name] ... end scope
defines an area of code which can be seen from the outside under certain conditions, and from where the default namespace can't be seen without an explicit prefix. The name may be used as a namespace prefix. See chapter 7 in part A for more details.
use name
allows a given area of code to access the global symbols of a scope named name using the name as a namespace prefix. The area of code can be either the top level code of a file, a scope or a routine.

10 Instruction flow control.

if cond then
starts an if block. If cond is true, executes until next elsif/else (exclusive), or end of block if there's none. Jumps to the next elsif/else otherwise, or out of the block if there's none.
elsif cond then
same as if, but only inside an if block.
else
allowed only in an if block. Executes until the end of the if block, because no if/elsif cond was true.
exif [number|identifier]
jumps out of the specified if block. See part A, 9.5, for details of exited block specification.
select expr
prepares to execute statements conditionally to the value of expr. This value is called selector, and is not computed again inside the block.
case expr:
executes if selector equals to expr. There should be no isolated "_" in expr.
case cond:
isolated "_" in cond are repleced by the selector value. Then, cond is evaluated, and the case branch executes if and only if this value is True.
case relational expr:
short for case _relational expr:
case expr1 thru expr2:
short for case expr1<=_<expr2:
stop
jump out of the current case branch.
break [identifier|number]
jump out of the designated select block. See part A, 9.5, for details of exited block specification.
otherwise
executes statements to the end of select block, if no case branch in the current select block was taken.
for index=start value to end value [by increment] do
starts a for loop block. index is the for loop index variable; it must not be declared. All these are evaluated only once. If there is no increment, +1 is assumed. The loop iterates until index is out of bounds. No iteration occurs if index cannot reach end value from start value by adding some number of increment.
wfor index=start value to end value [by increment] do
starts a wfor loop block. This is the same as a for loop, except that the index variable must be declared, and that start value, end value and increment are computed at each new loop iteration.
while cond do
starts a while loop. The loop iterates until cond is no longer true.
end block name
ends a block. The block name must match the opening block name.
label identifier
tags a cstatement. This tag may be used as an argument of exit, exif, break, next and retry when tagging a code block header. A label statement can be the target of a goto statement..
exit [number|identifier]
jumps out of the specified loop loop.
next [number|identifier]
starts the next iteration of the specified loop immediately.
retry [number|identifier]
restart the current iteration of the specified loop immediately.
goto identifier
Transfers the execution point to the statement immediately following a matching label statement. A goto statement must be labelled, and its target must lie in the same named scope.
goto_far(namespace, identifier)
Transfers the execution point to the statement immediately following a matching label statement in the designated namespace, which may be a filename or a standard namespace..

11 Nonatomic types manipulations.

reverse(expr)
returns a nonatom which is the reversed image of expr: first element beccomes last, second element becomes second last,...,last element becomes first.
find(what,where)
returns the position of the first occurrence of what as an element in the nonatom where, or 0 if none is found.
match(what,where)
returns the first occurrence of what as a slice of where, or 0 if none is found.
find_all(what,where)
returns the sequence of the positions of all occurrences of what as an element in the nonatom where, or {} if none is found.
match_all(what,where)
returns the sequence of all occurrences of what as a slice of where, or {} if none is found.
insert(target,places,items)
returns a sequence which is target where the elements of items have been inserted in the positions defined by places, notionally starting backwards.
insert_sequence(target,places,items)
returns a sequence which is target where the elements of items have been inserted as subsequences at the positions specified in places, notionally starting backwards.
remove(target,places)
returns a sequence which is target with elements specified in places removed, notionally starting backwards.
replace(target,places,items)
returns a sequence which is target where the subsequences specified by places were replaces by the elements in items.
move(target,start,end,where)
moves target[start..end] to where inside target. If the new position of the slice causes it to extend past the length of target, an error will occur.
lower(string)
Converts all chars from string to lower case.
upper(string)
Converts all chars from string to upper case.
sort(target)
Returns target sorted in increasing order.
custom_sort(sort_id,target)
Returns target sorted in increasing order from the sorting routine's standpoint. That routine is specified by its routine_id, sort_id.
wildcard_match(pattern,subject)
Returns True if subject matches pattern, and False otherwise. pattern may contain the '?' and '*' wildcards anywhere.
wildcard_file(pattern,subject)
Same as wildcard_match, but the matches are case sensitive on Linux/FreeBSD systems only.
sprint(anything)
returns a string, the flat text representation of anything that print would send to an I/O channel.
sprintf(format,values)
Returns the result of replacing, in the string format, the first format specifier by the first value in values printed with this format, and so forth. printf does the same, but outputs to an I/O channel.
value(string)
Tries to read a flat text representation of an OpenEuphoria object from string and returns as get would from reading an I/O channel: a pair {status,value}.
 

12 Dynamic code execution.

call_func(expr,list)
calls the function with routine_id expr using the list of arguments list, which may be {}. Evaluates to whatever that function returns.
c_func(expr,list)
Acts like call_func, but must be used on external routines declared using define_c_func.
call_proc(expr,list)
calls the procedure with routine_id expr using the list of arguments list, which may be {}. No return value is expected.
c_proc(expr,list)
Acts like call_proc, but must be used on external routines declared using define_c_proc.
call_routine(expr,list)
calls the routine with routine_id expr using the list of arguments list, which may be {}.
eval(string)
Evaluates string to a string representing valid OpenEuphoria statements, evalutes it and returns the value.
execute(expr)
if expr evaluates to a string, executes the statement(s) contained in this string.
routine_id(expr)
expr must evaluete to a string. The id of the visible routine with this name is returned, or -1 if none.
get_name(expr)
expr must evaluate to an integer, and the name of the routine with this id is returned, or "" if none.
resume_execute(expr)
returns from current handler, execute()s the argument and then possibly acts as resume would.
return_execute(expr)
returns from current handler, execute()s the argument and then possibly acts as return would.
call_chain()
Returns a list representing the call stack. The list is made of strings or pairs of strings. Isolated strings are routine names. Pis are {routine name,label} pairs, which occur if and only if the calling statement has a label. For calls at top level, replace "routine" by "file name".
come_from()
Returns the label of the last executed goto statement.
come_from_far()
Returns the label of the last executed goto_far statement.
come_back
Returns execution oint to the statement following the last goto statement executed.
come_back_far
Returns execution oint to the statement following the last goto_far statement executed.
goto_clear()
Clears the internal variable that holds the label of the last goto taken, and which come_from() returns.
goto_clear_far()
Clears the internal variable that holds the label of the last goto_far taken, and which come_from_far() returns.

13 Defining and calling a routine

[global ][forward ]routine type routine name({[update ] type  name})
declares a possibly global routine, of the type routine type, and with name routine name. The possibly empty parameter list contains formal parameters. A formal parameter has one to three components:
  • an optional update keyword, which states that the argument mapped to this formal parameter is to be passed by reference. If this keyword is absent, the argument will be passed by value;
  • the parameter type;
  • the parameter name.

Making the routine global may make it visible in files other than the current one.
Using the forward keyword means that the routine statements do not immediately follow.
The known routine types are: routine, function, procedure, type, reftype and handler.
routine type routine name
this short form immediately precedes the statements of a routine that was declared as forward.
routine name({[attr ]expr})
invokes the routine routine name and passes it its possibly empty argument list. When a formal parameter was declared using the update keyword, the with byref directive is in force, and the corresponding argument is a posssibly indexed variable, an attr must be provided. attr has two possible values: byval if parameter is to be passed by value, byref if the parameter is to be passed by reference. byval may be used to emphasize that the argument is to be passed by value, even when this is bound to happen anyway. No attr is needed without byref.
return [value]
Returns from a routine, no matter its type. Execution resumes at the statement immediately following the call to the routine being returned from. If this routine is a function, ie if its call is supposed to evaluate to something, it will evaluate to value. Parentheses are not required in the latter case.
extended_return(levels[,value])
Performs levels routine returns, without any statement in the skipped routines being excuted. Execution resumes at the statement immediately following the calllevels stack frales upstream. If that call is to evaluate, it does to value. If any function was skipped in the process, no assignment is performed on the memory locations that should have received a value.
coroutine
Like a routine, but its execution may be suspended by a yield statement, so that it resumes on the next call to it.
yield [expression]
Like return, but valid in coroutines only. It saves the private variables and its own location, so that, on the next call to the coroutine, the variables are restored and execution resumes right after the yield statement.

14 I/O.

open(filename,mode)
returns a channel id for the file or device filename, opened in the mode mode specifies.
close(channel)
closes channel.
flush(channel)
writes to channel all buffers related to it.
lock_file(channel,mode,bounds)
locks the whole of, or a portion (specified by bounds) of, channel. mode may allow to fine tune the external access restrictions. Returns 1 on success and 0 on failure.
unlock_file(channel,bounds)
Lifts a previous lock on channel. The value of bounds must match the one used in the relevant lock_file call.
print(channel,expr)
Writes expr to channel using braces and commas so as to emphasize the object's structure.
pretty_print(channel,expr,options)
same as print, but with more formatting options. It shorthands to ?, using the option string SystemPPOptions in this case.
printf(channel,format,values)
Writes format to channel, replacing each format specifier in format by the corresponding value in values, to which the specifier is applied before substitution.
puts(channel,stream)
Writes the characters in stream to channel.
getc(channel)
Reads the next character of channel, returns -1 on failure.
gets(channel)
Reads the next logical line from channel, returns -1 on failure.
get_bytes(channel,number)
Reads number bytes from channel and returns a sequence made of them.
prompt_number(message,bounds)
Displays message and waits for a number passing the bound checking bounds specifies; returns the number.
prompt_string(message)
Displays message and waits for a string to be entered; returns the string.
get_key()
Returns the key code of last key pressed.
wait_key()
Waits for a key to be pressed and returns the code for that key.
get(channel)
Reads from channel the next sequence of characters representing an OpenEuphoria object, and returns that object.
seek(channel,position)
Sets the pointer for channel to position and returns a success code. A position of -1 means end of file.
where(channel)
Returns the pointer associated with channel.

15 Memory management.

peek(parms)
Returns a single byte at parms if it is an integer, or a sequence if parms takes the form {address,number}, of length number and starting at address.
peek(1|2|4|8|16)(s|u)(parms)
Same as peek, but a (sequence of) bytes, words, dwords, qwords or 128-bit chunks is returned. You can specify whether they represent signed or unsigned quantities.
poke(address,values)
Writes remainder(values,256) to memory starting at address. If values is a single integer, it is converted to {values} first.
poke(2|4|8|16)(parms)
Same as poke, but a (sequence of) words, dwords, qwords or 128-bit chunks is written to memory.
mem_copy(target,source,length)
The length bytes at source re copied onto the length bytes at target.
mem_set(start,value,length)
Sets the length bytes starting at start to remainder(value,256). <
mem_set4(start,value,length)
Sets the length dwords starting at start to remainder(value,power(2,32)). dt>allocate(size)
Returns the address of a memory block of size bytes, or 0 on failure.
allocate_string(string)
Allocates space in memory for remainder(string,256) & 0, copies the last string and returns the block address, or 0 if it failed.
free(address)
Frees a memory block previously allocated at address.
register_block(address,size)
Registers a memory block starting at address, of size size, to the memory monitoring routines of the RAM debug safe.oe library.
unregister_block(address)
Unregisters a block starting at address that was previously register_blocked.
allocate_low(size)
Returns an address below 1Mb of a size byte memory block, or 0 if it could not allocate such a block.
free_low(address)
Frees a block allocated using allocate_low.

16 OS calls.

16.1 File system calls.

current_dir()
Returns a string, the current directory name.
chdir(path)
Performs a "change directory to path" command, returns 1 on success and 0 on failure.
dir(dirspecs)
returns a sequence of structures. Each structure is a directory entry matching dirspecs. It holds name, attributes, size, date and time reative to the entry.
walk_dir(path,filter_id,recurse)
Passes in turn all directory entries of path to the function whose routine_id is filter_id. This function returns True to stop the process or False to continue. recurse is a boolean, True to recursively scan subdirectories of path. Returns 0 on success and a nonzero exit code otherwise.

16.2 Video and graphics.

video_config()
Returns an array(8) of integer, holding video parameters.
text_color(color)
Causes the color secified by the integer color to be used to display text.
bk_color(color)
Causes the color specified by the integer color to be used for the background of displayd text.
clear_screen()
Clears the screen to the current background color.
text_rows(nblines)
Tries to set the number of text rows on screen to nblines, and returns the actual number that could be achieved.
scroll(amount,start,end)
Scrolls the lines from start to end inclusive by amount lines (up or down).
position(coord1,coord2)
Sets the cursor position.
get_position()
Returns the cursor position as {coord1,coord2}.
cursor(hexvalue)
Sets cursor shape.
wrap(bool)
Let long lines wrap or have them truncated.
display_text_image(position,image)
Display a combination character-attribute, specified by image, at position.
save_text_image(ULcorner,BRcorner)
Returns a sequence of sequence of alternating ASCII and attribute codes representing a screen rectangle.
read_bitmap(filename)
Reads a bitmap file and returns a pair representing the file data as a palette and a sequence of sequence of pixels.
save_bitmap(bmpdata,filename)
Creates filename as a bitmap file and saves bmpdata to it. bmpdata has the format of the value returned by read_bitmap.
mouse_pointer(yesno)
Hides the mouse pointer once more if the boolean yesno is False, and shows it once more if it is True.
mouse_events(mask)
Sets the list of events get_mouse will report. mask is a sum of powers of 2, each of them associated with a mouse event.
get_mouse()
Returns the last monitored mouse event as a triple {event,x,y}, or -1 if none.
message_box(message,title,buttons)
Displays a message box, displaying message, titled title and with characteristics given by buttons (see individual entry in part C for details).

16.3 Process control.

allow_break(yesno)
Allows control-C and control-Break to terminate the running program if the argument is True, and diable this facility if it is False.
check_break()
Returns the number of times control-C or control-Break was pressed since the last call, and resets the counter.
sleep(seconds)
Suspends current thread for seconds seconds.
abort(exitcode)
Terminates program and returns exitcode to whoever launched the program.
instance()
Returns the program handle under Windows, or 0.

16.4 Other cross-platfom calls.

sound(frequency)
Turns the PC speaker on at frequency frequency if this is positive. Turns speaker off if frequency is 0.
free_console()
Closes the displayed text mode window.
time()
Returns the number of clock ticks elapsed since some fixed point.
tick_rate(number)
Sets the number of clock ticks per second if number is greater than 18, or resets it to normal if it is 0. Only supported by DOS.
date()
Returns a sequence of integer representing the current system date.
command_line()
Returns the executable name, main program file name and extra words on the command line as a sequence of string.
getenv(varname)
Returns the string held by the environment variable varname, or -1 if there's none.
platform()
Returns a small integer identifying the host OS.
system(comand,mode)
Passes command to the host OS and restores graphic mode on return according to mode.
system_exec(invocation,mode)
Instructs the OS to run invocation and returns the exit code from the invoked program. mode acts like in system above.

16.5 DOS specific calls.

dos_interrupt(16|32)(number,registers)
Calls DOS interrupt number using registers as CPU register contents. Returns a sequence of integer in the same format as registers with the new CPU state.
get_vector(number)
Returns a pair {segment,offset} representing the address for DOS interrupt number handler.
set_vector(number,address)
Sets the address for DOS interrupt number handler to segment:offset, where address is {segment,offset}.

17 Interface.

call(address)
Calls a near routine at address. On return, the next program statement is executed.
open_dll(libname)
Opens a .dll or .so file called libname and returns an addres used to access routines and data in the library.
define_c_func(entry_point,name,args,return_type)
Get a routine_id for a function that's inside an opened library. entry_point is the address returned on opening the library with open_dll. name is a (possibly +-prefixed) function name. args is the sequence of the formal parameters' external types, and return_type is the external type of the returned value.
define_c_func({},address|{'+',address},args,return_type)
Get a routine_id for a function that's in memory, known by its address. args is the sequence of the formal parameters' external types, and return_type is the external type of the returned value. The {'+',address} form is used when the routine is to be called using the __cdecl convention.
define_c_proc(entry_point,name,args)
Get a routine_id for a procedure that's inside an opened library. entry_point is the address returned on opening the library with open_dll. name is a (possibly +-prefixed) function name. args is the sequence of the formal parameters' external types.
define_c_proc({},address|{'+',address},args)
Get a routine_id for a procedure that's in memory, known by its address. args is the sequence of the formal parameters' external types. The {'+',address} form is used when the routine is to be called using the __cdecl convention.
define_c_var(entry_point,name)
Get the address of external variable name from alibrary whoe entry_point was returned by open_dll.
call_back(id|{'+',id})
Returns an address for the routine in your code with routine_id id to be called by external code.

18 External types and structures.

memory({ext_type name|_})
Starts the definition of a raw memory structure. It looks like the definition of a structure, except that it can contain external type definitions only.
byte[(number)] [ (number)]
Defines an array of elementary quantities. The first number gives their size, and the second their number. When a number is not given, it is assumed to be 1.
[un]signed
Elementary quantities are unsigned by default, but may represent signed integers.
counted(nmber)
Specifies that the first number elementary quantities are to be read as a single unsigned integer, which is the number of the remaining elementary quantities.
delimited(list)
Specifies that the following array of elementary quantities will end on encountering any element of the comma separated list. Grouping using braces is allowed to refer to a specific combination of elementary quantities as an end-of-array signal.
optional
Specifies that all fields following the current one inclusive may not be found in a given instance of a memory structure. The number of unexpected optional blocks is dynamically controled by the @deftype metadata of the memory.
atom_to_float(32|64)(fp)
Converts a floating point nummber fp to a sequence of 4 or 8 bytes representing an IEEE 32- or 64-bit floating point number.
float(32|64)_to_atom(seq)
Converts a sequence seq of bytes of length 4 or 8, representing an IEEE floating point number in single or double precision, to an atom.
int_to_bytes(some_int)
Returns a sequence of bytes representing the integer some_int, least significant byte first. The returned sequence has length multiple of 4, or 8 on 64-bit systems.
byte_to_int(some_seq)
Merges the sequence of bytes remainder(some_seq,256) into a nonnegative integer, some_seq[1] holding its least significant byte.

19 Event and error handling.

set_handler(expr,expr)
set the handler for events listed in the first expr as the routine with id the second expr.
get_handler(expr)
returns the id of the handler for the event name expr evaluates to. Returns -1 for an unknown event.
error(expr)
raises a mostly fatal error. expr must evaluate to a string, and that string is displayed as an error message at crash time.
crash_message(message)
Changes the message displayed on stderr to message.
crash_file(filename)
Defines the name of the file generated on an abnormal program termination as filename.
crash_process(id)
id is the routine_id of a routine that receives the crash message as a reference and possibly modifies it. The modified message gets displayed on return.

20 Miscellaneous.

get_meta(symbol)
returns a structure containing the metadata for the argument. The argument is the symbol name or id. The type of the returned value is either SystemVarMeta or SystemRtMeta, according to whether the argument refers to a variable or to a routine. See 5.1 and 8.8 in part A for a description of the metadata.
isvarid(id)
returns True if id is the id of a variable, and False otherwise. Remember that ids are never recycled, so that a stored id may be invalid if one is not careful enough.
analyze_id(id)
returns a triple {name,index,parent}. name is any name the variable or nonatom element has. index is 0 for variables, and the index of the element referred to in the sequence it is an element of. parent is the id of that sequence if it exists, or id otherwise.



prev | next | contents