ngeor / rusty-basic

An interpreter for QBasic, written in Rust.

rusty-basic

An interpreter for QBasic, written in Rust.

Goals

The primary goal is to have an interpreter compatible with QBasic.

• Be able to interpret the sample TODO.BAS from my basic Docker project ✅
• Be able to interpret MONEY.BAS (an original demo program from QBasic) ✅

Secondary goals:

• Be able to cross-compile to Rust and/or JavaScript
• Unit tests for QBasic programs, with code coverage
• VS Code debugging

Development

Tip: run tests continuously with make watch or nodemon -e rs -x "cargo test".

Architecture

• Parsing
• Linting
• Instruction generation
• Instruction interpretation

Parsing

A program is read from a file character by character.

input (file or str) -> CharReader -> EolReader -> Parser

• CharReader returns one character a time, working with a BufRead as its source.
• EolReader adds support for row-col position, handling new lines.
• Parsing is done with parser combinators, ending up in a parse tree of declarations, statements, expressions, etc.

Linting

The next layer is linting, where the parse tree is transformed into a different tree. In the resulting tree, all types are resolved. Built-in functions and subs are identified.

Instruction generation

The instruction generator converts the linted parser tree into a flat list of instructions (similar to assembly instructions).

Instruction interpretation

This is the runtime step where the program is being run, interpreted one instruction at a time.

Names

Bare and qualified names

In QBasic, you can have a simple variable like this A = 42.

You can also specify its type like this A$ = "Hello, world!".

In rusty-basic, the first style is called bare name and the second style is called qualified name. The character that denotes the type is called a type qualifier.

There are five of these characters, matching the five built-in types:

• % for integer
• & for long
• ! for single
• # for double
• $ for string

Bare names also have a type. By default, it's single. So typing A and A! will point to the same variable.

The default type can be changed to integer with the DEFINT A-Z statement. There's also DEFLNG, DEFSNG, DEFDBL and DEFSTR.

This simple name resolution mechanism gets a bit more complicated with the AS keyword.

Extended names

For the lack of a better name, rusty-basic calls these variables extended:

• DIM A AS INTEGER
• DIM A AS SomeUserDefinedType
• FUNCTION Add(A AS INTEGER, B AS INTEGER)

These names:

• cannot have a type qualifier (i.e. you can't say DIM A$ AS INTEGER)
• when in scope, you can't have any other qualified name of the same bare name

So it's possible to have this:

A = 42 ' this is a single by default name resolution
A$ = "hello"

But not this:

DIM A AS INTEGER
A = 42 ' this is an integer because it's explicitly defined as such
A$ = "hello" ' duplicate definition error here

rusty-basic's Issues

Support DIM SHARED

• Gives subprograms access to module (global) variables
• Only allowed on module level, throws an error if used on sub/fn level
• Cannot DIM a variable by the same name in a sub/fn level

Implement EXIT SUB

Support DIM keyword for built-in types

e.g.

DIM X AS STRING
X = "hello"
PRINT X

should print hello (even though X is not marked with the dollar sign).

X = 42 should yield a Type Mismatch error, as X is a string

Built-in types: Integer, Long, Single, Double, String

Support PRINT with comma and semicolon separators

PRINT with comma should print at the next print zone (14 characters wide).
PRINT with semicolon should print immediately after the previous expression.
It is possible to combine commas and semicolons in one PRINT statement.
Positive numbers have a leading space (possibly to align with the minus sign of negative numbers).
Numbers have a trailing space even when using semicolons.

Bug: support space after sub name

DECLARE SUB ScrollUp () (note the extra space after the sub name)

Add the parsed text to the token as a reference

e.g.

ExpressionNode( A + B )

should have a function:

pub fn get_captured_text(&self) -> &str {
}

that returns A + B

Support user defined types

Support parser unit tests without matching location

How to deal with comments

Implement random access files

Example statements

OPEN file$ FOR RANDOM AS #1 LEN = 84
FIELD #1, 8 AS IoDate$, 10 AS IoRef$
GET #1, 1
LSET IoDate$ = ""
PUT #1, 2

For OPEN:

• LEN = reclen%, only for random access files, the record length in bytes. The default is 128 bytes.
• RANDOM is the default file mode

For FIELD:

FIELD [#]filenumber%, field-width% AS string-variable$ [, field-width% AS string-variable$ ] ...

For GET and PUT:

GET [#]filenumber% [, [record-number&][,variable] ]
PUT [#]filenumber% [, [record-number&][,variable] ]

For LSET and RSET:

LSET and RSET move data into a random-access file buffer (in preparation for a PUT statement) and left- or right- justify the value of a string variable. LSET also copies the contents of one record variable to another.

LSET string-variable$ = string-expression$
RSET string-variable$ = string-expression$
LSET record-variable1 = record-variable2

Support popping arguments in built-in functions to avoid clone

For example, in ubound.rs:

let v: Variant = interpreter.context()[0].clone()

can be done by popping the variant instead.

Note that this is more difficult due to the way ByRef arguments are implemented (they're expected to be in-place, so popping causes issues).

Support DIM with fixed string length

e.g. DIM X AS STRING * 5

Note that this is not supported for parameters

Support arrays

Arguments should be ByVal when in parenthesis

When you call the SUB procedure, you can specify that an argument's value will not be changed by the procedure by enclosing the argument in parentheses

Rename binary to rusty_basic

Support multiple case expressions

e.g. CASE 24, 25

Setup CI pipeline

Ideally it should publish the artifact in the GitHub release

Migrate issues from old repo

Move issues from the dockerfiles repo here

Implement DEF SEG

DEF SEG [=address]

Sets the current segment address.

Used by BLOAD, BSAVE, CALL ABSOLUTE, PEEK OR POKE. Address is a value in the range 0 to 65535. If omitted, resets the current segment.

Implement the following example:

DIM ScrollUpAsm(1 TO 7) ' notice 7 elements here
P = VARPTR(ScrollUpAsm(1))
DEF SEG = VARSEG(ScrollUpAsm(1))
FOR I = 0 TO 13 ' but 14 iterations here
    READ J
    POKE (P + I), J
NEXT I

Visual Studio Code debugger extension

Implement pretty printer

Implement pretty printer. It should indent elements and preserve comments.

Support renaming directories in NAME

Support GOSUB

Implement MOD operator (modulo)

PRINT 19 MOD 6.7
QBasic rounds 6.7 to 7, then divides. Output is 5.

Implement DATA statement

Implement DATA and READ statements

e.g.

DATA "hello", 42
READ A$, B%
PRINT A$, B%

Can throw runtime error "Out of DATA" (or type mismatch)

Support RESUME and RESUME NEXT

FaaS PoC

Performance drop from 0.3.0 to 0.4.0

When running a performance test, it seems that version 0.3.0 averages on 265msec and 0.4.0 on 429msec.

Cross-compiler to rust

Serve HTTP without Apache PoC

Outgoing HTTP calls PoC

Support hexadecimal literals

e.g. &H10

Allow keywords as variable names for compact string variables

This is allowed:

DIM DIM$

The rest aren't:

DIM DIM
DIM DIM!
...

Compiler - Generate DOS binary

should run from Windows 3.x until Windows 10

Implement WIDTH

e.g. WIDTH , 25

Assign an output-line width to a device or file

WIDTH [columns%] [,rows%]
WIDTH #filenumber% columns%
WIDTH LPRINT columns%

[Tech Debt] Unify or refactor errors

• Each layer has its own error similar error class. See if we can reduce their number (e.g. ParseError vs RuntimeError).
• Remove the Result<T> aliases, always use Result<T, E>

Implement STATIC sub

unit testing and code coverage

Functions that start with Test could be considered as unit tests and they can return a boolean condition to indicate pass or fail:

FUNCTION Add(a, b)
    Add = a + b
END FUNCTION

FUNCTION TestAdd
    TestAdd = Add(1, 2) = 3
END FUNCTION

basic-interpreter-rust PROGRAM.BAS --test --with-code-coverage

Support multiple variables in a single DIM

Implement GW-Basic interpreter/compiler

Remove Expression::Constant from linter, use resolved variant value

Implement DO LOOP

DO [ WHILE | UNTIL ] condition
    statements
LOOP

or

DO
    statements
LOOP [ WHILE | UNTIL ] condition

Support CLOSE without arguments

CLOSE without arguments closes all open files

Implement REDIM

Pre-parser?

Consider adding a layer between the lexer and the parser. It would generate a flat list of items (not a parse tree) but a bit richer than the ones the lexer generates.

Example items:

• Comment(String)
• Operand(LessOrEqual)

[Tech Debt] Remove Location from LexemeNode

Make MONEY.BAS work

Code generator for parser code

Would it be possible to automatically generate some of the parsing code?

Evaluate https://crates.io/crates/nom ( https://github.com/Geal/nom ) and https://crates.io/crates/racc ( https://github.com/sivadeilra/racc )

Evaluate parser combinators as it is closer to what rusty-basic already does http://theorangeduck.com/page/you-could-have-invented-parser-combinators

Add a flag to indicate if running on Apache

When running in Apache with cgi-bin we have two hacks in place:

• reading the program from the BLR_PROGRAM variable
• setting the current directory to the program's current directory

These two hacks should be applied only when running in Apache.

Implement VIEW PRINT

Sets the boundaries of the screen text viewport

VIEW PRINT [toprow% TO bottomrow%]

If the arguments are omitted, the entire screen will be used as the text viewport.