Ángel Ortega III

Un naufragio personal

MPSL Function Library Reference

This reference documents version 2.2.0 of the MPSL Function Library.

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

adel - Deletes an element of an array.

Synopsis

 v = adel(a, offset);

Arguments

a
the array
offset
subscript of the element to be deleted

Description

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

Categories

chdir

Name

chdir - Changes the working directory

Synopsis

 integer = chdir(dir);

Arguments

dir
the new path

Description

Changes the working directory

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

close

Name

close - Closes a file descriptor.

Synopsis

 close(fd);

Arguments

fd
the file descriptor

Description

Closes the file descriptor.

Categories

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.

Categories

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.

Categories

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.

Categories

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

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

mutex

Name

mutex - Returns a new mutex.

Synopsis

 var = mutex();

Description

Returns a new mutex.

Categories

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.

Categories

mutex_unlock

Name

mutex_unlock - Unlocks a mutex.

Synopsis

 mutex_unlock(mtx);

Arguments

mtx
the mutex

Description

Unlocks a mutex.

Categories

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

Categories

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.

Categories

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.

Categories

pclose

Name

pclose - Closes a pipe.

Synopsis

 pclose(fd);

Arguments

fd
the value containing the file descriptor

Description

Closes a pipe.

Categories

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

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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

Categories

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.

Categories

random

Name

random - Returns a random value.

Synopsis

 integer = random(value);

Description

Returns a random number from 0 to value - 1.

Categories

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.

Categories

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.

Categories

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.

Categories

semaphore

Name

semaphore - Returns a new semaphore.

Synopsis

 var = semaphore(cnt);

Description

Returns a new semaphore.

Categories

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.

Categories

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.

Categories

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.

Categories

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

Categories

sleep

Name

sleep - Sleeps a number of milliseconds.

Synopsis

 sleep(msecs);

Description

Sleeps a number of milliseconds.

Categories

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

Categories

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

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

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.

Categories

time

Name

time - Returns the current time.

Synopsis

 integer = time();

Description

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

Categories

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.

Categories

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.

Categories

unlink

Name

unlink - Deletes a file.

Synopsis

 bool = unlink(filename);

Arguments

filename
file name to be deleted

Description

Deletes a file.

Categories

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.

Categories

Angel Ortega - angel@triptico.com - Built with mp_doccer 1.2.2
documents, mpsl