M/C Part 19

ADDING COMMANDS TO BASIC!!!

Right. If you read me last month, you'll know how BASIC lines
are stored. (If not, tuff - I can't be bothered going over it
again). You remember that keywords are stored as tokens? Well,
the first thing you need to do is to allocate a token value to
your new word. If you look at the list somewhere, (eg. in the
MasterBASIC manual) you'll find a free one. 208 isn't used so
that's okay, but my wimp environment proggie uses it, so please
leave it alone for any important programs.

But, to make sure I know that these routines work, I'll assume
that you are using 208.

Now, there are several things we have to do for the new command,
and these help modulise everything into seperate routines. We
have be able to:-

1. Match the keyword.
2. Print the keyword.
3. Syntax check the command.
4. Execute the command.

The great thing is that there are vectors (yup, remember them?)
that call user routines to do all these things. So all we have
to do is to write simple routines, set the vectors and hey
tesco! Remember though, the vectors might already be used, so to
initialise the routines, store the existing values, and if your
routines aren't needed you can jump there.

1. Match The Keyword

The vector for this is MTOKV (5AFA). Your routine is called if a
potential keyword ain't recognised by the ROM. On entry, DE
points to the keyword. On exit, the zero flag indicates a match.
(set for no match). A holds the token-59, HL points to the start
of the keyword, and DE points just past its end.

(In theory...)

The routine must be somewhere in page 0. (eg. the heap, but if
you put it there rewrite it to be relocatable and obey the
proper instructions).

match_keyword    PUSH  DE
                 LD    HL,keyword_text
                 LD    B,keyword_length
mk_loop          LD    A,(DE)
                 CALL  lower_to_upper
                 CP    (HL)
                 JR    NZ,mk_nomatch
                 INC   HL
                 INC   DE
                 DJNZ  mk_loop
                 LD    A,(DE)
                 CALL  lower_to_upper
                 CP    "A"
                 JR    C,mk_match
                 CP    "Z"+1
                 JR    C,mk_nomatch
mk_match         LD    A,token-59
                 POP   HL
                 CP    token             ; (Reset zero)
                 RET

mk_nomatch       POP   DE
                 LD    HL,(mtokv_store)
                 INC   H
                 DEC   H
                 RET   Z
                 JP    (HL)

lower_to_upper   CP    "a"               ; Change any lower case
                 RET   C                 ; letter into upper
                 CP    "z"+1             ; case.
                 RET   NC
                 SUB   32
                 RET

2. Print The Keyword.

A bit easier, this. The vector is PRTOKV (5ADE), and your
routine is entered with A= token value.

print_keyword    CP    token
                 JR    NZ,pk_tryagain
                 LD    DE,keyword_text
                 LD    BC,keyword_length
                 CALL  0013              ; ROM routine.
                 XOR   A                 ; Clear A.
                 POP   HL                ; Junk RET address.
                 RET

pk_tryagain      LD    HL,(prtokv_store)
                 INC   H
                 DEC   H
                 RET   Z
                 JP    (HL)

3/4. Syntax Checking and Executing.

The interpreter lumps these two together through the single
vector CMDV (5AFA). It has a set of flags in a system variable,
one of which tells you if you're syntax checking, or executing.
Your routine is entered with A= command code.

This can also be used to modify/ expand the effect of existing
commands. Let's assume that the command has no parameters.

run_keyword      CP    token
                 JR    NZ,rk_tryagain
                 RST   20                ; Get next char.
                 CP    0D                ; Command OK if next
                 JR    Z,rk_okay         ; char is CR or ":"
                 CP    ":"
                 JR    Z,rk_okay
syntax_error     RST   08
                 DB    1D

rk_okay          POP   HL                ; Junk RET address.
                 LD    A,(flags)

                 ADD   A,A
                 RET   NC                ; Return if syntax
                                         ; checking.
                 .
                 .
                 command routines.
                 .
                 .
                 RET

rk_tryagain      LD    HL,(cmdv_store)
                 INC   H
                 DEC   H
                 RET   Z
                 JP    (HL)

Various variables:-

keyword_text     DM    "FRED"
keyword_length   EQU   4
mtokv_store      DW    0           ; Set up by initialisation
prtokv_store     DW    0           ; routine.
cmdv_store       DW    0           ;
flags            EQU   5C3B

I hope that's of some help. Incidentally, all the numbers are in
hex.