MPSL Function Library Reference
===============================

This reference documents version 2.72 of the MPSL Function Library.

By Category
-----------

Arrays
~~~~~~

 * ./#cmp (cmp)
 * ./#collapse (collapse)
 * ./#expand (expand)
 * ./#grep (grep)
 * ./#ins (ins)
 * ./#join (join)
 * ./#map (map)
 * ./#omap (omap)
 * ./#pop (pop)
 * ./#push (push)
 * ./#queue (queue)
 * ./#seek (seek)
 * ./#shift (shift)
 * ./#sort (sort)
 * ./#split (split)

Character Set Conversion
~~~~~~~~~~~~~~~~~~~~~~~~

 * ./#encoding (encoding)
 * ./#open (open)
 * ./#read (read)
 * ./#write (write)

Code Control
~~~~~~~~~~~~

 * ./#compile (compile)
 * ./#error (error)
 * ./#eval (eval)
 * ./#load (load)

Debugging
~~~~~~~~~

 * ./#dump (dump)
 * ./#dumper (dumper)

Hashes
~~~~~~

 * ./#exists (exists)
 * ./#map (map)
 * ./#omap (omap)

Input-Output
~~~~~~~~~~~~

 * ./#chdir (chdir)
 * ./#chmod (chmod)
 * ./#chown (chown)
 * ./#close (close)
 * ./#connect (connect)
 * ./#dump (dump)
 * ./#encoding (encoding)
 * ./#feof (feof)
 * ./#flock (flock)
 * ./#fseek (fseek)
 * ./#ftell (ftell)
 * ./#getchar (getchar)
 * ./#getcwd (getcwd)
 * ./#glob (glob)
 * ./#link (link)
 * ./#mkdir (mkdir)
 * ./#open (open)
 * ./#popen (popen)
 * ./#popen2 (popen2)
 * ./#print (print)
 * ./#putchar (putchar)
 * ./#read (read)
 * ./#rename (rename)
 * ./#socket.accept (socket.accept)
 * ./#socket.server (socket.server)
 * ./#socket.timeout (socket.timeout)
 * ./#stat (stat)
 * ./#unlink (unlink)
 * ./#write (write)

Localization
~~~~~~~~~~~~

 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)

Miscellaneous
~~~~~~~~~~~~~

 * ./#random (random)

Object-oriented programming
~~~~~~~~~~~~~~~~~~~~~~~~~~~

 * ./#new (new)

Regular Expressions
~~~~~~~~~~~~~~~~~~~

 * ./#grep (grep)
 * ./#regex (regex)
 * ./#sregex (sregex)

Sockets
~~~~~~~

 * ./#connect (connect)
 * ./#socket.accept (socket.accept)
 * ./#socket.server (socket.server)
 * ./#socket.timeout (socket.timeout)

Strings
~~~~~~~

 * ./#chr (chr)
 * ./#cmp (cmp)
 * ./#dumper (dumper)
 * ./#fmt (fmt)
 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)
 * ./#join (join)
 * ./#lc (lc)
 * ./#ord (ord)
 * ./#split (split)
 * ./#sprintf (sprintf)
 * ./#sscanf (sscanf)
 * ./#uc (uc)

Threading
~~~~~~~~~

 * ./#mutex (mutex)
 * ./#mutex_lock (mutex_lock)
 * ./#mutex_unlock (mutex_unlock)
 * ./#semaphore (semaphore)
 * ./#semaphore_post (semaphore_post)
 * ./#semaphore_wait (semaphore_wait)
 * ./#sleep (sleep)
 * ./#tr (tr)

Time
~~~~

 * ./#sleep (sleep)
 * ./#time (time)

Value Management
~~~~~~~~~~~~~~~~

 * ./#clone (clone)
 * ./#is_exec (is_exec)
 * ./#size (size)

By Source
---------

mpsl_f.c
~~~~~~~~

 * ./#chdir (chdir)
 * ./#chmod (chmod)
 * ./#chown (chown)
 * ./#chr (chr)
 * ./#clone (clone)
 * ./#close (close)
 * ./#cmp (cmp)
 * ./#collapse (collapse)
 * ./#compile (compile)
 * ./#connect (connect)
 * ./#dump (dump)
 * ./#dumper (dumper)
 * ./#encoding (encoding)
 * ./#error (error)
 * ./#eval (eval)
 * ./#exists (exists)
 * ./#expand (expand)
 * ./#feof (feof)
 * ./#flock (flock)
 * ./#fmt (fmt)
 * ./#fseek (fseek)
 * ./#ftell (ftell)
 * ./#getchar (getchar)
 * ./#getcwd (getcwd)
 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)
 * ./#glob (glob)
 * ./#grep (grep)
 * ./#ins (ins)
 * ./#is_exec (is_exec)
 * ./#join (join)
 * ./#lc (lc)
 * ./#link (link)
 * ./#load (load)
 * ./#map (map)
 * ./#mkdir (mkdir)
 * ./#mutex (mutex)
 * ./#mutex_lock (mutex_lock)
 * ./#mutex_unlock (mutex_unlock)
 * ./#new (new)
 * ./#omap (omap)
 * ./#open (open)
 * ./#ord (ord)
 * ./#pop (pop)
 * ./#popen (popen)
 * ./#popen2 (popen2)
 * ./#print (print)
 * ./#push (push)
 * ./#putchar (putchar)
 * ./#queue (queue)
 * ./#random (random)
 * ./#read (read)
 * ./#regex (regex)
 * ./#rename (rename)
 * ./#seek (seek)
 * ./#semaphore (semaphore)
 * ./#semaphore_post (semaphore_post)
 * ./#semaphore_wait (semaphore_wait)
 * ./#shift (shift)
 * ./#size (size)
 * ./#sleep (sleep)
 * ./#socket.accept (socket.accept)
 * ./#socket.server (socket.server)
 * ./#socket.timeout (socket.timeout)
 * ./#sort (sort)
 * ./#split (split)
 * ./#sprintf (sprintf)
 * ./#sregex (sregex)
 * ./#sscanf (sscanf)
 * ./#stat (stat)
 * ./#time (time)
 * ./#tr (tr)
 * ./#uc (uc)
 * ./#unlink (unlink)
 * ./#write (write)

Alphabetical
------------

 * ./#chdir (chdir) - Changes the working directory
 * ./#chmod (chmod) - Changes a file's permissions.
 * ./#chown (chown) - Changes a file's owner.
 * ./#chr (chr) - Returns the Unicode character represented by the codepoint.
 * ./#clone (clone) - Creates a clone of a value.
 * ./#close (close) - Closes a file descriptor.
 * ./#cmp (cmp) - Compares two values.
 * ./#collapse (collapse) - Collapses an array.
 * ./#compile (compile) - Compiles a string of MSPL source code file.
 * ./#connect (connect) - Opens a client TCP/IP socket.
 * ./#dump (dump) - Dumps a value to stdin.
 * ./#dumper (dumper) - Returns a visual representation of a complex value.
 * ./#encoding (encoding) - Sets the current charset encoding for files.
 * ./#error (error) - Simulates an error.
 * ./#eval (eval) - Evaluates MSPL code.
 * ./#exists (exists) - Tests if a key exists.
 * ./#expand (expand) - Expands an array.
 * ./#feof (feof) - Returns the EOF condition of a file pointer.
 * ./#flock (flock) - Locks a file.
 * ./#fmt (fmt) - Formats one sprintf-like value.
 * ./#fseek (fseek) - Sets a file pointer.
 * ./#ftell (ftell) - Returns the current file pointer.
 * ./#getchar (getchar) - Reads a character from a file descriptor.
 * ./#getcwd (getcwd) - Returns the current working directory
 * ./#gettext (gettext) - Translates a string to the current language.
 * ./#gettext_domain (gettext_domain) - Sets domain and data directory for translations.
 * ./#glob (glob) - Executes a file globbing.
 * ./#grep (grep) - Greps inside a multiple value.
 * ./#ins (ins) - Insert an element in an array.
 * ./#is_exec (is_exec) - Tests if a value is executable.
 * ./#join (join) - Joins an array.
 * ./#lc (lc) - Converts a string to lowercase.
 * ./#link (link) - Create a file link.
 * ./#load (load) - Loads an MPSL source code file.
 * ./#map (map) - Maps a set to an array.
 * ./#mkdir (mkdir) - Creates a directory
 * ./#mutex (mutex) - Returns a new mutex.
 * ./#mutex_lock (mutex_lock) - Locks a mutex (possibly waiting).
 * ./#mutex_unlock (mutex_unlock) - Unlocks a mutex.
 * ./#new (new) - Creates a new object using another as its base.
 * ./#omap (omap) - Maps a multiple value to a hash.
 * ./#open (open) - Opens a file.
 * ./#ord (ord) - Returns the Unicode codepoint of a character.
 * ./#pop (pop) - Pops a value from an array.
 * ./#popen (popen) - Opens a pipe.
 * ./#popen2 (popen2) - Opens a pipe and returns an array of two pipes.
 * ./#print (print) - Writes values to stdout.
 * ./#push (push) - Pushes a value into an array.
 * ./#putchar (putchar) - Writes a character to a file descriptor.
 * ./#queue (queue) - Implements a queue in an array.
 * ./#random (random) - Returns a random value.
 * ./#read (read) - Reads a line from a file descriptor.
 * ./#regex (regex) - Matches a regular expression.
 * ./#rename (rename) - Renames a file.
 * ./#seek (seek) - Seeks a value in an array (sequential).
 * ./#semaphore (semaphore) - Returns a new semaphore.
 * ./#semaphore_post (semaphore_post) - Increments the value of a semaphore.
 * ./#semaphore_wait (semaphore_wait) - Waits for a semaphore to be ready.
 * ./#shift (shift) - Extracts the first element of an array.
 * ./#size (size) - Returns the size of a value.
 * ./#sleep (sleep) - Sleeps a number of milliseconds.
 * ./#socket.accept (socket.accept) - Accepts a connection from a server socket.
 * ./#socket.server (socket.server) - Opens a server TCP/IP socket.
 * ./#socket.timeout (socket.timeout) - Sets a socket's receiving and/or sending timeouts.
 * ./#sort (sort) - Sorts an array.
 * ./#split (split) - Separates a string into an array of pieces.
 * ./#sprintf (sprintf) - Formats a sprintf()-like string.
 * ./#sregex (sregex) - Matches and substitutes a regular expression.
 * ./#sscanf (sscanf) - Extracts data like sscanf().
 * ./#stat (stat) - Gives status from a file.
 * ./#time (time) - Returns the current time.
 * ./#tr (tr) - Transliterates a string.
 * ./#uc (uc) - Converts a string to uppercase.
 * ./#unlink (unlink) - Deletes a file.
 * ./#write (write) - Writes values to a file descriptor.


chdir
-----

Name
~~~~

*chdir* - Changes the working directory

Synopsis
~~~~~~~~

 integer = chdir(dir); 


Arguments
~~~~~~~~~

 * dir: the new path

Description
~~~~~~~~~~~

Changes the working directory.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#value_management (Value Management)

close
-----

Name
~~~~

*close* - Closes a file descriptor.

Synopsis
~~~~~~~~

 close(fd); 


Arguments
~~~~~~~~~

 * fd: the file descriptor

Description
~~~~~~~~~~~

Closes the file descriptor.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#strings (Strings)
 * ./#arrays (Arrays)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

compile
-------

Name
~~~~

*compile* - Compiles a string of MSPL source code file.

Synopsis
~~~~~~~~

 func = compile(code, source); 


Arguments
~~~~~~~~~

 * source: the source code string

Description
~~~~~~~~~~~

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

Categories
~~~~~~~~~~

 * ./#code_control (Code Control)

connect
-------

Name
~~~~

*connect* - Opens a client TCP/IP socket.

Synopsis
~~~~~~~~

 static mpdm_t F_connect(F_ARGS);

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
~~~~~~~~~~

 * ./#sockets (Sockets)
 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#debugging (Debugging)
 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#debugging (Debugging)
 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)
 * ./#character_set_conversion (Character Set Conversion)

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
~~~~~~~~~~

 * ./#code_control (Code Control)

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
~~~~~~~~~~

 * ./#code_control (Code Control)

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
~~~~~~~~~~

 * ./#hashes (Hashes)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

feof
----

Name
~~~~

*feof* - Returns the EOF condition of a file pointer.

Synopsis
~~~~~~~~

 bool = feof(fd); 


Arguments
~~~~~~~~~

 * fd: the file descriptor

Description
~~~~~~~~~~~

Returns the EOF condition of _fd_.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

flock
-----

Name
~~~~

*flock* - Locks a file.

Synopsis
~~~~~~~~

 integer = flock(fd, operation); 


Arguments
~~~~~~~~~

 * fd: the file descriptor
 * operation: the operation

Description
~~~~~~~~~~~

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.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

fmt
---

Name
~~~~

*fmt* - Formats one sprintf-like value.

Synopsis
~~~~~~~~

 string = fmt(f, v); 


Arguments
~~~~~~~~~

 * f: format string
 * v: value

Description
~~~~~~~~~~~

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

Categories
~~~~~~~~~~

 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

getcwd
------

Name
~~~~

*getcwd* - Returns the current working directory

Synopsis
~~~~~~~~

 path = getcwd(); 


Description
~~~~~~~~~~~

Returns the current working directory.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#strings (Strings)
 * ./#localization (Localization)

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
~~~~~~~~~~

 * ./#strings (Strings)
 * ./#localization (Localization)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

grep
----

Name
~~~~

*grep* - Greps inside a multiple value.

Synopsis
~~~~~~~~

 array = grep(set, filter); 


Arguments
~~~~~~~~~

 * set: 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
~~~~~~~~~~

 * ./#arrays (Arrays)
 * ./#regular_expressions (Regular Expressions)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

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
~~~~~~~~~~

 * ./#value_management (Value Management)

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
~~~~~~~~~~

 * ./#arrays (Arrays)
 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#strings (Strings)

link
----

Name
~~~~

*link* - Create a file link.

Synopsis
~~~~~~~~

 status = link(src, dest); 


Arguments
~~~~~~~~~

 * src: source file
 * dest: destination file

Description
~~~~~~~~~~~

Links _dest_ as a hard link to _src_ (UNIX only)

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#code_control (Code Control)

map
---

Name
~~~~

*map* - Maps a set to an array.

Synopsis
~~~~~~~~

 array = map(set, sub (v, i) { expression; }); 
 array = map(set, hash); 
 array = map(set, regex); 


Arguments
~~~~~~~~~

 * set: the set
 * filter: the filter

Description
~~~~~~~~~~~

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.


Categories
~~~~~~~~~~

 * ./#arrays (Arrays)
 * ./#hashes (Hashes)

mkdir
-----

Name
~~~~

*mkdir* - Creates a directory

Synopsis
~~~~~~~~

 integer = mkdir(dir, mode); 


Arguments
~~~~~~~~~

 * dir: the new path
 * mode: permissions (number)

Description
~~~~~~~~~~~

Creates a directory.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

mutex
-----

Name
~~~~

*mutex* - Returns a new mutex.

Synopsis
~~~~~~~~

 var = mutex(); 


Description
~~~~~~~~~~~

Returns a new mutex.

Categories
~~~~~~~~~~

 * ./#threading (Threading)

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
~~~~~~~~~~

 * ./#threading (Threading)

mutex_unlock
------------

Name
~~~~

*mutex_unlock* - Unlocks a mutex.

Synopsis
~~~~~~~~

 mutex_unlock(mtx); 


Arguments
~~~~~~~~~

 * mtx: the mutex

Description
~~~~~~~~~~~

Unlocks a mutex.

Categories
~~~~~~~~~~

 * ./#threading (Threading)

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

If the new object has an __init__() method, it's executed with
the newly created object as its unique argument. It MUST return
the same object or NULL if the object has been destroyed due to
a failed initialization.


Categories
~~~~~~~~~~

 * ./#object-oriented_programming (Object-oriented programming)

omap
----

Name
~~~~

*omap* - Maps a multiple value to a hash.

Synopsis
~~~~~~~~

 hash = omap(set, filter); 


Arguments
~~~~~~~~~

 * set: the set (array or hash)
 * filter: the filter

Description
~~~~~~~~~~~

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.


Categories
~~~~~~~~~~

 * ./#arrays (Arrays)
 * ./#hashes (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.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)
 * ./#character_set_conversion (Character Set Conversion)

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
~~~~~~~~~~

 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

random
------

Name
~~~~

*random* - Returns a random value.

Synopsis
~~~~~~~~

 integer = random(range); 
 real = random(); 
 element = random(array); 


Arguments
~~~~~~~~~

 * range: range of values.

Description
~~~~~~~~~~~

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

Categories
~~~~~~~~~~

 * ./#miscellaneous (Miscellaneous)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)
 * ./#character_set_conversion (Character Set Conversion)

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
~~~~~~~~~~

 * ./#regular_expressions (Regular Expressions)

rename
------

Name
~~~~

*rename* - Renames a file.

Synopsis
~~~~~~~~

 bool = rename(oldpath, newpath); 


Arguments
~~~~~~~~~

 * oldpath: old path
 * newpath: new path

Description
~~~~~~~~~~~

Renames a file.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

semaphore
---------

Name
~~~~

*semaphore* - Returns a new semaphore.

Synopsis
~~~~~~~~

 var = semaphore(cnt); 


Description
~~~~~~~~~~~


Returns a new semaphore.

Categories
~~~~~~~~~~

 * ./#threading (Threading)

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
~~~~~~~~~~

 * ./#threading (Threading)

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
~~~~~~~~~~

 * ./#threading (Threading)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

size
----

Name
~~~~

*size* - Returns the size of a value.

Synopsis
~~~~~~~~

 integer = size(v); 


Arguments
~~~~~~~~~

 * v: the value

Description
~~~~~~~~~~~

Returns the size of a value. Its meaning may not be totally
obvious; use count() instead for all type of values.

Categories
~~~~~~~~~~

 * ./#value_management (Value Management)

sleep
-----

Name
~~~~

*sleep* - Sleeps a number of milliseconds.

Synopsis
~~~~~~~~

 sleep(msecs); 


Description
~~~~~~~~~~~

Sleeps a number of milliseconds.

Categories
~~~~~~~~~~

 * ./#threading (Threading)
 * ./#time (Time)

socket.accept
-------------

Name
~~~~

*socket.accept* - Accepts a connection from a server socket.

Synopsis
~~~~~~~~

 static mpdm_t F_accept(F_ARGS);

Arguments
~~~~~~~~~

 * sock: the server socket

Description
~~~~~~~~~~~

Accepts a connection from the _sock_ server socket, that was created
in a call to _server_.

Categories
~~~~~~~~~~

 * ./#sockets (Sockets)
 * ./#input-output (Input-Output)

socket.server
-------------

Name
~~~~

*socket.server* - Opens a server TCP/IP socket.

Synopsis
~~~~~~~~

 static mpdm_t F_server(F_ARGS);

Arguments
~~~~~~~~~

 * addr: bind address (NULL for any)
 * port: port number

Description
~~~~~~~~~~~

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

Categories
~~~~~~~~~~

 * ./#sockets (Sockets)
 * ./#input-output (Input-Output)

socket.timeout
--------------

Name
~~~~

*socket.timeout* - Sets a socket's receiving and/or sending timeouts.

Synopsis
~~~~~~~~

 static mpdm_t F_socket_timeout(F_ARGS);

Arguments
~~~~~~~~~

 * sock: the socket
 * r_to: receiving timeout (in seconds)
 * s_to: sending timeout (in seconds)

Description
~~~~~~~~~~~

Sets the receiving and/or sending timeouts (in seconds) for _sock_.
If any of the timeouts is NULL, it's not touched.

Categories
~~~~~~~~~~

 * ./#sockets (Sockets)
 * ./#input-output (Input-Output)

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
~~~~~~~~~~

 * ./#arrays (Arrays)

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
~~~~~~~~~~

 * ./#arrays (Arrays)
 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#regular_expressions (Regular Expressions)

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
~~~~~~~~~~

 * ./#strings (Strings)

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
~~~~~~~~~~

 * ./#input-output (Input-Output)

time
----

Name
~~~~

*time* - Returns the current time.

Synopsis
~~~~~~~~

 real = time(); 


Description
~~~~~~~~~~~

Returns the current time from the epoch, with decimals.

Categories
~~~~~~~~~~

 * ./#time (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_.

Categories
~~~~~~~~~~

 * ./#threading (Threading)

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
~~~~~~~~~~

 * ./#strings (Strings)

unlink
------

Name
~~~~

*unlink* - Deletes a file.

Synopsis
~~~~~~~~

 status = unlink(filename); 


Arguments
~~~~~~~~~

 * filename: file name to be deleted

Description
~~~~~~~~~~~

Deletes a file.

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)

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 _fd_ (versions previous to 2.2.5 returned the number
of bytes written).

Categories
~~~~~~~~~~

 * ./#input-output (Input-Output)
 * ./#character_set_conversion (Character Set Conversion)

----
ttcdt - dev@triptico.com - Built with http://triptico.com/software/mp_doccer.html (mp_doccer 1.2.2)
