# MPSL C API

This reference documents version 1.0.8 of the C API.

## By Source

### mpsl.y

- mpsl_compile
- mpsl_compile_file
- mpsl_eval

### mpsl_c.c

- mpsl_argv
- mpsl_boolean
- mpsl_error
- mpsl_get_symbol
- mpsl_is_true
- mpsl_set_symbol
- mpsl_shutdown
- mpsl_startup

## Alphabetical

- mpsl_argv - Fills the ARGV global array.
- mpsl_boolean - Returns 'true' or 'false' MPSL stock values.
- mpsl_compile - Compiles a string of MPSL code.
- mpsl_compile_file - Compiles a file of MPSL code.
- mpsl_error - Generates an error.
- mpsl_eval - Evaluates MSPL code.
- mpsl_get_symbol - Gets the value of a symbol.
- mpsl_is_true - Tests if a value is true.
- mpsl_set_symbol - Sets value to a symbol.
- mpsl_shutdown - Shuts down MPSL.
- 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 mp_doccer 1.2.2