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.
PC-BASIC can be loaded as a package from Python, which makes it possible to call BASIC code directly from Python.
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.
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.
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
''')