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

This reference documents version 1.0.8 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)

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_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);

Arguments
~~~~~~~~~

 * file: File stream or file name.

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 MPSL global array (take note that the current
directory is NOT searched by default). 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);

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

Arguments
~~~~~~~~~

 * s: symbol name

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

This function is only meant to be executed from inside an MPSL
program; from outside, it's exactly the same as calling mpdm_sget()
(as the local symbol table won't exist).


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

Arguments
~~~~~~~~~

 * s: symbol name
 * v: value

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

This function is only meant to be executed from inside an MPSL
program; from outside, it's exactly the same as calling mpdm_sset()
(as the local symbol table won't 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.


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