Home

Awesome

Go Report Card license Release

05 PRINT "Index"

<br /> <br /> <br /> <br />

10 PRINT "GOBASIC!"

This repository contains a naive implementation of BASIC, written in Golang.

If you'd prefer to see a more "real" interpreted language, implemented in Go, you might prefer monkey.

The implementation is simple for two main reasons:

The following obvious primitives work as you'd expect:

Most of the maths-related primitives I'm familiar with are also present, for example SIN, COS, PI, ABS, along with the similar string-related primitives:

<br /> <br /> <br /> <br />

20 PRINT "Limitations"

This project was started as a weekend-project, although it has subsequently been improved and extended.

The code has near-total test-coverage, and has been hammered with multiple days of fuzz-testing (i.e. Feeding random programs into the interpreter to see if it will die - see FUZZING.md for more details on that.)

That said there are some (obvious) limitations:

Arrays

Arrays are used just like normal variables, but they need to be declared using the DIM statement. Individual elements are accessed using the offsets in brackets after the variable name:

10 DIM a(10,10)
20 LET a[1,1]=10
30 PRINT a[1,1], "\n"

Arrays are indexed from 0-N, so with an array size of ten you can access eleven elements:

 10 DIM a(10)
 20 a[0] = 0
 30 a[1] = 1
 40 ..
 90 a[9] = 9
100 a[10] = 10

ZX Spectrum BASIC indexed arrays from 1, denying the ability to use the zeroth element, which I've long considered a mistake.

Line Numbers

Line numbers are mostly optional, for example the following program is valid and correct:

 10 READ a
 20 IF a = 999 THEN GOTO 100
 30 PRINT a, "\n"
 40 GOTO 10
100 END
    DATA 1, 2, 3, 4, 999

The main reason you need line-numbers is for the GOTO and GOSUB functions, if you prefer to avoid them then you're welcome to do so.

IF Statement

The handling of the IF statement is perhaps a little unusual, since I'm used to the BASIC provided by the ZX Spectrum which had no ELSE clause. The general form of the IF statement I've implemented is:

IF $CONDITIONAL THEN $STATEMENT1 [ELSE $STATEMENT2]

Only a single statement is permitted between "THEN" and "ELSE", and again between "ELSE" and NEWLINE. These are valid IF statements:

IF 1 > 0 THEN PRINT "OK"
IF 1 > 3 THEN PRINT "SOMETHING IS BROKEN": ELSE PRINT "Weird!"

In that second example you'll see that ":" was used to terminate the PRINT statement, which otherwise would have tried to consume all input until it hit a newline.

The set of comparison functions probably includes everything you need:

You can see several examples of the IF statement in use in the example examples/70-if.bas.

DATA / READ Statements

The READ statement allows you to read the next value from the data stored in the program, via DATA. There is no support for the RESTORE function, so once your data is read it cannot be re-read.

Builtin Functions

You'll also notice that the primitives which are present all suffer from the flaw that they don't allow brackets around their arguments. So this is valid:

10 PRINT RND 100

But this is not:

10 PRINT RND(100)

This particular problem could be fixed, but I've not considered it significant.

Types

There are no type restrictions on variable names vs. their contents, so these statements are each valid:

The sole exception relates to the INPUT statement. The INPUT statement prompts a user for input, and returns it as a value - it doesn't know whether to return a "string" or a "number". So it returns a string if it sees a $ in the variable name.

This means this reads a string:

10 INPUT "Enter a string", a$

But this prompts for a number:

10 INPUT "Enter a number", a

This seemed better than trying to return a string, unless the input looked like a number (i.e. the input matched /^([0-9\.]+)$/ we could store a number, otherwise a string).

<br /> <br /> <br /> <br />

30 PRINT "Installation"

We don't pull in any external dependencies, except for the embedded examples, so installation is simple.

git clone https://github.com/skx/gobasic
cd gobasic
go install

You can also install directly via:

go install github.com/skx/gobasic@latest

If you don't have a golang environment setup you should be able to download a binary release from our release page:

<br /> <br /> <br /> <br />

40 PRINT "Usage"

gobasic is very simple, and just requires the name of a BASIC-program to execute. Write your input in a file and invoke gobasic with the path.

For example the following program was useful to test my implementation of the GOTO primitive:

 10 GOTO 80
 20 GOTO 70
 30 GOTO 60
 40 PRINT "Hello, world!\n"
 50 END
 60 GOTO 40
 70 GOTO 30
 80 GOTO 20

Execute it like this:

$ gobasic examples/10-goto.bas

NOTE: I feel nostalgic seeing keywords in upper-case, but PRINT and print are treated identically.

<br /> <br /> <br /> <br />

50 PRINT "Implementation"

A traditional interpreter for a scripting/toy language would have a series of well-defined steps:

As is common with early 8-bit home-computers this implementation is a little more BASIC:

As there is no AST step errors cannot be detected prior to the execution of programs - because we only hit them after we've started running.

<br /> <br /> <br /> <br />

60 PRINT "Sample Code"

There are a small number of sample-programs located beneath examples/. These were written in an adhoc fashion to test various parts of the implementation.

Perhaps the best demonstration of the code are the following two samples:

<br /> <br /> <br /> <br />

70 PRINT "Embedding"

The interpreter is designed to be easy to embed into your application(s) if you're crazy enough to want to do that!

You can see an example in the file embed/main.go.

The example defines several new functions which can be called by BASIC:

When the script runs it does some BASIC variable manipulation and it also creates a PNG file - the PLOT function allows your script to set a pixel and the CIRCLE primitive draws an outline of a circle. Finally the SAVE function writes out the result.

Extending this example to draw filled circles, boxes, etc, is left as an exercise ;)

Hopefully this example shows that making your own functions available to BASIC scripts is pretty simple. (This is how SIN, COS, etc are implemented in the standalone interpreter.)

<br /> <br /> <br /> <br />

75 PRINT "DoS"

When it comes to security problems the most obvious issue we might suffer from is denial-of-service attacks; it is certainly possible for this library to be given faulty programs, for example invalid syntax, or references to undefined functions. Failures such as those would be detected at parse/run time, as appropriate.

In short running user-supplied scripts should be safe, but there is one obvious exception, the following program is valid:

10 PRINT "STEVE ROCKS!"
20 GOTO 10

This program will never terminate! If you're handling untrusted user-scripts, you'll want to ensure that you explicitly setup a timeout period.

The following will do what you expect:

// Setup a timeout period of five seconds
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

// Now create the interpreter, via the tokenizer
t := tokenizer.New(string(`10 GOTO 10`))

// Ensure we pass the context over
e, err := eval.NewWithContext(ctx,t)
if err != nil {
   fmt.Printf("error creating interpreter: %s\n", err.Error())
   panic(err)   // proper handling here
}

// Now run the program
err = e.Run()
if err != nil {
  fmt.Printf("error running: %s\n", err.Error())
  panic(err)   // proper handling here
}

// Here we'll see a timeout eror

The program will be terminated with an error after five seconds, which means that your host application will continue to run rather than being blocked forever!

80 PRINT "Visual BASIC!"

Building upon the code in the embedded-example I've also implemented a simple HTTP-server which will accept BASIC code, and render images!

To run this:

cd goserver ; go build . ; ./goserver

Once running open your browser at the URL:

The view will have an area of entering code, and once you run it the result will be shown in the bottom of the screen. Something like this:

alt text

There are several included examples which you can load/launch by clicking upon them.

<br /> <br /> <br /> <br />

90 PRINT "Bugs?"

It is probable that bugs exist in this interpreter, but I've tried to do as much testing as I can. If you spot anything that seems wrong please do report an issue.

The project contain a number of test-cases, which you can execute like so:

$ go test ./...

Finally if our test-coverage drops beneath 95% that is a bug. The test coverage of most of our packages is 100%, unfortunately the main eval/ package is not yet completely covered.

You can see the global coverage via:

$ ./test-coverage
97.9%

In addition to the test-cases which have been manually written the interpreter has also been fuzz-tested, which has resulted in some significant improvements.

See FUZZING.md for details of how to run the fuzz-tests.

<br /> <br /> <br /> <br />

100 PRINT "Project Goals / Links"

It is never the intention of this project to support all things that are possible in the various dialects of BASIC.

There are facilities which will make porting programs useful, such as the ability to use WHILE/END loops, functions with named-parameters, and primitives such as SLEEP, BEEP, & etc.

Above all else this project is supposed to be fun, for me. Which means if there are two ways of implementing something I'll pick the way I remember back when I was 12 and computers were .. fun!

If there are feature-requests which seem less fun, and less immediately useful to me - with my biased memories of coding on a ZX Spectrum - I will tag them "wontfix". If you contribute a pull-request to support them I will accept them, but I'm probably not likely to work upon them directly.

That said there are cases where I can be persuaded, and there are a lot of other BASIC intepreters out there, so I won't feel bad if this particular project doesn't suit your needs.

One project, slightly related to this, which might be worth checking up on is this one:

Github Setup

This repository is configured to run tests upon every commit, and when pull-requests are created/updated. The testing is carried out via .github/run-tests.sh which is used by the github-action-tester action.

Releases are automated in a similar fashion via .github/build, and the github-action-publish-binaries action.

Steve