## Developer's guide

The features described in this guide are intended for Python developers only. They are experimental, may not work as expected, and may be removed from future releases without warning. You may not be able to get help if you have any problems. Luckily, none of the features described here are needed for the normal functioning of PC-BASIC.

### Session API

PC-BASIC can be loaded as a package from Python, which makes it possible to call BASIC code directly from Python.

##### class `Session(**kwargs)`

Open a PC-BASIC session. The session object holds the interpreter state, e.g. the value of variables, program code and pointers, screen state, etc. Note that `Session` can be used as a context manager with the `with` statement.

Keyword arguments are largely (but not entirely) analogous to PC-BASIC command-line options.

By default, the Session object grabs the standard input and output as keyboard an screen. This may be undesirable in some applications; in such cases, set the keyword arguments `input_streams` and `output_streams` explicitly (for example, to `None`).

##### `execute(basic_code)`

Execute BASIC code. `basic_code` can be commands or program lines, separated by `\n` or `\r`.

##### `evaluate(basic_expr)`

Evaluate a BASIC expression and return its value as a Python value. For type converson rules, see `get_variable`.

##### `set_variable(name, value)`

Set the value of a scalar or array to a Python value.

`name` is a valid BASIC name, including the sigil, and is not case-sensitive. If the target is an array, `name` should end with `()`.

`value` should be of a compatible type: `int`, `bool` or `float` for numeric variables and `bytes` or `unicode` for strings. If the target is an array, `value` should be a `list` of such values. Multi-dimensional arrays should be specified as nested `list`s.

`bool`s will be represented as in BASIC, with `-1` for `True`. `unicode` will be converted according to the active codepage.

##### `get_variable(name)`

Retrieve the value of a scalar or array as a Python value.

`name` is a valid BASIC name, including the sigil, and is not case-sensitive. If the target is an array, `name` should end with `()`.

Integers will be returned as `int`, single- and double-precision values as `float`, and string as `bytes`. If the target is an array, the function returns a (nested) `list` of such values.

##### `close()`

Close the session: closes all open files and exits PC-BASIC. If used as a context manager, this method is called automatically.

### Extensions

It's possible to enable your own BASIC statements using extensions. An extension is a Python object or module loaded through the `--extension` option or through the `extension` parameter of the `Session` object.

Python functions and other callable objects in the extension's namespace will be made accessible through basic as extension statements or functions whose name starts with an underscore `_`

In order for this to work, the function must have a name that is also a valid BASIC variable name: alphanumeric only, no underscores, not equal to a BASIC keyword. The name will be case-insensitive in BASIC; that is, `def mytestfunc(): print 1` and `def myTestFunc(): print 2` both map to the extension statement or function `_MYTESTFUNC`. Which one of these functions would be chosen is not defined, so avoid this situation.

Any arguments provided to the extension statement or function are supplied to the Python function as the corresponding type: BASIC integers become `int`s, single- and double-precision numbers become `float`s and strings become `bytes` (not `unicode` and no codepage conversions are applied).

For example, a call to `_MYTESTFUNC 5, "test-string"` would expect to find a Python function `mytestfunc(i, s)` with two parameters, and will supply `i=int(5)` and `a=bytes('test-string')`.

The same Python function can also be called as an extension function, e.g. `A = _MYTESTFUNC(5, "test-string")`. If called as a function, `mytestfunc(i, s)` must return a value that is one of `int`, `float`, both of which will be converted to a BASIC double-precision float; `bool`, which will be converted to a BASIC integer; or `bytes` or `unicode`, which will be converted to a BASIC string.

### Examples

    import pcbasic
    import random

    with pcbasic.Session(extension=random) as s:
        s.execute('a=1')
        print s.evaluate('string$(a+2, "@")')
        s.set_variable('B$', 'abcd')
        s.execute('''
            10 a=5
            20 print a
            run
            _seed(42)
            b = _uniform(a, 25.6)
            print a, b
        ''')