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

This reference documents version 2.2.2 of the MPSL Function Library.

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

Arrays
~~~~~~

 * ./#adel (adel)
 * ./#cmp (cmp)
 * ./#collapse (collapse)
 * ./#expand (expand)
 * ./#grep (grep)
 * ./#hmap (hmap)
 * ./#ins (ins)
 * ./#is_array (is_array)
 * ./#join (join)
 * ./#keys (keys)
 * ./#map (map)
 * ./#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)
 * ./#hdel (hdel)
 * ./#hmap (hmap)
 * ./#hsize (hsize)
 * ./#is_hash (is_hash)
 * ./#keys (keys)
 * ./#map (map)

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

 * ./#chdir (chdir)
 * ./#chmod (chmod)
 * ./#chown (chown)
 * ./#close (close)
 * ./#connect (connect)
 * ./#dump (dump)
 * ./#encoding (encoding)
 * ./#fseek (fseek)
 * ./#ftell (ftell)
 * ./#getchar (getchar)
 * ./#getcwd (getcwd)
 * ./#glob (glob)
 * ./#open (open)
 * ./#pclose (pclose)
 * ./#popen (popen)
 * ./#popen2 (popen2)
 * ./#print (print)
 * ./#putchar (putchar)
 * ./#read (read)
 * ./#rename (rename)
 * ./#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)

Strings
~~~~~~~

 * ./#chr (chr)
 * ./#cmp (cmp)
 * ./#dumper (dumper)
 * ./#fmt (fmt)
 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)
 * ./#join (join)
 * ./#lc (lc)
 * ./#ord (ord)
 * ./#splice (splice)
 * ./#split (split)
 * ./#sprintf (sprintf)
 * ./#sscanf (sscanf)
 * ./#strftime (strftime)
 * ./#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)
 * ./#strftime (strftime)
 * ./#time (time)

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

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

By Source
---------

mpsl_f.c
~~~~~~~~

 * ./#adel (adel)
 * ./#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)
 * ./#fmt (fmt)
 * ./#fseek (fseek)
 * ./#ftell (ftell)
 * ./#getchar (getchar)
 * ./#getcwd (getcwd)
 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)
 * ./#glob (glob)
 * ./#grep (grep)
 * ./#hdel (hdel)
 * ./#hmap (hmap)
 * ./#hsize (hsize)
 * ./#ins (ins)
 * ./#is_array (is_array)
 * ./#is_exec (is_exec)
 * ./#is_hash (is_hash)
 * ./#join (join)
 * ./#keys (keys)
 * ./#lc (lc)
 * ./#load (load)
 * ./#map (map)
 * ./#mutex (mutex)
 * ./#mutex_lock (mutex_lock)
 * ./#mutex_unlock (mutex_unlock)
 * ./#new (new)
 * ./#open (open)
 * ./#ord (ord)
 * ./#pclose (pclose)
 * ./#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)
 * ./#sort (sort)
 * ./#splice (splice)
 * ./#split (split)
 * ./#sprintf (sprintf)
 * ./#sregex (sregex)
 * ./#sscanf (sscanf)
 * ./#stat (stat)
 * ./#strftime (strftime)
 * ./#time (time)
 * ./#tr (tr)
 * ./#uc (uc)
 * ./#unlink (unlink)
 * ./#write (write)

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

 * ./#adel (adel) - Deletes an element of an array.
 * ./#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.
 * ./#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.
 * ./#hdel (hdel) - Deletes a key from a hash.
 * ./#hmap (hmap) - Maps a multiple value to a hash.
 * ./#hsize (hsize) - Returns the number of pairs of a hash.
 * ./#ins (ins) - Insert an element in an array.
 * ./#is_array (is_array) - Tests if a value is an array.
 * ./#is_exec (is_exec) - Tests if a value is executable.
 * ./#is_hash (is_hash) - Tests if a value is a hash.
 * ./#join (join) - Joins an array.
 * ./#keys (keys) - Returns the keys of a hash.
 * ./#lc (lc) - Converts a string to lowercase.
 * ./#load (load) - Loads an MPSL source code file.
 * ./#map (map) - Maps a multiple value to an array.
 * ./#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.
 * ./#open (open) - Opens a file.
 * ./#ord (ord) - Returns the Unicode codepoint of a character.
 * ./#pclose (pclose) - Closes a pipe.
 * ./#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.
 * ./#sort (sort) - Sorts an array.
 * ./#splice (splice) - Creates a new string value from another.
 * ./#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.
 * ./#strftime (strftime) - Formats the time as a string.
 * ./#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.


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

 * ./#arrays (Arrays)

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

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

 * ./#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)

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

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

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

 * ./#hashes (Hashes)

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

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

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

 * ./#hashes (Hashes)

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

 * ./#value_management (Value Management)
 * ./#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)

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

 * ./#value_management (Value Management)
 * ./#hashes (Hashes)

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)

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

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

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)

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

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

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


Categories
~~~~~~~~~~

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

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)

pclose
------

Name
~~~~

*pclose* - Closes a pipe.

Synopsis
~~~~~~~~

 pclose(fd); 


Arguments
~~~~~~~~~

 * fd: the value containing the file descriptor

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

Closes a pipe.

Categories
~~~~~~~~~~

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

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(value); 


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

Returns a random number from 0 to value - 1.

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

 * ./#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)

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)

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

 * ./#strings (Strings)

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)

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

 * ./#strings (Strings)
 * ./#time (Time)

time
----

Name
~~~~

*time* - Returns the current time.

Synopsis
~~~~~~~~

 integer = time(); 


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

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

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

 bool = 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 the total size written to _fd_.

Categories
~~~~~~~~~~

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

----
Angel Ortega - angel@triptico.com - Built with http://triptico.com/software/mp_doccer.html (mp_doccer 1.2.2)
