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

This reference documents version 1.0.8 of the MPSL Function Library.

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

Arrays
~~~~~~

 * ./#adel (adel)
 * ./#cmp (cmp)
 * ./#collapse (collapse)
 * ./#expand (expand)
 * ./#grep (grep)
 * ./#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)
 * ./#eval (eval)
 * ./#load (load)

Debugging
~~~~~~~~~

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

Hashes
~~~~~~

 * ./#exists (exists)
 * ./#hdel (hdel)
 * ./#hsize (hsize)
 * ./#is_hash (is_hash)
 * ./#keys (keys)

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

 * ./#chdir (chdir)
 * ./#chmod (chmod)
 * ./#chown (chown)
 * ./#close (close)
 * ./#dump (dump)
 * ./#encoding (encoding)
 * ./#fseek (fseek)
 * ./#getchar (getchar)
 * ./#glob (glob)
 * ./#open (open)
 * ./#pclose (pclose)
 * ./#popen (popen)
 * ./#print (print)
 * ./#putchar (putchar)
 * ./#read (read)
 * ./#stat (stat)
 * ./#unlink (unlink)
 * ./#write (write)

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

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

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

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

Strings
~~~~~~~

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

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

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

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)
 * ./#dump (dump)
 * ./#dumper (dumper)
 * ./#encoding (encoding)
 * ./#error (error)
 * ./#eval (eval)
 * ./#exists (exists)
 * ./#expand (expand)
 * ./#fseek (fseek)
 * ./#fseek (fseek)
 * ./#getchar (getchar)
 * ./#gettext (gettext)
 * ./#gettext_domain (gettext_domain)
 * ./#glob (glob)
 * ./#grep (grep)
 * ./#hdel (hdel)
 * ./#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)
 * ./#open (open)
 * ./#ord (ord)
 * ./#pclose (pclose)
 * ./#pop (pop)
 * ./#popen (popen)
 * ./#print (print)
 * ./#push (push)
 * ./#putchar (putchar)
 * ./#queue (queue)
 * ./#read (read)
 * ./#regex (regex)
 * ./#seek (seek)
 * ./#shift (shift)
 * ./#size (size)
 * ./#sort (sort)
 * ./#splice (splice)
 * ./#split (split)
 * ./#sprintf (sprintf)
 * ./#sregex (sregex)
 * ./#sscanf (sscanf)
 * ./#stat (stat)
 * ./#sweep (sweep)
 * ./#time (time)
 * ./#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.
 * ./#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.
 * ./#fseek (fseek) - Sets a file pointer.
 * ./#fseek (fseek) - Returns the current file pointer.
 * ./#getchar (getchar) - Reads a character from a file descriptor.
 * ./#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 an array.
 * ./#hdel (hdel) - Deletes a key from 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 all elements of an array into one.
 * ./#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 an array into another.
 * ./#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.
 * ./#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.
 * ./#read (read) - Reads a line from a file descriptor.
 * ./#regex (regex) - Matches a regular expression.
 * ./#seek (seek) - Seeks a value in an array (sequential).
 * ./#shift (shift) - Extracts the first element of an array.
 * ./#size (size) - Returns the size of a value.
 * ./#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.
 * ./#sweep (sweep) - Sweeps unreferenced values.
 * ./#time (time) - Returns the current time.
 * ./#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 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)

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.


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)

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)

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)

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 an array.

Synopsis
~~~~~~~~

 array = grep(filter, a); 


Arguments
~~~~~~~~~

 * filter: the filter
 * a: the array

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

Greps inside an array 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.
If _filter_ is executable, it will be called with the element as its
only argument and its return value used as validation.

The new array 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)

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 all elements of an array into one.

Synopsis
~~~~~~~~

 string = join(s, a); 


Arguments
~~~~~~~~~

 * s: joiner string
 * a: array to be joined

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

Joins all elements from _a_ into one string, using _s_ as a glue.

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 an array into another.

Synopsis
~~~~~~~~

 array = map(filter, a); 


Arguments
~~~~~~~~~

 * filter: the filter
 * a: the array

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

Returns a new array built by applying the _filter_ to all the
elements of the array _a_. The filter can be an executable function
accepting one argument, in which case the return value of the function
will be used as the output element; _filt_ can also be a hash, in which
case the original element will be used as a key to the hash and the
associated value used as the output element.


Categories
~~~~~~~~~~

 * ./#arrays (Arrays)

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)

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

 e = push(a, e); 


Arguments
~~~~~~~~~

 * a: the array
 * e: the value

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

Pushes a value into an array (i.e. inserts at the end).

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 _s_ or NULL if the writing failed.

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)

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(r, v); 
 string = regex(r, v, offset); 
 array = regex(ra, v); 
 array = regex(); 


Arguments
~~~~~~~~~

 * r: the regular expression
 * ra: an array of regular expressions
 * v: the value to be matched
 * 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)

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)

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)

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(s, v); 


Arguments
~~~~~~~~~

 * s: the separator
 * v: the value to be separated

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(r, v, s); 
 string = sregex(r, v, s, offset); 
 integer = sregex(); 


Arguments
~~~~~~~~~

 * r: the regular expression
 * v: the value to be matched
 * 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(fmt, str); 
 array = sscanf(fmt, str, offset); 


Arguments
~~~~~~~~~

 * fmt: the string format
 * str: the string to be parsed
 * 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)

sweep
-----

Name
~~~~

*sweep* - Sweeps unreferenced values.

Synopsis
~~~~~~~~

 sweep(count); 


Arguments
~~~~~~~~~

 * count: number of values to be swept

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

Destroys values with a reference count of 0. _count_ is the
number of values to be checked for deletion; special values of
_count_ are -1, that forces a check of all currently known values
(can be time-consuming) and 0, which tells sweep() to check a
small group of them on each call.

Categories
~~~~~~~~~~

 * ./#value_management (Value Management)

time
----

Name
~~~~

*time* - Returns the current time.

Synopsis
~~~~~~~~

 integer = time(); 


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

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


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)
