-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathuse.txt
1419 lines (1098 loc) · 57.2 KB
/
use.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Matrix Brandy
~~~~~~~~~~~~~
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
~~~~~~~~~~~~
Matrix Brandy is a BASIC V/VI interpreter. It is source code compatible with
Acorn's BASIC V/VI interpreter and runs under a number of different operating
systems. It currently works with NetBSD (arm32 and i386), Linux (x86, z86-64
and arm32) and Microsoft Windows. The aim of this project is to write a Basic
interpreter that is compatible with the Acorn interpreter and that runs
almost 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/VI 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-2014 David Daniels.
Matrix Brandy modifications are copyright (C) 2018-2024 Michael McConnell and
contributors.
The program is distributed under the terms of the GNU GPL.
Brandy, and Matrix 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.
Matrix 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
Matrix Brandy; see the file COPYING. If not, write to the Free Software
Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Disclaimer
~~~~~~~~~~
The Matrix 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 [ <options> ] [ <filename> ]
where <filename> is the optional name of the program to load and
<options> is one or more of the following:
-help Print a summary of these options.
-version Print the version of Matrix Brandy.
-nocheck Don't try to check for new versions of Brandy on
interactive mode startup.
-size <size> Set the size of the Basic workspace to <size> bytes
when starting the interpreter. The minimum size
allowed is 16384 bytes and anything below this value
will be set to it. The maximum size is 4294966272
bytes (1K short of 4GB), The size may have a
suffix of 'k', 'm' or 'g' to denote that the size is
in kilobytes, megabytes or gigabytes respectively, 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).
-fullscreen (SDL build only) Start Brandy in fullscreen mode.
-nofull (SDL build only) Never use fullscreen mode.
-swsurface (SDL build only) Use a software SDL surface.
-tek (Text-mode 'tbrandy' build only) Enable Tektronics
graphics.
-path <directory list> 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.
-load <filename> Load Basic program <filename> when the interpreter
starts.
-chain <filename> Load and run the Basic program <filename>. Remain in
the interpreter when the program has finished running.
-quit <filename> Load and run the Basic program <filename>. Leave the
interpreter when the program has finished running.
-lib <filename> Load Basic library <filename> 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 <filename>' 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.
-ignore (If strict mode enabled by default) Ignore certain
'unsupported feature' errors.
This option allows some unsupported features that do
not affect the basic running of the program to be
ignored.
-strict (If ignore mode enabled by default) The interpreter
will report an error whenever it comes across a
BASIC V/VI feature that it does not support, and
some obvious BASIC program bugs that are ignored by
the Acorn interpreter.
-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.
-- Subsequent options are passed to the Basic program,
rather than being considered as options to the
interpreter.
<filename> Load and run the Basic program <filename>. Remain in
the interpreter when the program has finished running.
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.
Most of these items can be put into a configuration file, those that cannot
be used are -load, -chain, -quit, -version, --help or a supplied program to
run. This configuration file lives, depending on your platform, in
$HOME/.brandyrc
%APPDATA%\brandyrc
<Brandy$Dir>.brandyrc
Some tunables can also be set in this file. For more details see Config.txt.
Minimum Abbreviations
---------------------
Options can be abbreviated. The interpreter only checks the first
few characters of the option name to identify it.
-chain -c
-fullscreen -f
-help -h
-ignore -ig
-lib -li
-load -lo
-nocheck -noc
-nofull -nof
-nostar -nos
-path -p
-quit -q
-size -s
-strict -st
-swsurface -sw
-tek -t
-version -v
Parameters for Basic Programs
-----------------------------
The interpreter assumes that any unrecognised options are meant to be for the
Basic program and ignores them.
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 <filename>
Load program <filename> into the Basic workspace.
SAVE <filename>
Save the program in the Basic workspace in file <filename>.
RUN
Run the program.
LIST
LIST <line number>
LIST <line number> , <line number>
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 <line number>
This copies the line specified to the command line where it can be edited.
DELETE <line number>
DELETE <line number> , <line number>
The first version of DELETE deletes a single line from the program, line
<line number>. The second version is used to delete a block of lines. Note that
it is not possible to recover any lines deleted. Leaving the start and end lines
out is permissible, in this case lines from the start of the program and to the
end of the program respectively will be deleted. Leaving both out (just specifying
the ,) will delete the entire program.
AUTO [<base number>[,<step size>]]
This command generates line numbers for typing in a program. Where not
specified, <base number> and <step size> both default to 10.
RENUMBER
Renumbers the lines of a program.
NEW
Discard the program in the Basic workspace.
WARNING: Unlike the Acorn interpreter, OLD cannot be used to retrieve
a program discarded with NEW.
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/VI.
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 or Russell 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.
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
edited. 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/VI. These are covered in more
detail below.
Differences Between Matrix Brandy and Acorn's Interpreter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Matrix 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) The SDL build implemention supports a subset of the graphics commands
and some sound.
2) Brandy has no support for machine code programs. It does not support either
the 'CALL' statement nor the 'USR' function
(except for a limited number of calls to BBC-style OS interfaces, notably
OSBYTE and OSWORD). The built-in assembler has not been implemented.
3) The 'APPEND' command has not been implemented.
4) The 'OVERLAY' statement has not been implemented.
5) INKEY(-128) to INKEY(-255) are not implemented (and were only implemented
on the original 6502 MOS). While INKEY(-1) to INKEY(-127) aim to match
the Acorn keynumbers as closely as possible, there are inevitably a small
handful of differences due to physical keyboard hardware differences.
6) Not all of the VDU commands have been implemented.
7) 'PRINT' leaves something to be desired.
8) The TRACE option 'TRACE STEP' has not been implemented yet.
9) A new TRACE option 'TRACE VDU' has been added, this redirects TRACE output
to the controlling terminal.
10) Some 'LISTO' options have not been implemented yet.
11) The 'END=' version of the END statement is not supported.
12) 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 following differences only apply on non-RISC OS builds:
13) Support of the 'SYS' statement is minimal.
14) Cursor editing is not available. A line editor is available in its place.
15) EXIT <FOR|REPEAT|WHILE> from BB4W, BBCSDL, BBCTTY and BBC allow for
immediately breaking out of a loop.
The major omissions in the versions of the interpreter are some graphics.
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) (Only if compiled with -DBRANDY_ALLOW_LOWERCASE_COMMANDS)
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 64M (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', as with Z80, 80x86 and PDP11
BASICs.
11) The 'RUN' command can also be followed by a line number to start program
execution at that line.
12) There are two extra 'TRACE' option: 'TRACE GOTO' and 'TRACE VDU'.
'TRACE GOTO' prints out the source and destination line numbers of any
branches in the program.
'TRACE VDU' redirects trace output to the controlling terminal's stderr
output stream.
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 Linux and NetBSD it calls 'vi' and currently does not work under
Windows.
19) 'EDIT' followed by a line number allows that line to be edited using the
built-in line editor.
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.
23) Under RISC OS on the Risc PC or later, the UnixLib build uses a Dynamic
Area rather than the WimpSlot for workspace, so BASIC's workspace can
be as large as the available memory.
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 <list of variables and arrays>
where <list of variable and arrays> 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$ <factor>
where <factor> 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$(<string>)
XLATE$(<string>, <translate table>)
In the first version, the function returns the string <string> converted to
lower case. Note that only ASCII characters are converted. The second version
is more powerful in that <string> is converted according to the user-supplied
translate table <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(<string 1>, <string 2> [, <start>])
It returns the offset (from one) of the first character in string <string 1>
that is not in string <string 2>. <start> is an optional parameter that gives
the offset at which to start the check. If all the characters in <string 1> are
present in <string 2> 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 <string 1> is an empty string or the start position is greater than the
string length then the function always returns zero. If <string 2> is an empty
string then the function always returns one or the value of <start> (if this is
supplied).
ARM 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
MODE "X800 Y600 C256"
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.
In addition, other extensions from BB4W, BBCSDL, Basalt have been implemented:
GET(x,y) and GET$(x,y)
These return the character at a particular point on the screen.
Implemented for SDL builds and RISC OS.
Following on from += and -= operators, Matrix Brandy also supports:
DIV=, AND=, OR=, EOR=
A Matrix Brandy-specific extension:
OPENUP can be used to open a TCP network connection as a client.
See docs/networking.txt for full details on this extension.
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 <command> [ TO <string array> [ , <variable> ] ]
<command> is a string expression that is the command to be issued. <string
array> 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. <variable> is set to the number of lines stored in <string array>.
Again, it is optional.
The existing contents of <string array> 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 <variable>. 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 <size>
where <size> 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).
The minimum size allowed is 16K bytes. The upper limit is whatever the
operating system on which the interpreter is running allows, to a limit of
4 bytes short of 2GB.
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 <format> [,<filename>]
where <format> is a number that gives the 'listo' format to be used and
<filename> 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 not supported.
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 VDU
---------
The purpose of this option is to redirect all TRACE output to the controlling
terminal's stderr stream, where it can be examined without affecting the
running program's display. Use 'TRACE VDU OFF' to disable this.
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 <option> [ON | OFF]
-------------------------
Individual trace options can be turned on and off without affecting any other
settings, for example, 'TRACE PROC OFF' turns off the procedure and function
call trace. 'TRACE OFF' turns off all traces. 'TRACE <option> ON' is provided
for consistency. 'TRACE PROC' and 'TRACE PROC ON' both turn on the procedure
and function call trace.
TRACE <line number>
-------------------
This is not supported.
TRACE STEP and TRACE PROC STEP
------------------------------
These have not been implemented yet.
ON ERROR and ON ERROR LOCAL
---------------------------
ON ERROR and ON ERROR LOCAL provide a means for errors to be trapped in a Basic
program. The documentation for these in the Acorn interpreter says that the
effect is as if there is a GOTO statement that takes you from the point of the
error to the statements after the ON ERROR clause. There is little (if any)
cleaning up after the error. Brandy differs from the Acorn interpreter in that
it tidies up before restarting at the ON ERROR statement: LOCAL variables and
arrays are reset to the state they were in at the point of the ON ERROR and
procedures and functions ended cleanly. The intention is to provide something
closer to exception handling than what the Acorn interpreter has.
EDIT
----
This is not available on RISC OS.
The EDIT command loads the Basic program into a text editor. The program is
reloaded by the interpreter when leaving the editor. The editor used by default
varies from operating system to operating system as follows:
Linux vi
NetBSD vi
Windows (not working)
It is possible to override which editor the program uses by means of an
environment variable. Under Linux and NetBSD it looks for the standard 'EDITOR'
environment variable. The DOS version checks for 'EDITOR'. Care should be taken
with DOS to choose an editor that runs under DOS and not Windows due to the way
in which DOS/Windows invokes the editor. (The editor is started as a separate
program from the interpreter and the interpreter itself continues to run rather
than being suspended until the editor has finished.)
Unless the Basic program contains statements such as GOTO that reference line
numbers, they can be completely ignored in a text editor. Lines can be added
without line numbers or moved around without any problem. The lines of the
Basic program will be renumbered when the program is reloaded by the
interpreter.
EDITO
-----
There is a variation on the EDIT command, EDITO, that affects how the program
is formatted when it is passed to the editor. The command syntax is:
EDITO <value>
where <value> controls how the program will be formatted. This takes the same
values as 'LISTO' and it has the same effect. EDITO allows, for example, a
program to be passed to the editor without line numbers. 'EDITO 8' is the
command to use here. If EDIT is used, the program is formatted according to the
current 'LISTO' setting. EDITO otherwise works in the same way as EDIT.
Line Editor
-----------
The Linux, NetBSD and Windows versions of the interpreter have a simple
built-in line editor. Apart from allowing input lines to be edited, there is
also a command line history feature that allows the last twenty or so lines
entered to be recalled. The editing commands are:
LEFT or Ctrl-B Move left one character
RIGHT or Ctrl-F Move right one character
HOME or Ctrl-A Go to start of line
END or Ctrl-E Go to end of line
DELETE or Ctrl-D Delete right, deleting character under cursor
BACKSPACE or Ctrl-H Delete left, deleting character to left of cursor
Ctrl-K Delete from cursor to end of line
Ctrl-U Delete from cursor to start of line
INSERT Toggle between 'insert' and 'overwrite' mode
UP or CTRL-P Go to previous entry in the command line history
DOWN or CTRL-N Go to next entry in the command line history
RETURN or CTRL-M Finish editing
CTRL-J Finish editing, as with RETURN/CTRL-M
ESCAPE Abort editing
The aim is to provide both DOS and Unix (emacs) style editing.
The 'Escape' Key
----------------
In builds other than SDL, the 'Escape' key is not the 'Esc' key but Control-C,
that is, to break into a program press the keys 'Ctrl' and 'C' at the same
time. In graphical SDL builds, the 'Escape' key works as normal.
(Note: being updated)
Identifying the Environment Under Which Brandy is Running
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~