Contact: zeng  @  zegraph.com      Last update: 10 May 2011

ZeScript Standard Library

A calling convention documented as

.func(p1,...)

means to call func by a specific type of object, e.g., 

a = "123ABC";
b = a.find("AB", 0);     // returns 5

Math functions and most operators require that an array argument contains only numbers that are indexed sequentially by integer e.g.,

a = [1, 2, 3.5, 4.2, 5];
b = sin(a);

Generic

Function Parameter Type Remark
assert(expr[,...]) any Checks the assert condition, throws exception if the predicate is false.
getarg(n) number/string Returns the nth command line argument if n is an integer. If n is string, returns the value for the key that has been passed to ZeScript as a key=value option.
getenv(name) string Returns the named environmental variable as string or null if there is no such a named environmental variable.
error(msg) string Displays the error message and exits program.
exec(cmd) string Executes a system command and returns the exit status of the command.
load(fname[,...]) strings Loads dynamic link libraries (DLL).
malloc(n) integer Returns a pointer to n bytes of memory.
now([utc]) boolean Returns the current time as an array. Set utc=true to get the time as Universal Time Coordinate.
sleep(ms) integer Sleeps for ms milliseconds.

Array

Function Parameter Type Remark
array(size) integer Returns array with a hash table of the specified size.
.clear()   Clears all key-values in the array.
.escale()   Returns a URL encoding string including all key=value pairs in the array.
.find(key) string/integer Returns true if the array has the key; returns false otherwise.
.foreach(name) string Calls the named script function with two parameters: key and value in the array.
.keys()   Returns a new array containing keys of the array.
.remove(key[,...]) integer/string Removes the values with the keys from the array.
.size()   Returns the number of key-values in the array.

String

.escale()   Returns a URL encoding string .
.find(substr, start) string, integer Returns the position of the sub-string. If start < 0, finds the last substring. Position counts from zero.
.left(pos) integer Returns the left part of the string starting at the position.
.mbs2utf() string Returns a UTF-8 string converted from the multibyte string.
.utf2mbs() string Returns a multibyte string converted from the UTF-8 string.
.numstr(s) string Returns true if the string contains only numbers, e.g. 12, 3.0, 0.1e-23.
.regex(pattern[, func]) strings Regular expression using Sswater Shi's library. If the optional callback function name is given, the function will be called for each matched case with a string as the first parameter, the start match position as the second, and the end match position as the third; otherwise, regex returns matched strings in an array.
.replace(substr, rpl) string, string Returns a copy of the caller with substring substr replaced by rpl. Returns the caller if substr is not found.
.right(pos) integer Returns the right part of the string starting at the position.
.size() string Returns the string length.
.tolower()   Converts the string to lower case and returns a string.
.toupper()   Converts the string to upper case and returns a string.
.trim()   Removes leading and trailing spaces and returns a string.
.tokenize([del, trim]) string, boolean Breaks the string into an array of tokens. The delimiter is assumed to be space characters if del is not specified. The optional trim parameter may be used to remove space characters on both sides of a token string (true by default).

Standard Input/Output

csv(a, b, ...) any Displays the string representations of objects with comma between them and a new-line character at the end.
curdir([dir]) string Returns the current directory as string or set the working directory to dir if the optional parameter is set.
input(msg) string Displays the content of msg, waits for user input, and returns the input as string. Your may use the function to write a simple user interface, e.g., year=integer(input("Year: ")); if (year > 2000) {...}; ...
isfile(fname) string Returns true if the named file exists or false otherwise.
isdir(dir) string Returns true if dir is a directory or false otherwise.
mkdir(dir) string Makes a new directory.
print(a, b, ...) any The same as csv() but without the comma and new-line character.
scandir(callback, dir) string, string Scans the directory dir and its sub-directories for files. The callback parameter must be the name of a callback function, which gets two parameters with the first being the path name and the second the file name.
tmpnam()   Returns a temporal file name.

File Input/Output

open(fname, mode) string, boolean Opens the file and returns the handle as user object or null if failed. If fname is "stdout", "stderr", or "stdin", the file handle will be assigned to one of those standard C file handles and the mode argument has no effect. The most frequently used modes include "r", "w", and "a" for reading, writing, and appending text respectively; and "rb" and "wb" for binary reading and writing.
.eof()   Returns true if the current position of file handle is at the end-of-file; returns false otherwise.
.flush()   Flushes the output buffer of the file handle that is opened for output.
ftime(fname[, utc]) string, boolean Returns the file timestamp as array. Set utc=true to get the timestamp as Universal Time Coordinate.
.read()   Reads a line of string and returns it. The length of a line in the file should be less then 8192.
.read(ptr, n) user, integer Reads n bytes of binary data from the file to the memory pointed to by ptr. Returns the actual bytes read.
.read(type) string Reads a binary number. The type parameter may be "char", "uchar", "short", "ushort", "int", "uint", "int64", "float", or "double".
.write(obj) any Writes the string form of obj to the file.
.write(ptr, n) user, integer Writes n bytes of binary data pointed to by ptr to the file.
.write(num, type) number, string Writes a binary number to the file. The number will be converted to integer or real according to the type parameter, which may be "char", "uchar", "short", "ushort", "int", "uint", "int64", "float", or "double".
.seek(offset, flag) integer, string Moves the file handle by the offset according to the flag, by which "set" means offset from the start, "end" means from the end, and "cur" means from the current position.
.seek(str[, limit]) string, integer Finds the string in the file and returns the position at the end of the string if successful; otherwise returns 0.
.tell()   Returns the current position of the file handle as integer.

Type Checking

isnull(obj) any Checks if the object is null and returns true or false.
isinteger(obj) any Checks if the object is integer and returns true or false.
isreal(obj) any Checks if the object is real and returns true or false.
isnumber(obj) any Checks if the object is integer or real, and returns true or false.
isstring(obj) any Checks if the object is string and returns true or false.
isarray(obj) any Checks if the object is array and returns true or false.
isuser(obj) any Checks if the object is user type and returns true or false.
isclass(obj) any Checks if the object is class type and returns true or false.

Math

cos(v) user, array, integer, real Returns real of cos(v) if v is a number. If v is an array, applies the function element-wise and the array must be indexed sequentially by integer and contain only numbers. If v is a user object, cos must be registered for that type of user object.
cosh(v) user, array, integer, real Returns real of cosh(v) if v is a number. See cos(v) requirement for array or user object.
acos(v) user, array, integer, real Returns real of acos(v) if v is a number. See cos(v) requirement for array or user object.
sin(v) user, array, integer, real Returns real of sin(v) if v is a number. See cos(v) requirement for array or user object.
sinh(v) user, array, integer, real Returns real of sinh(v) if v is a number. See cos(v) requirement for array or user object.
asin(v) user, array, integer, real Returns real of asin(v) if v is a number. See cos(v) requirement for array or user object.
tan(v) user, array, integer, real Returns real of tan(v) if v is a number. See cos(v) requirement for array or user object.
tanh(v) user, array, integer, real Returns real of tanh(v) if v is a number. See cos(v) requirement for array or user object.
atan(v) user, array, integer, real Returns real of atan(v) if v is a number. See cos(v) requirement for array or user object.
atan2(a, b) user, array, integer, real Returns real of atan2(v1, v2) if a and b are numbers. See cos(v) requirement for array or user object.
sqrt(v) user, array, integer, real Returns real of sqrt(v) if v is a number. (no check for v < 0) See cos(v) requirement for array or user object.
exp(v) user, array, integer, real Returns real of exp(v) if v is a number. See cos(v) requirement for array or user object.
log(v) user, array, integer, real Returns real of log(v) if v is a number. (no check for v <= 0) See cos(v) requirement for array or user object.
log10(v) user, array, integer, real Returns real of log10(v) if v is a number. (no check for v <= 0) See cos(v) requirement for array or user object.
ceil(v) user, array, integer, real Returns real of ceil(v) if v is a number. See cos(v) requirement for array or user object.
floor(v) user, array, integer, real Returns real of floor(v) if v is a number. See cos(v) requirement for array or user object.
abs(v) user, array, integer, real Returns real of abs(v) if v is a number. See cos(v) requirement for array or user object.
pow(a, b) user, array, integer, real Returns real of pow(a, b) if a and b are numbers. See cos(v) requirement for array or user object.
pi()   Returns constant of pi.

Convertion

base64(ptr, n) user, integer Encodes n bytes in ptr to string.
base64(str) string Decodes a base64 string. Returns an array containg a pointer and the number of bytes in the pointer.
cal2jul(year, month, day,[hour, minute, second]) numbers Converts Gregorian date to Julian day number and returns the number, of which 1 refers to 1-Jan-1900.
jul2cal(jul) number Converts Julian day number to Gregorian date and returns an array.
format(fmt, item[,...]) string, number or string Returns a string of formatted items. The fmt parameter is a C-format string. For example, format( "%02d", 9) gives "09", format("%5.2f", 1.99999) gives "2.00", and format("%d-%02d-%02d %02d:%02d", 2000, 1, 1, 12, 30) gives 2000-01-01 12:00.
integer(s) string/real/real Converts string or real to integer and returns a integer.
real(s) string/integer/real Converts string or integer to real and returns returns a real.
string(o) any Returns the string representative of the object.
revb(ptr, n, e) user, integer, integer Reverses bytes oder of the pointer. n is the number of data and e is the datum size in byte. Use the function to convert real or integer from Big-endian to Little-endian and vice versa.

Operator Precedence

Precedence Operators
0 ::   .
1 ++   --   !   ~   unary-
2 *   /   %
3 -   +
4 >>   <<
5 <   <=   >   >=
6 ==   !=
7 ^   &   |
8 &&   ||   :
9 =   -=   +=   *=   /=   %=   |=   &=   ^=   <<=   >>=

Unary Operators

Operator Left Operand Right Operand Remark
::   Variable name Sets or gets a global variable.
new   Class name Returns a new object of a class.
!   array, number Returns 1 if the number is 0; otherwise returns 0. If the operand is array, operation is element-wise and the array must be indexed sequentially by integer and contain only numbers.
-   array, number Returns the negative of the original. See the "!" operator requirement for array.
++ array, number   Increase the number by 1. See the "!" operator requirement for array.
-- array, number   Decrease the number by 1. See the "!" operator requirement for array.

Binary Operators

Operator Left Operand Right Operand Remark
+   -   *   /   % array, number array, number Returns a real, an integer, or an array of numbers. If the operand is array, the array must be an integer indexed array containing only numbers.
+ string any Appends the right to the left and returns a new string.
>> integer integer Bit shift of the left to the right by the right value.
<< integer integer Bit shift of the left to the left by the right value.
| integer integer Returns the bitwise-or of the two operands.
& integer integer Returns the bitwise-and of the two operands
^ integer integer Returns the bitwise-xor of the two operands.
+=   -=   *=   /=   %= array, number array, number The efficient version of +, -, *, /, and %.
<<=   >>=   |=   &=   ^= integer integer The efficient version of <<, >>, |, & and ^.
== any any Equal comparison. For numbers, returns 1 if the numbers are equal; otherwise returns 0. For string, comparison is character by character; and a zero-length string is treated as null. For array, comparison is element-wise.
!= any any Refer to ==
>   >=   <   <= array, number, string array, number, string Refer to ==
&&   || any any Logical and/or operation. For number, non-zero is true; otherwise is false. For string and array, zero-length means false; otherwise means true. The null is false.
: any any Returns an array when used independently and specifies a range when used for getting/setting string, array, or user object.
= variable name any Assign the right to the left.

Access Operators

Operator Remark
caller.key
  1. For caller type of array, sets or gets array value of the key;
  2. For caller type of class, sets or gets class variable;
  3. For caller type of user object, calls __get or __set primitive functions defined for that type with the first argument being the caller, the second argument being the key as string, and for the __set function, the third argument is the object to be assigned to the caller.
caller[key...]
  1. For caller type of array, sets or gets array values of the keys;
  2. For caller type of string, sets or gets string characters;
  3. For caller type of user object, calls __get or __set primitive functions defined for that type with the first argument being the caller, the second argument being the first key and so on; and for the __set function, the last argument is the object to be assigned to the caller.
caller.func(...) Calls primitive function registered for the caller object or calls script function defined for a class.