prev | next | contents


Part C: ALPHABETICAL REFERENCE.

   Here is the list of all supported symbols and keywords, with detailed meaning, usage notes (when applicable) and examples.

   Sometimes, a single keyword embodies or implemens a whole concept, so that the "usage notes" under he entry would virtually reproduce the relevant section from the structural part A. Instead, a link is provided so as to just go and read this section.

   All I/O, math, C interfacing and machine-level routines, ... may not be implemente in the core language engine, but in external libraries instead. Various versions of OpenEuphoria may take a different approach on the issue, and will need to state their own scheme in their own documentation, as this ia pat of their own implementation choices.

   Math operaors and function always extend to nonatoms as descibed in part A, 3.2. So, this fact will not appear repeatedly under individual entries.


+ operator

   Adds two atomic values together. The result is represented as an integer of any size or by a fraction if possible; otherwise, a floating point is returned.

   Usage notes:

   A + sign not preceded by an identifier is valid; 0 is assumed, so +5 equals 5.

   Example:

?5+7 -> 12
?+3 -> 3


- operator

   Adds the negative of the second operand to the first. The returned result is an integer or fzction whenever possible.

Usage notes: same as +.

   Example:

   ?5-7  -> -2
?-3 -> -3

-- comment

   Starts a comment. Any text found between this mark and the end of the physical line where it lies will be ignored by the language engine, so that the coder can freely use it to document the code.


* operator

   Multiplies two atomic values together. The returned result is an integer or fraction whenever possible, and a floating point number otherwise.

   Example:

?-5*7 -> -35
?3.2*20 -> 64

/ operator

   Divides the leftmost atomic value by the rightmost one and returns a fraction whenever possible, or a floating point number.

   Usage notes:

   If the right operand is 0, an exception is raised.
Use the floor and ceiling functions to get integer quotients for euclidian division.

   See also: floor, ceiling.

   Example:

?5/3 -> 1.666666666...
?16/4 -> 4
?16/4.0 > 4.0 --not an integer, since one of the operand is a floating point number.


& operator

   Concatenates two entities.

   Usage notes:

   The left operand must be a type whose length may vary. If it has a common element type, the right operand must be of this type.

   The result of s1&x has length length(s1)+length(x) if x is nonatomic, length(s1)+1 if x is atomic.

   The last element of s1 & x is always the last element of x, or x itself if it has no elements.

   See also: append, prepend.

   Example:

   {5,8,11} & -3 = {5,8,11,-3}
   {5,8,11} & {7,-3} = {5,8,11,7,-3}
   "albert" & "zoe"  = "albertzoe"


&& operator

   Performs a bitwise AND between both operands.

   Usage notes:

   If the atoms are stored with different sizes, the shorter operand is notionally extended by 0's on the left before the operation.

   Example:

27 && 41 = 9 (in binary form , 27 has its six last bits equal to 011011, while they are 101001 for the second operand. The result has its six last bits equal to 001001. All other bits are zero.


|| operator

   Performs a bitwise OR between both operands.

   Usage notes:

   If the atoms are stored with different sizes, the shorter operand is Notionally extended by 0's on the left before the operation.

   Example:

27 || 41 = 59 (in binary form, 27 has its six last bits equal to 011011, while they are 101001 for the second operand. The result has its six last bits equal to 111011. All other bits are zero.


~~ operator

   Performs a bitwise XOR between both operands.

   Usage notes:

   If the atoms are stored with different sizes, the shorter operand is notionally extended by 0's on the left before the operation.

   Example:

27 ~~ 41 = 50 (in binary ofrm , 27 has its six last bits equal to 011011, while they are 101001 for the second operand. The result has its six last bits equal to 110010. ALL other bits are zero.


^ operator

   Inverts all bits of the only operand. On an integer greater than zero, this amounts to negate it, then add 1. Otherwise, negate the integer and substract 1.

   Example:

^27 = -26
^x = x ~~ -1 --true whatever x is.


?expr I/O; procedure

   A shorthand for pretty_print(1,expr,{}). See pretty_print.


<< operator

   Shifts an atomic value a by n bits to the left. This operation is recommended on integers only, and has no effect on fractions. Shifting a floating point number may yield strange results and is not recommended.

   Usage notes:

n must be an integer.
If n is negative, a<<n is equal to a>>-n.
Shifting an integer by n positions to the left amounts to multiplying it by power(2,n).

>> operator

   Shifts an atom a by n bits to the right, padding with 0's. If a is an integer, the integer returned has the same initial size as a.

   Usage notes:

n must be an integer.
If n is greater than the number of bits a is stored into, 0 is returned.
If n is not zero, the result is an nonnegative integer. Use the signed shift operatorto get a more expected result on a negative integer.

If n is negative, a >> n is equal to a << -n. Shifting a floating point number may yield strange results. This operation is recommended on integers only.

See also: <<, >>>

   Example:

-257 >> 3 = 32 -- -257 is a 32-bit integer, so the shift is computed over 32 bits.


>>> operator

   Shifts the atom a by n bits to the right, padding with the leading bit of a.

   Usage notes:

n must be an integer.
If n is less than zero, a >>> n returns a << -n. Shifting a floating point number may yield strange results. This operation is recommended on integers only. It then amounts to taking the integer quotient of the left operand by power(2,n).

   Example:

-257 >>> 3 = -32


+=,-=,*=,/=,&=,&&=,||=,~~=,^= assignment

   Shorthand for the corresponding three term operation when the result is the first operand. These forms are generally more efficient and save some typing.

   For instance, x*=y is short for x=x*y.


=,:= assignment

Assignment operator: x gets the same value as y, and any value x had is lost forever.

   Usage notes:

   The := synonym is needed when = is clearly a relational operator. This happens in conditional clauses, where any value involved in some logical computation can be assigned to a symbol.

   Example:

   The following snippet:

if x:=f(y)=0 then ?(x+3) end if
computes f(y), assigns it to x and tests if this value is 0. If this test returns True, the value 3 is printed: indeed, if the if branch is taken, f(y), and hence x, is 0.

   The following snippet:

if x:=f(y)=0 or x<y0:=y then ?(x+3) end if
computes f(y), assigns it to x and tests if this value is 0. If this test returns True, the value 3 is printed: indeed, if the if branch is taken, f(y), and hence x, is 0. Otherwise, y0 is assigned the value of y, and x is tested to be less than y. If this second test returns Fales, nothing else happens. Otherwise, the value of x+3 is printed. Note that y0 gets a new value if and only if x is not 0.

=,!= relational operator

   Comparison operator. (x=y) is equal to 1 if x and y are equal, and to 0 otherwise. (x!=y) is always 1-(x=y).

   Usage notes:

   For nonatomic types, equality means that they have the same number of elements, and that all the elements of any operand are equal to the elements in matching position in the other operand.

    For nonatomic types, Euphoria returns a sequence of 0's and 1's. This behaviour can be forced back using the with seq_compat or with RDS directives.

   Atoms are never equal to non-atoms. Atoms are equal when they resolve to the same value: the integer 5 equals the floating point number 5.0 or the frction -10/-2.

   When the with rounding directive is on, floating point numbers are rounded to the nearest multiple of the current rounding value, as set on the most recent call to with rounding=, before being compared. By default, this is turned off for compatibility reasons, and can be turned on and off using the with rounding directive.


<,<=,>,>= relational operator

   Inequality test operators. For instance, x<y is 1 if x is less than y, and 0 otherwise.

   There are obvious identities:

      (x>y) + (x<y) + (x=y) = 1
      (x!=y) = (x<y) + (x>y)
      (x<=y) = 1 - (x>y)
      (x>=y) = 1 - (x<y)

   Usage notes:

   For nonatomic data types, the order relation used to compare them is lexicographic. This means that strings will be ordered just like they would be if listed in a dictionary.

   Notionally, elements are successively compared in the order they appear while they are equal.

   The process terminates when:

   Euphoria returns a sequence, since it extends relational operators to sequences like it does for other operations. You can force this behaviour back using the with seq_compat or with RDS directives.

   When the with rounding directive is on, floating point numbers are rounded to the nearest multiple of the current rounding value, as set on the most recent call to with rounding=, before being compared. By default, this is turned off for compatibility reasons.

   See the entry for rel_eq below.


#({general_identifiers})[operator]=expr assignment

   Simultaneously assigns the value of the righthand expr to all variables after the # sign.

   Example:

   #(x,y,...z)=27    -- the variables x, y,..., z are all set to 27.

#({general_identifier})#[operator]=expr assignment

   The righthand side is a nonatom. Each element in the lefthand (indexed) variable list is assigned the matching element in the righthand expr, until one or both operand runs out of elements. This operation is known as desequencing.

   Usage notes:

   The _ sign may appear in the lefthand list as an identifier. This causes the matching element on the right to be ignored. Without the _ sign, desequencing, is the symmetric operation of assigning an explicit sequence of symbols to a single sequence.

   Examples:

 #(x,y)#={y,x} swaps symbols x and y.
 If s is a sequence, the statement #(x,_,y)#=s will cause x to get s[1] if s is not empty, and y to get s[3] if s is long enough. No error will be raised because of the length of s, since extra arguments are simply ignored.

abort(exitcode) OS, procedure

   Terminates process and returns (even though it is a procedure) exitcode to the parent process or to the OS.

   On succesful execution of an OpenEuphoria program, 0 is returned. On abnormal termination, 1 is returned.


abs(number) math, function

   Returns the atomic value number if it is nonnegative, and -number otherwise.


allocate(size) RAM, function

   Sets up a memory block of size bytes and returns its starting address, or 0 on failure. The returned address is 8-byte aligned or better.


allocate_low(size) RAM, function

   Sets up a memory block of size bytes in conventional DOS memory, below 1Mb, and returns its starting address, or 0 on failure.


allocate_string(string) RAM, function

   Converts string to a block of length(string) bytes plus a trailing ASCII 0 character, sets up a memory block for this and returns its address, or 0 on failure. The conversion is by taking the remainder modulo 256.


allow_break(yesno) OS, procedure

   Allows control-C and control-Break to terminate the running program if the yesno boolean is True, and disallows it if it is False.


analyze_id(id)variables, function

   Returns a triple {name,index,value }. name is the name of the variable or named nonatom element referred to. If dealing with an element of some nonatom, index is the index of the element in that nonatom, and parent is the id of that nonatom.

   Usage notes:

   Unnamed nonatom elements return a name of "".

   For variables, index is 0 and parent is id.

   Recursively calling analyze_id until the latter condition occurs yields the indexing sequence to apply to the root nonatom in order to access an element nested in tht nonatom and of which only the id is known.


andlogical

   Performs a bitwise AND between its two operands. Each bit of the result is set if and only if matching bits of both operands are set. Otherwise it is cleared. Returns False if the result is 0, and True otherwise.

   Example:

27 and 41 = True there is at least one bit set in both operands at the same position, namely bit #1.


and_bits(expr1,expr2) logical, function

Performs a bitwise AND between both operands. So and_bits(x,y) = x && y.


append(expr1,expr2) sequences, function

   Returns expr1 after expr2 was added to it as its last element. From this description, expr1 must be a sequence.

   Usage notes:

   There is no restriction on expr2.

   The length of the returned sequence is 1+length(expr1) always.
When expr2 is an atom, append(expr1,expr2)=expr1 & expr2.

   Example:

append("albert","zoe") = {'a','l','b','e','r','t',"zoe"}. This is not a string because the last element of the result is a string, not a char.

arccos(number) math, function

   Returns the angle between 0 and PI radians whose cosine is the atomic value number.

   Note the equality:

arcsin(x)+arccos(x)=PI/2
for every number x.

arcsin(number) math, function

   Returns the angle between -PI/2 and PI/2 radians whose sine is the atomic value number.


arctan(number) math, function

   Returns the angle between -PI/2 and PI/2 radians whose tangent is the atomic value number.


atom_to_float(32|64)(fp) external types, function

   Converts an atomic value to a sequence of byte of length 4 or 8 that can be poked as-is into a field of external type C_FLOAT/C_DOUBLE.

   See also: float(32|64)_to_atom.


bits_to_int(some_seq) math, function

   Interprets some_seq as a sequence of boolean, and returns the integer made of these. The least significant bit of the returned value is some_seq[1].

   For instance, bits_to_int({3,-1,0,0,1,2.5,{}}) is bits_to_int({1,1,0,0,1,1,1})=115=#73='s'.

   See also: int_to_bits.


bk_color(color) OS, procedure

   color is an integer that defines the color of the background of any further displayed text.

   See also: text_color.


break [label|number] flow

   Exits the designated select statement. Execution resumes at the first statement following the next end select statement.

   See also: exit, select.


but particle, globals

   Specifies that the first argument to promote or demote is an exclusion list rather than an inclusion list.

See also: demote, promote.


by particle, loops

   Optional part of the for block parameter, introducing the increment for the loop index.

   An increment of 1 is assumed when this clause is not used.

See also: for, wfor.


byref, byval prefix, calls

   When a (possibly indexed) variable is given as an argument to a routine, the with byref directive is in force and the formal parameter of the routine to which it is mapped is declared as update, it must be preceded by one of byref or byval. byref means that the variable is indeed to be passed by reference; byval means that only the value is passed, as if there were no update.

   If an expression other than a single variable is mapped to a formal parameter of a routine declared as update, the keyword byval can still be used to emphasize that only a value is passed. A byref keyword in this context causes an error.

   without byref, none of these keywords is mandatory.


byte[(number) ][(number)] external types

   Specifies the granularity and length of an array which is some field of a memory declaration. The first number is the size, in bytes, of the elementary quantities the array is made of. The second number is the array length. Missing numbers are treated as 1.


bytes_to_int(seq) external types, function

   Converts a sequence of bytes to an unsigned integer by setting seq[1] as the least significat byte and so forth.

   See also: int_to_bytes.


c_func(id,args)
c_proc(id,args) interface

   Calls an external routine whose id was gotten through define_c_func or define_c_proc. args is the argument list, as in call_func or call_proc.

   You can use c_proc to call a function and ignore the value it returns.

   See also: define_c_func, call_func.


call(address) interface, procedure

   Calls machine code at address. The code executes in rotected mode at CPL=DPL=3, CS=DS, and must return using the retn (#C3) opcode. On return, the next program statement gets executed.

   You cannot directly pass arguments to the called code. However, you may poke the address of some data buffer before the call. The other option is to use define_c_func (for functions) with {} as a first parameter to get a routine_id, so that c_func can be used to perform an ordinary call.

   See also: define_c_func, c_func.


call_back(id|{'+',id}) interface, function

   Returns a machine size integer. This address is to b passed to external code in order for it to call the routine with routine_id id in your own code.

   Usage notes:

   The routine must have between 0 and 9 arguments, all of them representable by machine size integes, as well as the returned vale, if any.

   Use the + form under Windows only if you want your routine to be called using the __cdecl convention.


call_func(expr,list)
call_proc(expr,list)
call_routine(expr,list)
dynamic

   Calls the routine whose id is given by expr using the argument list list. If the routine does not take any argument, list must be {}.

   call_proc can be used if the routine is a procedure, and call_func can be used for functions and types. They are provided for compatibility only.


case shortcond select, subblock

   case statements only appear inside select blocks. They introduce statements to be executed when the selector expression (the expr in select expr) satisfies shortcond.

   Usage notes:

A shortcond is an abbreviated form of a condition. Four forms are recognized:

   In the above, selector refers to the selector expression in the ambiant select statement.

   After a case statement executes, control falls through to the next case statement, unless a break statement was encountered. The break statement exits the current select block. The statements following case are executed until their natural end, or at a stop or break statement.

See also: select, thru, break, stop.


cast(general_identifier,expr1,expr2) sequences, types

   Sets the type information of the element numbered expr1 of the nonatom general_identifier to expr2. Yhis may be needed when the known type information is richer than the standard assumption and needs to be kept.

   Usage notes:

   A type check will be performed after this call completes, using the current value and the supplied type information. expr2 is the routine id of the type function to be used, or the type name.


ceiling(number) math, function

   Returns the smallest integer not less than number. Extends to nonatoms.

   See also: floor.


chdir(path) OS, function

   Takes the name of the new current directory as its string argument, and requests the OS to perform the directory change. Returns 1 on success and 0 on failure.

   See also: current_dir.


check prefix, types

   This prefix applies only to types and reftypes. It causes type checks on assignment to variables of the prefixed types to happen regardless of whether systematic type checking is in force.


check_break() OS, function

   Returns the number of times control-C or control-Break was pressed since the last call from the current program, and resets the counter.

   This is mostly useful when an allow_break(0) was issued, since the running instance of the program would have been terminated otherwise.

   Note that control-C or control-Break are never reported while reading the keyboard; check_break is the only way to detect them.

   See also: allow_break.


clear_screen() logical, function

   Clears the screen to the currrent background color.


close(channel) I/O, procedure

   Closes the channel, flushing all its data buffers to it first. Further attempts to reference channel will raise errors.


command_line() OS, function

   Returns a sequence of string representing the current program invocation. The first element is the executable path. The second element is the name of the main program file. Any extra element is a word entered on the command line as an agument to the running program.

   A word is any string enclosed between whitespace (not returned). To have several words grouped as one, enclose them between double quotes.


compare(expr1,expr2) relational function

   Compares the two objects given as its arguments, and returns an integer.

    The returned value is -1 if the first object is less than the second, 1 if it is greater and 0 if they are equal.

   Note that testing for equality of floating point numbers can be tricky because of rounding errors. Adequate use of the with rounding directive may solve this issue, as comparison will occur between integer multiples of a small value.


[global ]constant {[type ]identifier=expr} var_decl

   Declares a (list of) constant(s). Constants are symbols whose values cannot be modified and must be set at definition time.

   The type of the constants can be specified. Otherwise, they are only assumed to be objects.


cos(angle) math, function

   Returns the cosine of the atomic value angle. angle is assumed to be in radians; a right angle is PI/2 radians.


counted(number) external types

   Indicates that the current array starts with number elementary quantities. They form a single unsigned integer, which is the actual length of the array.


crash_file(filename) error, procedure

   Sets the name of the file generated on abnormal program termination to filename. The default file name is "oe.err".


crash_message(message) error, procedure

   Sets the message displayed by default on stderr when a fatal error occurs to message. By default, the message is the header and traceback part in the crash file.

   You can pass the crash message to crash_proces for some dynamic processing before display.

   See also: crash_process.


crash_process(id) error, pocedure

   On a fatal error, the routine with id id gets the crash message passed by reference, so that it can be modified. On return, the modified message is displayed on stderr, the crash file is generated and the program aborts.


current_dir() OS, function

   Returns the current directory name as a string. Note that the meaning of "current directory" is OS specific.

   See also: chdir.


cursor(hexvalue) logical, function

   Sets the cursor shape.

   To better understand the coding of hexvalue, it is probably better to represent it as #wxyz:

   Scan lines range from 0 (top) to 7 (bottom) on most displays.

   The following are frequently used values:

               NO_CURSOR = #2000,
             UNDERLINE_CURSOR = #0607,
       THICK_UNDERLINE_CURSOR = #0507,
            HALF_BLOCK_CURSOR = #0407,
                 BLOCK_CURSOR = #0007

custom_sort(target,sort_id) nonatoms, function

   Returns target sorted in increasing order, from the sorting routine's standpoint. The sorting routine is specified through its routine_id, sort_id.

   Like compare, the sorting routine takes two arguments and returns an integer in {-1,0,1}. The above means that, if retval is the returned value, for all index values i for which the equality is defined, one has:

find(call_func(routine_id(sort_id),{retval[i],retval[i+1]}),{0,1})>0

   See also: sort.


cut_paste(target,position,source,start,end) nonatom handling, procedure

   Removes the slice [start..end] from source and pastes it onto target starting at position.

   For instance if s2="abcde" and s1="ABCDE", then transfer(s2,4,s1,3,4) results in s2 being "abcCD" and s1 being "ABE".

   Usage notes:

   Since this procedure implicitly involves clobbering data, it may have to be handled with care.

   If the pasted slice extends past the end of target, that is to say position+end-start>length(target), an error will occur.


date() OS, function

   Returns a sequence of integer representing the current system date. The meaning of its elements is as follows:

  1. year-1900
  2. month
  3. day
  4. hour
  5. minute
  6. second
  7. day of week, Sunday = 1
  8. day of year, January 1st = 1

define_c_func(entry_point,name,args,return_type)
define_c_proc(entry_point,name,args) interface
define_c_var(entry_point,name)

   Gets a routine_id for an external routine, or an address for an external variable. The accessed item is called name and must come from an external library opened with open_dll, who returned enty_point.

   Accessing a routine requires the possibly empty list (args) of the formal parameters' external types. define_c_func also needs return_type, the external type of the returned value.

   The routine_id can then be used by c_func or c_proc to call the routine, and the address can be peeked or poked as needed. The coder is reponsible for storing allowable values only at a returned variable address.

   Usage notes:

   Routines stored in libraries use two calling conventions: __stdcall and __cdecl. The former is more common, and is assumed by default. You must prefix name with a plus sign ('+') to request a __cdecl call. Don't do this unless you get some information from the library documentation, or you get unexpected repeated crashes when calling the routine. Further, __cdecl is for Windows only.

   You can define_c_proc an external function whose returned value will never matter in your program.

   See also: c_func, c_proc, open_dll.


define_c_func({},address|{'+',address},args,return_type)
define_c_proc({},address|{'+',address},args) interface

   Gets a routine_id for an external routine whose address only is known.

   The meaning of +, args and return_type is the same than in the forms above.

   Usage notes:

   Routines normally use one of two calling conventions: __stdcall and __cdecl. The former is more common, and is assumed by default. You must use the {'+',address} to request a __cdecl call. Note that this convention is for Windows only.


del_var(expr) var-decl

   Deletes a variable that was created using new_var. An exception will occur on any attempt to delete any other sort of variable. Additionally, this procedure cannot be called on a symbol being shadowed.

   expr evaluates to the id or name of the variable to destroy.


delimited(list) external types

   Sets up a memory block of size bytes in conventional DOS memory, below 1Mb, and returns its starting address, or 0 on failure.


demote [but] "{identifier}"|identifier [from identifier]
demote _ from identifier
globals

   Removes symbols from the default namespace, thus making it unavailable without a prefix. The syntax is the same as for promote.

   Usage notes:

   When the but keyword is used, the from identifier clause is mandatory.

   The '_' catchall symbol stands for "all symbols from".

   A symbol can be demoted if and only if it has a source namespace. Otherwise, this statement has no action.

See also: promote


dir(dirspecs) OS, function

   Returns a sequence of structures. Each structure describes a directory entry matching dirspecs from the OS standpoint.

   Each structure has the reserved type of SystemDirEntry. The layout for this type is as follows:

	structure SystemDirEntry(
		string name,
		string attributes,
		integer size,
		integer year,month,day,
		integer hour,minute,second
	end structure

   The attributes string holds the following characters:
Attribute Meaning
v volume
d directory
r read-only
h hidden
s system
a archive

   On DOS and Windows, you can use wildcards in the directory specifications.


display_text_image(position,image) OS, procedure

   Displays a combination of characters and attributes specified as image, at a position specified by position. position is a pair of integer as returned by get_position in text mode.

   image is a sequence of sequence of integer. Each inner sequence represents part of a line, specified as alternating ASCII codes and attributes.

   The first line starts at position, the second line starts at position+{1,0} and so forth.

   Example: the following snippet

	clear_screen()
	attr=RED+16*BLUE
--characters will appear red on blue
	img={{'A',attr},
		 {'B',attr,'B',attr},
		 {'C',attr,'C',attr,'C',attr}}
	display_text_image({5,3},img)
displays the following on screen:
1 2 3 4 5 6 7
1
2
3
4
5 A
6 B B
7 C C C

do particle, loops

   Signals the end of loop parameters.


dos_interrupt(16|32)(number,registers) DOS, function

   Calls interrupt number with registers, a sequenc of integers, holding the CPU state. Returns a sequence with the same layout as regiters.

   The elements of registers and of the returned value are unsigned integers betwen 0 and #FFFF for DOS16, 0 and #FFFF_FFFF for DOS32.

   registers has the following layout:

  1. (E)DI
  2. (E)SI
  3. (E)BP
  4. (E)BX
  5. (E)DX
  6. (E)CX
  7. (E)AX
  8. (E)FLAGS
  9. ES
  10. DS

E math, constant

   The base of natural logarithm (2.7182818...), which means that log(E)=1.


else flow

   Marks the start of the optional part of an if block that is executed if none of the conditions specified in the if or elsif statements in the current if block was met.

   Usage notes:

   This statement can appear only once in an if block. It can be reached only From an if or elsif statement.

See also: if, elsif.


elsif cond then subblock

    Checks if the condition cond is met.
If so, execution starts right after the then, exactly as for an if statement. Otherwise, if there is still another uninspected elsif or else statement in the current if block, that statement get executed.

   Otherwise, the if block is exited.

   Usage notes:

   This statement may appear only in an if block, and can be reached only From an if or elsif statement. See part A, chapter 5 "Condition evaluation" for details on what cond may be.

See also: if, else


end block type flow

   Marks the end of a code block of type block type. It belongs to the following list: for, if, memory, scope, select, structure, wfor, while, plus all routine type keywords.

   Failing to close a code block with the corresponding end statement causes a syntax error.


equal(expr1,expr2) logical, function

   Returns True if both expressions have the same value, and False otherwise. Numerical values in different format, as the integer 5 and the floating point number 5.0, have the same value, and hence are equal.

See also: compare.

error(expr) procedure

   Passes a string as an error message to the RaisedError handler, so that it can display it before the program aborts. The error routine is to be used mainly when there is hardly anything else to do but end the running program. Built-in routines invoke it, and any routine can use it, for a variety of software-detected error conditions.


eval(expr) dynamic, function

   This function assumes the string it is passed is a valid OpenEuphoria expression. It evaluates it and returns the computed value.


execute(expr) dynamic

   Executes statements specified by the argument string.

   Usage notes:

   The argument expr must evaluate to a string. That string is then treated as if it had been in the source file, even though it results from evaluating an expression.

   This feature may not be supported by translators, which work on source files before they are compiled or run.


exif [number|identifier] flow

   Exits an if block. Same operation as exit, except that it applies to if blocks rather than loops.

   See also: exit.


exists(expr) function

   The argument must evaluate to a string. The function returns True if there is either a routine or variable in scope with this string as a name. Otherwise, it returns False


exit [number|identifier] flow

   Exits the specified loop. Execution resumes right after that loop ends.

   Usage notes:

   exit without argument means "exit the current loop".

   exit with a nonnegative integer argument n causes n extra levels of loop to be exited at the same time. So, exit 0 is the same as exit, exit 1 exits the loop above the current one and so on. Assume the loops form a sequence starting at 0 with the current loop; then, the argument to exit is the index of the exited loop in this sequence.

   exit with a negative integer argument n leaves all active loop blocks except the -n-1 topmost such blocks. So, exit -1 leaves all loops (0 active loops left), exit -2 causes execution to resume in the topmost Loop, right after the end of the active loop directly nested ln that topmost loop, and so on. This is just counting the loops backwards in the 0-based sequence suggested in the paragraph above.

   exit with an identifier as argument will exit the loop that has the argument as label. See the label entry below.

   Exiting a nonactive or nonexisting loop causes an exception.

   See also: label.


find(expr,expr) sequence handling

   Returns the position of the first occurence of the first argument in the second, and 0 if no occurrence can be found. The second argument must be nonatomic.

   See also: find_all, match.


find_all(expr,expr) sequence handling

   Same as find(), but returns the sequence of all positions of the first argument as an element of the second one.

   Usage notes:

   {} is returned if not a single element of the second argument equals the first one.

   See also: find, match_all.


fit(target,source,padding|_) assignment

   Assigns to target the part of source that fits into target. If target is longer than source, the remaining elements of target are set to padding, or left alone if the universal _ is used as a third argument.


float(32|64)_to_atom(seq) external types, function

   Converts a sequence of bytes of lenth 4 or 8 representing an IEEE floating point number to an atom.

   See also: atom_to_float(32|64).


floor(number) math, function

   Returns the greatest integer not more than number.

   See also: ceiling.


flush(channel) I/O, procedure

   Writes to channel all data buffers related to it. Indeed, OpenEuphoria buffers all writes for more performance.


for loop

   A for loop is a block of code executed a fixed number of times. It has the following form:

   for identifier=start value to end value [by increment] do general-code end for

   Here, identifier is an atomic loop index variable whose initial value is start value. start value, end value and increment are computed once per loop execution, at the time when the for statement is reached from outside the for block. If no by clause is present, increment is set to 1.

   If (start value-end value)*increment is greater than 0, the loop is exited without any iteration taking place, because end value cannot be reached from start value by adding any positive number of increment to it.

   Whenever execution reaches the end for statement, the value of increment is added to the loop index variable. The new value is then compared to start value and end value.

   If the loop index value is not between these two bounds, the loop is exited and execution resumes right after the end for. Otherwise, another iteration starts right after the do using the new index value.

   The loop index variable cannot be modified inside the loop. Loop index variables should not be declared. They are available in the for loop they are defined in, and remain available until the next for statement using the same loop index identifier.

   See also: wfor.


forward prefix, routines

   Specifies that the statements of the routine being defined are not immediately following the current routine definition. They will follow a short declaration.

   See chapter 8 in part A for details.


frac_to_seq(expr) fractions, ,function

   Returns an array(2) of integer. The first element in this array is the numerator of the fraction expr must evaluate to, and the second is the denominator.

   Usage notes:

   If expr evaluates to an integer n, the pair {n,1} is returned.

   Otherwise, the returned pair {numerator,denominator} is unique in the following respect:

   Example:

	frac_to_seq(-639/-381)=213/127
The common factor 3 was cancelled out, and the common -1 sign was also removed so that the denominator is greater than zero.

frac_to_atom(expr) fractions, ,function

   Returns an atom representing the numerical value of the fraction, or an integer if possible.

   Example:

	frac_to_atom(-639/-381)=1.6771653...

free(address) RAM, procedure

   Frees a previously allocated memory block starting at address.


free_console() OS, procedure

   Closes the text mode window automatically created at the first need to output to stdout/stderr or read from stdin.

   Usage notes:

    On WIN32 this window will automatically disappear when your program terminates, but you can call free_console() to make it disappear sooner. On Linux or FreeBSD, the text mode console is always there, but an xterm window will disappear after OpenEuphoria issues a "Press Enter" prompt at the end of execution.

   On Linux or FreeBSD, free_console() will set the terminal parameters back to normal, undoing the effect that curses has on the screen.

   In a Linux or FreeBSD xterm window, a call to free_console(), without any further printing to the screen or reading from the keyboard, will eliminate the "Press Enter" prompt normally issued at the end of execution.

   The trace facility also creates a console.


free_low(address) RAM, procedure

   Frees a memory block allocate_lowed at address.


[global ][forward ]function identifier({[update ]type  identifier})
function identifier
routine

   The first form defines the status and the formal parameters of a routine. It is followed by the routine's statements if the forward keyword is not used. The second form introduces the routine's statements if it was defined as forward.

   A function is a routine that must return a value. Provided for compatibility only.

   See part A, chapter 8 for more details.


get(channel) I/O, function

   Reads the next flat text representation of an OpenEuphoria object from channel and returns a {status,value} pair.

   Usage notes:

   status may take three distinct values:

value is meaningful only when status is GET_SUCCESS.

   Top-level objects must be separated by at least one whitespace character. An extra whitespace character is read on each call to get.


get_bytes(channel,number) I/O, function

   Reads number bytes from channel and returns a sequence made of the bytes that could be read.


get_handler(expr) events, ,function

   Returns the id of the handler for the event name expr resolves to, or -1 if none.

   See part A, chapter 11 for details on events and handlers.


get_key() logical, function

   Returns the key code of last pressed key. Returns -1 if no code can be retrieved: get_key does not wait for a keypress, contrary to wait_key.

   See also: wait_key.


get_meta(expr) symbols

   Returns a structure of metadata for the symbol whose name or id is given to the function.

   Usage notes:

   The type of returned data is either SystemVarMeta (described in part A, 5.1) if the symbol is a variable, or SystemRtMeta (described in part A, 8.8) if the symbol is a routine.


get_mouse() OS, function

   Returns a triple {event,x,y} representing the last monitored mouse event that occurred. event is a code as set using mouse_events, and {x,y} is the position where this event occurred. Returns -1 if there's no event to report.

   Simultaneous mouse events (like dragging the mouse) are reported as one, with event being the sum of the codes for all elementary events involved (see mouse_events entry for a list). You may need to use and_bits on the event code to sort out the elementary event you want to detect.

   Usage notes:

   A DOS driver is needed for this routine to work, or GPMServer under Linux.

   Under Linux, RIGHT_UP and MIDDLE_UP report as LEFT_UP. Also, get_mouse does not report events from an xterm window.

   Under DOS, the position is in pixels, and some scaling is in order to get a {line,column} position. Also, the returned position may have to be corrected by one pixel, according to various hardware and software settings.

   The first call to get_mouse shows the mouse pointer once.

   See also: mouse_events.


get_name(expr) routine, function

   Returns the name of the routine whose id expr evaluates to. If no such routine exists, the empty string "" is returned.


get_position() OS, function

   Returns the position of the cursor as {coord1,coord2}, zn zrray(2) of integer.

   For pixels, coord1 is horizontal, coord2 is vertical and the lowest value for both is 0. Otherwise, i.e. when referring to text, coord1 is the line number, coord2 is the column number, and they both start at 1.

   See also: position.


get_var(expr) variable, function

   This function returns the value of the variable whose id expr evaluates to.

See also: set_var


get_vector(number) DOS, function

   Returns the address of DOS interrupt number handler as {segment,offset}.


global prefix

   Specifies that the symbol(s) to which it applies can be seen from other files, possibly using a namespace prefix.

See also: include, import.


getenv(varname) OS, function

   Returns the value of the environment variable varname as a string, if there's any, or -1 if varname does not exist.


[global ][forward ]handler identifier(arguments)
handler identifier
event, routine

   A routine primarily intended to be triggered by an event, as opposed to the other sorts of routines which are primarily intended to be called explicitly.

   See part A, chapter 11 for details, and particularly the layout of arguments.


id(expr) variable, function

   Returns the id of the variable whose name the argument evaluates to.

   If no variable with the supplied name exists, -1 is returned.


if

block

   Checks if the condition cond is met.

    If so, execution starts after the then particle until the next elsif, else or end if statement is to be reached. Execution then resumes right after the end if statement.

   Otherwise, if there is an uninspected elsif or else statement, this statement is executed; Otherwise, the block is exited.

   Usage notes:

   See part A, chapter 4, "Condition evaluation", for more details on what cond may be.


import filename|(expr) as identifier globals

   Executes the top level statements in filename if filename is referred to for the first time in a program. If parentheses are used, the string expr must evaluate to is taken as filename.

   Makes the global symbols in filename accessible to the current file. The symbols are available using the prefix identifier:. Unprefixed access is not granted, contrary to what the include statement does.

   Usage notes:

To access imported symbols without any prefix, the promote statement must be used.
From the import or include standpoint, files whose names differ or whose explicit paths differ are different. This allows to include duplicate sets of symbols from the same file, by supplyin different paths each time.

   Example:

   import misc.oe as msc
--the global symbols in the file misc.oe are available using the prefix msc:.

   import ( misc.oe) as msc
--there must be some structure or sequence misc with a member or named element called oe, and the element wirh this name must hold a string. The global symbols in the file with this string as name are available using the prefix misc:.

See also: include, promote.


include filename|(expr) [as identifier] globals

   Executes the top level statements in filename if filename is referred to for the first time in a program. If parentheses are used, they enclose an expression wose value is taken as filename.

   Makes the global symbols in filename potentially available to any file in the program without prefix (they are automatically promoted). If an as identifier clause is specified, the symbols are also available using the prefix identifier: in the file the include statement appears in.

   Usage notes:

   Namespaces are known only in the file they appear in after an as keyword.

    From the import or include standpoint, files whose names differ or whose explicit paths differ are different. This allows to include duplicate sets of symbols from the same file, by supplyin different paths each time.

   Several files may share the same namespace. A file may be included in several namespaces, but the identifiers thus affected are not duplicated.

   Symbols usable without prefix actually belong to a special namespace called default.

   If an include statement appears inside a scope block, the global sylbols are available to any code that uses this scope. The block must be global in order to other file to iuse it. This is because the include statement is notionally equivalent to an import statement followed by a general "promote _" statement, even though there may be no explicit namespace supplied, contrary to the import statement.

See also: import, scope.


[+|-]inf math, symbol

   A symbol lesser than any atom if the minus sign is used, or a symbol greater than any atom otherwise. It may intervene in about any arithmetic or math operation, but with some restrictions. See part A, The infinity, for a complete decription.


insert(target,places,added) sequences, function

   Inserts inside target the elements of the sequence added at the locations specified in the sequence of integers places must evaluate to.

   Usage notes:

    added and places must have the same length; otherwise an error occurs.

    Notionally, the last element of added is inserted at the position given by the last element of places. Then, added and places are chopped off, and the process goes on until both added and places are empty. For this reason, places will be sorted in increasing order for most applications, even though interesting and possibly desirable effects may arise from failing to meet this criterium.

   The returned sequence has length(places) more elements than target had when the call was issued.

   insert(s,i,x) equals append(s[1..i-1],x) & s[i..-1], but executes much faster.

See also: insert_sequence


insert_sequence(target,places,added) esquences, function

   Inserts by concatenation inside the target the elements of the sequence added at the locations specified in the sequence of integers to which places must evaluate to.

   Usage notes:

   added and places must have the same length; otherwise an error occurs.

    Notionally, the last element of added is inserted by concatenation at the position given by the last element of places. Then, added and places are chopped off, and the process goes on until both added and places are empty. For this reason, places will be sorted in increasing order for most applications, even though interesting and possibly desirable effects may arise from failing to meet this criterium.

   The returned sequence has n more elements than target had when the call was issued. n is the number of atoms in added plus the sum of the lengths of the nonatoms in added.

   insert_sequence(s,i,x) equals s[1..i-1] & x & s[i..-1], but executes much faster.

See also: insert.


instance() OS, function

   Returns the program handle under Windows, and 0 otherwise.


int_to_bits(some_int,size) math, function

   Returns a sequence of boolean of length size, representing the size least significant bits of some_int. The first element of the returned sequence is the lowest order bit of some_int.

   For instance, int_to_bits(273_473_123479,6)=int_to_bits(1123_479)=int_to_bits(23)={1,1,1,0,1,0}.

   See also: bits_to_int.


int_to_bytes(some_int) external types, function

   Converts an integer to a sequence of bytes, so that the first byte is the least significant byte of some_int, and so forth.

   See also: bytes_to_int.


is type, particle

   Enables to define an alias for a type or reftype, as described in part A, 1.6. This construct applies to both types and reftypes.

   Example:

	type intSeq is sequence of integer
defines a type function intSeq that checks a value to be a sequence of integer. intSeq can be used from that statement on as an alias for "sequence of integer".

isvarid(expr) dynamic

   Returns True if its argument, which must evaluate to an integer, is the id of a variable, and False else.


label flow

   Marks a block with the tag identifier, to be used in flow control instructions.


length(expr) sequence handling, function

   Returns the number of elements in the nonatom expr. This function fails on atoms, causing an exception.


lock expr variables, action

   Makes a variable read-only. The variable can be specified either by its name or its id.

   Writing to a read-only variable will cause a warning.


lock_file(channel,mode,bounds) I/O, function

   Informs the OS that some portion of channel is reserved by the current process and that concurrent access to that portion must be denied or restricted. Returns 1 on success and 0 on failure.

   mode is an integer some OSes support; bounds is a sequence which may be empty to lock the whole channel, or a {lower bound,upper bound} pair to specify a portion to lock.

   Usage notes:

   Unix-like OSes allow the values LOCK_SHARED (accept read access from other processes) and LOCK_EXCLUSIVE (don't) for the mode integer. Other OSes will ignore this integer.

   Unix-like systems do not enforce locks strictly. The bounds parameter should be {} for these OSes.

   See also: unlock_file.


log(number) math, function

   Returns the natural logarithm of the atomic value number.


lower(string) strings, function

   Converts all chars from string to lower case. The pairing between lower and upper case characters is specified by the string SystemCharPairing.


match(expr,expr) sequence handling, function

   Returns the position of the first occurence of expr1 as a subsequence of expr2, or a nonpositive value if none could be found.

   Usage notes:

   expr1 must be of nonatomic type.

   If expr2 is an atom, match behaves as find.

   If expr1 is empty, the matching does not quite make sense, so a negative value is returned: -1 if expr2 is not empty, and -2 if it is.


match_all(expr,expr) sequence handling, function

   Same as match(), but returns all positions of occurences of the first argument as a slice of the second argument.

   Usage notes:

If the first argument is not a slice of the second one, {} is returned.
If the first argument resolves to the empty sequence, then an atom is returned, with the same values and meanings as for match().


mem_copy(target,source,length) RAM, procedure

   Notionally, copies the length bytes starting at source and pastes this block at address target.


mem_set(start,value,length) RAM, procedure

   Sets length bytes, starting at start, to the same value, which is the less sugnificant byte of value.


message_box(message,title,buttons) S, function

   Displays a message box with title title, displaying message and buttons as specified by buttons. Tis argument also defines displayed icons and some window attributes.

   The following list enumerates the supported features buttons is the sum of:


mouse_events(mask) OS, procedure

   Selects the mouse events get_mouse will report. mask is the sum of small integers associated each with an elementary mouse event.

   Usage notes:

   This call is primarily intended for DOS32 programs; it has no effect under Linux.

   Here is the list of elementary mouse events and the associated mask values:
Event Mask value
MOVE 1
LEFT_DOWN 2
LEFT_UP 4
RIGHT_DOWN 8
RIGHT_UP 16
MIDDLE_DOWN 32
MIDDLE_UP 64
Thus, monitoring left clicks will be done with a mask of 2+4=6. To also monitor middle button presses, add 32 to this, for a mask value of 38.

   By default, the mask is 127 (all events).

   See also: get_mouse.


mouse_pointer(yesno) OS, procedure

   Hides the mouse pointer once more if yesno is False, and shows it once more if it is True.

    The default mouse handler stores the pointer state as a counter. The pointer is displayed when this counter is positive and hidden otherwise. Thus, you may have to repeatedly call mouse_pointer to get the desired result.

   Usage notes:

   This call is primarily intended for DOS32 programs. It has no effect under Linux.

   Some functions implicitly hide the cursor (text_rows) or show it (first call to mouse_events or get_mouse)

   See also: get_mouse, mouse_events, text_rows.


move(target,start,end,where) nonatoms, function

   Moves the slice target[start..end] to position where in target.

   Usage notes:

   If the end of the moved slice has an index higher than length(target), which happens if where+end-start is greater than length(target), an error is raised. Otherwise, the functions acts by rotating a larger slice of target so that the element at position where in the returned value is target[start].

   example:

	target ="abcdefghi"
	s=move(target,7,9,3)	--s is now "abghicdef"
	s=move(target,2,5,7)	--error, as 'e' ends up at  position 10
	s=move(target,2,6,4)	--s is now "aghbcdefi"
	s=move(target,2,4,7)	--s is now "aefghibcd"

name general_identifier as identifier
rename general_identifier as identifier
unname general_identifier
variables

   Allow to specify and manage aliases for elements of nonatoms. The second identifier acts as a structure member name.

   name defines an alias, rename changes it and unname discards it.

   The member name tracks the element it tags. For instance, assume the following statement is issued:
name s[3][5] as s35

    After that, s[1] is deleted, and then two elements are prepended to the new s[2]. Then, s35 refers to s[2][7], as this is the place in s where the element tagged as s35 lies now.


new_var(varname,vartype,value|_) var_decl, function

    Creates a new variable on the spot and return its id. The type of the variable is given by vartype, either by name or by id. The variable name is given by varname. Its initial value, if any, is evaluated by expr. To create a variable without an initial value, use the symbol "_" as third argument.

   A variable created in this way cannot be static or global. It is private if new_var appears inside a routine; it is public otherwise.


next [expr|identifier] flow

   Skips the remainder of the specified loop iteration and start a new iteration, updating indexes and evaluating conditions as needed. The optional argument is specified exactly as for exit.

   The optional expr specifies the currently active loop block to be affected: the current one has index 0 and the others are numbered upwards. An argument of 0 is assumed if there is none; this stands for "restart the current loop". A negative integer refers to the active loops counted backwards, so that next -1 means "exit all loops", next -2 means "exit all loops but one" and so on.

   An optional identifier argument may be given, in which case a new iteration of the loop thus tagged starts if it cn. If there is no active loop with this tag, an error occurs.

See also: retry, exit


not logical

   Reverses each bit of its sole operand, reversing True to False and vice versa. Notionally, not x is x~~-1.


not_bits(expr) logical, function

Performs a bitwise NOT on its operand, so that not_bits(x) = ^x.

See also: ^.


open(filename,mode) I/O, function

   Associates a channel id to the external file or device name filename and returns that id. The open mode is a string of one or two characters.

   The first mode character is either:

   To open the file or device in binary mode, add the "b" modifier as the second character of mode.

   Usage notes:

   Ids 0, 1 and 2 are already assigned to standard input, standard output and standard error respectively.

   If open fails, it returns -1.

   OpenEuphoria always reads from or wites to channel ids, so that a file or device other than the three stanndard devices must be opened before being used.

   A text file is organized in logical lines separated by a format specific token: CR+LF (DOS/Windows), LF (Linux/FreeBSD), CR (Mac). They are supposed to mostly consist of printable characters. Binary files don't now about lines and may hold any kind of bytes.


open_dll(libname) interface, function

   Opens a Windows dynamic link library (.dll) or Linux/FreeBSD shared object (.so) file named libname. Returns 0 on failure, and a machine size integer representing an entry point for the library. Use this address to define external routines.

   See also: define_c_func.


optional external types, prefix

   Indicates that the current field as well as all those which follow are optional, so that a memory with only the fields defined beforehand qualifies as the memory it pretends to be, even though some fields are missing.

   Let's call optional block a contiguous subset of fields starting with an optional field and stopping just bfore another one or at the end of the raw memory structure definition. Then, for any given instance of that memory, the @deftype metadata holds the number of unneeded optional blocks, 0 by default.


or logical

   Performs a bitwise OR between its two operands. Each bit of the result is cleared if and only if matching bits of both operands are not set. Otherwise it is set. Returns True is the result is nonzero and False otherwise, i.e. when both operands are zero.

   If the operands don't have the same length, the shortestis padded with 0's before the logical operation takes place.


or_bits(expr1,expr2) logical, function

Performs a bitwise OR between both operands. So or_bits(x,y) = x || y.

otherwise flow

   Inside a select block, introduces the statements to be executed if no case statement could be executed. This clause is optional and must be the last one in the select statement.


peek(address|{address,number) RAM, function

   The shorter form returns the byte at address. The longer form returns the sequence formed by the number bytes starting at address. Bytes are returned as integers in the range 0-255.


peek(1,2|4|8|16)(s|u)(address|{address,number}) RAM, procedure

   Arguments are as for peek above. Returned values are words (peek2), dwords (peek4), qwords (peek8), 128-bit chunks (peek16) or even bytes (peek1). They are assumed to represent signed quantities whn the 's' modifier is used, and unsigned quantities when using 'u'. Thus, peek4s will return signed dword(s).

   Note that peek1u is equivalent to peek.

   See also: peek.


platform() OS, procedure

   Returns an identfier of the host OS. The available constants are:


poke[2|4|8|16](address,values) RAM, procedure

   Writes bytes, words, dwords, qwords or 128-bit chunks to memory. Either writes a single value at address, or writes a sequence of values, in the chosen format, starting at address. Only the less significant byte/word/dword/qword of elements of values are effectively written.

   See also: peek.


position(coord1,coord2) OS, procedure

   Set position of the next drawn pixel (pure graphic mode) or text (other video modes).

   For pixels, coord1 is horizontal, coord2 is vertical and the lowest value for both is 0. Otherwise, i.e. when referring to text, cood1 is the line number, coord2 is the column number, and they both start at 1.


power(base,exponent) math, function

   Raises base to the power exponent, and returns the result.

   Usage notes:

   Raising a nonzero atom to the power 0 returns 1, except when base is also 0; this is a MathIndeerminacy exception condiion.

   If base is less than 0, the exponent must be either an integer or a fraction with even numerator; otherwise, a MathIndeterminacy exception is raised.

   The behaviour of power when one of its arguments is [+|-]inf is described in part A, The infinity.


prepend(s,x) sequence handling, function

   Same as append, except that x becomes the first element of the returned value.


pretty_print(channel,expr,options) I/O; procedure

    Prints, using braces { , , , }, indentation, and multiple lines to show the structure, the value of expr to the file or device identified by channel.

   options is a sequence of length at most 8 that controls the prsentation of the printout. A {} value selects the default value for options.

   options has the following layout:

  1. display of ASCII characters:
  2. amount to indent for each level of sequence nesting ( default = 2)
  3. starting column (default = 1)
  4. approximate column to wrap at (default = 78)
  5. format to use for integers (default = "%d")
  6. format to use for floating-point numbers (default = "%.10g")
  7. minimum value for printable ASCII (default = 32)
  8. maximum value for printable ASCII (default = 127)

    If the length of options is less than 8, unspecified options at the end of the sequence will keep the default values. e.g. {0, 5} will choose "never display ASCII", plus 5-character indentation, with defaults for everything else.

   The display will start at the current cursor position. Normally you will want to call pretty_print when the cursor is in column 1 (after printing a \n character). If you want to start in a different column, you should call position() and specify a value for options[3]. This will ensure that the first and last braces in a sequence line up vertically.

   ?expr is a shorthand for pretty_print(1,expr,{}).

   See also: print


print(expr1,expr2) I/O; procedure

   Prints to the I/O channel number expr1 the second argument.

    If the second argument is a variable name, and if its format metadata was set, the value of the variable will print using that strng as format string, as if specified in printf() (see below).

   When the above does not apply and the type of the argument can be inferred, the relevant format metadata string is used to format the output. Otherwise, the default output format for objects is used.


printf(expr1,expr2,something|{{expr}}) I/O; procedure

   Prints the third argument to the file or device channel specified by expr1, using format string expr2. The short form is allowed only if there is only one format specifier in expr2 and something is an atom.

   Usage notes:

   A format specifier is a string whose first character is '%'. For this reason, the percent sign must appear as "%%" in a format string. The number of format specifiers in the format string must equal the length of the third argument (or equal 1 if the shorter form is used). The first specifier is appliied to print the first item, the second specifier for the second element and so on.

The basic formats supported are:

              %d - print an atom as a decimal integer
              %x - print an atom as a hexadecimal integer
              %o - print an atom as an octal integer
              %s - print a sequence as a string of characters, or print an atom
              as a single character
              %e - print an atom as a floating point number with exponential
              notation
              %f - print an atom as a floating-point number with a decimal
              point but no exponent
              %g - print an atom as a floating point number using either the %f
              or %e format, whichever seems more appropriate
              %v - use the format string of the variable's metadata @format.
              %t - use the format string of the variable's type metadata @format.

   Field widths can be added to the basic formats, e.g. %5d, %8.2F, %10.4s. The number before the decimal point is the minimum field width to be used. The number after the decimal point is the precision to be used, when applicable.

   If the field width is negative, e.g. %-5d then the value will be left-justified within the field. Normally it will be right-justified. If the field width starts with a leading 0, e.g.08d then leading zeros will be supplied to fill up the field. If the field width starts with a '+' e.g. %+7d then a plus sign will be printed for positive values.

   As each format specifier applies to one argument only, printing a string requires the following form: printf(x,"%s",{the_string}). Forgetting the braces will result in printing the first character of the_string only.

   When a variable format metadata is the empty string, print routines fall back on the variable's type format metadata.

   When a type format metadata is the empty string, print routines fall back on the default formatting for objects.

   When an expression other than a single (indexed) variable name is to be formatted with a %t or %v specifier, which doesn't make much sense, the default formatting for objects is used instead.


[global ][forward ]procedure  identifier({[update ] type identifier})
procedure identifier
routine

   The first form defines the status and the formal parameters of a routine. It is followed by the routine's statements if the forward keyword is not used. The second form introduces the routine's statements if it was defined as forward.

   A procedure is a routine that can't return a value. Provided for compatibility only.

   See part A, chapter 8 "Routines", for more details.


promote [but] "{identifier}"|identifier from identifier
promote _ from identifier
globals

   Makes symbols from an imported abstract file accessible without any prefix, effectively aliasing them in default.

   The first argument is an explicit list if between double quotes, and is an expression evaluating to a sequence of strings otherwise.

   The but keyword says that the first argument is a list of symbols to be excluded from promotion rather than to promote.

   The shorter second form makes all symbols available without any prefix.

    The last identifier argument is the namespace from which the designated symbols are to be promoted.

   See also: demote.


prompt_number(message,bounds) I/O, function

   Displays message, waits for the user to enter a number between the bounds in bounds and returns the number.

   Usage notes:

   If no bound checking is needed, bounds must be empty. Otherwise, it is a pair {lower bound,upper bound}.


prompt_string(message) I/O, function

   Displays message, waits for the user to input a string and returns this string.

   Usage notes:

   The user ends inputting the string by hitting the Enter key; the trailing OS specific line terminator is not returned.

   Hitting ^Z causes "" to be returned immediately.


puts(channel,stream) I/O, procedure

   Writes athe sequence of bytes stream to channel.


rand(expr) math function

   Returns a random nonnegative integer not greater than the absolute value of expr. The random number generator itself is deterministic, so that the same series of rand calls after the same call to set_rand will return the same results.

   See also: set_rand.


read_bitmap(filename) OS, function

   Reads a file in bitmap format called filename. filename will most likely have a .bmp extension. Returns a sequence of length 2. save_bitmap would generate a copy of filename from it.

   The first element is a palette structure, which is a sequence of RGB triples, each of them representing a color.

   The second element is a sequence of sequence of pixels. Each pixel is represented by the index of its color into the palette.

   Usage notes:

   This function has specific error messages which are as follows:

On error, the error code is returned, instead of a valid bitmap structure.

   See also: save_bitmap.


[check ][forward ][global ]reftype typename(integer identifier1,update type identifier2)
reftype typename
type

   The first form defines the status and the formal parameters of a reftype. It is followed by the reftype's statements if the forward keyword is not used. The second form introduces the reftype's statements if it was defined as forward.

   A reftype is a routine with eactly two arguments that returns a boolean. It may be invoked as any routine, except that it returns a value.

   When a (sub)variable get assigned, the (ref)type function associated to its type is implicitly called, with the id of the assigned variable and the value to be assigned as arguments.

   typename may be in the form structname.membername. In this case,the type function may access the members of the host structure by putting a dot before the member names.

   Context types and reftypes are discussed in detail in part A, chapter 1.


register_block(address,size) RAM debug, procedure

   Registers the block of length size starting at address to the memory monitoring routines of safe.oe.

   See also: unregister_block.


rel_eq, rel_ge, rel_gt, rel_le, rel_lt, rel_ne(nonatom,x) logical, function

   Extends the relational operators to nonatomic types. Returns a sequence of boolean, of the same length as nonatom. Thus, assuming x1<x2<x3:

rel_eq({x1,x2,x3},x2)={False,True,False}
rel_le({x1,x2,x3},x2)={True,True,False}
rel_lt({x1,x2,x3},x2)={True,False,False}
rel_ge({x1,x2,x3},x2)={False,True,True}
rel_gt({x1,x2,x3},x2)={False,False,True}
rel_ne({x1,x2,x3},x2)={True,False,True}

   Usage notes:

   The Euphoria idioms nonatom>=x and friends return rel_ge(nonatom,x) and friends when the with seq_compat directive is in force.


remainder(expr1,expr2) math, function

   Notionally divides expr1 by expr2, and adjusts the returned value rem so that:

Extends both ways to nonatoms.

remove(target,places) sequence handling, function

   Removes from target the elements whose positins are listed in places.

   Usage notes:

   places is an expression that must evaluate to a sequence of integers. target is an expression that must resolve to a nonatom.

   Notionally, places is sorted in decreasing order. Then, the element of target whose index is the first element in places is removed. The process goes on until all elements of places have been considered.

   remove(s,i) equals s[1..i-1] & s[i+1..-1], but executes much faster.

See also: replace.


rename general_identifier as identifier variables

   See name above.


repeat(what,howmany) sequence handling, function

   Returns a sequence of object whose howmany terms all equal what.

   See also: repeat_pattern.


repeat_pattern(what,howmany) sequence handling, function

   Returns a sequence of length howmany*length(what) made of the sequence what repeated howmany times.

   For instance, repeat_pattern("abc",4) is "abcabcabcabc", still a string of length 12, while repeat("abc",4) is {"abc","abc","abc","abc"}, a sequence of string.

   If what is atomic, repeat_pattern falls back on repeat.

   See also: repeat.


replace(target,places,items) sequence handling, function

   Replaces, in the argument specified by target, the subsequences specified by places by the elements of items.

   Usage notes:

   places and items must have the same length; otherwise, an error occurs. places must resolve to a sequence of array(2) of integer. An atom x is first replaced by {{x,x}}. An atom x inside places is first replaced by { x,x}.

   If places is not sorted in ascending order, strange, but sometimes desirable, effects may occur (see the lines just below). For most applications, places will be sorted in ascending order.

    Notionally, the slice of target whose bounds are the last element of places is removed and the last element of items is insert_sequence()'d at the same position into target. places and items are then chopped off, and the process goes on until both are empty.

   replace can be used on arrays on the condition that the length of the result is the same as the length of target. Otherwise, a type check error occurs.

See also: insert_sequence, remove


resume events, routine

   Exits the current routine and executes again the statement that caused the routine to be executed.

   Usage notes:

This statement is mainly intended for exception handlers.
If resume causes execution of the same statement more than MaxResumeRepeat times in a row, an exception is caused.

resume_execute(expr) events, dynamic

   This statement executes a statement on resuming normal program execution. The argument must evaluate to a string on which execute is applied.

   This instruction is intended for handlers only.


retry [number|identifier] flow

   Skips the remainder of current iteration of the specified loop and restarts the current iteration.

   For for loops, this means the loop index is not updated. For while or wfor loops, this means that the initial test is not performed.

   Specifying the affected active loop is done exactly in the same way as for the exit dtatement.

See also: next, exit.


return [expr] routine

   Exits a routine and optionally sets a value to be assigned after returning, when the routine is called as a function.

   See part A, chapter 8 "Routines" for a description of routine calls and returns.


return_execute(expr) events, dynamic

   This instruction executes statements on returning from a handler. expr must evaluate to a string, on which execute() is applied.

   This statement is intended for handlers only.


reverse(expr) sequence handling, function

   Returns a nonatom of the same length as expr. The first element in the returned value is the last one in expr, the second one in the returned value is the second last in expr, and so on.

   Usage notes:

   As expected, the argument must be a nonatom.


rotate(memory,field,number) external types, procedure

   Performs a bitwise rotation of memory.field by number positions to the right, where memory is a raw RAM structure.. This operation is not permitted on any other kind of data, as OpenEuphoria types are mostly without fixed size.

   Negative values of number cause a rotation to the left.

   Example:

   The letter 's' has ASCII code 115, which reads in binary as 01110011 . Assume letters.test holds the letter 's' as one byte, so:

rotate(letter,test,3)
results in letters.test=01101110, the letter 'n'. The three lower order bits of the initial value (011) are now its three upper order bits.
rotate(letters.test,-3)
results in letters.test=10011011=#9B, as the three most significant bits wound up as less significant bits instead.

[forward ][global ]routine identifier({[update ]type  identifier})
routine identifier

routine

   The first form defines the status and the formal parameters of a routine. It is followed by the routine's statements if the forward keyword is not used. The second form introduces the routine's statements if it was defined as forward.

   A routine may or may not return any value, and thus can be called both as a procedure and as a function.

   See part A, chapter 8 "Routines", for more details.


routine_id(expr) dynamic

   Returns the id of the routine the name of which expr evaluates to. If no such routine exists in the calling scope, -1 is returned.


save_bitmap(bmpdata,filename) OS, function

   Creates a bitmap file filename and saves a bitmap represented by bmpdata to it. bmpdata evaluates to a sequence of lrngth 2 of the form {palette,pixels}.

   palette is a sequence of RGB triples coding a color. pixels is a sequence of sequence of indexes into palette, each of which is the color of the pixel at the corresponding position. Each inner sequence is a column of pixels.

   Usage notes:

   As read_bitmap, which works in reverse, save_bitmap has returned status codes of its own:

   See also: read_bitmap.


save_text_image(ULcorner,BRcorner) OS, function

   ULcorner and BRcorner are the positions, as returned by get_position, of the upper left and bottom right corners of a rectangular zone of the screen. Returns a sequence of sequence of alternating ASCII and attribute codes representing that zone.

   The returned sequence is in the format display_text_image expects.

   See also: get_position, display_text_image.


scale10(expr) math, function

   Returns the exponent of the highest power of 10 not greater than the absolute value of expr.

   This function might be inefficiently implemented as floor(log(abs(expr))/log(10)), and provides fast, loose bounds for powers and logarithms.


scale2(expr) math, function

   Returns the exponent of the highest power of 2 not greater than the absolute value of expr.

   This function might be inefficiently implemented as floor(log(abs(expr))/log(2)), and provides fast, loose bounds for powers and logarithms.


[global ]scope [identifier] block

   This statement isolates a section of code. This section may have symbols of its own.

   When the scope has a name and is global, its global symbols may appear outside it as if they came from an external file, using the scope name as a namespace. There is no point in making an unnamed scope global.

   When the scope is inside a routine, it cannot have a name, must hold code allowed in a routine and have its specific variables defined at the top, just like routines.

   Global symbols in named scopes can be accessed from routines or scopes that issue an use identifier statement.

See also: use.


scroll(amount,start,end) OS, function

   Scolls the text lines from start to end inclusive by amount lines down (amount>0) or -amount lines up (amount<0).

   New empty lines created by the scrolling will use the current background color.


seek(channel,position) I/O, function

   Set the pointer for channel to position, and returns a success code (1 on success, 0 on failure).

   Usage notes:

   A position of -1 means the end of the file.

   It may be necessary to call seek after a series of reads and writes, even though it is theoretically unnecessary.


select selector block

   select is a more versatile form of stacked elsif statements. Inside a select block are case statements, which specify things to do if selector meets some condition. If no such case statement was executed, and if an otherwise clause is present, the statements in that clause are executed.

   Each case statement in the select block is inspected. It specifies a condition the selector must meet. If it does, the statements forming this case branch are executed. Then, the next case is inspected, if any, and if the block was not exited.

   The break statement allows to exit a select statement in the same way exit allows to exit a loop.

See also: case, break.


set_handler(event,expr) event, procedure

   Sets the handler for named events. The first argument must resolve to an event name, or to a comma separated list of event names between braces (a string anyway). The second argument must resolve to an integer, the routine id of the handler being put in charge.

   Usage notes:

   Using -1 as the second argument disables any user-defined handler for the specified events, causing default handlers to be called instead, as an event always has some handler.


set_rand(expr) math, procedure

   Initializes the random number generator rand uses.

   See also: rand.


set_var(expr1,expr2) variable, procedure

   This procedure assigns a value to a variable. expr1 resolves to the id of the variable, and hence must resolve to an integer, while expr2 evaluates to the value to assign.


set_vector(number,address) DOS, procedure

   Sets the address of DOS interrupt number handler to segment:offset. address supplies the address as {segment,offset}.


signed external types, prefix

   Specifies that the elementary quantity it qualifies is to be read as a signed integer.


sin(angle) math, function

   Returns the sine of the atomic value angle. angle is assumed to be a number of radians; a right angle is PI/2 radians.


sleep(seconds) OS, procedure

   Suspends the current proess for seconds seconds. Under DOS, the process will execute a tight loop an use some CPU cycles as a result.


sort(target) nonatoms, function

   Returns target sorted in increasing order, from compare's standpoint.

   See also: custom_sort.


sound(frequency) OS, procedure

   Turns the PC speaker on at frequency if it is nonzero. Note that actual sound will be heard under DOS only. sound(0) turns the speaker off.


sprint(anything) strings, function

   Returns the flat text representation of the general object anything. print does the same, but outputs to an I/O channel.

   See also: print.


sprintf(format,values) nonatoms, function

   Returns the result of replacing, in format, each format specifier by the corresponding element in values, printed with the specified format. printf does the same, but outputs to an I/O channel.

   See also: printf.


sqrt(number) math, function

   Returns the square root of number, if it can. Extends to nonatoms.


stop flow

   Allowed only in the code following a case statement. It causes the execution to resume at the next case statement if there is any, or forces exit from the current select block.

   See also: case, select.


structure identifier({type|_  identifier|_}) end structure type

   Defines the structure type identifier, which becomes a nonatomic user-defined type.

   Use of "_" as a type means the type of the member is a context type (see part A, 1.4). The context type is declared as stated in the entry for reftype.

   Use of "_" as a name means the member has no name, and can be accessed only through indexing.

   Usage notes:

   A structure type layout may contain fields that have the same type as the one being declared.

   Members of structure instances can be accessed by indexing or, if they have a name, naming.


swap_slices(target,t_start,t_end,source,s_start,s_end) Nonatom handling, procedure

   Swaps the slices source[s_start..s_end] and target[t_start..t_end].

   For instance, if s2="abcde" and s1="ABCDE", swap_slices(s2,2,2,s1,3,5) results in s2 being "aCDEcde" and s1 being "ABb".


system(command,mode) OS, procedure

   Passes command to the OS command interpreter, opening a new shell when applicable. mode controls how return from the OS is handled:


system_exec(invocation,mode) OS, function

   Passes invocation to the OS as an external program to run, possibly complte with command line arguments. Returns the exit code of that program.

   mode controls how return from the OS is handled:


tan(angle) math, function

   Returns the tangent of the atomic value angle. angle is assumed to be a number of radians. A right angle is PI/2 radians.


text_color(color) OS, procedure

   color is an integer that defines the color to print any further displayed text with.

   See also: bk_color.


text_rows(color) OS, function

   Tries to set the number of tex rows on screen. Returns the actual number of rows set.

   Not suported under Unix-like systems.


then particle

   Signals the end of if block/elsif subblock parameters.

See also: if, elsif


thru relational operator

   Used in case statements to specify lower and upper bounds for the selector expression in the ambiant select statement.

   See also: case.


tick_rate(number) DOS, procedure

   Under DOS, sets the number of clock ticks per second. number must be greater than 18 (the normal value), or 0 to restore normal operation.


time() OS, function

   Returns an integer representing the number of tick_rates elapsed since some fixed point. The tick rate is about 0.01 second. Under DOS32, it is 0.05 second, but can be modified using tick_rate.

   Under DOS, the elapsed reported time is reset every 24 hours.

   See also: tick_rate.


to particle

   Part of the for/wfor block parameters, introducing the end value for the loop index.

See also: for, wfor.

transfer(target,position,source,start,end) nonatom handling, procedure

   Removes the slice [start..end] from source and inserts it into target so that it starts at position.

   For instance if s2="abcde" and s1="ABCDE", then transfer(s2,4,s1,3,4) results in s2 being "abcCDde" and s1 being "ABE".

   See also: transfer_as_one.


transfer_as_one(target,position,source,start,end) nonatom handling, procedure

   Removes the slice [start..end] from source and inserts it into target at position as a new element.

   For instance if s2="abcde" and s1="ABCDE", then transfer(s2,4,s1,3,4) results in s2 being {'a','b','c',"CD",'d','e'} and s1 being "ABE".

   See also: transfer.


[check ][forward ][global ]type name(type identifier)
type identifier
type

   The first form defines the status and the formal parameter of a type. It is followed by the type's statements if the forward keyword is not used. The second form introduces the type's statements if it was defined as forward.

   A type is a routine with exactly one argument that returns a boolean. It may be invoked as any routine, except that it returns a value.

   When a (sub)variable get assigned, the type function associated to its type may be implicitly called, with the value to be assigned as argument.

   name may be in the form structname.membername. In this case,the type function may access the members of the host structure by putting a dot before the names.

   See part A, chapter 1 for more details.


unlock expr variables, action

   Makes a previously locked variable writeable again. This call does not affect constants.


unlock_file(channel,bounds) logical, procedure

   Lifts the lock on a previously lock_fileed (region of) channel. bounds must match the bounds parameter of the lifted lock.

   See also: lock_file.


unname identifier variables

   See name above.


unregister_block(address) RAM debug, procedure

   Unregisters the block starting at address that was previously register_blocked.


unsigned external types, prefix

   Specifies that the elementary quantities it qualifies are to be read as nonnegative integers. Not really needed as this is the default interpretation.


update prefix

   This keyword must precede any formal parameter passed by reference in a routine definition. Passing a variable by reference means that the modifications the called routine will make to this variable will be preserved on return, while they are not if passed by value.

See also: byref, byval.

upper(string) strings, function

   Converts all chars from string to upper case. The pairing between lower and upper case characters is specified by the string SystemCharPairing.


use identifier directive

   The identifier is the name of a scope. Global symbols in this scope are accessed from the code following the use statement without any namespace-like prefix.

   When the code in the file, scope or routine stops executiing, the effects of the use statement stop as well. This allows to select the places where included symbols can appear, thus reducing or eliminating name conflicts.

See also: scope.

value(string) strings, function

   Tries to read a valid flat text representation of an OpenEuphoria object from string an returns a two element sequence. This output has the same format and meaning as get's.

   See also: get.


var(expr) variables, function

   Returns the name of the variable whose id expr evaluates to. If the variable does not exist for any reason, the empty string "" is returned.


video_config() OS, function

   Returns video parameters as an array(8) of integer:


wait_key() I/O, function

   Waits for a key to be pressed, and returns the code of that key.

   Usage notes:

   wait_key() is equivalent to getc(0), except that the latter returns physical codes, while wait_key handles special codes for arrows, grey keys etc.


walk_dir(path,filter_id,recurse) OS, function

   Scans path for files and subdirectories, passing each corresponding dir() entry to the routine with id filter_id. Returns 0 on success and a nonzero exit code on failure.

   Usage notes:

   Subdirectories will be inspected recursively if and only if recurse is True; it must be atomic anyway.

   The filter routine returns a boolean: True to stop, False to keep going.

   To enforce a specific order of inspection, you must modify the my_dir global integer in file.oe to be the routine_id of a modified dir function enforcing the desired options.

   See also: dir.


wfor loop

   A wfor loop is a block of code executed as long as its index is between the two bounding expressions in the following complete decription:

   wfor identifier=start value to end value [by increment] dogeneral-code end wfor

   Here, identifier is an atomic loop index variable whose initial value is start value. start value, end value and increment are computed before each new loop execution. If there is no by clause, a value of 1 is assumed for the increment.

   If start value-end value has the same sign as increment, the loop is exited without any (further) iteration taking place.

   Whenever execution reaches the end wfor statement, the current value of increment is added to the loop index variable. The new value is then compared to the current values of start value and end value, which must be atomic.

   If the loop index value is not between these two values, the loop is exited and execution resumes right after the end wfor. Otherwise, another iteration starts right after do using the new index value.

   The loop index variable is an ordinary variable, previously declared and whose value may be modified inside the wfor loop.


where(channel) I/O, function

   Returns the pointer for the I/O channel channel.


while loop loop

   Repeats a chunk of code until the condition cond is not met.

   A while loop has the general form:
while cond do .... end while
where cond is a condiional clause just like those in if or elsif statements.

   Usage notes:

   Contrary to the for and wfor loops, the while loop has no index variable. As for wfor loops, its cond is evaluated each time the while statement is executed.

   The end while statement transfers control to the while statement.
See part A, chapter 4 "Condition evaluation", for more details on what cond may be.

   Example:

   The "repeat ... until cond" construct of some languages is easily emulated using a while loop. Indeed,

repeat something until cond

is equivalent to the more verbose:

while 1 do

do_something
if not cond then exit
end if
end while

wildcard_file(pattern,subject) nonatoms, function

   pattern may contain any number of the the '?' (any single character) or '*' (any number of characters, including zero), at any position. If subject matches pattren, the function returns True, and False otherwise. The above means that there is a way to substitute all '?' and '*' in pattern so that it becomes subject. Matches are case sensitive on Linux/FreeBSD systems only.


wildcard_match(pattern,subject) nonatoms, function

   pattern may contain any number of the the '?' (any single character) or '*' (any number of characters, including zero), at any position. If subject matches pattren, the function rturns True, and False otherwise. The above means that there is a way to substitute all '?' and '*' in pattern so that it becomes subject. Matches are case sensitive always.


with identifier directive

   Specifies that a boolean governing the way the interpreter/compiler works is to be set.

   Usage notes:

   The closed list of keywords that can be used as argument to with or without appears in Appendix 2.


without identifier directive

   Specifies that a boolean governing the way the interpreter/compiler works is to be cleared.

   Usage notes:

    The closed list of keywords that can be used as argument to with or without iappears in Appendix 2.


wrap(bool) OS, procedure

   Controls whether long lines wrap (bool=True) or are truncated (bool=False).


xor logical

   Performs a bitwise XOR between its two operands. Each bit of the result is set if and only if matching bits of both operands are different. Otherwise it is cleared. Then returns False if the result is 0 (both operands are equal), and True otherwise. xor is provided for completeness, as it is synonym to !=.


xor_bits(expr1,expr2) logical, function

Performs a bitwise XOR between both operands. So xor_bits(x,y) = x ~~ y.




prev | next | contents