This reference documents version 2.2.0 of the MPSL Function Library.
adel - Deletes an element of an array.
v = adel(a, offset);
Deletes the element at offset of the a array. The array is shrinked by one. If offset is negative, is counted from the end of the array (so a value of -1 means delete the last element of the array).
Returns NULL (previous versions returned the deleted element).
chdir - Changes the working directory
integer = chdir(dir);
Changes the working directory
chmod - Changes a file's permissions.
integer = chmod(filename, perms);
Changes the permissions for a file.
chown - Changes a file's owner.
integer = chown(filename, uid, gid);
Changes the owner and group id's for a file.
chr - Returns the Unicode character represented by the codepoint.
string = chr(c);
Returns a 1 character string containing the character which Unicode codepoint is c.
clone - Creates a clone of a value.
v2 = clone(v);
Creates a clone of a value. If the value is multiple, a new value will be created containing clones of all its elements; otherwise, the same unchanged value is returned.
close - Closes a file descriptor.
Closes the file descriptor.
cmp - Compares two values.
integer = cmp(v);
Compares two values. If both are strings, a standard string
wcscmp()) is returned; if both are arrays,
the size is compared first and, if they have the same number
elements, each one is compared; otherwise, a simple pointer
comparison is done.
In either case, an integer is returned, which is < 0 if v1 is lesser than v2, > 0 on the contrary or 0 if both are equal.
collapse - Collapses an array.
collapse(a, offset, num);
Collapses an array value, deleting num elements at the specified offset.
compile - Compiles a string of MSPL source code file.
func = compile(source);
Compiles a string of MPSL source code and returns an executable value.
connect - Opens a client TCP/IP socket.
f = connect(h, s);
Opens a client TCP/IP socket to the h host at s service (or port).
Returns NULL if the connection cannot be done or a file type value,
that can be used with all file operation functions, including
dump - Dumps a value to stdin.
Dumps a value to stdin. The value can be complex. This function is for debugging purposes only.
dumper - Returns a visual representation of a complex value.
string = dumper(v);
Returns a visual representation of a complex value.
encoding - Sets the current charset encoding for files.
integer = encoding(charset);
Sets the current charset encoding for files. Future opened files will be assumed to be encoded with charset, which can be any of the supported charset names (utf-8, iso-8859-1, etc.), and converted on each read / write. If charset is NULL, it is reverted to default charset conversion (i.e. the one defined in the locale).
This function stores the charset value into the
Returns a negative number if charset is unsupported, or zero if no errors were found.
error - Simulates an error.
Simulates an error. The err error message is stored in the
global variable and an internal abort global flag is set, so no further
MPSL code can be executed until reset.
eval - Evaluates MSPL code.
v = eval(code, args);
Evaluates a piece of code. The code can be a string containing MPSL
source code (that will be compiled) or a direct executable value. If
the compilation or the execution gives an error, the
will be set to a printable value and NULL returned. Otherwise, the
exit value from the code is returned and
ERROR set to NULL. The
internal abort flag is reset on exit.
exists - Tests if a key exists.
bool = exists(h, k);
Returns 1 if k is defined in h, or 0 othersize.
expand - Expands an array.
expand(a, offset, num);
Expands an array value, inserting num elements (initialized to NULL) at the specified offset.
fseek - Sets a file pointer.
integer = fseek(fd, offset, whence);
Sets the file pointer position of fd to offset. whence can be: 0 for SEEK_SET, 1 for SEEK_CUR and 2 for SEEK_END.
Returns the value from the
fseek() C function call.
ftell - Returns the current file pointer.
integer = ftell(fd);
Returns the position of the file pointer in fd.
getchar - Reads a character from a file descriptor.
string = getchar(fd);
Returns a character read from fd, or NULL on EOF. No charset conversion is done.
gettext - Translates a string to the current language.
string = gettext(str);
Translates the str string to the current language.
This function can still be used even if there is no real gettext support by manually filling the I18N hash.
If the string is found in the current table, the translation is returned; otherwise, the same str value is returned.
gettext_domain - Sets domain and data directory for translations.
bool = gettext_domain(dom, data);
Sets the domain (application name) and translation data for translating
strings that will be returned by
gettext(). data must point to a
directory containing the .mo (compiled .po) files.
If there is no gettext support, returns 0, or 1 otherwise.
glob - Executes a file globbing.
array = glob(spec, base);
Executes a file globbing. spec is system-dependent, but usually
the * and ? metacharacters work everywhere. base can contain a
directory; if that's the case, the output strings will include it.
In any case, each returned value will be suitable for a call to
Returns an array of files that match the globbing (can be an empty array if no file matches), or NULL if globbing is unsupported. Directories are returned first and their names end with a slash.
grep - Greps inside a multiple value.
array = grep(filter, a);
Greps inside a multiple value and returns another one containing only the elements that passed the filter. If filter is a string, it's accepted as a regular expression, which will be applied to each element or hash key. If filter is executable, it will be called with the element as its only argument if a is an array or with two if a is a hash, and its return value used as validation.
The new value will have the same type as a and will contain all elements that passed the filter.
hdel - Deletes a key from a hash.
v = hdel(h, k);
Deletes the key k from the hash h. Returns the previous value, or NULL if the key was not defined.
hmap - Maps a multiple value to a hash.
hash = hmap(a, filter);
Returns a new hash built by applying the filter to all the elements of the a multiple value. The filter can be an executable function accepting one argument if a is an array and two if a is a hash, in which case the return value of the function is expected to be a two element array, with the 0th element to be the key and the 1st element the value for the new pair in the output hash.
hsize - Returns the number of pairs of a hash.
integer = hsize(h);
Returns the number of key-value pairs of a hash.
ins - Insert an element in an array.
e = ins(a, e, offset);
Inserts the e value in the a array at offset. Further elements are pushed up, so the array increases its size by one. Returns the inserted element.
is_array - Tests if a value is an array.
bool = is_array(v);
Returns non-zero if v is an array.
is_exec - Tests if a value is executable.
bool = is_exec(v);
Returns non-zero if v is a executable.
is_hash - Tests if a value is a hash.
bool = is_hash(v);
Returns non-zero if v is a hash.
join - Joins an array.
string = join(a, joiner_str); array = join(a1, a2);
If s is a string or NULL, returns a new string with all elements in a joined using s. If s is an array, it returns a new one containing all elements of a followed by all elements of s.
keys - Returns the keys of a hash.
array = keys(h);
Returns an array containing all the keys of the h hash.
lc - Converts a string to lowercase.
string = uc(str);
Returns str converted to lowercase.
load - Loads an MPSL source code file.
Loads and executes an MPSL source code file and returns its value.
map - Maps a multiple value to an array.
array = map(a, filter);
Returns a new array built by applying the filter to all the elements of the a multiple value. The filter can be an executable function accepting one argument if a is an array and two if a is a hash, in which case the return value of the function will be used as the output element; filter can also be a hash, in which case each array element or hash key will be used as a key to the hash and the associated value used as the output element.
mutex - Returns a new mutex.
var = mutex();
Returns a new mutex.
mutex_lock - Locks a mutex (possibly waiting).
Locks a mutex. If the mutex is already locked by another process, it waits until it's unlocked.
mutex_unlock - Unlocks a mutex.
Unlocks a mutex.
new - Creates a new object using another as its base.
o = new(c1 [, c2, ...cn]);
Creates a new object using as classes or base objects all the ones sent as arguments (assumed to be hashes).
open - Opens a file.
fd = open(filename, mode);
Opens a file. If filename can be open in the specified mode, a value will be returned containing the file descriptor, or NULL otherwise.
If the file is open for reading, some charset detection methods are
used. If any of them is successful, its name is stored in the
DETECTED_ENCODING global variable. This value is
suitable to be copied over
If the file is open for writing, the encoding to be used is read from
ENCODING global variable and, if not set, from the
TEMP_ENCODING one. The latter will always be deleted afterwards.
ord - Returns the Unicode codepoint of a character.
integer = ord(str);
Returns the Unicode codepoint for the first character in the string.
pclose - Closes a pipe.
Closes a pipe.
pop - Pops a value from an array.
v = pop(a);
Pops a value from the array (i.e. deletes from the end and returns it).
popen - Opens a pipe.
fd = popen(prg, mode);
Opens a pipe to a program. If prg can be open in the specified mode, return file descriptor, or NULL otherwise.
The mode can be
r (for reading),
w (for writing), or
for a special double pipe reading-writing mode.
popen2 - Opens a pipe and returns an array of two pipes.
array = popen2(prg);
Opens a read-write pipe and returns an array of two descriptors, one for reading and one for writing. If prg could not be piped to, returns NULL.
print - Writes values to stdout.
print(arg1 [,arg2 ... argn]);
Writes the variable arguments to stdout.
push - Pushes a value into an array.
argn = push(a, arg1 [, arg2, ... argn]);
Pushes values into an array (i.e. inserts at the end). Returns the last element pushed.
putchar - Writes a character to a file descriptor.
s = putchar(fd, s);
Writes the first character in s into fd. No charset conversion is done.
Returns the number of chars written (0 or 1).
queue - Implements a queue in an array.
v = queue(a, e, size);
Pushes the e element into the a array. If the array already has size elements, the first (oldest) element is deleted from the queue and returned.
Returns the deleted element, or NULL if the array doesn't have size elements yet.
random - Returns a random value.
integer = random(value);
Returns a random number from 0 to value - 1.
read - Reads a line from a file descriptor.
string = read(fd);
Reads a line from fd. Returns the line, or NULL on EOF.
regex - Matches a regular expression.
string = regex(v, r); string = regex(v, r, offset); array = regex(v, ra); array = regex();
Matches a regular expression against a value. Valid flags are
for case-insensitive matching,
m, to treat the string as a
multiline string (i.e., one containing newline characters), so
that ^ and $ match the boundaries of each line instead of the
l, to return the last matching instead of the
first one, or
g, to match globally; in that last case, an array
containing all matches is returned instead of a string scalar.
If r is a string, an ordinary regular expression matching is tried over the v string. If the matching is possible, the match result is returned, or NULL otherwise.
If r is an array (of strings), each element is tried sequentially as an individual regular expression over the v string, each one using the offset returned by the previous match. All regular expressions must match to be successful. If this is the case, an array (with the same number of arguments) is returned containing the matched strings, or NULL otherwise.
If r is NULL, the result of the previous regex matching is returned as a two element array. The first element will contain the character offset of the matching and the second the number of characters matched. If the previous regex was unsuccessful, NULL is returned.
seek - Seeks a value in an array (sequential).
integer = seek(a, k, step);
Seeks sequentially the value k in the a array in increments of step. A complete search should use a step of 1. Returns the offset of the element if found, or -1 otherwise.
semaphore - Returns a new semaphore.
var = semaphore(cnt);
Returns a new semaphore.
semaphore_post - Increments the value of a semaphore.
Increments by 1 the value of a semaphore.
semaphore_wait - Waits for a semaphore to be ready.
Waits for the value of a semaphore to be > 0. If it's not, the thread waits until it is.
shift - Extracts the first element of an array.
v = shift(a);
Extracts the first element of the array. The array is shrinked by one.
Returns the deleted element.
size - Returns the size of a value.
integer = size(v);
Returns the size of a value. For scalars, the size is the
string length; for arrays, the number of elements, and
for hashes, the number of buckets in the hash (which is
probably not useful, see
sleep - Sleeps a number of milliseconds.
Sleeps a number of milliseconds.
sort - Sorts an array.
array = sort(a); array = sort(a, sorting_func);
Sorts the array. For each pair of elements being sorted, the sorting_func is called with the two elements to be sorted as arguments. This function must return a signed integer value indicating the sorting order.
If no function is supplied, the sorting is done using
Returns the sorted array (the original one is left untouched).
splice - Creates a new string value from another.
array = splice(v, i, offset, del);
Creates a new string value from v, deleting del chars at offset and substituting them by i. If del is 0, no deletion is done. both offset and del can be negative; if this is the case, it's assumed as counting from the end of v. If v is NULL, i will become the new string, and both offset and del will be ignored. If v is not NULL and i is, no insertion process is done (only deletion, if applicable).
Returns a two element array, with the new string in the first element and the deleted string in the second (with a NULL value if del is 0).
split - Separates a string into an array of pieces.
array = split(v, s);
Separates the v string value into an array of pieces, using s as a separator.
If the separator is NULL, the string is splitted by characters.
If the string does not contain the separator, an array holding the complete string as its unique argument is returned.
sprintf - Formats a
string = sprintf(fmt, arg1 [,arg2 ... argn]);
Formats a string using the
sprintf() format taking the values from
the variable arguments.
sregex - Matches and substitutes a regular expression.
string = sregex(v, r, s); string = sregex(v, r, s, offset); integer = sregex();
Matches a regular expression against a value, and substitutes the
found substring with s. Valid flags are
i, for case-insensitive
g, for global replacements (all ocurrences in v
will be replaced, instead of just the first found one).
If s is executable, it's executed with the matched part as the only argument and its return value is used as the substitution string.
If s is a hash, the matched string is used as a key to it and its value used as the substitution. If this value itself is executable, it's executed with the matched string as its only argument and its return value used as the substitution.
If r is NULL, returns the number of substitutions made in the
previous call to
sregex() (can be zero if none was done).
Returns the modified string, or the original one if no substitutions were done.
sscanf - Extracts data like
array = sscanf(str, fmt); array = sscanf(str, fmt, offset);
Extracts data from a string using a special format pattern, very
much like the
scanf() series of functions in the C library. Apart
from the standard percent-sign-commands (s, u, d, i, f, x,
n, [, with optional size and * to ignore), it implements S,
to match a string of characters upto what follows in the format
string. Also, the [ set of characters can include other % formats.
Returns an array with the extracted values. If n is used, the position in the scanned string is returned as the value.
stat - Gives status from a file.
array = stat(filename);
Returns a 14 element array of the status (permissions, onwer, etc.) from the desired filename, or NULL if the file cannot be accessed. (man 2 stat).
The values are: 0, device number of filesystem; 1, inode number; 2, file mode; 3, number of hard links to the file; 4, uid; 5, gid; 6, device identifier; 7, total size of file in bytes; 8, atime; 9, mtime; 10, ctime; 11, preferred block size for system I/O; 12, number of blocks allocated and 13, canonicalized file name. Not all elements have necesarily meaningful values, as most are system-dependent.
strftime - Formats the time as a string.
string = strftime(f); string = strftime(f, t);
Returns as a string, formatted using the f format string,
the time t given as argument (or now if t is not given).
See the local clib
strftime() implementation for details
on the format string.
time - Returns the current time.
integer = time();
Returns the current time from the epoch (C library
tr - Transliterates a string.
tr(str, from, to);
Transliterates str to a new string with all characters from from replaced by those in to.
uc - Converts a string to uppercase.
string = uc(str);
Returns str converted to uppercase.
unlink - Deletes a file.
bool = unlink(filename);
Deletes a file.
write - Writes values to a file descriptor.
integer = write(fd, arg1 [,arg2 ... argn]);
Writes the variable arguments to the file descriptor, doing charset conversion in the process.
Returns the total size written to fd.