brandy-1.20.1/0000755000175000017500000000000012410524253012042 5ustar colincolinbrandy-1.20.1/makefile0000644000175000017500000002316012163052654013552 0ustar colincolin# Makefile for brandy under NetBSD and Linux CC = gcc LD = gcc CFLAGS += -g -DDEBUG -I/usr/include/SDL -DUSE_SDL CFLAGS2 = -O2 -I/usr/include/SDL -DUSE_SDL LDFLAGS += LIBS = -lm -lSDL SRCDIR = src OBJ = $(SRCDIR)/variables.o $(SRCDIR)/tokens.o $(SRCDIR)/graphsdl.o \ $(SRCDIR)/strings.o $(SRCDIR)/statement.o $(SRCDIR)/stack.o \ $(SRCDIR)/miscprocs.o $(SRCDIR)/mainstate.o $(SRCDIR)/lvalue.o \ $(SRCDIR)/keyboard.o $(SRCDIR)/iostate.o $(SRCDIR)/heap.o \ $(SRCDIR)/functions.o $(SRCDIR)/fileio.o $(SRCDIR)/evaluate.o \ $(SRCDIR)/errors.o $(SRCDIR)/emulate.o $(SRCDIR)/editor.o \ $(SRCDIR)/convert.o $(SRCDIR)/commands.o $(SRCDIR)/brandy.o \ $(SRCDIR)/assign.o $(SRCDIR)/geom.o SRC = $(SRCDIR)/variables.c $(SRCDIR)/tokens.c $(SRCDIR)/graphsdl.c \ $(SRCDIR)/strings.c $(SRCDIR)/statement.c $(SRCDIR)/stack.c \ $(SRCDIR)/miscprocs.c $(SRCDIR)/mainstate.c $(SRCDIR)/lvalue.c \ $(SRCDIR)/keyboard.c $(SRCDIR)/iostate.c $(SRCDIR)/heap.c \ $(SRCDIR)/functions.c $(SRCDIR)/fileio.c $(SRCDIR)/evaluate.c \ $(SRCDIR)/errors.c $(SRCDIR)/emulate.c $(SRCDIR)/editor.c \ $(SRCDIR)/convert.c $(SRCDIR)/commands.c $(SRCDIR)/brandy.c \ $(SRCDIR)/assign.c $(SRCDIR)/geom.c brandy: $(OBJ) $(LD) $(LDFLAGS) -o brandy $(OBJ) $(LIBS) # Build VARIABLES.C VARIABLES_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/variables.h $(SRCDIR)/evaluate.h $(SRCDIR)/tokens.h \ $(SRCDIR)/stack.h $(SRCDIR)/heap.h $(SRCDIR)/errors.h \ $(SRCDIR)/miscprocs.h $(SRCDIR)/screen.h $(SRCDIR)/lvalue.h $(SRCDIR)/variables.o: $(VARIABLES_C) $(SRCDIR)/variables.c $(CC) $(CFLAGS) $(SRCDIR)/variables.c -c -o $(SRCDIR)/variables.o # Build TOKENS.C TOKENS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/miscprocs.h $(SRCDIR)/convert.h \ $(SRCDIR)/errors.h $(SRCDIR)/tokens.o: $(TOKENS_C) $(SRCDIR)/tokens.c $(CC) $(CFLAGS) $(SRCDIR)/tokens.c -c -o $(SRCDIR)/tokens.o # Build GRAPHSDL.C GSDL_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/errors.h $(SRCDIR)/scrcommon.h $(SRCDIR)/screen.h $(SRCDIR)/graphsdl.o: $(GSDL_C) $(SRCDIR)/graphsdl.c $(CC) $(CFLAGS) $(SRCDIR)/graphsdl.c -c -o $(SRCDIR)/graphsdl.o # Build GEOM.C GEOM_C = $(SRCDIR)/target.h $(SRCDIR)/geom.o: $(GEOM_C) $(SRCDIR)/geom.c $(CC) $(CFLAGS) $(SRCDIR)/geom.c -c -o $(SRCDIR)/geom.o # Build STRINGS.C STRINGS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/strings.h $(SRCDIR)/heap.h $(SRCDIR)/errors.h $(SRCDIR)/strings.o: $(STRINGS_C) $(SRCDIR)/strings.c $(CC) $(CFLAGS) $(SRCDIR)/strings.c -c -o $(SRCDIR)/strings.o # Build STATEMENT.C STATEMENT_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/commands.h $(SRCDIR)/stack.h \ $(SRCDIR)/heap.h $(SRCDIR)/errors.h $(SRCDIR)/editor.h \ $(SRCDIR)/miscprocs.h $(SRCDIR)/variables.h $(SRCDIR)/evaluate.h \ $(SRCDIR)/screen.h $(SRCDIR)/fileio.h $(SRCDIR)/strings.h \ $(SRCDIR)/iostate.h $(SRCDIR)/mainstate.h $(SRCDIR)/assign.h \ $(SRCDIR)/statement.h $(SRCDIR)/statement.o: $(STATEMENT_C) $(SRCDIR)/statement.c $(CC) $(CFLAGS) $(SRCDIR)/statement.c -c -o $(SRCDIR)/statement.o # Build STACK.C STACK_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/stack.h $(SRCDIR)/miscprocs.h $(SRCDIR)/strings.h \ $(SRCDIR)/tokens.h $(SRCDIR)/errors.h $(SRCDIR)/stack.o: $(STACK_C) $(SRCDIR)/stack.c $(CC) $(CFLAGS) $(SRCDIR)/stack.c -c -o $(SRCDIR)/stack.o # Build MISCPROCS.C MISCPROCS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/errors.h $(SRCDIR)/keyboard.h \ $(SRCDIR)/screen.h $(SRCDIR)/miscprocs.h $(SRCDIR)/miscprocs.o: $(MISCPROCS_C) $(SRCDIR)/miscprocs.c $(CC) $(CFLAGS) $(SRCDIR)/miscprocs.c -c -o $(SRCDIR)/miscprocs.o # Build MAINSTATE.C MAINSTATE_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/variables.h $(SRCDIR)/stack.h \ $(SRCDIR)/heap.h $(SRCDIR)/strings.h $(SRCDIR)/errors.h \ $(SRCDIR)/statement.h $(SRCDIR)/evaluate.h $(SRCDIR)/convert.h \ $(SRCDIR)/miscprocs.h $(SRCDIR)/editor.h $(SRCDIR)/emulate.h \ $(SRCDIR)/screen.h $(SRCDIR)/lvalue.h $(SRCDIR)/fileio.h \ $(SRCDIR)/mainstate.h $(SRCDIR)/mainstate.o: $(MAINSTATE_C) $(SRCDIR)/mainstate.c $(CC) $(CFLAGS) $(SRCDIR)/mainstate.c -c -o $(SRCDIR)/mainstate.o # Build LVALUE.C LVALUE_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/evaluate.h $(SRCDIR)/stack.h \ $(SRCDIR)/errors.h $(SRCDIR)/variables.h $(SRCDIR)/miscprocs.h \ $(SRCDIR)/lvalue.h $(SRCDIR)/lvalue.o: $(LVALUE_C) $(SRCDIR)/lvalue.c $(CC) $(CFLAGS) $(SRCDIR)/lvalue.c -c -o $(SRCDIR)/lvalue.o # Build KEYBOARD.C KEYBOARD_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/errors.h $(SRCDIR)/keyboard.h $(SRCDIR)/screen.h $(SRCDIR)/keyboard.o: $(KEYBOARD_C) $(SRCDIR)/keyboard.c $(CC) $(CFLAGS) $(SRCDIR)/keyboard.c -c -o $(SRCDIR)/keyboard.o # Build IOSTATE.C IOSTATE_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/stack.h $(SRCDIR)/strings.h \ $(SRCDIR)/errors.h $(SRCDIR)/miscprocs.h $(SRCDIR)/evaluate.h \ $(SRCDIR)/convert.h $(SRCDIR)/emulate.h $(SRCDIR)/fileio.h \ $(SRCDIR)/screen.h $(SRCDIR)/lvalue.h $(SRCDIR)/statement.h \ $(SRCDIR)/iostate.h $(SRCDIR)/iostate.o: $(IOSTATE_C) $(SRCDIR)/iostate.c $(CC) $(CFLAGS) $(SRCDIR)/iostate.c -c -o $(SRCDIR)/iostate.o # Build HEAP.C HEAP_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/heap.h $(SRCDIR)/target.h $(SRCDIR)/errors.h \ $(SRCDIR)/miscprocs.h $(SRCDIR)/heap.o: $(HEAP_C) $(SRCDIR)/heap.c $(CC) $(CFLAGS) $(SRCDIR)/heap.c -c -o $(SRCDIR)/heap.o # Build FUNCTIONS.C FUNCTIONS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/variables.h $(SRCDIR)/strings.h \ $(SRCDIR)/convert.h $(SRCDIR)/stack.h $(SRCDIR)/errors.h \ $(SRCDIR)/evaluate.h $(SRCDIR)/keyboard.h $(SRCDIR)/screen.h \ $(SRCDIR)/emulate.h $(SRCDIR)/miscprocs.h $(SRCDIR)/fileio.h \ $(SRCDIR)/functions.h $(SRCDIR)/functions.o: $(FUNCTIONS_C) $(SRCDIR)/functions.c $(CC) $(CFLAGS) $(SRCDIR)/functions.c -c -o $(SRCDIR)/functions.o # Build FILEIO.C FILEIO_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/errors.h $(SRCDIR)/fileio.h $(SRCDIR)/strings.h $(SRCDIR)/fileio.o: $(FILEIO_C) $(SRCDIR)/fileio.c $(CC) $(CFLAGS) $(SRCDIR)/fileio.c -c -o $(SRCDIR)/fileio.o # Build EVALUATE.C EVALUATE_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/variables.h $(SRCDIR)/lvalue.h \ $(SRCDIR)/strings.h $(SRCDIR)/stack.h $(SRCDIR)/errors.h \ $(SRCDIR)/evaluate.h $(SRCDIR)/statement.h $(SRCDIR)/miscprocs.h \ $(SRCDIR)/functions.h $(SRCDIR)/evaluate.o: $(EVALUATE_C) $(SRCDIR)/evaluate.c $(CC) $(CFLAGS) $(SRCDIR)/evaluate.c -c -o $(SRCDIR)/evaluate.o # Build ERRORS.C ERRORS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/errors.h $(SRCDIR)/stack.h $(SRCDIR)/fileio.h \ $(SRCDIR)/tokens.h $(SRCDIR)/screen.h $(SRCDIR)/miscprocs.h $(SRCDIR)/errors.o: $(ERRORS_C) $(SRCDIR)/errors.c $(CC) $(CFLAGS) $(SRCDIR)/errors.c -c -o $(SRCDIR)/errors.o # Build EMULATE.C EMULATE_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/errors.h \ $(SRCDIR)/basicdefs.h $(SRCDIR)/emulate.h \ $(SRCDIR)/screen.h $(SRCDIR)/keyboard.h $(SRCDIR)/emulate.o: $(EMULATE_C) $(SRCDIR)/emulate.c $(CC) $(CFLAGS) $(SRCDIR)/emulate.c -c -o $(SRCDIR)/emulate.o # Build EDITOR.C EDITOR_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/errors.h $(SRCDIR)/variables.h $(SRCDIR)/heap.h \ $(SRCDIR)/tokens.h $(SRCDIR)/strings.h $(SRCDIR)/miscprocs.h \ $(SRCDIR)/stack.h $(SRCDIR)/fileio.h $(SRCDIR)/editor.o: $(EDITOR_C) $(SRCDIR)/editor.c $(CC) $(CFLAGS) $(SRCDIR)/editor.c -c -o $(SRCDIR)/editor.o # Build CONVERT.C CONVERT_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/convert.h $(SRCDIR)/errors.h $(SRCDIR)/miscprocs.h $(SRCDIR)/convert.o: $(CONVERT_C) $(SRCDIR)/convert.c $(CC) $(CFLAGS) $(SRCDIR)/convert.c -c -o $(SRCDIR)/convert.o # Build COMMANDS.C COMMANDS_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/miscprocs.h $(SRCDIR)/tokens.h $(SRCDIR)/statement.h \ $(SRCDIR)/variables.h $(SRCDIR)/editor.h $(SRCDIR)/errors.h \ $(SRCDIR)/heap.h $(SRCDIR)/stack.h $(SRCDIR)/strings.h \ $(SRCDIR)/evaluate.h $(SRCDIR)/screen.h $(SRCDIR)/keyboard.h $(SRCDIR)/commands.o: $(COMMANDS_C) $(SRCDIR)/commands.c $(CC) $(CFLAGS) $(SRCDIR)/commands.c -c -o $(SRCDIR)/commands.o # Build BRANDY.C BRANDY_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/tokens.h $(SRCDIR)/errors.h $(SRCDIR)/heap.h \ $(SRCDIR)/editor.h $(SRCDIR)/commands.h $(SRCDIR)/statement.h \ $(SRCDIR)/fileio.h $(SRCDIR)/emulate.h $(SRCDIR)/keyboard.h \ $(SRCDIR)/screen.h $(SRCDIR)/miscprocs.h $(SRCDIR)/brandy.o: $(BRANDY_C) $(SRCDIR)/brandy.c $(CC) $(CFLAGS) $(SRCDIR)/brandy.c -c -o $(SRCDIR)/brandy.o # Build ASSIGN.C ASSIGN_C = $(SRCDIR)/common.h $(SRCDIR)/target.h $(SRCDIR)/basicdefs.h \ $(SRCDIR)/target.h $(SRCDIR)/tokens.h $(SRCDIR)/heap.h \ $(SRCDIR)/stack.h $(SRCDIR)/strings.h $(SRCDIR)/variables.h \ $(SRCDIR)/errors.h $(SRCDIR)/miscprocs.h $(SRCDIR)/editor.h \ $(SRCDIR)/evaluate.h $(SRCDIR)/lvalue.h $(SRCDIR)/statement.h \ $(SRCDIR)/assign.h $(SRCDIR)/fileio.h $(SRCDIR)/emulate.h $(SRCDIR)/assign.o: $(ASSIGN_C) $(SRCDIR)/assign.c $(CC) $(CFLAGS) $(SRCDIR)/assign.c -c -o $(SRCDIR)/assign.o recompile: $(CC) $(CFLAGS) $(SRC) $(LIBS) -o brandy nodebug: $(CC) $(CFLAGS2) $(SRC) $(LIBS) -o brandy strip brandy check: $(CC) $(CFLAGS) -Wall -O2 $(SRC) $(LIBS) -o brandy clean: rm -f $(SRCDIR)/*.o brandy all: brandy brandy-1.20.1/docs/0000755000175000017500000000000012410524252012771 5ustar colincolinbrandy-1.20.1/docs/use0000644000175000017500000014767110546535642013545 0ustar colincolinBrandy ~~~~~~ Contents ~~~~~~~~ Introduction Copyright Disclaimer Using the Interpreter Running Programs Programs and Libraries Differences Between Brandy and RISC OS's Interpreter Identifying the Environment Under Which Brandy is Running I/O Redirection Using Basic as a Script Language Under NetBSD and Linux The SYS Statement The 'key' Command Performance Important Error Messages Known Problems Miscellaneous Comments Conclusion Contact Introduction ~~~~~~~~~~~~ Brandy is a Basic V interpreter. It is source code compatible with Acorn's Basic V interpreter and runs under a number of different operating systems. It currently works with RISC OS, NetBSD (arm32 and i386), Linux (X86) and DOS using the DJGPP DOS extender. The aim of this project is to write a Basic interpreter that is compatible with the Acorn interpreter and that runs identically across all supported operating systems, emulating features of the RISC OS environment where necessary so that a program will run unchanged using the Acorn interpreter under RISC OS or this one under any other OS. No attempt has been made to support features of operating systems other than RISC OS, for example, it is not possible to make operating system calls from within a program except under RISC OS. The program is simply a Basic interpreter and that is all. These notes describe how to use the program and discuss differences between it and Acorn's interpreter. They also detail the extensions to Basic V that have been implemented and finish with some miscellaneous remarks about the program and a list of the known bugs. Copyright ~~~~~~~~~ Brandy is copyright (C) 2000, 2001, 2002, 2003, 2004 David Daniels. The program is distributed under the terms of the GNU GPL. Brandy is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. Brandy is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with Brandy; see the file COPYING. If not, write to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Disclaimer ~~~~~~~~~~ The Brandy Basic interpreter is provided 'as is' and people using it do so entirely at their own risk. No liability whatsoever will be accepted for any loss or damage arising from the use of this software. Using the Interpreter ~~~~~~~~~~~~~~~~~~~~~ To invoke the interpreter, type: brandy [ ] [ ] where is the optional name of the program to load and is one or more of the following: -help Print a summary of these options. -size Set the size of the Basic workspace to bytes when starting the interpreter. The minimum size allowed is 10000 bytes and anything below this value will be set to it. The maximum size is limited only by the environment in which the program is being run. The size may have a suffix of 'k' to denote that the size is in kilobytes or 'm' if it is in megabytes, for example, '-size 100k' will set the workspace size to 100 kilobytes (102400 bytes) and '-size 8m' will set it to eight megabytes (8388608 bytes). -lib Load Basic library when the interpreter starts. This option can be repeated as many times as required to load a number of libraries. This is equivalent to typing 'INSTALL ' at the interpreter's command line. The libraries are loaded in the order given on the command line. Note that the search order is the reverse of this. -load Load Basic program when the interpreter starts. -path This specifies a list of directories that the interpreter will search when looking for libraries and programs. The directory names are separated by commas. The pseudo- variable 'FILEPATH$' is set to this value. See the section below on FILEPATH$ for more details. -quit Load and run the Basic program . Leave the interpreter when the program has finished running. -chain Load and run the Basic program . Remain in the interpreter when the program has finished running. -graphics Start the interpreter with the screen in graphics mode in versions of the program which support graphics and the screen can be in either text or graphics modes. -ignore Ignore certain 'unsupported feature' errors. By default the interpreter reports an error whenever it comes across a Basic V feature that it does not support. This option allows some unsupported features that do not affect the basic running of the program to be ignored. Load and run the Basic program . Remain in the interpreter when the program has finished running. -nostar Do not check commands issued via OSCLI to see if they are dealt with by Brandy. Pass all commands to the underlying operating system. The case of the names of the options is ignored. It depends on the operating system under which the interpreter is running as to whether the names of files are case sensitive or insensitive. Minimum Abbreviations --------------------- Options can be abbreviated. The interpreter only checks the first one or two characters of the option name to identify it. -chain -c -graphics -g -help -h -ignore -ig -lib -li -load -lo -path -p -quit -q -size -s -nostar -no Parameters for Basic Programs ----------------------------- The interpreter assumes that any unrecognised options are meant to be for the Basic program and ignores them. !!Brandy -------- This is an obey file for RISC OS that runs Brandy in a Taskwindow. The file can be placed on the pinboard and the interpreter started by double clicking on it. Running Programs ~~~~~~~~~~~~~~~~ The name of the program to run can be specified on the command line. If no name is given, the interpreter starts with a '>' prompt. Programs can be loaded, edited and run from here. Briefly, the commands to use are as follows: QUIT Leaves the interpreter. LOAD Load program into the Basic workspace. SAVE Save the program in the Basic workspace in file . RUN Run the program. LIST LIST LIST , The first version lists the entire program. The second one lists just the line supplied. The third lists lines with line numbers in the range given. EDIT This transfers the program in memory to a text editor where it can be more easily edited. The program is reloaded when the editor is quitted. EDIT This copies the line specified to the command line where it can be edited. DELETE DELETE , The first version of DELETE deletes a single line from the program, line . The second version is used to delete a block of lines. Note that it is not possible to recover any lines deleted. RENUMBER Renumbers the lines of a program. NEW Discard the program in the Basic workspace. Editing Programs ---------------- Any Basic statement typed in without a line number is executed immediately. Basic statements typed in which start with a line number are either added to the program or replace the line if the line number duplicates ones already in the program. The 'EDIT' command can be used to transfer a program into a text editor where it can be edited more easily. The file 'basic' contains more details of these commands and others as well as information on Basic V. Programs and Libraries ~~~~~~~~~~~~~~~~~~~~~~ Loading and Saving Programs --------------------------- The interpreter can read Basic programs that have been saved as plain text or tokenised using Acorn Basic tokens. It always stores them as plain text. The reasons for working with text files are that it is not a large overhead to tokenise and expand programs, it is more portable and it allows programs to be edited with any text editor. Line numbers can be left out when creating a program in a text editor. The interpreter will add them when it reads the program. The line numbers added start at 1 and go up by 1 so that the line numbers given in error messages match up with the lines of the program in a text editor. One feature of the interpreter is that it notes the name of the file on a 'LOAD' command and uses that name if the 'SAVE' command is used without specifying a filename. The interpreter also supports the case where the filename is supplied on the first line of the program. This take precedence over the name saved from the 'LOAD' command. (change?) Libraries --------- The interpreter supports libraries of procedures and functions that can be loaded using either the 'INSTALL' command or the 'LIBRARY' statement in a program. Those loaded via the 'INSTALL' command will be permanently loaded and are available until the run of the interpreter finishes. The command line option '-lib' can be used to specify libraries that will be 'INSTALL'ed when the interpreter starts. Libraries loaded by the 'LIBRARY' statement are read at the time the statement is encountered and will be discarded when a further RUN statement is issued, when NEW or CLEAR are used or when the program is editted. Effectively they are only available when a Basic program is running. Examples: INSTALL "catlib" LIBRARY "doglib" Libraries loaded using 'INSTALL' cannot be discarded. However the same library can be loaded via 'LIBRARY' and it will effectively take precedence as libraries loaded this way are searched first. Libraries can be held as plain text, with or without line numbers, or can be tokenised. Local Variables in Libraries ---------------------------- It is possible for libraries to have variables and arrays that are private to that library. This is an extension to Basic V. These are covered in more detail below. Differences Between Brandy and Acorn's Interpreter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Brandy is compatible with the Acorn interpreter and should produce the same results as the Acorn one. However perfect compatibility cannot be achieved for a number of reasons, for example, the lack of graphic commands in some versions of the program greatly limits which programs will work. There are also some enhancements that could lead to incompatibilites, for example, Brandy allows strings to be up to 65536 characters long compared to the Acorn interpreter's limit of 255. The list of differences are as follows: 1) Only the RISC OS version has graphics and sound. The DOS implemention supports a subset of the graphics commands. 2) Brandy has no support for machine code programs. It does not support either the 'CALL' statement nor the 'USR' function (except for one specific case, to use OS_Byte call 0 to identify the host type). The built-in assembler has not been implemented. 3) Only the RISC OS version supports the 'SYS' statement. 4) The follow Basic commands have not been implemented: APPEND and AUTO. 5) The 'OVERLAY' statement has not been implemented. 6) The functions 'INKEY' and 'INKEY$' have only been implemented fully for RISC OS as yet. 7) Not all of the VDU commands have been implemented yet in non-RISC OS versions. 8) Cursor editing is not available in non-RISC OS versions. 9) 'WIDTH' has not been implemented. 'PRINT' leaves something to be desired too. 10) The TRACE option 'TRACE STEP' has not been implemented yet. 11) Some 'LISTO' options have not been implemented yet. 12) The 'END=' version of the END statement is not supported. 13) Brandy behaves differently to the Acorn interpreter after an error when the program contains ON ERROR or ON ERROR LOCAL statements to trap errors. The major omissions in the versions of the interpreter that run under operating systems other than RISC OS are graphics and sound. The built-in assembler and support for machine code programs are missing too. Apart from that, the interpreter is essentially a full implementation of the Acorn interpreter. The interpreter has the following extensions: 1) Strings can be up to 65536 characters long. 2) Statements can be up to 1024 characters long. 3) Libraries can have their own private variables. 4) The OSCLI statement has been extended to allow the output from operating system commands to captured. 5) The case of commands such as 'LIST' and 'RUN' is ignored, so 'LIST' could be entered as 'list' or 'List'. The downside is that variable names that are the lower case equivalents of commands will now be seen as commands, something that seems to happen all too frequently. 6) There is a new pseudo-variable 'FILEPATH$' that gives a list of directories to be searched when loading programs and libraries (see the section on this below). 7) There are two functions for dealing with command line parameters, 'ARGC' and 'ARGV$' (see the section below). 8) There are two new string functions, 'VERIFY' and 'XLATE$' (see the section below). 9) 'NEW' can be followed by a parameter, the new size of the Basic workspace. This allows it to be changed from the default of half a megabyte (see section on this below). 10) The 'RUN' command can be followed by the name of a program to run. It behaves just like the statement 'CHAIN'. 11) The 'RUN' command can also be followed by a line number to start program execution at that line. 12) There is an extra 'TRACE' option: 'TRACE GOTO'. This prints out the source and destination line numbers of any branches in the program. 13) 'TRACE PROC' shows returns from procedures and functions as well as when they are called. 14) Individual TRACE options may be turned off and on, for example, 'TRACE PROC OFF' will turn off the only the procedure trace and leave any other running. 15) There is an extra 'LISTO' option, 32. When this option is in effect, listing of a program pauses every twenty lines with the prompt '-- more --'. Press the space bar to show the next twenty lines, 'return' to print just the next line or the 'Escape' key to stop the command. 16) 'LISTO' can be used as a function to find out the current setting of 'listo'. 17) There are a couple of extra 'LIST' commands. 'LISTB' dumps memory in byte form between the two addresses specified. 'LISTW' is the same, but dumps memory as words. These were added for debugging but will probably be left in. 18) The 'EDIT' command on its own invokes a text editor to edit the program. Under RISC OS it calls StrongEd Zap, Edit or 'twin', under Linux and NetBSD it calls 'vi' and under DOS it calls 'edit'. 19) 'EDIT' followed by a line number allows that line to be edited using the built-in line editor. This feature is not available under RISC OS. 20) When a program is loaded via a 'LOAD' command the name of the file is kept and saving the program using the 'SAVE' command with no argument will save the program using that name. 21) Programs are always saved as plain text. 22) The latest extended versions of COLOUR, GCOL, MODE and DIM are supported. VDU can also be used as a function to read RISC OS mode variables. COLOUR can also be used as a function to return a number that represents the closest match to the colour whose colour components were passed to the function. There is quite a list here but really apart from the longer maximum string and statement lengths, local variables in libraries and the change to 'new', most of these are really cosmetic changes. Local Variables in Libraries ---------------------------- Libraries can have their own private variables and arrays. The variables are only accessible in the library in which they were declared. The LIBRARY LOCAL statement is used to declare the variables. The syntax is as follows: LIBRARY LOCAL where is a list of variable and array names separated by commas, for example: LIBRARY LOCAL abc%, def%, ghi$, jkl(), mno(), pqr$() In the case of arrays, this merely defines that the array is local to the library. The dimensions of the array have to be declared using a DIM statement in the normal way, for example: LIBRARY LOCAL jkl(), pqr$() DIM jkl(100), pqr$(table_size%) There can be as many LIBRARY LOCAL and DIM statements as necessary but they have to be before the first DEF PROC or DEF FN statement in the library. They also have to be the first item on the line. The variables can only be referenced in the library. They are not visible outside it. This is different to the way in which local variables are dealt with in a procedure or function, where local varables can be accessed by any procedure of function called by the procedure in which they were declared. They can duplicate the names of variables in the Basic program or other libraries. When looking for a variable in a library, the interpreter first searches for it amongst the library's private variables and then in the Basic program's. The variables and arrays are created the first time the library is referenced. In practice this means that they are set up when the interpreter has to search the library for a procedure or function. Private variables in a library can further be used as local variables in a procedure or function. Note that they can only be accessed in the library, for example: LIBRARY LOCAL abc%, def, ghi$, jkl(), mno$() DIM jkl(100) DEF PROCaaa(abc%) LOCAL def, ghi$ ENDPROC DEF PROCbbb(def, jkl()) LOCAL mno$() DIM mno$(100) ENDPROC DEF PROCccc(xyz, abc%) ENDPROC Here, abc%, def, ghi$, jkl() and mno$() are all declared to be private to the library. The dimensions of jkl() are also defined. In PROCaaa, abc% is used as a formal parameter (effectively a local variable) and def and ghi$ declared to be local to the procedure. Any procedure or function *in the library* that PROCaaa calls that use def and ghi$ will use PROCaaa's local versions. Any procedure or function that PROCaaa calls that are *outside* the library *will not* see these variables. In PROCbbb, def and jkl() are used as formal parameters and mno$() is defined as a local array and its dimensions given. Note that this is the first place where the dimensions have been defined. In PROCccc, two variables are used as formal parameters, xyz and abc%. This case is more complex in that abc% is one of the library's private variables whereas xyz is not. xyz is one of the Basic program's variables. abc% can only be referenced in the library but xyz is visible anywhere. The rules for the scope of private library variables may sound complex but they are quite simple. The point to remember is that a private variable in *only* accessible in the library in which it was declared. If a variable is not declared on a LIBRARY LOCAL statement then it is visible anywhere. FILEPATH$ --------- This is an extra pseudo variable. It gives a list of directory names that the interpreter will search when looking for programs and libraries. The names are separated by commas with no intervening blanks or other white space characters, for example: FILEPATH$="/home/dave,/usr/local/basic/lib" The format of the directory names is operating system-dependent and the program assumes that they are correct. FILEPATH$ can be treated like any other string variable except that only the '=' assignment operator is allowed, thus: FILEPATH$="/usr/local/basic/lib" is fine but: FILEPATH$+=",/usr/local/lib" is not supported and will give an error. The interpreter first of all tries to find the program or library using the name as supplied. If it cannot find it and the name is just the name of a file, that is, it does not contain any directories, it then looks in each of the directories given by FILEPATH$ until either it finds the file or it reaches the end of the list. If the file can be found, the name of the file as far as the interpreter is concerned is the name as orginally supplied with the name of the directory in which it was found prepended to it, for example: load "earthworks" If this program was found in the directory '/home/dave' the name of the program would show up as '/home/dave/earthworks' in the output from 'help'. Saving the program without specifying a new file name would write to the file '/home/dave/earthworks'. As FILEPATH$ is a pseudo variable, its value is not affected by CLEAR or NEW. The initial value of FILEPATH$ can be set using the command line option '-path'. The main purpose of FILEPATH$ is to provide a search path for libraries but it is also used when looking for programs. It would be useful here for 'CHAIN'. Use of FILEPATH$ can effectively be disabled by setting it to the empty string, that is, by entering 'FILEPATH$=""'. ARGC and ARGV$ -------------- These functions return parameters from the command line used to start the interpreter. ARGC returns the number of parameters and ARGV$ the parameters themselves. ARGC ---- Returns the number of parameters, for example: count = ARGC ARGV$ ----- Returns parameters. The syntax is: ARGV$ where is a numeric value that identifies the parameter to return, for example: FOR N%=1 TO ARGC PRINT ARGV$ N% NEXT Parameter numbers are in the range 1 to the value returned by ARGC. ARGV$0 is the name of the Basic program if it was started from the command line otherwise it is an empty string. XLATE$ ------ This function is used to translate character strings. There are two forms of it as follows: XLATE$() XLATE$(, ) In the first version, the function returns the string converted to lower case. Note that only ASCII characters are converted. The second version is more powerful in that is converted according to the user-supplied translate table . This can be either a character string or a one dimensional string array. The effect is the same in both cases: each character in the original string is replaced by the corresponding character in the translate table. If the table is a string, the character at offset 1 replaces the character with ASCII code 0, the character at offset 2 replaces the one with ASCII code 1 and so forth. It is not necessary for the string to be 256 characters long: any character whose code would place it beyond the end of the string is left unchanged. The use of a string array is more convenient in that each character is replaced by the array entry corresponding to its ASCII code. Note that only the first character of the string in the array is used. If the array entry contains an empty string then the original character is left unchanged. As with the character string translate table, the array does not have to contain 256 elements: characters whose ASCII code place them beyond the end of the array are left unchanged. Examples: PRINT XLATE$("AbCdEfGh") DIM table$(255) FOR N%=ASC"0" TO ASC"9": table$(N%)="*": NEXT PRINT XLATE$("abc123def456", table$()) VERIFY ------ The format of this function is as follows: VERIFY(, [, ]) It returns the offset (from one) of the first character in string that is not in string . is an optional parameter that gives the offset at which to start the check. If all the characters in are present in the function returns zero; otherwise it returns the offset of the first bad character. Examples: X% = VERIFY(a$, "0123456789") REPEAT A$=GET$: UNTIL VERIFY(a$, "YNyn")=0 P%=1 REPEAT P%=VERIFY("...x..x..", ".", P%) IF P%<>0 THEN PRINT P% UNTIL P%=0 If is an empty string or the start position is greater than the string length then the function always returns zero. If is an empty string then the unction always returns one or the value of (if this is supplied). BBC Basic 1.26 Extensions ------------------------- The following statement types have been extended in this version of the interpreter: COLOUR DIM GCOL MODE VDU function COLOUR The new 'OF' and 'ON' parts are supported, for example: COLOUR OF 255,255,255 ON 0,0,0 DIM It is now possible for local byte arrays to be created in procedures and functions. The memory for the byte array is reclaimed when the procedure or function ends, for example: DIM pointer% LOCAL 1000 GCOL The new 'OF' and 'ON' parts are supported, for example: GCOL OF 0,0,0 ON 255,255,255 MODE The extended form of MODE where the screen size to be used is supplied is now supported. Example: MODE 800,600,8 VDU Function VDU can now be used as a function to return the values of mode variables. Example: PRINT "Width in characters is ";VDU 1 All of these extensions are described in the file 'basic'. COLOUR function This returns a value that represents the colour with the closest match in the current screen mode to the colour with the colour components passed to the function. The value is for use with the COLOUR OF and GCOL OF statements. Example: red = COLOUR(255, 0, 0) blue = COLOUR(0, 0, 255) COLOUR OF red ON blue This could also be written as: COLOUR OF 255, 0, 0 ON 0, 0, 255 or even: COLOUR OF COLOUR(255, 0, 0) ON COLOUR(0, 0, 255) The advantage of the new forms of GCOL and COLOUR are that they are mode independent. They are more flexible than the old versions of the statements and do away with the need for TINT. Command Line Parameters ----------------------- The interpreter assumes that any unrecognised parameter on the command line is meant to be for the Basic program, for example: brandy aprog parm1 parm2 -xyz would be assumed to consist of the name of the program to run, aprog, and three parameters for the program, 'parm1', 'parm2' and '-xyz'. brandy aprog -size 256k parm1 parm2 -xyz would be interpreted in exactly the same way. '-size 256k' would be treated as an option for the interpreter itself. Beware of cases like: brandy aprog -size 256k parm1 -start Here, '-start' would be seen as '-size' by the program as it only checks for '-s' to identify '-size'. Capturing Command Output with OSCLI ----------------------------------- The OSCLI statement has been extended so that the output from operating system commands can be read by the program. The syntax of the statement is now: OSCLI [ TO [ , ] ] is a string expression that is the command to be issued. is an array that will be used to hold the output from the command. It is optional. If it is not present then the command output goes to the normal place. is set to the number of lines stored in . Again, it is optional. The existing contents of are discarded before the output from the command is stored in it. Elements of the array that are not used are set to the empty string. The first element of the array used is 1, so the output is found in elements 1 to . If there is more output than will fit in the array the excess is discarded. There is nothing to indicate that this has happened so it is up to the user to ensure that the array is large enough. Example: OSCLI "ex" TO array$(), lines% FOR N%=1 TO lines% IF LEFT$(array$(N%), 1)="a" THEN PRINT array$(N%) NEXT Note that there some problems still to be resolved with OSCLI ... TO. Errors (or to be more precise, messages written to stderr) are not caught in the DOS version of the program as DOS does not provide a way to redirect them. They are therefore missed out. The NEW Command --------------- The NEW command has been extended to allow the size of the Basic workspace to be changed. By default, Brandy allocates half a megabyte of memory to hold the program, variables, strings and so forth. This can be changed by means of the 'NEW' command as follows: NEW where is the new size of the workspace in bytes, for example: NEW 1000000 would set the workspace size to 1,000,000 bytes. Note that using this command will result in the loss of the current contents of the workspace, including any programs and libraries (except for libraries loaded by means of the 'INSTALL' command). It is not possible to recover a program by means of 'OLD' under these circumstances. The minimum size allowed is 10K bytes. The upper limit is whatever the operating system on which the interpreter is running allows. Note that the initial size of the Basic workspace can also be set using the command line option '-size'. SAVE ---- There are two versions of the 'SAVE' command used to save a program. 'SAVE' uses the current 'LISTO' setting to control the format of the program when it is written to disk. 'SAVEO' allows the format to be more precisely specified. The format of the SAVEO command is: SAVEO [,] where is a number that gives the 'listo' format to be used and is the name of the file. The name can be omitted, in which case the name defaults to either the name used on the last 'LOAD' command or the name given on the first line of the program. Example: SAVEO 10,"test" would save a program called "test" using 'listo' option 10 (omit line numbers and indent lines inside loops, block IF statements and so forth). OLD --- The OLD command is supported but is only of limited use in this interpreter. It only works when trying to recover a program immediately after typing 'NEW'. It does not work after 'NEW ' variant of NEW, nor can it be used after quitting from the interpreter and rerunning it. The Acorn Basic trick of having many programs in memory at once and switching between them by modifying PAGE and typing OLD does not work. 'OLD' works in a different way to the version in Acorn's interpreter. TRACE ----- Several changes have been made to the TRACE command. TRACE PROC ---------- This shows both when a procedure or function is entered and when it is exited. '==>PROCabcd' indicates that PROCabcd has been entered and 'PROCabcd-->' shows that it has been exited. TRACE GOTO ---------- The purpose of this option is to trace program flow. It logs all jumps in the code, showing the number of the line at which the branch occured and the line at which execution continues. It works not just for GOTO statements but anywhere where a branch can occur, for example, in IF statements. Example: consider the following code: 100 IF X%<10 THEN 110 PRINT"X% is less than ten" 120 flag%=TRUE 130 ELSE 140 PRINT"X% is greater than or equal to ten" 150 flag%=FALSE 160 ENDIF 170 PRINT flag% If X% was set to five, the branch trace would show the following entries: [100->110][130->170] and if X% was set to 25, it would look like: [100->140] (Note that the program output has been omitted for clarity here). In the first case, as X% is less that ten the condition is true and so the program branches to line 110. When it reaches the ELSE it branches from the ELSE to the line after the ENDIF. In the second case, as the condition is false the program flow passes from line 100 to the line after the ELSE. As there is no branch at the end of the ELSE part of the 'IF' and control runs straight through to line 170, there is no trace entry. FOR, WHILE and REPEAT loops, procedure and functions calls and returns, GOTO, GOSUB, ON GOTO, ON GOSUB, ON PROC and RETURN statements are all traced by this option. Note, however, that some of the trace entries are not intuitive, for example, the line number of the start of a WHILE loop will be that of the statement after the WHILE itself, for example: 200 X%=7 210 WHILE X%<10 220 X%+=1 230 ENDWHILE will produce the following trace: [230->220][230->220] The reason for this is tied up in the way WHILE loops work. It is considered that this trace cuts out much of the 'noise' that results from simply tracing line numbers. TRACE