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

bools 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 ints, single- and double-precision numbers become floats 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
    ''')