Dumbo BASIC - a curiosity for those of us who remember the '80s !

All,

I'm not getting as much time as I'd like to work on Catalina at the moment, but here is something I've been working on for a while in the background ... a new version of Dumbo BASIC. A version of Dumbo BASIC is already distributed as part of Catalina, but this version is much more complete. I'm posting it because it may be a while before I get a chance to release the next full version of Catalina.

Dumbo BASIC is a GWBASIC clone, written in C, which runs on Windows, Linux, and the Propeller (P1 and P2). Those of us who fondly remember the early days of PCs and GWBASIC might find it amusing.

On the P1 Dumbo BASIC is quite slow (because it must execute from XMM RAM) but on the P2 it is very usable. I have recently added most of the GWBASIC language, including all the file handling statements and functions, and now verified most of it against GWBASIC itself (the differences are explained in the README.TXT file).

Still missing are all the graphics functions, which are waiting on me getting a working version of a VGA tile driver and a graphics package for the P2. I plan to use Rayman's tile driver, but this may take me some time to complete. Then, Dumbo BASIC will be a complete GWBASIC clone.

Attached you will find the source (and a Windows executable!), and also a binary release of Catalyst (which includes Dumbo BASIC) that can be loaded onto an SD card and used on a P2_EVAL board. Along with the vi text editor, this makes dbasic quite a usable BASIC development system. It uses a serial terminal at 230400 baud. You will need a VT100 compatible terminal emulator (such as putty, or Catalina's own payload program).

Here is the README.TXT:

                          ================
                           Dumbo BASIC v1.0
                           ================

Dumbo BASIC is a BASIC interpreter. It was initially written as a demo program
for Catalina/Catalyst, but it can also be used stand-alone, either on the
Propeller, or on Windows or Linux.

Dumbo BASIC implements a substantial subset of the GWBASIC language. The main
things missing are some of the very PC or MS-DOS specific features, such as 
graphics and COM functions - but there may be Propeller equivalents added.

On the Propeller 1, Dumbo BASIC should be compiled using the LARGE memory
model (it can be compiled with the SMALL memory model but it would only be
able to execute very small BASIC programs). It requires 512KB XMM SRAM 
(or 512KB of XMM FLASH plus at least 64KB of XMM SRAM) and an SD card.

On the Propeller 2, Dumbo BASIC can be compiled using the NATIVE or COMPACT
memory model. It requires an SD card.

Dumbo BASIC can also be compiled with gcc, either on Windows or Linux.

Unlike GWBSIC, Dumbo BASIC is not an interactive environment. It just loads
and executes a BASIC source file, which must be edited in another program. 
If you are using Catalyst, the vi text editor can be used to create or edit 
the program, and then Dumbo BASIC can be used to execute it.

Dumbo BASIC is loosely based on "Mini Basic" by Malcolm McLean, but has been 
heavily modified and extended to add many common BASIC statements that Mini 
Basic lacked (e.g. WHILE .. WEND, ON .. GOTO, ON..GOSUB) and also additional 
types (Dumbo BASIC supports both integers and reals, whereas Mini Basic only 
supports real variables). The token parsing and the expression parsing have 
both been completely rewritten (Mini Basic failed to parse anything except 
trivially simple expressions). Dumbo BASIC also supports statements without 
line numbers, and multiple statements on the same line (Mini Basic supports 
neither). File support has been added (Mini Basic had none). There are various
other tweaks to bring the overall syntax closer to that used by GWBASIC. 

Dumbo BASIC currently executes BASIC programs at between 50 - 100 lines per 
second on the Propeller 1 at 80Mhz, or about 5500 lines per second on the 
Propeller 2 at 180 Mhz (or about 8000 lines per second at 260 MHz).

The reason Dumbo BASIC is so much slower (and so variable!) on the Propeller 1
is that it must execute from XXM RAM, and so the speed depends on the speed of
the XMM interface, the memory model (SMALL or LARGE), the cache size (1k - 8k)
etc. However, it is still fast enough to successfully run many BASIC programs,
and further speed improvements will be forthcoming in future versions.

This release of Dumbo BASIC (1.0) implements most of the GWBASIC statements 
and functions, and can be used to execute real-world programs - for example, 
it can execute the classic ELIZA psychoanalyst program - albeit a bit slowly 
on the Propeller 1 (it can take up to 30 seconds for Eliza to respond to each 
line of input). 

As well as various small example programs, and Eliza, there are three different 
BASIC versions of Startrek included - mostly "as is" but sometimes with a few 
tweaks to make them GWBASIC compliant (they were originally written for other 
BASIC interpreters). They are:

   startrek.bas
   trek15.bas
   ut-trek.bas

NOTE: These programs all expect an 80 character terminal, and therefore may
not look very good on platforms that only have TV ouptut (such as the Hybrid)
where Dumbo BASIC has to use a 40 character screen. 

Also, note that many old BASIC programs only recognize UPPER CASE input.


BUILDING DUMBO BASIC
====================

To compile Dumbo BASIC for all Propeller platforms except Morpheus, use the 
'build_all' script provided, specifying the platform on the command line (for 
Morpheus, see the next section). 

Note that you will need to specify the HMI option if you do not want to use 
the default HMI on the platform, plus any other platform specific options, 
such as the CPU to use.

For example:

   build_all HYBRID
or
   build_all DRACBLADE
or
   build_all TRIBLADEPROP CPU_2 PC
or
   build_all QUICKSTART PMC FLASH CACHED_1K
or
   build_all P2_EVAL TTY VT100 MHZ_260


BUILDING DUMBO BASIC FOR MORPHEUS
=================================

On Morpheus, Dumbo BASIC requires the use of proxy drivers. There is a batch
file provided which builds both the interpreter and the proxy.

Use the command:

   build_morphues


BUILDING DUMBO_BASIC FOR WINDOWS OR LINUX
=========================================

Note that you can also build Dumbo BASIC to run under Windows or Linux. This 
requires gcc to be installed. To compile Dumbo BASIC with gcc, use a command
similar to the following: 

   gcc -o dbasic -lm dumbo_basic.c basic.c tokenizer.c 


RUNNING DUMBO BASIC
===================

To run Dumbo BASIC on the Propeller 1 using Catalyst, first copy the Catalyst
programs to a FAT16 SD Card, and program the catalyst.bin into EEPROM. Then 
copy the following files to the SD card, renaming them to fit into 8.3 
filenames. The following names are recommended:

   dbasic.binary    -> DBASIC.BIN
   proxy.binary     -> PROXY.BIN (Morpheus only)

A script to do this (copy_all) is provided. It will also copy the example 
basic programs. Note that depending on your version of Catalina, Catalyst 
may already have a version of dbasic.bin - if so, overwrite it with this 
version.

On the Propeller 2, the process is much the same, except that you do not need 
to load Catalyst into EEPROM - it can execute directly from the SD Card.

On other platforms, simply execute the 'dbasic' program.

To load a basic program on all platforms except Morpheus simply specify the
basic file to load and execute on the command line. For example:

   dbasic eliza.bas

If you do not specify a basic file to load and execute, Dumbo BASIC will 
prompt for one.

On Morpheus, you must execute both the Dumbo BASIC interpreter and a proxy 
driver. When Dumbo BASIC is loaded this way you cannot specify command line
parameters - so you must tell Dumbo BASIC the name of the BASIC file to load 
when it prompts. Enter the commands:

   boot_2                 <- load the boot loader into CPU #2
   @                      <- to select CPU #2 for next load
   dbasic                 <- load the client into CPU #2
   proxy                  <- load the proxy server into CPU #1


IMPLEMENTATION STATUS
=====================

The core BASIC language is fully implemented. The following sections summarize 
the current status of Dumbo BASIC versus GWBASIC. 


==============================================================
 CURRENTLY IMPLEMENTED GWBASIC STATEMENTS (FULLY OR PARTIALLY)
==============================================================

  ABS
  ASC
  ATN               (synonym for ATAN)
  ACOS
  ASIN

  CLS
  CDBL              (currently equivalent to CSNG)
  CHR$
  CINT
  COS
  CSNG
  CLOSE
  CVS
  CVI
  CVD

  DATA
  DATE$
  DEF FN
  DEFINT
  DEFSNG
  DEFDBL            (currently equivalent to DEFSNG)
  DEFSTR
  DIM

  END
  EXP
  EOF
  ERROR
  ERL
  ERR

  FIX
  FOR
  FIELD

  GOSUB
  GOTO
  GET#

  HEX$

  IF
  INPUT
  INPUT#
  INSTR
  INT
  INKEY$

  LINE INPUT
  LINE INPUT#
  LEFT$
  LEN
  LET
  LOG
  LOC
  LOCK
  LOF

  MKD$
  MKI$
  MKS$
  MID$

  NEXT

  OCT$
  ON GOTO
  ON GOSUB
  ON ERROR GOTO
  OPTION BASE
  OPEN

  POS
  POW
  PRINT             (also ? is a synonym for PRINT)
  PRINT USING       (partial)
  PUT#
  PEEK
  POKE

  RANDOMIZE
  READ
  REM               (also ' is a synonym for REM)
  RETURN
  RIGHT$
  RESTORE
  RESUME
  RND

  SGN
  SIN
  SPC
  SQR
  SPACE$
  STOP
  SWAP

  TAB
  TAN
  TIMER
  TRON
  TROFF

  VAL
  VALLEN

  WHILE 
  WEND
  WIDTH
  WRITE
  WRITE#


==========================
 NOT CURRENTLY IMPLEMENTED 
==========================

  BEEP

  CALL
  CHAIN
  CIRCLE
  COLOR
  COM(n)
  CSRLIN

  DEF SEG
  DEF USR
  DRAW

  ENVIRON
  ENVIRON$
  ERRDEV
  ERRDEV$
  EXTERR
  ERASE

  FRE

  GET               (except for files)

  INP
  IOCTL
  IOCTL$
  INPUT$


  KEY

  LINE
  LPOS
  LPRINT 
  LPRINT USING
  LOCATE
  LOCK

  ON COM
  ON KEY
  ON PEN
  OM PLAY
  ON STRIG
  ON TIMER
  OPEN "COM(n)"
  OUT

  PAINT
  PALETTE
  PALETTE USING
  PCOPY
  PEN
  PLAY
  PLAY(n)
  PMAP
  POINT
  POS
  PRESET

  SCREEN
  SHELL
  SOUND
  STICK
  STRIG
  STRIG(n)

  USR
  UNLOCK

  VARPTR
  VARPTR$

  VIEW
  VIEW PRINT

  WAIT

  WINDOW


==========================================================
IMPLEMENTATION DIFFERENCES BETWEEN DUMBO BASIC AND GWBASIC
==========================================================

The following dfferences between Dumbo BASIC and GWBASIC may affect how 
some BASIC programs behave:

1. In Dumbo BASIC, integers are 32 bits, not 16 bits.

2. In Dumbo BASIC, single precision and double precision floats are both 32 
   bits, not 32 bits for singles and 64 bits for doubles.

3. In Dumbo BASIC, the maximum number of dimensions for an array is 5.

4. In Dumbo BASIC, the maximum number of open files is hardcoded to 3. 
   This can be changed in the Dumbo BASIC source file "basic.c"

5. In Dumbo BASIC, the maximum record size for random access files is 
   hardcoded to 128. This can be changed in the Dumbo BASIC source file 
   "basic.c"

6. In Dumbo BASIC, the maximum number of user-defined functions is 32, and 
   the maximum number of arguments to a user defined function is 5. Both of 
   these can be changed in the Dumbo BASIC source file "basic.c".

7. In Dumbo BASIC, the maximum number of nested fors, whiles, or gosubs is 
   hardcoded to 32. Each of these can be changed in the Dumbo BASIC source 
   file "basic.c".

8. In Dumbo BASIC, file access modes and lock options specified in OPEN 
   statements are accepted but ignored.

9. In Dumbo BASIC, strings are normal C strings (i.e. terminated by a zero
   character), except when a string variable is used in a FIELD statement. 
   This means that you should not put a zero character in a string variable 
   EXCEPT when the string variable represents a FIELD, and also that the LEN
   function may return an incorrect length when used on a string variable that
   is actually a FIELD, or one which contains a zero byte. 

10. In Dumbo BASIC, the functions MKI$, CVI, MKS$, CVS, MKD$, CVD all work as
    expected in conjunction with FIELDs (which is where they are mostly used),
    but note that you must assign to FIELD variables using the LET or LSET 
    statements, not RSET. RSET will not work if the value being assigned
    contains a zero character. This is a consequence of difference 9 (above).

11. Dumbo BASIC uses the size of C int and float types for the MKI$, MKS$ and
    MKD$ functions on whatever platform it is running, not 2 bytes, 4 bytes 
    and 8 bytes as GWBASIC does. Similarly, the CVI, CVS & CVD functions all
    expect strings of those sizes. This means (for example) that when Dumbo
    BASIC is compiled with Catalina for the Propeller, integers, single and 
    double precision numbers are all 4 bytes long when converted to strings.

12. PEEK and POKE use a simple linear address on the Propeller, not the
    segment address (DEF SEG is not implemented) and offset used in MS-DOS.

13. The USING clause of the PRINT and PRINT# statements is not yet fully
    implemented. 

    The implemented options are:

       !         for printing just the first character of a string
       \   \     for specifying a fixed length string field
       &         for specifying a variable length string field
       #         for specifying digits
       .         for specifying a decimal point
       $$        for specifying a dollar sign
       _         for specifying the character following the underscore
       
    Not implemented are:

       **        for specifying numbers should be filled with * (not space)
       ^^^^      for specifying exponential formatting (this is automatic)
       + or -    for forcing the printing of a sign (leading or trailing)
       ,         for separating each group of 3 digits by a comma
       %         printed if the number exceeds the specified field length

Note that this version should be compilable with any C compiler, but I have only tried compiling it with gcc and Catalina. If anyone gets it working with some of the other C compilers available, I'd be happy to incorporate any modifications you had to make.

Errata: When using the Catalyst vi text editor on some of the BASIC files, you may need to specify msdos formatting. Use a command like:

vi -s fmt=msdos startrek.bas

Also, I forgot to include the CR_ON_LF option when compiling, so if you are using putty as your terminal emulator, you will probably need to set the "Implicit CR in every LF" terminal option.

Ross.