Changed mpdm_sscanf().

[mpsl.git] / doc / mpsl_overview.txt

MPSL Overview
=============

MPSL (Minimum Profit Scripting Language) is a programming language
concieved as a scripting engine for the Minimum Profit Text Editor,
though it can also be used as a general-purpose programming tool.

Basic Syntax
------------

An MPSL program consists of a sequence of statements which run from top to
bottom. Loops, subroutines and other control structures allow you to jump
around within the code. It is a free-form language, meaning that you can
format and indent it however you like, as whitespace serves to separate
tokens. MPSL borrows syntax and concepts from many languages: C, Perl, Java
or JavaScript. Statements end in a semi-colon, blocks are enclosed between {
and } (curly brackets).

Comments
~~~~~~~~

Text enclosed between /* and */ is ignored, as in C. It can span multiple
lines.

Strings
~~~~~~~

Strings are enclosed around single or double quotes:

 print("This a string");
 print('This is also a string');

However, double quotes give special treatment to backslash-escaped
characters, also as in C:

 print("Hello, world\n");       /* ends with a new line */
 print('Hello, World\n');       /* prints Hello, World\n literally */

Strings can be broken between lines by using backslashes:

 print("Hello, "\
        "world\n");

Non-ASCII characters (Unicode) can be included in strings using the
following syntax:

 print("Hello, world \x{263A}\n"); /* a smiley follows the greeting */

Subroutine calls
~~~~~~~~~~~~~~~~

Function and subroutine calls must enclose its arguments between
parentheses, and separate them by commas:

 print("This is ", 'a list ', "of ", 5, " arguments\n");

Parentheses are needed even if a function has no arguments.

True and false
~~~~~~~~~~~~~~

The number 0, the strings '0' and '' and NULL are all false as boolean
values. Any other value is considered true.

Variables and data types
------------------------

Data types in MPSL match the mpdm (Minimum Profit Data Manager) single,
array and hash values. They are very similar to Perl ones. However,
variable names don't have a prefix indicating its type as in Perl; they
can hold any type.

Variables need not be declared (unless for local values, see below); they
are created on assignation.

Scalars
~~~~~~~

A scalar represents a single value. They can be strings, integers or
floating point numbers, and they will be converted as required.

 fruit = "pear";
 months = 12;
 pi = 3.1416;

There are other types of scalar values, as file descriptors and executable
values; they will be treated later.

Scalar assignation is always by value; by doing

 a = 100; b = a; b = 5;

The a variable still holds its original value of 100.

Arrays
~~~~~~

An array represents a list of values. Arrays are zero-indexed. Each
element of an array can be of any type (scalar, array, or hash). Array
size is dynamic and can grow or shrink at the programmer's wish.

 workdays = [ 'monday', 'tuesday', 'wednesday', 'thursday', 'friday' ];
 
 print(workdays[0], "\n");      /* prints monday */
 
 heterogeneous_array = [ 1, "string", [ 1, 2, 3 ], NULL, function(), workdays ];

Array assignation is always by reference; by doing

 a = [ 10, 20, 30 ]; b = a; b[0] = 100;

The value for the element a[0] is also 100; a and b both point to the same
array. A special-purpose function, clone(), can be used if you want them
to be different values.

Arrays grow when assigned to an out-of-bounds subscript:

 ary = [ 0, 1, 2, 3 ];
 print("size: ", size(ary), "\n");      /* prints size: 4 */
 ary[100] = 100;
 print("size: ", size(ary), "\n");      /* prints size: 101 */

The range operator can be used to populate an array with consecutive,
integer values, as in the example:

 ary = [ 1 .. 100 ];    /* ary contains 100 elements, from 1 to 100 */

Hashes
~~~~~~

A hash, or associative array, represents a set of key/value pairs. Keys and
values can be of any type (scalar, array or hash). However, keys are
usually scalar values, in particular strings.

 en2es_workdays = {
        'monday'        =>      'lunes',
        'tuesday'       =>      'martes',
        'wednesday'     =>      'miercoles',
        'thursday'      =>      'jueves',
        'friday'        =>      'viernes'
        };
 
 print(en2es_workdays['monday'], "\n"); /* prints lunes */
 
 week = {
        'workdays'      =>      workdays,
        'weekend'       =>      [ 'saturday', 'sunday' ]
        };

Hash definitions *must* use the => to mark key/value pairs.

Hash assignation is always by reference, as in arrays (in fact, hashes are
just a special case of array).

Compact access to hash members
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hashes can, and ofter are, used as records. Given the following hash of
hashes:

 app = {};
 app['config'] = {};
 app['config']['save_on_exit'] = 1;

The save_on_exit component can also be accessed by using:

 app.config.save_on_exit = 1;

Please note that variables are *not* automatically created unless the path
to them already exist; so 'app' and 'app.config' must exist and be hashes,
or the 'save_on_exit' component will not be created and fail silently.
This is a common pitfall.

Variable names
~~~~~~~~~~~~~~

A variable name must start with a letter or underscore and can be followed
by any number of letters, numbers and underscores. Case is significative,
so aaa and AAA and aAa are different symbols.

Variable scope
~~~~~~~~~~~~~~

By default, non-existent assigned variables are created as global symbols.
Though they are useful, it's not a good programming practice to have all
variables as global, so local variables can be used. They are defined by
using the local directive:

 local a;       /* creates the local variable a, with NULL value */
 local b = 100; /* creates the local variable b, with a value of 100 */

Local variables have its life limited to the subroutine where they are
defined or, if defined inside a block, limited to that block. Inner
variables obscure more global ones, as in the example:

 var = 6;       /* global variable var, with a value of 6 */
 
 {              /* start of block */
        local var = 10;                 /* local variable var */
        print("var: ", var, "\n");      /* prints var: 10 */
        var = 20;                       /* local var now has 20 */
        print("var: ", var, "\n");      /* prints var: 20 */
 }              /* end of block */
 
 print("var: ", var, "\n");             /* prints var: 6 */

Subroutine arguments are treated as local variables.

Conditional and looping constructs
----------------------------------

If
~~

MPSL has the usual `if' conditional construct. The condition can be any
MPSL expression, and the conditional code must be written between braces
if it's more than one instruction, just like in C.

 /* one instruction */
 if (a > b)
        do_something();
 
 /* more than one instruction (braces needed) */
 if (c == d) {
        do_this();
        do_that();
 }

`If' conditionals can also include an else instruction or block:

 if (tab_size == 8)
        print("You are sane\n");
 else
        print("Weirdo!\n");

While
~~~~~

`While' conditionals are exactly as you suppose they are:

 while (player_is_alive) {
        /* game loop */
        move_player();
        move_baddies();
        update_counter();
 }

As in `if', the loop body needs braces if it has more than one instruction.

Foreach
~~~~~~~

`Foreach' is a special statement to do something with all elements of an
array. The usual construction is as follows:

 /* week days */
 weekdays = [ 'monday', 'tuesday', 'wednesday', 'thurday', 'friday' ];
 
 foreach (w, weekdays)
        print("I hate ", w, "s\n");

Each value of the array will be assigned to the variable and the loop body
executed. The variable is local to the loop body.

Break
~~~~~

Exit from `while' and `foreach' loops can be forced by using `break', just
as in C.

Builtin operators
-----------------

Assignment
~~~~~~~~~~

To assign a value to a variable, use the = operator. Remember that scalars
are always assigned by value, and multiple values (arrays and hashes) are
always assigned by reference (in case you need a copy of a multiple value,
use the clone() function).

Arithmetic
~~~~~~~~~~

The usual +, -, *, /, ** and % operators are used for addition,
substraction, multiply, divide, power and modulo, as always. Operands
for the modulo operator are treated as integers, and for the rest of them,
as real numbers. Operator precedence are like in C; you can always use
parentheses to explicitly force your desired precedence.

Numeric comparison
~~~~~~~~~~~~~~~~~~

The usual == (equality), != (inequality), > (greater than), < (less than),
>= (greater or equal than) and <= (less or equal than) operands can be
used.

Strings
~~~~~~~

The 'eq' operator is used for testing string equality, 'ne' for the
opposite and ~ is used for concatenating strings.

MPSL's scalar values are used for both string and numerical values, so (as
in Perl) the string and numeric comparison operators must be different:

 a = 0; b = 0.0;
 if (a == b) { /* this is truth */ }
 if (a eq b) { /* this is false */ }

Boolean logic
~~~~~~~~~~~~~

As in C, && (logical and) and || (logical or) are used. They don't return
just a boolean value, but the value that matches the condition, so that
you can do:

 a = 0; b = 100;
 c = a || b;            /* c ends with a value of 100 */
 c = a && b;            /* c ends with a value of 0 */
 a = 50;
 c = a || b;            /* c ends with a value of 50 */
 c = a && b;            /* c ends with a value of 100 */

MPSL lacks a ternary conditional operator (as the ? : one in C), but it
can be easily simulated with && and || operators:

 /* assigns to c the greatest of a and b */
 c = a > b && a || b;

There is also the ! operator, that negates a condition.

Immediate operators
~~~~~~~~~~~~~~~~~~~

Immediate operators act directly over variables. The most usual examples
are the unary ++ and --, that are used as in C.

 a = 100;
 a++;           /* a's value is now 101 */
 a--;           /* back to 100 */

Also as in C, this operators can be used as prefixes or suffixes, giving
the following result:

 a = 100;
 b = a++;       /* b's value is 100, a's value is 101 */
 c = ++a;       /* c's and a's value are both 102 */

The well known binary +=, -=, *=, /= and %= also exist:

 a += 25;       /* adds 25 to a */

Subroutines
-----------

Subroutines (also called functions) are created with the 'sub' keyword:

 sub main_loop
 {
        while (!exit_requested) {
                local o;
 
                o = get_option();
                process_option(o);
                draw_screen();
        }
 }

Subroutines can also accept arguments:

 sub process_option(o)
 {
        if (o == -1)
                exit_requested = 1;
        else
                print("Option is ", o, "\n");
 }

Subroutine arguments can be used as local variables (in fact, that is exactly
what they are).

As in assignations, when you pass a multiple value (arrays and hashes) as
an argument to a subroutine, it's always done by reference, so modifying
it will change the original value:

 sub dequeue(queue) { local a = pop(queue); do_something_with(a); }
 
 my_q = [ 10, 20, 30 ];
 dequeue(my_q);         /* on exit, my_q will contain only [ 10, 20 ] */

As every code fragment in MPSL, subroutines always return a value. By
default, a subroutine returns the result of the last operation:

 sub avg(a, b) { a += b; a /= 2; }

The value to be returned can be explicitly expressed by using the 'return'
keyword, that can also be used to break execution flow:

 sub div(a, b)
 {
        if (b == 0) {
                print("Invalid value for b.\n");
                return 0;
        }
 
        return a / b;
 }

When calling a subroutine, parentheses are always mandatory, even if it
has no arguments. If a subroutine is referenced without its arguments,
it's not called, but a pointer to it returned instead:

 sub sum(a, b) { return a + b; }
 
 a = sum(10, 20);       /* a == 30 */
 b = sum;               /* b has a pointer to the sum subroutine */
 
 c = b(20, 30);         /* c == 50, same as calling sum(20, 30) */

The `sub' directive can also be used as an rvalue to define anonymous
subroutines. So, the following can be done:

 on_exit_subs = [];
 push(on_exit_subs, sub { print("Close files\n"); } );
 push(on_exit_subs, sub { print("Clean up memory\n"); } );
 push(on_exit_subs, sub { print("Other stuff\n"); } );
 
 /* exiting; calling all functions stored in on_exit_subs */
 foreach (f, on_exit_subs) f();

Anonymous functions can also accept arguments:

 math_ops = [
        sub (a, b) { print(a, " + ", b, ": ", a + b, "\n"); },
        sub (a, b) { print(a, " - ", b, ": ", a - b, "\n"); },
        sub (a, b) { print(a, " * ", b, ": ", a * b, "\n"); },
        sub (a, b) { print(a, " / ", b, ": ", a / b, "\n"); }
 ];
 
 foreach (f, math_ops) f(10, 20);

This kind of anonymous subroutines are commonly used as callbacks. The
following examples use the two-argument version of sort() to sort arrays
in different ways:

 /* reverse-sort the array (comparing each element backwards) */
 sorted_ary = sort(unsorted_ary, sub (a, b) { cmp(b, a); } );
 
 /* numeric sort (instead of plain ASCII) */
 sorted_ary = sort(unsorted_ary, sub (a, b) { a - b; } );

Subroutines are defined in execution time and *not* in compilation time.
This means that you can redefine a subroutine whenever you want, but be
aware that you can't use it before the `sub' instruction has been
executed. This is a common pitfall:

 /* call a function before it exists: error */
 print("Average for 2 and 3 is ", avg(2, 3), "\n");
 
 sub avg(a, b) { a += b; a /= 2; }
 
 /* now you can use it */
 print("Average for 4 and 5 is ", avg(4, 5), "\n");

It's easier to see subroutine definitions as an assignation of a code
block to a variable: you would never access a variable before assigning a
value to it.

Builtin functions
-----------------

General functions
~~~~~~~~~~~~~~~~~

The cmp() function can be used to compare two values. It returns a signed
number, negative if the first value is lesser than the second, positive
on the contrary or zero if they are the equal. It also can be used to
compare arrays and hashes:

 cmp('a', 'b');         /* < 0 ('a' is lesser than 'b') */
 cmp('aaa', 'aab');     /* < 0 ('aaa' is lesser than 'aab') */
 cmp( [ 1, 2, 3 ],
        [ 1, 2 ]);      /* > 0 ([1,2,3] is greater than [1,2]) */
 cmp( [ 1, 'a', 3 ],
        [ 1, "a", 3 ]); /* 0 (both arrays are equal) */

Arrays are first tested for number of elements (so bigger arrays are
greater than arrays with fewer elements), and if both are equal, then each
element is tested sequentially.

The split() and join() functions can be used to convert strings into
arrays and vice-versa. Examples:

 /* sets a to [ 12, 'abcd', 356, '', 'xxx' ] */
 local a = split('12:abcd:356::xxx', ':');
 
 /* sets b to 12->abcd->356->->xxx */
 local b = join(a, '->');

The split() function can have a special separator, NULL, that makes it
explode the string in characters:

 /* sets c to [ 't', 'h', 'i', 's' ] */
 local c = split("this");

The splice() function can be used to delete, insert or replace a subset of
a string with another one. It returns a two element array: one with the
newly created string, and another with the deleted part. Examples:

 local a = "This is a string";
 
 /* original string, string to be inserted, position, chars to delete */
 splice(a, 'not', 8, 0);        /* [ 'This is not a string', NULL ] */
 splice(a, '', 5, 3);           /* [ 'This a string', 'is ' ] */
 splice(a, 'can be', 5, 3);     /* [ 'This can be a string', 'is ' ] */

The chr() and ord() functions return the character represented by a Unicode
number and vice-versa:

 ord('A');      /* returns 65 (ASCII or Unicode for A) */
 chr(65);       /* return 'A' */

The sprintf() function works like any other sprintf() implementation in
the world: accepts a format string (with special, %-prefixed placeholders)
and a list of arguments, and substitutes them.

 sprintf("%s: %d", 'ERROR', 10);        /* returns 'ERROR: 10' */
 sprintf("%04X", 16384);                /* return '4000' */

The sscanf() function can be seen as the opposite of sprintf(): given a
format string and a scanning string, extracts a set of strings and returns
them as an array.

 sscanf("name 100", "%s %d");           /* returns [ 'name', 100 ] */

The standard %-commands can be used, as %d, %i, %u, %f and %x, for decimal,
unsigned, floating point or hexadecimal numbers, %n, to return a matching
offset, and %[, to match an explicit set of matching characters, than can
be negated by adding a ^ after the bracket. As a non-standard extension, a
special command %S is also implemented, that match a string upto the
following substring in the format string. For example:

 sscanf("key: value", "%S: %S");        /* returns [ 'key', 'value' ] */
 sscanf("text words 1", "%S%d");        /* returns [ 'text words ', 1 ] */

As in the standard, the format can include an optional number of maximum
characters and a * to mark the matched string as non-interesting (so it's
not returned).

The sscanf() function also accepts an optional third argument with an
offset to start scanning.

Array functions
~~~~~~~~~~~~~~~

Arrays can be easily manipulated by using push(), pop(), shift(), adel()
and ins():

 /* an empty array */
 ary = [];
 
 /* add three values: ary will contain [ 10, 20, 30, 40 ] */
 push(ary, 10); push(ary, 20); push(ary, 30); push(ary, 40);
 
 /* delete and return last value; ary contains now [ 10, 20, 30 ]
    and top contains 40 */
 top = pop(ary);
 
 /* shift() deletes from the beginning; ary contains now [ 20, 30 ] */
 first = shift(ary);
 
 /* ins() inserts an element in an array; ary contains now [ 20, 5, 30 ] */
 ins(ary, 5, 1);
 
 */ adel() does the opposite, delete values; ary is back [ 20, 30 ] */
 deleted_item = adel(ary, 1);

The seek() function searches sequentially for an exact value in an array,
returning its offset if found, or -1 otherwise:

 weekdays = [ 'monday', 'tuesday', 'wednesday', 'thurday', 'friday' ];
 
 /* returns 2 */
 seek(weekdays, 'wednesday');

The sort() function returns a sorted copy of the array sent as argument:

 sorted_weekdays = sort(weekdays);

The sorting is done with the cmp() function (see above); if another kind of
sort is wanted, the 2-argument version must be used, as mentioned
previously in the _Subroutines_ section.

Whenever a change must be done on every element of an array, the map()
function can be useful and much faster than iterating the array using
foreach() and storing the changes in another one.

The first argument of map() can be an executable value accepting one
argument, that will be set to each element of the array. The return
value will be used as the new value:

 /* a function to multiply by 10 its unique argument */
 sub multiply_by_10(val)
 {
        val * 10;
 }
 
 /* an array of values */
 a = [ 1, 5, 3, 7, 30, 20 ];
 
 /* a_by_10 will contain [10, 50, 30, 70, 300, 200 ] */
 a_by_10 = map(multiply_by_10, a);

Of course, the executable value can be an anonymous subroutine:

 /* Creates a zero-filled version of the numbers in a */
 a_zero_filled = map( sub(e) { sprintf("%04d", e); }, a);

The first argument of map() can also be a hash to directly
map keys to values:

 /* numerals as keys, names as values */
 english_nums = { 1 => "one", 2 => "two", 3 => "three" };
 
 /* translated_nums will have [ "one", "two", "three" ] */
 translated_nums = map(english_nums, [ 1, 2, 3 ]);

Another powerful array function is grep(); it matches a regular
expression on an array and returns a new one containing all
elements that matched:

 a = [ 1, 9, "mix190", 4, "foo", 9000 ];
 
 /* b is [ 9, "mix190", 9000 ] */
 b = grep('/9/', a);

The first argument of grep() can also be an executable value,
that will accept each element of the array on each call. The
output array will contain all elements for which the function
call returned true:

 /* return all elements greater than 10 */
 a = [ 1, 45, 20, 4, 0, 1000 ];
 
 /* b is [ 45, 20, 1000 ] */
 b = grep( sub(e) { e > 10; }, a);

If no element were generated, NULL is returned (instead of
an empty array).

Other lower level array functions are expand() and collapse().
The expand() function opens space in an array:

 ary = [ 1, 2, 3, 4 ];
 
 /* ary will have two more elements at offset 3,
    containing [ 1, 2, 3, NULL, NULL, 4 ] */
 expand(ary, 3, 2);

On the opposite, collapse() deletes space:

 /* deletes 3 elements at offset 1: ary is now [ 1, NULL, 4 ] */
 collapse(ary, 1, 3);

Take note that expand() and collapse() manipulate the array
directly (i.e. they don't return a new array).

Hash functions
~~~~~~~~~~~~~~

The hsize() function returns the number of pairs in a hash:

 /* returns three */
 num = hsize( { 1 => 'one', 2 => 'two', 3 => 'three' });

Take note that size() cannot be used for this purpose, as it returns the
number of buckets in the hash (which is probably of no use for you).

If the existence of a pair must be tested, the exists() function is handy:

 h = { 'a' => 1000, 'b' => 0, 'c' => 3000 };
 
 /* this is true */
 if (exists(h, 'b')) print("B exists\n");
 
 /* this is not, as 0 does not evaluates as true */
 if (h['b']) print("B is true\n");

The keys() function returns an array with the keys of a hash:

 /* will contain [ 'a', 'b', 'c' ] */
 h_keys = keys(h);

The hdel() function deletes a pair given its key. The deleted value is
returned:

 /* deletes 'c' and returns its value (3000) */
 c_value = hdel(h, 'c');

Type-checking functions
~~~~~~~~~~~~~~~~~~~~~~~

There are three functions to test a type of a value: is_exec(), is_hash()
and is_array(). They return true if the tested value is executable, a hash
or an array, respectively.

On this implementation, executable and hash values are also arrays, so if
you need to act differently on the type of a value, the correct order is
is_exec(), is_hash() and is_array(), as in the following example:

 if (is_exec(v)) { print("v is executable\n"); }
 else
 if (is_hash(v)) { print("v is a hash with ", hsize(v), " pairs\n"); }
 else
 if (is_array(v) { print("v is an array with ", size(v), " elements\n"); }
 else
        print("v is a scalar\n");

Regular expression matching
---------------------------

Regular expression matching is done with the regex() function. In the simpler
of its forms, it can be used to test if a string matches:

 /* hours, minutes, seconds */
 v = "07:55:35";
 
 if (regex("/^[0-2][0-9]:[0-5][0-9]:[0-5][0-9]$/", v))
        print("The v variable contains a valid time\n");

The regular expression can contain flags; those are `i', for case
insensitiveness, `l', to select the last matching instead of the first,
`m', to treat the string as a multiline one (i.e., one containing \n
characters), where the special ^ and $ markup match beginning and end of
lines and not the beginning or end of the string, or `g', to do a global
matching (return _all_ matching strings). Flags are written after the
final slash.

Regex() returns the matched string, or an array of matched strings if
the `g' flag is used. If no match is found, NULL is returned.

 v = "The value of PI is 3.1416, more or less";
 
 pi = regex("/[0-9]+\.[0-9]+/", v);

If regex() is called without arguments, it returns the last match as an array
of two elements; the first contain the offset of the matched strings, and the
second, the size in characters of it. If last match was unsuccessful, NULL is
returned.

 /* get the match of the previous example */
 coords = regex();
 
 /* prints 19:6 */
 print(coords[0], ":", coords[1], "\n");

Regex() can include an optional third argument, the offset where the regular
expression matching must start (instead of 0, the beginning of the string).
This can be used to extract many values from the same string:

 /* lets extract all numbers in the following string: */
 s = "There is 10 and 35 and 42 in the number 103542!";
 offset = 0;
 
 while (n = regex("/[0-9]+/", s, offset)) {
        local c;
 
        /* print result */
        print(n, "\n");
 
        /* get the coordinates */
        c = regex();
 
        /* start from there (previous match offset + size) */
        offset += c[0] + c[1];
 }

Though, for this particular example, the `g' flag could be more suitable:

 /* return all numbers in one step */
 foreach (s, regex('/[0-9]+/g', s))
        print(s, "\n");

For more complex situations, the first argument of regex() can be an array
of regular expressions (instead of a string). Those expressions will tried
one after the other on the string, each one using the offset returned by
the previous one. If all of them are matched, an array with the matched strings
is returned.

 /* match pairs of key=value commands, with many variants */
 v1 = "key1=value1";
 v2 = " KEY2 = value2";
 v3 = "key3=333  ";
 
 /* array regex: a regex for each part */
 r = regex([ "/\s*/",        /* possible leading blanks (0) */
             "/[a-z0-9]+/i", /* the key (1) */
             "/\s*=\s*/",    /* optional blanks, the = , more blanks (2) */
             "/[a-z0-9]+/i"  /* the value (3) */
           ], v1);
 
 if (r != NULL) {
        /* the key is the element #1 and the value the #3 */
        key = r[1];
        value = r[3];
 }

Regular expression substitutions
--------------------------------

The sregex() function can be used to substitute the matching part of a
string with another string. The simplest form:

 /* substitute all characters in password with asterisks */
 sregex('/./g', password, '*');

The substitution part can also be a hash:

 /* substitute \n, \r, etc with their equivalents */
 sregex("/\\[rnt]/g", var, {
        '\r'    =>      "\r",
        '\n'    =>      "\n",
        '\t'    =>      "\t"
        });

Or even a function:

 /* zero-pad all numbers in var */
 sregex('/[0-9]+/g', var, sub (m) {
        sprintf("%04d", m);
        });

The regular expression can contain flags; those are `i', for
case-insensitive matching, and `g', for global replacements (all ocurrences
in the string will be replaced, instead of just the first found).

Input/Output operations
-----------------------

File operations are done by opening files with the open() call. It accepts
two arguments, the file and the mode:

 /* open in read mode */
 local i = open('existingdata.dat', 'r');
 
 /* open in write mode (create) */
 local o = open('newdata.dat', 'w');

The opening mode is the same as the one in the fopen() C library call, so
other combinations exist.

If the file cannot be open or created, NULL is returned.

The read() function returns a line read from a file descriptor, or NULL if
no more lines can be read (i.e. on EOF). A line is considered from the
current file position until an end of line mark (\n or \r\n). All files
under MPSL are considered as text ones; before the read() call returns, the
string is converted to wide chars (the internal representation of strings
in MPSL) by using the current locale definitions, unless a explicit
encoding is set by calling encoding() (see below).

The opposite of read() is write(); it accepts a file descriptor and a
string to be written. As read(), the string is converted from wide chars by
using the current locale definitions unless a different encoding() was set.
The write() function does not write an end of line, though.

Similar functions getchar() and putchar() exist to read and write
characters instead of lines. This functions don't do any locale nor
encoding conversions.

The unlink() function can be used to delete files, chmod() to set the mode
and chown() to set the owner.

The stat() function returns an array containing information about a file,
similar to the C library function of the same name. The returned values
are: device number, inode, mode, number of links, uid, gid, rdev, size,
atime, mtime and ctime. Take note that not all values has meaning depending
on the filesystem or the architecture. The `mode' argument can be used in
chmod() and `uid' and `gid' in chown(). If the file does not exist, stat()
returns NULL (which is a good way to test for file existence).

The glob() function accepts a file spec as the only argument and returns
an array of filenames matching it. Directories have a / as the last
character. The file spec and the returned files are system-dependent, but
always usable by open().

The popen() and pclose() function calls are used for piping from / to
programs. Pipes can be open for reading ('r' mode), for writing ('w' mode),
or bidirectional (by appending '+' to the mode, which can be used to
communicate two-way with programs like ispell, smtp servers and such). Once
open, the read() and write() functions can be used the same as in plain
files.

As mentioned above, the encoding() function can be used to force the
reading or writing conversions to be done when doing IO. By default, the
current locale is used, and it's the same as calling encoding() without
arguments. If an encoding is forced, reading and writing is done by using
the selected converter. Take note that support for the `iconv' library must
be compiled in; if it's not, a special, ad-hoc converter called "utf-8"
is always available.

Each file can have a different encoding converter and is selected at open()
time.

A snippet to convert a file from current locale to iso8859-1 can be:

 sub convert_to_iso8859_1(fromfile, tofile)
 {
        local i, o, l;
        local ret = 0;
 
        /* open the file first */
        if ((i = open(fromfile, 'r')) == NULL)
                return -1;
 
        /* set encoding to iso8859-1 (can fail) */
        if (encoding("iso8859-1") < 0) {
                close(i);
                return -2;
        }
 
        /* create the new file now; it will have iso8859-1
           encoding as it's the last encoding set. The input
           file keeps its original encoding */
        if ((o = open(tofile, 'w')) != NULL) {
                while (l = read(i))
                        write(o, l);
 
                close(o);
        }
        else
                ret = -3;
 
        /* close input and revert to default encoding */
        close(i);
        encoding();
 
        return ret;
 }

The load() function can be used to load, compile and execute an MPSL
source file. The file will be searched for using the paths in the INC
array.

Special symbols
---------------

ARGV
~~~~

Stores the command line arguments sent to the main() function.

INC
~~~

Holds an array of paths on disk where source files will be searched
for by the load() command.

ERROR
~~~~~

Stores the last severe error message (compilation errors, etc.).

ERRNO
~~~~~

Stores the last error message from the system (file not found, etc.).

STDIN, STDOUT, STDERR
~~~~~~~~~~~~~~~~~~~~~

The famous standard file descriptors. Can be used in read(), write()
and related functions.

HOMEDIR
~~~~~~~

The home directory for the current user. It's supposed to be a writable
directory where users can store their configuration and documents.

APPDIR
~~~~~~

The application directory.

ENCODING
~~~~~~~~

The last successful charset encoding set by the encoding() function.

TEMP_ENCODING
~~~~~~~~~~~~~

Similar to ENCODING, but used only when opening a file for writing and
if ENCODING is not set. After opening, its content is destroyed.

DETECTED_ENCODING
~~~~~~~~~~~~~~~~~

Filled after each file opening in read mode, if a specific charset
encoding could be found. Can be copied onto ENCODING or TEMP_ENCODING.

MPSL.VERSION
~~~~~~~~~~~~

Stores the MPSL version as a string.

MPDM()
~~~~~~

This is an accessor / mutator function that allows to retrieve information
and tune some values for the MPDM (Minimum Profit Data Manager). If called
without arguments, the current values are returned. A hash can be sent as
argument to change some of them. These are the keys:

 * count: Total number of values being managed (read only).
 * hash_buckets: The default number of buckets a hash will use. It must
   be a prime number (read / write).

The default values are the best for normal usage. Of course, you only must
change any of them if you know what you are doing.

Examples:

 /* set a bigger value for hash buckets */
 MPDM( { 'hash_buckets' => 127 });
 
 /* dump current setup */
 dump(MPDM());

----
Angel Ortega <angel@triptico.com>