bbc-basic/README.md

   1 # Introduction
   2
   3 This is a (partial) implementation of mal in BBC BASIC V.  While there
   4 is already an implementation of mal in BASIC (in the "basic"
   5 directory), it's targeted at much more primitive versions of BASIC and
   6 relies on a pre-processor, both of which make it fairly un-idiomatic
   7 as a BBC BASIC V program.
   8
   9 BBC BASIC V is the version of BBC BASIC supplied with the first
  10 ARM-based computers.  It has substantial enhancements from the
  11 6502-based versions of BBC BASIC, which were themselves at the
  12 advanced end of 8-bit BASICs.  Mal uses many of the advanced features
  13 of BBC BASIC V and porting it to older versions would be difficult.
  14
  15 Mal is intended to run on all versions of BBC BASIC V and BBC BASIC
  16 VI, as well as on Brandy 1.20.1.  For compatibility with Brandy, it
  17 avoids operating system calls where possible.  The only exception
  18 is that is has separate mechanisms for reading command-line arguments
  19 under Brandy and RISC OS.
  20
  21 # Interesting features
  22
  23 This appears to be the first mal implementation that uses an table-driven
  24 deterministic finite automoton (a state machine) to implement its
  25 tokenizer.
  26
  27 The mal heap is represented as a large array of fixed-size objects.
  28 Lists and vectors are linked lists of these objects, while hash-maps
  29 are crit-bit trees.
  30
  31 Mal exceptions are implemented as BBC BASIC errors.  Errors generated
  32 by mal are numbered from &40E80900.
  33
  34 ## Assigned error numbers
  35
  36 No.| Description
  37 ---|------------
  38 &00| Native mal error generated by 'throw'
  39 &1x| Object not of type 'x'
  40 &1F| Miscellaneous type mismatch
  41 &20| Invalid operation on empty list
  42 &21| Wrong number of arguments to function
  43 &22| Undefined symbol
  44 &23| Subscript out of range
  45 &24| Invalid 'catch*' clause
  46 &30| Unexpected end of input
  47 &31| Unexpected ')'
  48 &32| Hash-map key mush be a string
  49 &40| File not found
  50 &Fx| Internal errors (indicating a bug in mal)
  51 &F0| Unprintable value
  52 &F1| Call to non-existent core function