Matanuska BASIC

Matanuska is a BASIC dialect designed for use as a shell. It asks what it would've been like if the classic 80s BASIC was better able to rise to the occasion when it came to disk features and/or competing with DOS.

Matanuska is still in development, and needs a lot of work before it's ready for regular use.

Install

There currently aren't any installable packages for Matanuska. If you would like to try it today, follow the instructions for development.

Development

Matanuska BASIC uses npm for all of its tasks. Refer to package.json for details.

ADRs

Architectural decisions are documented in ./adrs. Notes on future decisions I haven't made yet are in ./adrs/draft.

Current Status and Next Steps

The interpreter can run "hello world" in a REPL and evaluate simple expressions. Now is time to add some basic features and button up a few gaps.

Prioritized Backlog

• paths argument for github actions
• Path navigation builtins
  • cd
  • pwd
• Functions
  • Function syntax ADR
  • Add keywords to tokens/scanner
  • Add support to parser
  • Parser tests for functions
  • Add new op codes
  • Add support in runtime
  • Add support to disassembler
  • Add support to compiler
  • Compiler tests for functions
  • Runtime tests
  • Examples
  • Native function support
• Tests for InstrShifter in editor
• Support entering multiple lines in REPL
  • ADR
  • Probably a Reader class that handles readline stuff
  • Probably track block nesting
• Shell commands
  • Will need to research jobs in Bash
  • Investigate alt-shells
    • fish
    • nushell
    • elvish
  • Scanner and parser support for shell commands and "shell tokens"
  • Compiler support for shell commands
  • Host support for shell commands
  • Runtime support for shell commands
  • Support \j in prompt rendering
  • (Pipes will come later)
• PS1/PS2 support
  • SET PS1 and SET PS2?
• Runtime tests for Jump and Loop

Up Next

• Closures
  • Closures ADR
  • ???
• More robust citree parser
  • Setting defaults in List instr is no bueno
• Complete Print/Format syntax
  • Support ECMA-55?
  • Complete ADR
  • Print can take a channel config
• Shell variable export
• Date/Time/Duration/TZData types
  • Core library
  • Host support
  • (Language support can come later)
• Consider using end keyword as general purpose block end keyword
  • Finalize ADR
• Support next and continue keywords in loops
• Support for HISTSIZE and HISTFILESIZE
• Telemetry improvements
• Pipes support
• GOTOs
  • Probably a second pass on the chunk
  • Probably need to enforce being within current block/scope tree
  • Will need to close appropriate scopes
• Type-checking compiler
  • Implement type analogues to operations
  • Simulated stack in the compiler
• Add trace events to parser and compiler
• Audit/document OTEL environment variables
• Add tflint and terraform validate
  • entrypoint
  • fireball
• Split matanuska into modules
• grabthar improvements
  • swc cli build option
  • automatically update package.json
  • lint-staged and husky support
  • grabthar clean
• Assert module
  • Wrap 'node:assert'
  • Throw RuntimeFault
• Investigate Node.js inspector
• Escaped newlines
• Arrays
  • Including array literals - BASIC assigns each index one at a time, or uses the data command
  • Consider using eigen
• Environment info in runtime fault outputs
  • envinfo for inspiration
  • OS
  • CPU
  • Memory
  • Build tool versions (cmake, make, etc) if compiling native code
  • Will need to scrub from format test snapshot
• Implement Acey Ducey
  • center$(n)
  • rnd! (random) function
  • If/then/goto
  • functions
  • no-arguments print
  • end command
• Hashes
• Date/time language support
• Exception language support
• Test harness
  • test and assert commands
  • Runtime "test mode" and entrypoint subcommand
  • Reporter, possibly based off node-tap
• File I/O
• Research garbage collection
  • TypeScript is obviously garbage collected
  • But the architecture may hang onto references I don't want
• Tab-complete support in the REPL
• Starship support
• Stream/pipe support
• Break-in
  • MSX BASIC uses the stop and cont commands to control break-in behavior
  • Will need to intercept and handle ctrl-c from readline (ctrl-stop in MSX BASIC)
• Symbol dump
• Profiling
  • Line-based for users
  • Opcode-based for me
• Performance tests
  • Benchmarks
  • Profile slow benchmarks
• Editor plugins
• Generated "exceedingly large" script tests

The Future

• Optimize identifier constants - see ADR 019
• Reimplement citree in Rust and chumsky
• String templates
• Module system
• Package manager
• Partial rewrite in Rust and/or C/C++
• Implement entry point in Rust or C/C++
• Port to bun?
  • Nice FFI
  • Support for bundled executable
• Object support
• Vector/matrix support for 1D/2D integer/float arrays
• Assembler mini-language
• Stack trace tests robust against different node versions

Resources

• Architecture Diagram on Google Drawings
• Crafting Interpreters by Robert Nystrom
  • My implementations of lox: https://github.com/jfhbrook/crafting-interpreters
  • A blog series on adding exception handling to clox
• Writing Interactive Compilers and Interpreters by PJ Brown
• Modern MSX BASIC Game Development by Raul Portales
• List of Java bytecode instructions
• Z80 Instruction Set (Complete)
• OpenJDK Architecture
• cpython internals
  • Python disassembler
• MSX2 Technical Handbook
• MSX-BASIC Instructions - MSX Wiki
• An Introduction to Programming BBC BASIC
• BBC BASIC Reference Manual
• GW-BASIC User's Guide
• BASIC Computer Games Microcomputer Edition
• Fantasy BASIC Consoles
• Atto
• BASIC8 Manual
• MEG-4 Manual
• ECMA-55 Standard
  • https://ecma-international.org/publications-and-standards/standards/ecma-55/
  • bas55 implementation