MPSL C API
==========

This reference documents version 2.2.2 of the C API.

By Source
---------

mpsl.y
~~~~~~

 * ./#mpsl_compile (mpsl_compile)
 * ./#mpsl_compile_file (mpsl_compile_file)
 * ./#mpsl_eval (mpsl_eval)

mpsl_c.c
~~~~~~~~

 * ./#mpsl_argv (mpsl_argv)
 * ./#mpsl_boolean (mpsl_boolean)
 * ./#mpsl_error (mpsl_error)
 * ./#mpsl_get_symbol (mpsl_get_symbol)
 * ./#mpsl_is_true (mpsl_is_true)
 * ./#mpsl_set_symbol (mpsl_set_symbol)
 * ./#mpsl_shutdown (mpsl_shutdown)
 * ./#mpsl_startup (mpsl_startup)
 * ./#mpsl_trap (mpsl_trap)

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

 * ./#mpsl_argv (mpsl_argv) - Fills the ARGV global array.
 * ./#mpsl_boolean (mpsl_boolean) - Returns 'true' or 'false' MPSL stock values.
 * ./#mpsl_compile (mpsl_compile) - Compiles a string of MPSL code.
 * ./#mpsl_compile_file (mpsl_compile_file) - Compiles a file of MPSL code.
 * ./#mpsl_error (mpsl_error) - Generates an error.
 * ./#mpsl_eval (mpsl_eval) - Evaluates MSPL code.
 * ./#mpsl_get_symbol (mpsl_get_symbol) - Gets the value of a symbol.
 * ./#mpsl_is_true (mpsl_is_true) - Tests if a value is true.
 * ./#mpsl_set_symbol (mpsl_set_symbol) - Sets value to a symbol.
 * ./#mpsl_shutdown (mpsl_shutdown) - Shuts down MPSL.
 * ./#mpsl_startup (mpsl_startup) - Initializes MPSL.
 * ./#mpsl_trap (mpsl_trap) - Install a trapping function.


mpsl_argv
---------

Name
~~~~

*mpsl_argv* - Fills the ARGV global array.

Synopsis
~~~~~~~~

 void mpsl_argv(int argc, char *argv[]);

Arguments
~~~~~~~~~

 * argc: number of arguments
 * argv: array of string values

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

Fills the ARGV global MPSL array with an array of arguments. These
are usually the ones sent to main().


mpsl_boolean
------------

Name
~~~~

*mpsl_boolean* - Returns 'true' or 'false' MPSL stock values.

Synopsis
~~~~~~~~

 mpdm_t mpsl_boolean(int b);

Arguments
~~~~~~~~~

 * b: boolean selector

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

Returns MPSL's 'false' or 'true' values depending on the value in _b_.


mpsl_compile
------------

Name
~~~~

*mpsl_compile* - Compiles a string of MPSL code.

Synopsis
~~~~~~~~

 mpdm_t mpsl_compile(mpdm_t code);

Arguments
~~~~~~~~~

 * code: A value containing a string of MPSL code

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

Compiles a string of MPSL code and returns an mpdm value executable
by mpdm_exec(). If there is a syntax (or other type) error, NULL
is returned instead.


mpsl_compile_file
-----------------

Name
~~~~

*mpsl_compile_file* - Compiles a file of MPSL code.

Synopsis
~~~~~~~~

 mpdm_t mpsl_compile_file(mpdm_t file, mpdm_t inc);

Arguments
~~~~~~~~~

 * file: File stream or file name.
 * inc: search path for source files.

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

Compiles a source file of MPSL code and returns an mpdm value
executable by mpdm_exec(). If _file_ is an MPSL file descriptor,
it's read as is and compiled; otherwise, it's assumed to be a
file name, that will be searched for in any of the paths defined
in the _inc_ array. If the file cannot be found
or there is any other error, NULL is returned instead.


mpsl_error
----------

Name
~~~~

*mpsl_error* - Generates an error.

Synopsis
~~~~~~~~

 mpdm_t mpsl_error(mpdm_t err);

Arguments
~~~~~~~~~

 * err: the error message

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

Generates an error. The _err_ error message is stored in the ERROR
mpsl variable and the mpsl_abort global flag is set, so no further
mpsl code can be executed until reset.


mpsl_eval
---------

Name
~~~~

*mpsl_eval* - Evaluates MSPL code.

Synopsis
~~~~~~~~

 mpdm_t mpsl_eval(mpdm_t code, mpdm_t args, mpdm_t ctxt);

Arguments
~~~~~~~~~

 * code: A value containing a string of MPSL code, or executable code
 * args: optional arguments for @code
 * ctxt: context 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 abort flag is reset on exit.


mpsl_get_symbol
---------------

Name
~~~~

*mpsl_get_symbol* - Gets the value of a symbol.

Synopsis
~~~~~~~~

 mpdm_t mpsl_get_symbol(mpdm_t s, mpdm_t l);

Arguments
~~~~~~~~~

 * s: symbol name
 * l: local symbol table

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

Gets the value of a symbol. The symbol can be local or global
(if the symbol exists in both tables, the local value will be returned).


mpsl_is_true
------------

Name
~~~~

*mpsl_is_true* - Tests if a value is true.

Synopsis
~~~~~~~~

 int mpsl_is_true(mpdm_t v);

Arguments
~~~~~~~~~

 * v: the value

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

If _v_ is a valid MPSL 'false' value (NULL, "" or the "0" string),
returns zero, or nonzero otherwise.


mpsl_set_symbol
---------------

Name
~~~~

*mpsl_set_symbol* - Sets value to a symbol.

Synopsis
~~~~~~~~

 mpdm_t mpsl_set_symbol(mpdm_t s, mpdm_t v, mpdm_t l);

Arguments
~~~~~~~~~

 * s: symbol name
 * v: value
 * l: local symbol table

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

Assigns the value _v_ to the _s_ symbol. If the value exists as
a local symbol, it's assigned to it; otherwise, it's set as a global
symbol (and created if it does not exist).


mpsl_shutdown
-------------

Name
~~~~

*mpsl_shutdown* - Shuts down MPSL.

Synopsis
~~~~~~~~

 void mpsl_shutdown(void);

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

Shuts down MPSL. No MPSL functions should be used from now on.


mpsl_startup
------------

Name
~~~~

*mpsl_startup* - Initializes MPSL.

Synopsis
~~~~~~~~

 int mpsl_startup(void);

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

Initializes the Minimum Profit Scripting Language. Returns 0 if
everything went OK.


mpsl_trap
---------

Name
~~~~

*mpsl_trap* - Install a trapping function.

Synopsis
~~~~~~~~

 mpdm_t mpsl_trap(mpdm_t trap_func);

Arguments
~~~~~~~~~

 * trap_func: The trapping MPSL code

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

Installs a trapping function. The function is an MPSL
executable value receiving 3 arguments: the code stream,
the arguments and the return value of the executed code.

Returns NULL (previous versions returned the previous
trapping function).


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