This reference documents version 2.61 of the MPSL Function Library. <->
sprintf()
-like string.
sscanf()
.
accept - Accepts a connection from a server socket.
static mpdm_t F_accept(F_ARGS);
sock | the server socket |
Accepts a connection from the sock server socket, that was created in a call to server.
chdir - Changes the working directory
integer = chdir(dir);
dir | the new path |
Changes the working directory
chmod - Changes a file's permissions.
integer = chmod(filename, perms);
filename | the file name |
perms | permissions (element 2 from stat() )
|
Changes the permissions for a file.
chown - Changes a file's owner.
integer = chown(filename, uid, gid);
filename | the file name |
uid | user id (element 4 from stat() )
|
gid | group id (element 5 from stat() )
|
Changes the owner and group id's for a file.
chr - Returns the Unicode character represented by the codepoint.
string = chr(c);
c | the codepoint as an integer value |
Returns a 1 character string containing the character which Unicode codepoint is c.
clone - Creates a clone of a value.
v2 = clone(v);
v | the value |
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.
close(fd);
fd | the file descriptor |
Closes the file descriptor.
cmp - Compares two values.
integer = cmp(v);
v1 | the first value |
v2 | the second value |
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 - Collapses an array.
collapse(a, offset, num);
a | the array |
offset | deletion offset |
num | number of elements to collapse |
Collapses an array value, deleting num elements at the specified offset.
compile - Compiles a string of MSPL source code file.
func = compile(code, source);
source | the source code string |
Compiles a string of MPSL source code and returns an executable value.
connect - Opens a client TCP/IP socket.
f = connect(h, s);
h | host name or ip |
s | service or port number |
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 - Dumps a value to stdin.
dump(v);
v | The value |
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);
v | The value |
Returns a visual representation of a complex value.
encoding - Sets the current charset encoding for files.
integer = encoding(charset);
charset | the charset name. |
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 - Simulates an error.
error(err);
err | the error message |
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 - Evaluates MSPL code.
v = eval(code, args);
code | A value containing a string of MPSL code, or executable code |
args | optional arguments for @code |
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 - Tests if a key exists.
bool = exists(h, k);
h | the hash |
k | the key |
Returns 1 if k is defined in h, or 0 othersize.
expand - Expands an array.
expand(a, offset, num);
a | the array |
offset | insertion offset |
num | number of elements to insert |
Expands an array value, inserting num elements (initialized to NULL) at the specified offset.
feof - Returns the EOF condition of a file pointer.
bool = feof(fd);
fd | the file descriptor |
Returns the EOF condition of fd.
flock - Locks a file.
integer = flock(fd, operation);
fd | the file descriptor |
operation | the operation |
Locks a file. The operation can be 1 (shared lock),
2 (exclusive lock) or 4 (unlock). Closing the file
also unlocks. See the flock()
system call man page.
This function does nothing under win32.
Returns the value from the flock()
C function call.
fmt - Formats one sprintf-like value.
string = fmt(f, v);
f | format string |
v | value |
Like sprintf()
, but for only one value. It's a forward implementation
from MPSL 3.x $ (format operator). Accepts sprintf()
percent-formats
plus j (JSON output) and t (brace-enclosed strftime()
formats).
fseek - Sets a file pointer.
integer = fseek(fd, offset, whence);
fd | the file descriptor |
offset | the offset |
whence | the position |
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);
fd | the file descriptor |
Returns the position of the file pointer in fd.
getchar - Reads a character from a file descriptor.
string = getchar(fd);
fd | the file descriptor |
Returns a character read from fd, or NULL on EOF. No charset conversion is done.
getcwd - Returns the current working directory
path = getcwd()
;
Returns the current working directory
gettext - Translates a string to the current language.
string = gettext(str);
str | the string |
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);
dom | the domain (application name) |
data | directory contaning the .mo files |
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);
spec | Globbing spec |
base | Optional base directory |
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 - Greps inside a multiple value.
array = grep(set, filter);
set | the array or hash |
filter | the filter |
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.
ins - Insert an element in an array.
e = ins(a, e, offset);
a | the array |
e | the element to be inserted |
offset | subscript where the element is going to be inserted |
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_exec - Tests if a value is executable.
bool = is_exec(v);
v | the value |
Returns non-zero if v is a executable.
join - Joins an array.
string = join(a, joiner_str); array = join(a1, a2);
a | array to be joined |
s | joiner string or second array |
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);
h | the hash |
Returns an array containing all the keys of the h hash.
lc - Converts a string to lowercase.
string = uc(str);
str | the string to be converted |
Returns str converted to lowercase.
load - Loads an MPSL source code file.
load(source_file);
source_file | the source code file |
Loads and executes an MPSL source code file and returns its value.
map - Maps a set to an array.
array = map(set, sub (v, i) { expression; }); array = map(set, hash); array = map(set, regex);
set | the set |
filter | the filter |
Returns a new array built by applying the filter by iterating the set.
The set is iterated and can be an array, a hash, a scalar (taken as an integer) or a file. If filter is defined, it's applied to the value and the index, and the result shall be the new element for the array in this position.
The filter can be an executable function accepting two arguments, value and index, 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 or hash value will be used as a key to the hash and the associated value used as the output element; also, it can be a string, which is then assumed to be a regular expression that shall be matched against each value.
mutex - Returns a new mutex.
var = mutex()
;
Returns a new mutex.
mutex_lock - Locks a mutex (possibly waiting).
mutex_lock(mtx);
mtx | the mutex |
Locks a mutex. If the mutex is already locked by another process, it waits until it's unlocked.
mutex_unlock - Unlocks a mutex.
mutex_unlock(mtx);
mtx | the mutex |
Unlocks a mutex.
new - Creates a new object using another as its base.
o = new(c1 [, c2, ...cn]);
c1 | class / base object |
c2 | class / base object |
cn | class / base object |
Creates a new object using as classes or base objects all the ones sent as arguments (assumed to be hashes).
omap - Maps a multiple value to a hash.
hash = omap(set, filter);
set | the set (array or hash) |
filter | the filter |
Returns a new hash built by applying the filter to all the elements of the set 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.
If filter is NULL, the returned hash is the inverse (values are the new keys and keys are the new values).
open - Opens a file.
fd = open(filename, mode);
filename | the file name |
mode | an fopen-like mode string |
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 - Returns the Unicode codepoint of a character.
integer = ord(str);
str | the string |
Returns the Unicode codepoint for the first character in the string.
pclose - Closes a pipe.
pclose(fd);
fd | the value containing the file descriptor |
Closes a pipe.
pop - Pops a value from an array.
v = pop(a);
a | the array |
Pops a value from the array (i.e. deletes from the end and returns it).
popen - Opens a pipe.
fd = popen(prg, mode);
prg | the program to pipe |
mode | an fopen-like mode string |
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 - Opens a pipe and returns an array of two pipes.
array = popen2(prg);
prg | the program to pipe |
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]);
arg1 | first argument |
arg2 | second argument |
argn | nth argument |
Writes the variable arguments to stdout.
push - Pushes a value into an array.
argn = push(a, arg1 [, arg2, ... argn]);
a | the array |
arg1 | first value |
arg2 | second value |
argn | nth value |
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);
fd | the file descriptor |
s | the string |
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);
a | the array |
e | the element to be pushed |
size | maximum size of array |
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(range);
real = random()
;
element = random(array);
range | range of values. |
Returns a random value. If range is an array, it returns one of each elements randomly. If range it's a integer, returns a random integer from 0 to range - 1. If range is 0, NULL or undefined, it returns a real number from 0 to 1 (not included).
read - Reads a line from a file descriptor.
string = read(fd);
fd | the file descriptor |
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()
;
v | the value to be matched |
r | the regular expression |
ra | an array of regular expressions |
offset | offset from the start of the value |
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.
rename - Renames a file.
bool = rename(oldpath, newpath);
oldpath | old path |
newpath | new path |
Renames a file.
seek - Seeks a value in an array (sequential).
integer = seek(a, k, step);
a | the array |
k | the key |
step | number of elements to 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.
semaphore_post(mtx);
sem | the semaphore to increment |
Increments by 1 the value of a semaphore.
semaphore_wait - Waits for a semaphore to be ready.
semaphore_wait(sem);
sem | the semaphore to wait onto |
Waits for the value of a semaphore to be > 0. If it's not, the thread waits until it is.
server - Opens a server TCP/IP socket.
static mpdm_t F_server(F_ARGS);
addr | bind address (NULL for any) |
port | port number |
Opens a server TCP/IP socket in the specified port number. The addr can be NULL to bind to all interfaces or a hostname or IP to bind to a specific one (e.g. localhost).
shift - Extracts the first element of an array.
v = shift(a);
a | the array |
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);
v | the value |
Returns the size of a value. Its meaning may not be totally
obvious; use count()
instead for all type of values.
sleep - Sleeps a number of milliseconds.
sleep(msecs);
Sleeps a number of milliseconds.
sort - Sorts an array.
array = sort(a); array = sort(a, sorting_func);
a | the array |
sorting_func | sorting function |
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).
split - Separates a string into an array of pieces.
array = split(v, s);
v | the value to be separated |
s | the separator |
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 sprintf()
-like string.
string = sprintf(fmt, arg1 [,arg2 ... argn]);
fmt | the string format |
arg1 | first argument |
arg2 | second argument |
argn | nth argument |
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()
;
v | the value to be matched |
r | the regular expression |
s | the substitution string, hash or code |
offset | offset from the start of v |
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 - Extracts data like sscanf()
.
array = sscanf(str, fmt); array = sscanf(str, fmt, offset);
str | the string to be parsed |
fmt | the string format |
offset | the character offset to start scanning |
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);
filename | file name to get the status from |
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.
time - Returns the current time.
real = time()
;
Returns the current time from the epoch, with decimals.
tr - Transliterates a string.
tr(str, from, to);
str | the string |
from | set of characters to be replaced |
to | set of characters to replace |
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);
str | the string to be converted |
Returns str converted to uppercase.
unlink - Deletes a file.
bool = unlink(filename);
filename | file name to be deleted |
Deletes a file.
write - Writes values to a file descriptor.
integer = write(fd, arg1 [,arg2 ... argn]);
fd | the file descriptor |
arg1 | first argument |
arg2 | second argument |
argn | nth argument |
Writes the variable arguments to the file descriptor, doing charset conversion in the process.
Returns fd (versions previous to 2.2.5 returned the number of bytes written).