README.TXT~

   1 Information about BIF as of April 2019.\r
   2 \r
   3         Joel Rees, Amagasaki, Hyogo, Japan.\r
   4                                         joel.rees@gmail.com\r
   5                                         http://reiisi.blogspot.com\r
   6                                         https://defining-computers.blogspot.com/\r
   7                                         etc.\r
   8                                         \r
   9 -----\r
  10 \r
  11 (The following can be found in its original form in the bif-c \r
  12 repositories. bif-c is buggy, by the way.)\r
  13 \r
  14 -----\r
  15 \r
  16 BIF was a dialect of the early fig-standard FORTH.  It was a student\r
  17 project, not a commercial product, and no warranty has ever been made \r
  18 concerning it, whatsoever.  It was written on the Color Computer 2 in \r
  19 6809 assembler; the assembler used was disk EDTASM+.  It also ran on \r
  20 the Color Computer 3, with the expected limitations of requiring the \r
  21 32 column screen, etc. \r
  22 \r
  23 License information -- the rights to BIF and restrictions on \r
  24 distribution -- are described in the file BIFDOC.TXT, which really \r
  25 should distributed with the source.\r
  26 \r
  27 I add here the stipulation that I claim right to the word "BIF" as \r
  28 the name of a programming language.\r
  29 \r
  30 If you are going to distribute or redistribute the obect or source of \r
  31 bif in any of its forms, it really makes no sense not to include the \r
  32 BIFDOC.TXT. If you do something like that and you or anyone that gets \r
  33 the results has problems with it, and you come to me looking for help, \r
  34 expect to be teased mercilessly about it. And expect to be on the \r
  35 bottom of my priority list (not out of spite, out of self-protection).\r
  36 \r
  37 -----\r
  38 \r
  39 I have reconstructed something approximating my source disks (using the \r
  40 great emulator, xroar: https://www.6809.org.uk/xroar/ and the imgtool\r
  41 distributed with MAME, along with the *nix tools). Some useful commands \r
  42 are noted in commands.txt.\r
  43 \r
  44 The name of the disk image is (appropriately?) bifsource.dsk. It can be \r
  45 directly attached by xroar's disk emulator tools, and should be similarly \r
  46 useable with VCC, MAME, etc. al.\r
  47 \r
  48 -----\r
  49 \r
  50 The assembler source files are readable by the a variety of text editors,\r
  51 that respond flexibly about line termination. But if you try editing them\r
  52 with a normal editor and then assembling the result with EDTASM+, be very \r
  53 careful about line termination. Be prepared to use *nix command line tools \r
  54 like tr, cut, sed/awk, perl, etc. \r
  55 \r
  56 The source files retain the original line numbers as used by EDTASM+, \r
  57 which is why you will want the *nix tools. But I have included source to a \r
  58 short C program, stripln.c, which strips the line numbers. This program \r
  59 may also be useful for converting line endings, if that is necessary. Look \r
  60 for it in the junkbox directory, and be prepared to compile it. \r
  61 \r
  62 If you are under the burden of using Microsoft OSses, the Cygwin project \r
  63 should be of quite a bit of assistance, including the *nix command line \r
  64 tools and gcc and clang, etc.\r
  65 \r
  66 -----\r
  67 \r
  68 Macros are used in the source, but shouldn't cause too much confusion \r
  69 to a programmer with assembler experience. If anyone is brave enough \r
  70 to try to port it, key routines will be EMIT, KEY, ?TERMINAL, CR, R/W, \r
  71 and several routines in the EDITOR vocabulary where I used direct \r
  72 video I/O out of laziness.\r
  73 \r
  74 -----\r
  75 \r
  76 BIF might be useful for experimentation and for learning about FORTH, \r
  77 for someone who has access to a Color Computer or an emulator. The \r
  78 executable file may be run on the Color Computer by LOADMing it via \r
  79 Color Computer Disk BASIC. (More details in BIFDOC.TXT.) \r
  80 \r
  81 It is assembled to be EXECed at hexadecimal 1300 (&H1300). \r
  82 \r
  83 -----\r
  84 \r
  85 One specific warning must be given:\r
  86 \r
  87 DO NOT ATTEMPT TO ACCESS ORDINARY DISKS FORMATTED FOR USE BY OTHER\r
  88 OPERATING SYSTEMS WHILE BIF IS RUNNING! Because of disk buffering, it \r
  89 will be difficult to avoid unintentional writes to the disk. \r
  90 \r
  91 If you do try looking at an OS-9 or Color Computer DOS (etc.) disk with \r
  92 BIF, don't blame me if you destroy the directory and/or other valuable \r
  93 data.\r
  94 \r
  95 -----\r
  96 \r
  97 I tried a re-write in C (bif-c), but it's not working well. Issues with \r
  98 file systems (no real file system in BIF) and the current standardization \r
  99 committees ideas about what is meaningful code, problems with my own \r
 100 attention span, etc. keep it full of bugs. And I used a number of neat \r
 101 tricks that get in the way in C. \r
 102 \r
 103 One thing I want to retain is the use of nested binary trees in the \r
 104 symbol table. \r
 105 \r
 106 Incidentally, said re-write has been in process for over thirty years.\r
 107 Real life keeps getting in the way.\r
 108 \r
 109 -----\r
 110 \r
 111 I am including source to a Q&D C program, 32col.c, which will re-format \r
 112 files extracted from BIF disks for normal text editors. Mac-isms and \r
 113 Codwarrior-isms can probably be discerned by comparing it with stripln.c, \r
 114 mentioned above. \r
 115 \r
 116 When I brought the BIF high-level source with me, I used some feature of \r
 117 Color Computer BASIC and BIF that I have forgotten to dump some of the \r
 118 Forth style screen listings. \r
 119 \r
 120 The program stripln can be used to strip line numbers from such screen \r
 121 listings, as well. \r
 122 \r
 123 The documentation is ASCII text, with CR/LF line termination, and should\r
 124 be examined carefully by anyone considering a port.  Bear in mind that\r
 125 it was written toward Color Computer users.\r
 126 \r
 127 I apologize for not alphabetizing the FORTH words by name. I did it once \r
 128 with a C program, but got too ambitious and lost the results in the \r
 129 process of trying to split it up into modules. I haven't had enough time \r
 130 to finish the modularization, yet, either. (Getting an iBook so I could \r
 131 work on the train just gave me more things to do on the train.)\r
 132 \r
 133 Files in this distribution --\r
 134 \r
 135 6809 Assembly Language Source files:\r
 136 \r
 137 README.TXT\r
 138         this file.\r
 139 BIFDOC.TXT\r
 140         general explanations, including descriptions of every word.\r
 141 BIFU.I\r
 142         structure of the per-user variable page.\r
 143 BIF.M\r
 144         macros, including the inner interpreter (basis of the virtual machine),\r
 145         the dictionary (symbol table) structure offsets,\r
 146         and invocations for the fundamental objects.\r
 147 BIFDP.A\r
 148         things kept in the direct page, \r
 149         including the behaviours for the fundamental objects (was not a good idea after all),\r
 150         and the index to the per user variable page. \r
 151 BIFST.A\r
 152         cold and warm boot routines and the initial value table for the per-user variable page.\r
 153 BIF.ASM\r
 154         the main source file (includes other parts),\r
 155         basic expression evaluation, more of the inner interpreter, \r
 156         basic vocabulary access, basic symbol parsing.\r
 157 BIFB.A\r
 158         basic I/O, more of the inner interpreter, extended expression evaluation,\r
 159         the rest of the basic symbol table access.\r
 160 BIF1.A\r
 161         data movers, common expression evaluation,\r
 162         stack pointer access, more of the inner interpreter,\r
 163         high-level compiler.\r
 164 BIF1B.A\r
 165         common expression evaluation, extended expression evaluation,\r
 166         innards of the high-level compiler, more of the high-level compiler,\r
 167         compiler directive.\r
 168 BIF2.A\r
 169         more common expression evaluation, common constants,\r
 170         I/O constants, character typing constants,\r
 171         symbol table globals, compiler globals, parser globals, I/O globals.\r
 172 BIF2B.A\r
 173         compiler globals, more high-level compiler,\r
 174         more common expression evaluation, formatted output.\r
 175 BIF3.A\r
 176         more basic symbol table, symbol table, more compiler, more formatted output,\r
 177         more data movers, more low-level parser (formatted input), more I/O,\r
 178         more extended expression evaluation, more expression evaluation, \r
 179         more compiler directives, an extension to the inner interpreter.\r
 180 BIF3B.A\r
 181         more formatted output, more innards of the high-level compiler,\r
 182         more high-level compiler.\r
 183 BIF4.A\r
 184         more innards of the expression evaluator, more common expression evaluation,\r
 185         more I/O (buffer handling).\r
 186 BIF4B.A\r
 187         more high-level compiler, more compiler directive.\r
 188 BIF5.A\r
 189         more innards of the high-level compiler, more I/O (buffering),\r
 190         disk access, error handling, more formatted output.\r
 191 BIF5B.A\r
 192         more error handling, screen-based sector (character) editor.\r
 193 BIF6.A\r
 194         more parser (formatted input), I/O (terminal), compiler (input),\r
 195         symbol table (lookup).\r
 196 BIF6B.A\r
 197         symbol table, compiler innards, null vector test, \r
 198         more screen-based sector editor.\r
 199 BIF7.A\r
 200         compiler, formatted output, compiler directives\r
 201 BIF7B.A\r
 202         error handling, symbol tables, compiler directives.\r
 203 stripln.c,\r
 204 32col.c, \r
 205         C language source and Macintosh executables for stripping line \r
 206         numbers and reformatting 32 column source code "screens". The two \r
 207         XXX.GXX.out files below are output of the 32col program.\r
 208 \r
 209 -----\r
 210 \r
 211 Hopefully, I will shortly have time to reconstruct useful things from the \r
 212 following files on the tools.dsk disk image and/or the cs431 disk image:\r
 213 \r
 214 TOOLS.G00, TOOLS.G00.out\r
 215         FORTH source for disk listing, screen handling, definition dumping, \r
 216         sector copying, forward referencing, buffer maintenance, \r
 217         experimenting with hardware, double (32 bit) integer math, etc.,\r
 218         and a post-fix assembler.\r
 219 PAIRS.G28, PAIRS.G28.out\r
 220         a "database" example from one of my FORTH books.\r
 221 \r
 222 and\r
 223 \r
 224 SCR33.ARR\r
 225         arrays for CS431.\r
 226 SCR34.LOC\r
 227         some math for CS431.\r
 228 SCR40.431\r
 229         test suite for CS431.\r
 230 \r
 231 \r
 232 \r