2 - The Editor

 "You will kill ten of our men, and we will kill one of yours,
and in the end it will be you who tire of it."
                                                      Ho Chi Minh

                YOUR SECOND GFA BASIC 3.XX MANUAL
                             - or -
        HOW I LEARNED TO STOP WORRYING AND LOVE GFA-BASIC
                             PART 3
                    CHAPTER TWO - THE EDITOR
                          by Han Kempen

2.  THE EDITOR

Abbreviated Commands

 The following abbreviations  are worth remembering  (abbreviated
command in bold underlined characters):

 ALERT                    FILESELECT               POLYMARK
 ARECT                    FILL                     PRINT (or ?)
 ARRAYFILL                FUNCTION                 PROCEDURE
 ATEXT                    GOSUB (or @)             PSET
 BMOVE                    GRAPHMODE                QUIT
 BOUNDARY                 HIDEM                    REPEAT
 CASE                     HLINE                    RESTORE
 CIRCLE                   IF                       RETURN
 CLOSE                    INPUT                    RSET
 COLOR                    LINE                     SELECT
 DATA                     LINE INPUT               SETCOLOR
 DEFFILL                  LOCAL                    SETMOUSE
 DEFLINE                  LOOP                     SGET
 DEFMARK                  LPRINT                   SHOWM
 DEFMOUSE                 LSET                     SWAP
 DEFTEXT                  MID$(..)=                TEXT
 DELETE                   MOUSE                    UNTIL
 DRAW                     NEXT                     VARPTR (or V:)
 EDIT                     OPEN                     VOID (or ~)
 ELLIPSE                  PAUSE                    VSETCOLOR
 ELSE                     PBOX                     VSYNC
 ENDFUNC                  PCIRCLE                  WAVE
 ENDIF                    PELLIPSE                 WEND
 ENDSELECT                PLOT                     WHILE
 ERASE                    POLYFILL
 EXIT IF                  POLYLINE

 Actually  '@',  'V:' and '~' are not  abbreviations,  but  short
alternative  commands.  Although this list is not  complete  it's
already too long for me.  I just manage to remember the following
useful abbreviations:

 A  CA  CI  CL  C  D  E  ENDF  EN  ENDS  FILE  FU  HI  @  I   INP
LI  L    LPR  N  O  PA  PL  P  PRO  REP  RES  RET  S  SET  SH   T
U  V:  ~  W  WE

 If  the abbreviated command is followed by  anything  else,  you
have to insert a space, except with '@', '?', '~' and 'V:' :

          @proc1        ?"hello"       ~INP(2)       V:adr%
 C 1      G proc1       P "hello"      VO INP(2)
 COLOR 1  GOSUB proc1   PRINT "hello"  VOID INP(2)   VARPTR(adr%)

 Print  ABBREVNS.DOC  if  you need a complete  reference  of  all
abbreviations  (this file will be supplied with the last part  of
the course).

Syntax

 The  parser checks for correct syntax after you press  <Return>.
Many typo-bugs are prevented this way.  The only disadvantage  is
that  the  parser recognizes some  variables  as  commands.  It's
impossible  to  use the following names as the first  word  on  a
line:  data_byte|,  dirty$,  double&,  letter$,  printer$, name$,
quit!. The last one is nasty, because the parser changes the line
'quit!=FALSE'  into 'QUIT!=FALSE' without warning for  a  syntax-
error.  If you now run the program you will return to the desktop
when  QUIT  is  encountered.  Of course you have  not  lost  your
valuable program,  because you always Save before you Run. Do you
really? A variable like systemfont% will cause the same disaster.
If  the parser refuses the name of a variable,  you can  use  LET
(e.g. 'LET quit!=FALSE'). But you will have to change the name if
it  is  a label (e.g.  the label 'data1:' could be  changed  into
'1data:' or 'd.ata1:').

 I don't program every day.  Well,  I might as well admit it now,
sometimes I don't program for months.  My problem is that I  keep
forgetting the correct syntax,  although I do know the command. I
hate it when I have to look it up in my GFA-manual.  Perhaps  you
find  my  syntax-list as useful as I do.  The list seems  to  get
longer every year,  but I keep forgetting why.  Abbreviations  of
commands  are  bold and underlined  again.  Variables  without  a
postfix are word-variables.

ALERT icon,txt$,default,but$,button     ! icon=1 !,  2 ?,  3 Stop

x=BCLR(x,bit)
BLOAD file$,adr%
BMOVE source%,dest%,bytes%
BSAVE file$,adr%,bytes%
x=BSET(x,bit)
bit!=BTST(x,bit)
BYTE{adr%}=byte|              ! POKE a byte
byte|=BYTE{adr%}              ! PEEK a byte

DEFLINE [type],[width],[start],[end]    ! type=1 normal,2 dashes,
                                          3 points
DEFMOUSE shape   ! shape=0 arrow,1 cursor,2 bee,3 finger,
                   5 thin cross
DEFTEXT [colour],[type],[angle],[size],[font]
                 ! type= 2 fat,4 light,8 italics,16 underlined,
                   32 outlined

EVERY ticks GOSUB procedure   ! 1 tick = 1/200 s;
                                200 ticks = 1 second

FIELD #chan,bytes.1 AS f1$, bytes.2 AS f2$
FILESELECT path$,default$,file$
FORM INPUT length,txt$
FORM INPUT length AS txt$

GRAPHMODE mode                ! mode=1 replace, 2 transparent

{ADD(XBIOS(14,1),6)}=0        ! clear keyboard-buffer
                                (before INPUT)
INPUT txt$,i
~INP(2)                       ! wait for any keypress
position=INSTR(source$,search$[,start])

l$=LEFT$(source$[,length])
LINE INPUT txt$,i$
LONG{adr%}=integer%           ! POKE an integer
integer%=LONG{adr%}           ! PEEK an integer

MID$(source$,start)=replace$
part$=MID$(source$,start,length)

OPEN "I",#chan,file$
OPEN "O",#chan,file$
OPEN "R",#chan,file$,record.length
OUT 2,7                       ! bell (more like 'ping')

PAUSE ticks                   ! 1 tick = 20 ms;
                                50 ticks = 1 second
PRINT AT(column,row);txt$
PRINT USING format$,...
PUT x,y,pic$[,mode]           ! mode=3 replace, 7 transparent

n&=RAND(limit&)               ! 0 ? n& < limit&
n%=RANDOM(limit%)             ! 0 ? n% < limit%
RC_COPY source%,x1,y1,width,height TO dest%,x2,y2[,mode]
                              ! as PUT-mode
RECALL #chan,array$(),elements,lines%
                              ! first: OPEN "O" #chan,file$
RECALL #chan,array$(),-1,lines%         ! load complete array
RECALL #chan,array$(),first TO last,lines%
r$=RIGHT$(source$[,length])
position=RINSTR(source$,search$[,start])
n#=RND()*limit#               ! 0 ? n# < limit#
x#=ROUND(x#,[-]decimals)

STORE #chan,array$()[,elements]
                              ! first: OPEN "O" #chan,file$
STORE #chan,array$(),first TO last
t$=STRING$(length,char$)
t$=STRING$(length,ascii.code)

TEXT x,y[,[-]length],txt$     ! length>0 letter-distance,
                                <0 word-distance
t%=TIMER                      ! time in 1/200 s;
                                200 ticks = 1 second

adr%=V:txt$                   ! address of string
adr%=V:array&(0)              ! address of word-array

WORD{adr%}=word&              ! POKE a word
word&=WORD{adr%}              ! PEEK a word

Folded Procedures

 If  you  press  <Control>  <Help>  on  a   Procedure-line,   all
Procedures   following   and  including  the  current   one   are
folded/unfolded. You can unfold all Procedures at once by putting
the  cursor  on the first Procedure-line and  pressing  <Control>
<Help>. The editor-commands 'Find' and 'Replace' will skip folded
Procedures  if  you  have  GFA-version  3.0.   Never  change  the
Procedure-line of a folded Procedure,  always unfold it first. If
you don't believe me, and try it anyway, you're stuck. Serves you
right.  I hesitate to tell you that pressing <Undo> restores  the
original folded line.

Tab

 If  you press <Tab>,  the cursor jumps to the next  tab-position
without altering the current line. If you use <Left Shift> <Tab>,
the  line is filled with spaces from the current  cursor-position
to the next tab-position. Pressing <Right Shift> <Tab> erases all
consecutive  spaces to the left of the current  cursor-postition.
If the current cursor-position happens to be a space,  this space
and all spaces to the right are erased as well.

     <Tab>               - Tab in 'Overwrite-mode'
     <Left Shift> <Tab>  - Tab in 'Insert-mode'
     <Right Shift> <Tab> - 'un-Tab'

Cut and Paste 

 If you press <Control> <P>,  the current line from the cursor to
the  end  of the line is cut,  and saved in an  internal  buffer.
<Control>  <O>  inserts  the saved line at  the  current  cursor-
position.  You can use this method to "cut and paste" a part of a
line.  Press  <Control> <P>,  then <Control> <O> to  restore  the
original line.  Move the cursor to the desired position and press
<Control> <O> to place a copy of the cut part there.

Load

 You  can use Load only with *.GFA-files,  not  with  ASCII-files
(such as the *.LST-files).

 Programs  in  GFA-Basic from version 3.04 cannot  be  loaded  by
earlier interpreters (up to 3.02).  Of course you should have the
most current version (at least version 3.07),  but the  following
method  should always work.  Lengthen the program until  you  can
load it successfully:

     OPEN "A",#1,file$
     PRINT #1,STRING$(1000,0)    ! expand program with 1000 bytes
     CLOSE #1

Save

 After  'Save'  (*.GFA-file)  or 'Save,A'  (*.LST-file)  with  an
existing file, the old file is renamed with a BAK-extension. Nice
precaution, but you should delete those *.BAK-files every now and
then.  Talking  about  precautions,  you  could  save  your  most
precious  programs as LST-files on a back-up  disk.  A  corrupted
GFA-file  sometimes  cannot be loaded and is then  probably  lost
forever. A few strange bytes in a LST-file are seldom fatal. Just
Merge the LST-file and correct the errors.

 If you kill and save files regularly,  new files will be  stored
in  a fragmented way.  Loading a fragmented file takes more  time
than  loading  a file that occupies consecutive  sectors  on  the
disk.  You can correct this as follows. First make a backup-disk.
Yes, you should already have one. Copy all files to a RAM-disk by
clicking  on the drive-icon and dragging it to the window of  the
destination drive.  You can't use disk-copy (dragging  drive-icon
to  drive-icon)  because  the destination-drive  is  a  RAM-disk.
Format  the source-disk and copy all files back (this must  be  a
file-copy,  not  a  disk-copy).  Now,  all  files  are  saved  on
consecutive sectors.  You could speed up things a little bit more
by  copying the most-used files first.  The drive-head now  needs
less time to reach these files.

 Don't  try to 'Save,A' an existing file to a full disk.  I  have
tried it once and lost both the original file (should have become
a *.BAK-file) and of course the saved file.  Also, the editor (or
TOS) had erased the program from memory... Thank you.

Llist

 There has been some confusion about the following point-commands
for the printer:

     .p-       - point-commands are not printed
     .p+       - point-commands are printed again
     .llxx     - line-width (line-length)
     .plxx     - page-length
     .pa       - form feed (page)

 Sometimes  the  commands '.cp' and '.nu' are  mentioned,  but  I
don't know how to use these.

 You  can  use  only one point-command in one  line.  I  use  the
following lines for my Star-printer (96 characters/line in Elite-
mode):

     .p-
     .n4
     .lr3
     .ll88

 The  actual  listing is then printed  with  80  characters/line,
preceded by the line-numbers (4 characters + space). If a program
is  longer than 10000 lines,  you should use '.n5',  but in  that
case you probably don't have time to read this.  A nice touch  is
the  automatic  execution  of  a form  feed  after  printing  the
listing.

 If the listing contains special characters (ASCII-code < 32 or >
126),  some of those characters might be interpreted as  printer-
commands.   My  printer  switches  to  condensed  printing  after
receiving the Atari-symbol.  Installing the proper printer-driver
(e.g.  PTEPSON.PRG)  should prevent that.  But I never install  a
printer-driver because there are some serious disadvantages. Read
more about it in the paragraph 'HARDCOPY' in chapter 10.  If your
printer can switch to IBM character set #2,  most characters with
ASCII-code  ? 128 will be printed correctly.  You still won't  be
able to print the Atari-symbol (ASCII-codes 14 and 15),  but  you
should be able to print special characters like é,  ß or  ±.  The
special characters with codes 176 - 223 will not print correctly,
because IBM uses these for lines and patterns.

 You  could use a header-line to send a printer-command  to  your
printer.  I type '.he ' and then,  using the "<Alternate>-method"
(see  the paragraph 'Special Characters'),  I type the  following
five  numbers:  27,  116,  49,  27 and 54.  After  receiving  the
command-string '<Esc> t1 <Esc> 6' my Star-printer switches to IBM
character set #2:

     .he *t1*6                             [* = Escape-character]

 Of  course you could use this method to send other  commands  to
your printer as well.  You can send printer-commands also through
a comment-line. A header-line can be anywhere, but a comment-line
with  printer-commands should be one of the first lines  of  your
program:

   ' Switch to IBM character set #2: *t1*6 [ = Escape-character]

 You  can  stop  the printing process by  pressing  the  'Break'-
combination <Control> <Left Shift> <Alternate>,  unless Break has
been  disabled with 'ON BREAK CONT'.  Your printer will  continue
printing though,  until its input-buffer is empty,  or until  you
turn the printer off.

Insert-mode

 If  you return to the editor,  you'll always be in  Insert-mode,
even if you left the editor in Overwrite-mode.  By the  way,  the
editor  restores  the original colour-palette,  so  you  are  not
bothered by palette-changes in a program.  In the old days I  was
sometimes caught by the dreaded phenomenon of black characters on
a  black background,  but now you can always read the listing  on
your  screen,  unless  a VT52-command has changed the  colour  of
characters  and/or  background  to  a  nasty   combination.   Use
STANDARD.GFA to prevent this.

 By  the second way,  there is only one thing I don't like  about
the GFA-editor.  It's not easy to merge a block with the  program
you're  working on.  Save the program,  clear memory with  'New',
'Merge'  or  'Load' the file,  mark the block,  save  the  block,
'Load'  the original program,  find the correct line and  'Merge'
the saved block.  A new command NMerge (New+Merge) would make the
life of a GFA-programmer a little easier.  A better idea would be
the  command  BMerge  (Block-Merge).  Then I  could  choose  this
command,  clip a block from a LST-file or GFA-file, and the block
would be inserted in the listing automatically.  Are you  reading
this,  Frank? If you are, how about a function for changing upper
case into lower case. In the GFA-EDITOR I SOMETIMES (oops) forget
I pressed CapsLock. And how about a function to clear a line from
the cursor to the next space-character. And...

Direct Mode

 Enter  the Direct Mode by pressing <Esc> or <Shift> <F9> in  the
editor.

 In  Direct  Mode you can restore the previously used  line  with
<Undo>.  With <Up arrow> and <Down arrow> you can even recall  up
to  8 of the last used lines.  Press <Insert> to  switch  between
Insert-mode and Overwrite-mode.  As usual <Esc> clears the  line,
but if you press <Esc> on an empty line,  you will return to  the
editor  immediately.  You  can  also return to  the  editor  with
<Control>  <Shift> <Alternate>,  even without first clearing  the
command-line.

     <Undo>                      - restore last line
     <Up arrow>/<Down arrow>     - cycle through last (8) lines
     <Insert>                    - switch between Insert/
                                    Overwrite-mode
     <Esc>                       - clear line
     <Control><Shift><Alternate> - back to editor

 You  can  call Procedures in your program from the  Direct  Mode
(e.g.   '@show').   If  you  (temporarily)  merge  some   special
Procedures with the program you are developing, you could use the
Direct Mode as a Command Line Interpreter.

DEFLIST

 The  command  'DEFLIST n' only works in Direct Mode,  not  in  a
program.  You can also choose 'Deflist' from the drop-down  menu,
after clicking on the Atari-symbol.

Special Characters

 You  can enter characters with ASCII-code 32-126  directly  from
the  keyboard.   These  characters  are  usually  called   ASCII-
characters. The codes 0-31 and 127 are used as control-codes, but
additionally  special  characters  have been  assigned  to  these
codes.  The  characters  with code 128-255 are  sometimes  called
extended  ASCII-characters and are partly identical to  the  IBM-
characters  with  the same codes.  I loosely use  the  expression
'ASCII-code' for all codes 0-255.

 You  can enter characters with code 0-31 or 127-255 by  pressing
<Alternate>  and then entering the character  code.  Release  the
<Alternate>-key and the character appears on your  screen.  E.g.,
you could enter the Escape-character by holding <Alternate>  down
and  pressing  <2> and <7>.  This is much  faster  than  entering
CHR$(27),  but Llisting a file with Escape-characters is probably
not  a  good idea.  Less important,  "1st Word  Plus"  could  get
confused  too.  Llisting CHR$(27) doesn't bother your printer  at
all.  It's  not possible to enter CHR$(10) or CHR$(13)  with  the
'Alternate-method'. You can enter the first by pressing <Control>
<A>  and  then  <1> <0> <Return>.  For code 13 you  have  to  use
CHR$(13).

 All characters can be printed on the screen with 'PRINT' or 'OUT
5,code',  but  not all characters can be printed on your  printer
(see paragraph 'Llist'):

       0- 31: control-codes, not possible on printer
      32-128: true ASCII-characters, always possible on printer
         127: control-code, not possible on printer
     128-175: special characters, almost identical to IBM set #2
     176-223: special characters, not possible on printer
     224-255: special characters, mostly identical to IBM set #2

 Never use code 4 (EOT,  visible as left arrow) in a LST-file. If
you Merge a LST-file,  the GFA-editor thinks the end of the  file
is  reached  at that point (&H04) and refuses  to  load  anything
following this code!  If you are converting an ASCII-file to GFA-
Basic you should use another editor to (temporarily) change  code
4  to something else.  After this operation the  GFA-editor  will
'Merge'  the ASCII-file properly.  Now you could change the  code
back to 4, and save the program as a GFA-file.

 In case you still don't know what to do with the characters  28-
31:

     LOCATE 1,1
     OUT 5,28
     OUT 5,29
     LOCATE 1,2
     OUT 5,30
     OUT 5,31

 Now that you know what to do with these four codes,  I wonder if
this is supposed to be funny. I'm not laughing.

Procedures (CHAPTER.02)

Edit_debug                                               ED_DEBUG
 Debug a GFA-program after activating this Procedure:
     TRON edit_debug
 Run  the program and press <Alternate> <Control>  <Right  Shift>
for the debug-menu.

Llist_ibm2                                               LLISTIBM
 Switch printer (Star LC24-10) to IBM character set #2.  It's not
necessary  to  put the header-line in a Procedure  (it's  even  a
little weird,  as you're never going to call this Procedure in  a
program...), you could put it anywhere in your program.

Llist_settings                                            LLISTSET
 Llist-settings  for  Llisting  to  printer  in  Elite-mode   (96
characters/line):
     - point-commands are not printed
     - line-numbers of 4 digits (+ space)
     - left margin of 3 spaces
     - line-width of 88 characters
 It's  not necessary to put the printer-commands in a  Procedure,
you could put the point-commands anywhere in your program.