Un naufragio personal: MPSL Function Library Reference

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

Name

chdir - Changes the working directory

Synopsis

integer = chdir(dir);

Arguments

dir: the new path

Description

Changes the working directory

chmod

Name

chmod - Changes a file's permissions.

Synopsis

integer = chmod(filename, perms);

Arguments

filename: the file name
perms: permissions (element 2 from stat())

Description

Changes the permissions for a file.

chown

Name

chown - Changes a file's owner.

Synopsis

integer = chown(filename, uid, gid);

Arguments

filename: the file name
uid: user id (element 4 from stat())
gid: group id (element 5 from stat())

Description

Changes the owner and group id's for a file.

chr

Name

chr - Returns the Unicode character represented by the codepoint.

Synopsis

string = chr(c);

Arguments

c: the codepoint as an integer value

Description

Returns a 1 character string containing the character which Unicode codepoint is c.

clone

Name

clone - Creates a clone of a value.

Synopsis

v2 = clone(v);

Arguments

v: the value

Description

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

Name

close - Closes a file descriptor.

Synopsis

close(fd);

Arguments

fd: the file descriptor

Description

Closes the file descriptor.

cmp

Name

cmp - Compares two values.

Synopsis

integer = cmp(v);

Arguments

v1: the first value
v2: the second value

Description

Compares two values. If both are strings, a standard string comparison (using 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

Name

collapse - Collapses an array.

Synopsis

collapse(a, offset, num);

Arguments

a: the array
offset: deletion offset
num: number of elements to collapse

Description

Collapses an array value, deleting num elements at the specified offset.

compile

Name

compile - Compiles a string of MSPL source code file.

Synopsis

func = compile(source);

Arguments

source: the source code string

Description

Compiles a string of MPSL source code and returns an executable value.

connect

Name

connect - Opens a client TCP/IP socket.

Synopsis

f = connect(h, s);

Arguments

h: host name or ip
s: service or port number

Description

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 close().

dump

Name

dump - Dumps a value to stdin.

Synopsis

dump(v);

Arguments

v: The value

Description

Dumps a value to stdin. The value can be complex. This function is for debugging purposes only.

dumper

Name

dumper - Returns a visual representation of a complex value.

Synopsis

string = dumper(v);

Arguments

v: The value

Description

Returns a visual representation of a complex value.

encoding

Name

encoding - Sets the current charset encoding for files.

Synopsis

integer = encoding(charset);

Arguments

charset: the charset name.

Description

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 ENCODING global variable.

Returns a negative number if charset is unsupported, or zero if no errors were found.

error

Name

error - Simulates an error.

Synopsis

error(err);

Arguments

err: the error message

Description

Simulates an error. The err error message is stored in the ERROR global variable and an internal abort global flag is set, so no further MPSL code can be executed until reset.

eval

Name

eval - Evaluates MSPL code.

Synopsis

v = eval(code, args);

Arguments

code: A value containing a string of MPSL code, or executable code
args: optional arguments for @code

Description

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 ERROR variable 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

Name

exists - Tests if a key exists.

Synopsis

bool = exists(h, k);

Arguments

h: the hash
k: the key

Description

Returns 1 if k is defined in h, or 0 othersize.

expand

Name

expand - Expands an array.

Synopsis

expand(a, offset, num);

Arguments

a: the array
offset: insertion offset
num: number of elements to insert

Description

Expands an array value, inserting num elements (initialized to NULL) at the specified offset.

fseek

Name

fseek - Sets a file pointer.

Synopsis

integer = fseek(fd, offset, whence);

Arguments

fd: the file descriptor
offset: the offset
whence: the position

Description

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

Name

ftell - Returns the current file pointer.

Synopsis

integer = ftell(fd);

Arguments

fd: the file descriptor

Description

Returns the position of the file pointer in fd.

getchar

Name

getchar - Reads a character from a file descriptor.

Synopsis

string = getchar(fd);

Arguments

fd: the file descriptor

Description

Returns a character read from fd, or NULL on EOF. No charset conversion is done.

gettext

Name

gettext - Translates a string to the current language.

Synopsis

string = gettext(str);

Arguments

str: the string

Description

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

Name

gettext_domain - Sets domain and data directory for translations.

Synopsis

bool = gettext_domain(dom, data);

Arguments

dom: the domain (application name)
data: directory contaning the .mo files

Description

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

Name

glob - Executes a file globbing.

Synopsis

array = glob(spec, base);

Arguments

spec: Globbing spec
base: Optional base directory

Description

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 open().

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

Name

grep - Greps inside a multiple value.

Synopsis

array = grep(filter, a);

Arguments

a: the array or hash
filter: the filter

Description

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

Name

hdel - Deletes a key from a hash.

Synopsis

v = hdel(h, k);

Arguments

h: the hash
k: the key

Description

Deletes the key k from the hash h. Returns the previous value, or NULL if the key was not defined.

hmap

Name

hmap - Maps a multiple value to a hash.

Synopsis

hash = hmap(a, filter);

Arguments

a: the value (array or hash)
filter: the filter

Description

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

Name

hsize - Returns the number of pairs of a hash.

Synopsis

integer = hsize(h);

Arguments

h: the hash

Description

Returns the number of key-value pairs of a hash.

ins

Name

ins - Insert an element in an array.

Synopsis

e = ins(a, e, offset);

Arguments

a: the array
e: the element to be inserted
offset: subscript where the element is going to be inserted

Description

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

Name

is_array - Tests if a value is an array.

Synopsis

bool = is_array(v);

Arguments

v: the value

Description

Returns non-zero if v is an array.

is_exec

Name

is_exec - Tests if a value is executable.

Synopsis

bool = is_exec(v);

Arguments

v: the value

Description

Returns non-zero if v is a executable.

is_hash

Name

is_hash - Tests if a value is a hash.

Synopsis

bool = is_hash(v);

Arguments

v: the value

Description

Returns non-zero if v is a hash.

join

Name

join - Joins an array.

Synopsis

string = join(a, joiner_str); array = join(a1, a2);

Arguments

a: array to be joined
s: joiner string or second array

Description

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

Name

keys - Returns the keys of a hash.

Synopsis

array = keys(h);

Arguments

h: the hash

Description

Returns an array containing all the keys of the h hash.

lc

Name

lc - Converts a string to lowercase.

Synopsis

string = uc(str);

Arguments

str: the string to be converted

Description

Returns str converted to lowercase.

load

Name

load - Loads an MPSL source code file.

Synopsis

load(source_file);

Arguments

source_file: the source code file

Description

Loads and executes an MPSL source code file and returns its value.

map

Name

map - Maps a multiple value to an array.

Synopsis

array = map(a, filter);

Arguments

a: the value (array or hash)
filter: the filter

Description

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

Name

mutex - Returns a new mutex.

Synopsis

var = mutex();

Description

Returns a new mutex.

mutex_lock

Name

mutex_lock - Locks a mutex (possibly waiting).

Synopsis

mutex_lock(mtx);

Arguments

mtx: the mutex

Description

Locks a mutex. If the mutex is already locked by another process, it waits until it's unlocked.

mutex_unlock

Name

mutex_unlock - Unlocks a mutex.

Synopsis

mutex_unlock(mtx);

Arguments

mtx: the mutex

Description

Unlocks a mutex.

new

Name

new - Creates a new object using another as its base.

Synopsis

o = new(c1 [, c2, ...cn]);

Arguments

c1: class / base object
c2: class / base object
cn: class / base object

Description

Creates a new object using as classes or base objects all the ones sent as arguments (assumed to be hashes).

open

Name

open - Opens a file.

Synopsis

fd = open(filename, mode);

Arguments

filename: the file name
mode: an fopen-like mode string

Description

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 ENCODING or TEMP_ENCODING.

If the file is open for writing, the encoding to be used is read from the ENCODING global variable and, if not set, from the TEMP_ENCODING one. The latter will always be deleted afterwards.

ord

Name

ord - Returns the Unicode codepoint of a character.

Synopsis

integer = ord(str);

Arguments

str: the string

Description

Returns the Unicode codepoint for the first character in the string.

pclose

Name

pclose - Closes a pipe.

Synopsis

pclose(fd);

Arguments

fd: the value containing the file descriptor

Description

Closes a pipe.

pop

Name

pop - Pops a value from an array.

Synopsis

v = pop(a);

Arguments

a: the array

Description

Pops a value from the array (i.e. deletes from the end and returns it).

popen

Name

popen - Opens a pipe.

Synopsis

fd = popen(prg, mode);

Arguments

prg: the program to pipe
mode: an fopen-like mode string

Description

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 r+ or w+ for a special double pipe reading-writing mode.

popen2

Name

popen2 - Opens a pipe and returns an array of two pipes.

Synopsis

array = popen2(prg);

Arguments

prg: the program to pipe

Description

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

Name

print - Writes values to stdout.

Synopsis

print(arg1 [,arg2 ... argn]);

Arguments

arg1: first argument
arg2: second argument
argn: nth argument

Description

Writes the variable arguments to stdout.

push

Name

push - Pushes a value into an array.

Synopsis

argn = push(a, arg1 [, arg2, ... argn]);

Arguments

a: the array
arg1: first value
arg2: second value
argn: nth value

Description

Pushes values into an array (i.e. inserts at the end). Returns the last element pushed.

putchar

Name

putchar - Writes a character to a file descriptor.

Synopsis

s = putchar(fd, s);

Arguments

fd: the file descriptor
s: the string

Description

Writes the first character in s into fd. No charset conversion is done.

Returns the number of chars written (0 or 1).

queue

Name

queue - Implements a queue in an array.

Synopsis

v = queue(a, e, size);

Arguments

a: the array
e: the element to be pushed
size: maximum size of array

Description

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

Name

random - Returns a random value.

Synopsis

integer = random(value);

Description

Returns a random number from 0 to value - 1.

read

Name

read - Reads a line from a file descriptor.

Synopsis

string = read(fd);

Arguments

fd: the file descriptor

Description

Reads a line from fd. Returns the line, or NULL on EOF.

regex

Name

regex - Matches a regular expression.

Synopsis

string = regex(v, r); string = regex(v, r, offset); array = regex(v, ra); array = regex();

Arguments

v: the value to be matched
r: the regular expression
ra: an array of regular expressions
offset: offset from the start of the value

Description

Matches a regular expression against a value. Valid flags are i, 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 whole string, 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

Name

seek - Seeks a value in an array (sequential).

Synopsis

integer = seek(a, k, step);

Arguments

a: the array
k: the key
step: number of elements to step

Description

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

Name

semaphore - Returns a new semaphore.

Synopsis

var = semaphore(cnt);

Description

Returns a new semaphore.

semaphore_post

Name

semaphore_post - Increments the value of a semaphore.

Synopsis

semaphore_post(mtx);

Arguments

sem: the semaphore to increment

Description

Increments by 1 the value of a semaphore.

semaphore_wait

Name

semaphore_wait - Waits for a semaphore to be ready.

Synopsis

semaphore_wait(sem);

Arguments

sem: the semaphore to wait onto

Description

Waits for the value of a semaphore to be > 0. If it's not, the thread waits until it is.

shift

Name

shift - Extracts the first element of an array.

Synopsis

v = shift(a);

Arguments

a: the array

Description

Extracts the first element of the array. The array is shrinked by one.

Returns the deleted element.

size

Name

size - Returns the size of a value.

Synopsis

integer = size(v);

Arguments

v: the value

Description

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 hsize() instead).

sleep

Name

sleep - Sleeps a number of milliseconds.

Synopsis

sleep(msecs);

Description

Sleeps a number of milliseconds.

sort

Name

sort - Sorts an array.

Synopsis

array = sort(a); array = sort(a, sorting_func);

Arguments

a: the array
sorting_func: sorting function

Description

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 cmp().

Returns the sorted array (the original one is left untouched).

splice

Name

splice - Creates a new string value from another.

Synopsis

array = splice(v, i, offset, del);

Arguments

v: the original value
i: the value to be inserted
offset: offset where the substring is to be inserted
del: number of characters to delete

Description

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

Name

split - Separates a string into an array of pieces.

Synopsis

array = split(v, s);

Arguments

v: the value to be separated
s: the separator

Description

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

Name

sprintf - Formats a sprintf()-like string.

Synopsis

string = sprintf(fmt, arg1 [,arg2 ... argn]);

Arguments

fmt: the string format
arg1: first argument
arg2: second argument
argn: nth argument

Description

Formats a string using the sprintf() format taking the values from the variable arguments.

sregex

Name

sregex - Matches and substitutes a regular expression.

Synopsis

string = sregex(v, r, s); string = sregex(v, r, s, offset); integer = sregex();

Arguments

v: the value to be matched
r: the regular expression
s: the substitution string, hash or code
offset: offset from the start of v

Description

Matches a regular expression against a value, and substitutes the found substring with s. Valid flags are i, for case-insensitive matching, and 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

Name

sscanf - Extracts data like sscanf().

Synopsis

array = sscanf(str, fmt); array = sscanf(str, fmt, offset);

Arguments

str: the string to be parsed
fmt: the string format
offset: the character offset to start scanning

Description

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

Name

stat - Gives status from a file.

Synopsis

array = stat(filename);

Arguments

filename: file name to get the status from

Description

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

Name

strftime - Formats the time as a string.

Synopsis

string = strftime(f); string = strftime(f, t);

Arguments

f: format string
t: seconds (from the Unix epoch)

Description

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

Name

time - Returns the current time.

Synopsis

integer = time();

Description

Returns the current time from the epoch (C library time()).

tr

Name

tr - Transliterates a string.

Synopsis

tr(str, from, to);

Arguments

str: the string
from: set of characters to be replaced
to: set of characters to replace

Description

Transliterates str to a new string with all characters from from replaced by those in to.

uc

Name

uc - Converts a string to uppercase.

Synopsis

string = uc(str);

Arguments

str: the string to be converted

Description

Returns str converted to uppercase.

unlink

Name

unlink - Deletes a file.

Synopsis

bool = unlink(filename);

Arguments

filename: file name to be deleted

Description

Deletes a file.

write

Name

write - Writes values to a file descriptor.

Synopsis

integer = write(fd, arg1 [,arg2 ... argn]);

Arguments

fd: the file descriptor
arg1: first argument
arg2: second argument
argn: nth argument

Description

Writes the variable arguments to the file descriptor, doing charset conversion in the process.

Returns the total size written to fd.

MPSL Function Library Reference

By Category

Arrays

Character Set Conversion

Code Control

Debugging

Hashes

Input-Output

Localization

Miscellaneous

Object-oriented programming

Regular Expressions

Sockets

Strings

Threading

Time

Value Management

By Source

mpsl_f.c

Alphabetical

adel

Name

Synopsis

Arguments

Description

Categories

chdir

Name

Synopsis

Arguments

Description

Categories

chmod

Name

Synopsis

Arguments

Description

Categories

chown

Name

Synopsis

Arguments

Description

Categories

chr

Name

Synopsis

Arguments

Description

Categories

clone

Name

Synopsis

Arguments

Description

Categories

close

Name

Synopsis

Arguments

Description

Categories

cmp

Name

Synopsis

Arguments

Description

Categories

collapse

Name

Synopsis

Arguments

Description

Categories

compile

Name

Synopsis

Arguments

Description

Categories