Contact: zeng  @  zegraph.com      Last update: 20 January 2010

ZeScript Standard Library

A calling convention documented as

.func(p1,...)

is intended to be called by a specific type of object. But for backward compatibility, it may be called in the same way as before , e.g., 

a = "123ABC";
b = a.substr(0, 3);
c = substr(a, 0, 3);

Many functions with array arguments require that the arrays contain only numbers and be indexed sequentially by integer e.g.,

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

Math functions and most operators also require that the arrays contain only numbers (integer or real).

Generic

Function Parameter Type Remark
assert(expr[,...]) any Checks the assert condition, throws exception if the predicate is false.
base64(ptr, n) user, integer Encodes n-bytes binary data pointed to by ptr to base64 string and returns the string. Use the function to pack binary data, e.g., image, in text for network data transformation.
base64(s) string Decodes base64 string and returns an array containing the pointer to binary data and the number of bytes. The binary pointer has an extra byte with zero value for easy converting to string.
bits2u(bits, src, m, dst, n) integer, user, integer, user, integer Unpacks bit-packed integer in src of m bytes to unsigned integer in dst of length n. The function requires m*8/bits >= n. It is common to pack large grid datasets in variable bits, e.g., ECMWF's data in GRIB format.
cal2jul(year, month, day,[hour, minute, second]) numbers Returns the Julian day number converted from the calendar date. The reference date is 1-Jan-1900.
jul2cal(jul) number Returns an array containing ["year"], ["month"], ["day"], ["hour"], ["minute"], and ["second"] converted from the Julian day number.
error(msg) string Displays the error message and then exits program.
exec(cmd[, wait]); string, boolean Executes a system command or a program and returns the exit status of the command or program. If wait=false, the function will return immediately. (wait=true by default)
eval(script[, trace]) string, boolean Evaluates script code in the string as if the code is loaded from a file. If trace= true, variables values will be displayed. It returns null to indicate no error or returns the error string.
load(fname[,...]) strings Loads dynamic link libraries (DLL).
func(name) string Returns a user object containing pointer to the named script function.
import(fname) string Imports script module dynamically.
integer(s) string/real/real Converts string or real to integer and returns a integer.
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. Use csv function to see what are in the array.
real(s) string/integer/real Converts string to real and returns returns a real.
revb(ptr, n, esize) user, integer, integer Reverses data bytes of the pointer. n is the number of data and esize is the datum size in byte. Use the function to deal with Big-endian/Little-endian problems.
sendmail(name,value[,name,value...]) strings Sends e-mail. Name/value pairs set mail parameters. Valid names include "server", "message", "html", "subject", "sender", "receptors", "ccs", "bccs", "return", "charset", and "files". Meanings of most names are obvious, The server is "localhost" by default; "message" and "html" are for setting text and html message body respectively; and "files" are for sending files as attachement. It returns null if successful; otherwise it returns an error message.
sleep(s) integer Sleeps for s milliseconds.
string(o) any Returns the string representative of the object.
trace()   Shows variable values and waits for user's interaction (press ENTER key to continue).

Array

Function Parameter Type Remark
array(size) integer Returns array with a hash table of the specified size. Use this function when an array is expected to hold a large number of items. The has table An array created with [..] is about the number of key-values in []; and it is not efficient to add large number of new items to such an array.
.clear()   Clears all key-value in the array.
.escape()   Returns a HTTP query string.
.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 input 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

size(s) string Returns the string length.
.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. The function is useful for XML applications.
.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 str 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 sub is not found.
.right(pos) integer Returns the right part of the string starting at the position.
.substr(start, n) integer, integer Returns the sub-string with n-number of characters from the start.
.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. Returns null if the string contains only spaces.
.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.

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.
call(f[,...]) user Calls the function with optional numbers of parameters. Use func(name) to get the pointer to the function.
getarg(n) number/string Returns the nth command line argument; Or if n is string, returns the value for the key that has been passed to ZeScript as key=value.
getenv(name) string Returns the named environmental variable as string or null.
setenv(name, value) string, string Sets environmental variable.
input(msg) string Displays the message, waits for user input, and return 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.
rmdir(dir) string Removes the 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 for files and sub-directories. The callback must be the name of a callback function, which get two parameters with the first being the path name and the second the file name.
tmpnam()   Returns a temporal file name.

Input/Output

open(fname, mode) string, 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()   To be called by a file handle. Returns true if the current position of file pointer is at the end-of-file; returns false otherwise.
.flush()   To be called by a file handle to flush output buffer of the file handle that is opened for text output.
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) results in "09", format("%5.2f", 1.99999) in "2.00", and format("%d-%02d-%02d %02d:%02d", 2000, 1, 1, 12, 30) results in 2000-01-01 12:00.
ftime(fname[, utc]) string, boolean Returns the file timestamp as array. Set utc=true to get the timestamp as Universal Time Coordinate.
.read()   To be called by a file handle to read a lines from the file and return a string. The length of a line in the file should be less then 8192.
.read(ptr, nbyte) user, integer To be called by a file handle to read nbyte of binary data from the file to the memory pointed to by ptr. Returns the actual bytes read.
.read(type) string To be called by a file handle to read a binary number. The type parameter may be "char", "uchar", "short", "ushort", "int", "uint", "int64", "float", or "double".
.write(obj) any To be called by a file handle to write the string form of obj to the file.
.write(ptr, nbyte) user, integer To be called by a file handle to write to the file n-bytes of binary data pointed to by ptr.
.write(num, type) number, string To be called by a file handle to write a binary number to a 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 To be called by a file handle to move the file pointer by the offset according to the flag: "set" means offset from the start, "end" means from the end, and "cur" means from the current position.
.seek(str[, limit]) string, integer To be called by a file handle to find the string in the file handler and returns the file pointer position at the end of the string if successful; otherwise returns 0. As an example, your may use seek(f, "GRIB") to find the start of the next record in a GRIB format file. The optional parameter may be used to limit the number of bytes to search.
.tell()   To be called by a file handle and returns the current position of the file 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) array, integer, real Returns real of cos(v). If the operand is array, operation is element-wise and the array must be indexed sequentially by integer and contain only numbers.
cosh(v) array, integer, real Returns real of cosh(v). See cos(v) requirement for array.
acos(v) array, integer, real Returns real of acos(v). See cos(v) requirement for array.
sin(v) array, integer, real Returns real of sin(v). See cos(v) requirement for array.
sinh(v) array, integer, real Returns real of sinh(v). See cos(v) requirement for array.
asin(v) array, integer, real Returns real of asin(v). See cos(v) requirement for array.
tan(v) array, integer, real Returns real of tan(v). See cos(v) requirement for array.
tanh(v) array, integer, real Returns real of tanh(v). See cos(v) requirement for array.
atan(v) array, integer, real Returns real of atan(v). See cos(v) requirement for array.
atan2(v1, v2) array, integer, real Returns real of atan2(v1, v2). See cos(v) requirement for array.
sqrt(v) array, integer, real Returns real of sqrt(v). (no check for v < 0) See cos(v) requirement for array.
exp(v) array, integer, real Returns real of exp(v). See cos(v) requirement for array.
log(v) array, integer, real Returns real of log(v). (no check for v <= 0) See cos(v) requirement for array.
log10(v) array, integer, real Returns real of log10(v). (no check for v <= 0) See cos(v) requirement for array.
ceil(v) array, integer, real Returns real of ceil(v). See cos(v) requirement for array.
floor(v) array, integer, real Returns real of floor(v). See cos(v) requirement for array.
abs(v) array, integer, real Returns real of abs(v). See cos(v) requirement for array.
pow(a, b) array, integer, real Returns real of pow(a, b). See cos(v) requirement for array.
pi()   Returns constant of pi.

Thread

Function Parameter Type Remark
thread()   Returns thread object.
.start(name[, p1, p2, ...]) string, any Starts execution of the script function of the given named with optional parameters.
.suspend()   Sets the thread state to suspend.
.resume()   Sets the thread state to normal.

Mutex

Function Parameter Type Remark
mutex()   Returns a mutex object.
.lock()   Mutex lock.
.unlock()   Mutex unlock.

OS

fullscreen()   Resize the window created by the window() function to full screen.
hide()   Hides the console window.
message(text); string Shows the text in a Windows message box.
millisec() none Returns ticking count of the computer in milli-seconds.
resize(width, height) integers Resize the window created by the window() function.
sendkey(key[,hwnd]) string, user Sends a key-stroke to the foreground window. A key should be a single character or one of these key-names: "Shift", "Ctrl", "Alt" ,"Esc", "Back", "Tab", "Enter", "Space", "PgUp", "PgDn", "End", "Home", "Insert", "delete", "Left", "Up", "Right", "Down", "PrScr", "Scroll", "Pause", "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12", "Num", and "Caps". If not one of those, characters in the key string will be send to the window one by one. If the optional variable containing handle to a window is given, the window will be set as the foreground window to get the key stroke.
shellexec(flag, prog[, arg]); boolean, string, string Use the shell execution of Windows to run a program with optional argument and return the process handle of the application. If flag=true, the application window will be shown; otherwise, hidden.
tmpdir()   Returns the temporal path of OS as string.
terminate(handle) user Brutally terminates the process created by shellexec() function.
timer(ms) integer Starts (ms > 0) or stops (ms = 0) of the window created by the window() function. The window's callback function will receive the "TIMER" message in every ms milliseconds.
title(text); string Set the title bar text of the window created by window() function.
window(width, height, callback[, title]) integer, integer, string, string Creates window of given width and height. The callback function should handle events of the window, which will call the function with eight arguments: (1) window's handle (raw pointer), window message (string corresponding to message ID, i.e., "CREATE", "COMMAND", "SIZE", "PAINT", "KEYUP", "KEYDOW", "LBUTTONUP", "LBUTTONDOWN", "LBUTTONDBLCLK", "MOUSEMOVE", "RBUTTONUP", "RBUTTONDOWN", "RBUTTONDBLCLK", "SETCURSOR", and "TIMER" ), message WPARAM (integer), the low-word of WPARAM (integer), the high-word of WPARAM (integer), message LPARAM (integer), the low-word of LPARAM (integer), and the high-word of LPARAM (integer).
window();   Finds all visible windows and display their registered name and title-bar text.
window(name); string Finds the window with the specified registration name and returns the handle. If failed, finds the window whose title bar text includes the name.

Operator Precedence

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

Unary Operators

Operator Left Operand Right Operand Remark
::   any Access global variable.
new   Class name Returns a new object of the 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 !-operator requirement for array.
++ array, number   Increase the number by 1. See !-operator requirement for array.
-- array, number   Decrease the number by 1. See !-operator requirement for array.

Binary Operators

Operator Left Operand Right Operand Remark
+, -, *, /, % array, number array, number Returns a real if one of them is real; otherwise returns a integer. If the operand is array, the array must be a pure 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. For user object, if its operator function is not set, companion is strict pointer comparison.
!= 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. A valid class or user object always means true.
: 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.