README.md

qbjc

qbjc is a QBasic to JavaScript compiler. It can compile a QBasic / QuickBASIC program to:

• A standalone executable Node.js script, with zero external dependencies; or
• An ES6 module that can be imported and executed in both Node.js and browser environments.

Try it out in the browser: 👉 qbjc.dev 👈

But why?

QBasic was my first introduction to programming as a kid back in the 90s. Despite its many limitations, it really inspired my passion for building things with technology that continues to this day. The balance of simplicity and power made programming feel both approachable and incredibly fun [1].

I wanted to see if I could recreate a little bit of that magic for the modern age, something easy to get started with in today's web-centric world. So this project was born - a QBasic compiler + runtime + basic web IDE that compiles your QBasic code to JavaScript!

[1] See also: 30 years later, QBasic is still the best

Usage

qbjc playground

The qbjc playground (👉 qbjc.dev 👈) allows you to edit and run QBasic / QuickBASIC programs directly in the browser, no installation required.

Command line usage

# Install qbjc from NPM
npm install -g qbjc

# Compile hello.bas and write output to hello.bas.js
qbjc hello.bas

# Run the compiled program
./hello.bas.js

# ...or run hello.bas directly:
qbjc --run hello.bas

# See all command line options
qbjc --help

API usage

Compiling a QBasic program:

import {compile} from 'qbjc';

...
const {
  // Compiled JavaScript code.
  code,
  // Sourcemap for the compiled JavaScript code.
  map,
  // Abstract syntax tree representing the compiled code.
  astModule,
} = await compile({
  // QBasic source code.
  source: 'PRINT "HELLO WORLD"',
  // Optional - Source file name (for debugging information).
  sourceFileName: 'hello.bas',
  // Optional - Whether to bundle with Node.js runtime code in order
  // to produce a standalone script.
  enableBundling: false,
  // Optional - Whether to minify the output.
  enableMinify: false,
});

Executing the compiled code:

• In browsers (using xterm.js):

  import {Terminal} from 'xterm';
  import {BrowserExecutor} from 'qbjc/browser';
  
  // Set up xterm.js Terminal instance
  const terminal = new Terminal(...);
  
  await new BrowserExecutor(terminal).executeModule(code);

• In Node.js:

  import {NodeExecutor} from 'qbjc/node';
  
  await new NodeExecutor().executeModule(code);

• In Node.js with bundling enabled (i.e. compiled with enableBundling: true):

  import {run} from './hello.bas.js';
  await run();

Compatibility

What works:

• Core language features

  • Control flow structures - loops, conditionals, GOTO, GOSUB etc.
  • Data types - primitive types, arrays and user-defined types (a.k.a. records)
  • Expressions - arithmetic, string, comparison, boolean
  • SUBs and FUNCTIONs
  • DATA constants
  • Many built-in commands and functions like VAL, STR$, INSTR, MID$

• Text mode

  • Basic text mode I/O - PRINT, INPUT, INKEY$, INPUT$ etc.
  • Text mode screen manipulation - COLOR, LOCATE etc.
  • Note that the current implementation depends on a VT100-compatible terminal emulator.
    • On Windows, this means using WSL or something like PuTTY.
    • In the browser, the implementation uses xterm.js.

• It's just enough to run the original NIBBLES.BAS game that shipped with QBasic:

What doesn't work (yet):

• Graphics and audio
• Events - ON ERROR, ON TIMER etc.
• OS APIs like file I/O, CALL INTERRUPT etc.
• Direct memory access - PEEK, POKE etc.
• Less common syntax, inputs or options
• ...and more - contributions are welcome!

For detailed compatibility information on individual commands and functions, see 👉 Implementation Status.

About

qbjc is distributed under the Apache License v2.