QBasic & Borland Pascal & C/Delphi5.iso/Basic/Samples/BOZOL2/BOZOL2.ZIP/TEST.BOZ

Text File | 1994-02-08 | 35.1 KB | 721 lines

goto start

====================================================================
October 21, 1993 - Erik Lee Olson, PowerBASIC Tech Support
Port Charlotte, Florida

This is a test program for BozoL.  See BOZOL.DOC and BOZOL.REF for a
complete description of how to use and customize BozoL.

BozoL and the PowerBASIC interpreter source code are public domain
=====================================================================

start (this is the beginning of the program)

color 14,1:cls
locate 2,5:print "BozoL test program"
print            "==================" at locate 3,5
color 15,1  print chr 7

print        "1. WHAT IS BOZOL?"                              at locate 7,15
print        "2. BOZOL COMMANDS AND FUNCTIONS - STARTER SET"  at locate 8,15
print        "3. BOZOL PROGRAMMING RULES"                     at locate 9,15
print        "4. HOW TO ADD COMMANDS AND FUNCTIONS"           at locate 10,15
print        "5. CALLING BOZOL FROM YOUR OWN PROGRAMS"        at locate 11,15

print           "Or type Q to quit"   at locate 13,18  in color 14,1
color 15,1:locate 15,18:input  "Enter a selection --> ",Pick
if eval len pick=0: print chr 7:goto start

        goto one   if eval Pick=1
         goto two   if eval Pick=2
          goto three if eval Pick=3
           goto four  if eval Pick=4
            goto five  if eval Pick=5

if same upper Pick,"Q": color 7,0: Print "Goodbye!": end
print chr 7:goto start

one:
cls with color 1,7
print "        1. WHAT IS BOZOL?"
print ""
print "        BozoL (The Bozo Language) is an extremely simple interpretive"
print "        language written in PowerBASIC.  It is designed to be easy to"
print "        use, easy to modify, and to run as fast as possible."
print ""
print "        Some of the rules in BozoL may seem a bit wierd, but there is a"
print "        reason for this.  After writing a BASIC interpreter (EBASIC.ZIP)"
print "        I discovered that the fundamental design of BASIC makes it"
print "        extremely difficult to parse and interpret with any sort of"
print "        reasonable speed.  BozoL is purposely designed to run as fast"
print "        as possible as an interpreted language."
print ""
gosub pause
print "        Why BozoL?"
print ""
print "        Every now and then a situation may arise where you will want to"
print "        incorporate a command language into your programs.  BozoL can be"
print "        easily modified to do things relevant to your program's needs."
print "        Suppose you have a database program and you want to allow your"
print "        users to program their own custom procedures without having to"
print "        go back to the original source code and add them in."
print ""
print "        BozoL is a language skeleton.  All of the dirty work has been"
print "        done already.  BozoL already contains expression parsing, program"
print "        flow control, basic logic, and other fundamental building blocks"
print "        of a programming language (print, input, variables, etc)."
print ""
gosub pause
print "        BozoL is simple.  There are not a lot of rules, punctuation, or"
print "        wierd symbols in the language.  It is a real beginner's language."
print ""
print "        All you need to do now is add your own custom commands and key-"
print "        words to the language.  See section 4, " CHR 34 "How to add commands and"
print "        functions" CHR 34 " for the exact details on how to do this."
print ""
gosub pause
print "        Prototypes and Applications"
print ""
print "        Suppose you have a library of routines that pop up boxes, print"
print "        menus, display pictures, etc.  You can take these routines and"
print "        make BozoL commands out of them.  For instance, if you have a"
print "        PowerBASIC subroutine that displays a message inside a red box"
print "        on the center of the screen, you can make a BozoL command which"
print "        calls this subroutine.  So now in BozoL you can say"
print ""
print "                REDBOX " CHR 34 "press any key to continue!" CHR 34
print ""
print "        and BozoL will call your subroutine.  Using this technique, you"
print "        can take an entire library, or many libraries, and make BozoL"
print "        commands out of all of those subroutines."
print ""
gosub pause
print "        I'll give you a more advanced example.  Suppose you have a Power-"
print "        BASIC library that features pull-down menus, dialog boxes, list"
print "        boxes, a text editor, and data entry screens.  If you took every"
print "        callable SUB and FUNCTION in this library and made BozoL commands"
print "        out of them, then you could use the BozoL language to write"
print "        really neat user-interface programs, prototypes, or even finished"
print "        products.  Instead of shipping an EXE, you can ship the BozoL"
print "        interpreter along with an interpreted BozoL program that can"
print "        be easily modified by your customers without ever having to"
print "        give them the source code or customizing the program yourself."
print ""
print "        Software upgrades could be faxed to your customers or even"
print "        dictated over the phone."
print ""
gosub pause
print "        Process Control"
print ""
print "        You could use BozoL to control machinery.  You could add commands"
print "        like TURN EVERYTHING OFF or DISPLAY STATUS OF MIXER 1.  By inventing"
print "        commands and adding them to the language you could turn BozoL into"
print "        a high level language that does almost anything, for any purpose."
print "        Users could enter direct statements or run programs that display"
print "        menus and perform certain tasks, and easily add to or modify the"
print "        system without a lot of complicated programming.  Consider these"
print "        possible additions to the language:"
print ""
print "                DISPLAY SCHEMATIC"
print "                BLOCK PHONES"
print "                ELECTRIC FENCES OFF"
print "                DISENGAGE SECURITY IN DINOSAUR EMBRYO LAB"
print ""
gosub pause
print "        With the fundamental building blocks of the language already in"
print "        place (like GOTO, GOSUB, IF, LOAD, RUN, SAVE, PRINT, INPUT, LOCATE,"
print "        COLOR, LET, etc) you can easily build a custom language that works"
print "        well, runs fast, can handle almost any programming task, and can"
print "        call subroutines written in BASIC, C, Assembler, or BozoL.  Since"
print "        most of the nitty gritty is compiled in (like what do do when the"
print "        command BLOCK PHONES is issued) it will almost always seem to"
print "        run just as fast as a compiled program."
print ""
gosub pause
goto start


two:
cls with color 1,7
print "        2. BOZOL COMMANDS AND FUNCTIONS - STARTER SET"
print ""
print "        As I mentioned in part 1, all of the fundamental building blocks"
print "        of the language, its structure, variable handling and flow control"
print "        have already been built in.  All you need to do is add new key"
print "        words and the code that is executed when BozoL sees the key word."
print ""
print "        These are the key words that are built in to BozoL already:"
print ""
print ""
print "         ASC       ASCII     BE        CALC      CASE      CHR       CLS"
print "         COLOR     CR        EQUAL     EQUALS    EVAL      FALSE     GOSUB"
print "         GOTO      IF        IN        INKEY     INPUT     IS        LCASE"
print "         LEFT      LEN       LET       LIST      LOAD      LOCATE    LOWER"
print "         LTRIM     MID       NOT       PRINT     PROMPT    QUIT      RETURN"
print "         RIGHT     RTRIM     RUN       SAME      SAVE      SET       SUBSTR"
print "         TAB       TO        TRUE      UCASE     UNTIL     UPPER     WHAT"
print "         WHILE     WITH"
print ""
gosub pause
print "        (... and added since this writing...)"
print ""
print "        END, CWAIT"
print ""
print "        See the file BOZOL.REF for a complete description of each command"
print "        and examples of how to use them in your programs."
print ""
gosub pause
goto start

three:
cls with color 1,7
print "        3. BOZOL PROGRAMMING RULES"
print ""
print "        BozoL is funny for a couple of reasons.  First, the syntax is"
print "        probably unlike any language you have ever seen.  As I mentioned"
print "        earlier, this is to make it easier for the interpreter to"
print "        parse and execute its statements.  Easier means faster."
print ""
print "        BozoL also has keywords which don't do anything.  The reason for"
print "        these keywords is to make the awkward syntax a bit easier to"
print "        stomach.  Remember these keywords when adding your own commands"
print "        to BozoL.  They can come in handy."
print ""
print "        Keywords that don't do anything:"
print ""
print "                TO, IN, WITH, IS, BE, EQUAL, OF, THE, AT"
print ""
gosub pause
print "        You will see me using these in program examples every once in a while."
print "        For instance, to assign a value to a variable you could say"
print ""
print "                SET A TO 1"
print ""
print "        Although the word " CHR 34 "TO" CHR 34 " is not really necessary.  You could also"
print "        say"
print ""
print "                SET A 1"
print ""
print "        but that looks silly and its meaning would not be clear to someone"
print "        who does not know all about BozoL (like anyone does but me!)."
print ""
gosub pause
print "        Which brings up another rule:  BozoL statements are parsed with"
print "        spaces, commas, or semicolons.  It does not matter which you use"
print "        and it does not matter how you mix them.  For instance, these"
print "        expressions are all the same:"
print ""
print "                SET A TO 1"
print "                SET A,1"
print "                SET;A;1"
print "                SET   A   TO   1"
print ""
print "        Also, multiple statements can be on the same line.  In fact, it"
print "        is necessary to put multiple statements on the same line in some"
print "        cases.  Multiple statements are separated by colons, just like"
print "        BASIC."
print ""
print "                SET A TO 1: PRINT A: PRINT " CHR 34 "GoodBye!" CHR 34 ":END"
print ""
gosub pause
print "        Now here's another bit of silliness:  BozoL will also allow"
print "        you to place multiple statements on a line without using colons"
print "        to separate them, BUT if you do not use colons the statements will"
print "        be executed in REVERSE ORDER."
print ""
print "        For example, if you said"
print ""
print "                PRINT 1: PRINT 2: PRINT 3"
print ""
print "        BozoL would display this on the screen:"
print ""
print "                1"
print "                2"
print "                3"
print ""
gosub pause
print "        But if you said"
print ""
print "                PRINT 1 PRINT 2 PRINT 3"
print ""
print "        then BozoL would print this:"
print ""
print "                3"
print "                2"
print "                1"
print ""
print "        This is the magic of 'stack parsing', which is how BozoL processes"
print "        statements and functions.  For more info on stack parsing, read"
print "        the comments in the source code."
print ""
gosub pause
print "        This is not mean't to be funny or wierd.  It is very useful.  For"
print "        example, you could say"
print ""
print "        WHILE NOT LEN INKEY: NEXT RECORD: PRINT NAME,ADDRESS,PHONE"
print ""
print "        or you could also say it like this:"
print ""
print "        PRINT NAME,ADDRESS,PHONE OF THE NEXT RECORD WHILE NOT LEN INKEY"
print ""
print "        Do you see the difference between the two lines?  There is none."
print "        In the first line we broke up the sentence with colons to indicate"
print "        a specific order of the actions.  In the second line we said"
print "        everything we wanted to do and with the help of a couple of"
print "        placeholder keywords (OF and THE) which do nothing, and without"
print "        the colons it almost seems like english!"
print ""
gosub pause
print "        So to review, we have 'placeholder' commands which do nothing but"
print "        make the syntax more readable, and we have a language syntax which"
print "        goes forwards or backwards depending on whether or not you use"
print "        colons to separate multiple statements.  If you follow me this"
print "        far then we'll go on.  If not, go back a few pages."
print ""
print "        Bozol, as it is right now, leaves out some basic language functions"
print "        which may be considered important.  Particularly file I/O.  There"
print "        are no facilities to open, read, write, or append any sort of"
print "        file except for LOAD and SAVE.  Most of the major string handling"
print "        and arithmetic is included, as well as basic user interface"
print "        primatives: INPUT, PRINT, PROMPT, and INKEY."
print ""
gosub pause
print "        BozoL variable names can be any letter or word which does not"
print "        have a numeric value and is not already defined as a keyword."
print "        A BozoL variable can be of any data type.  BozoL does not"
print "        distinguish between strings and numeric data.  If a BozoL variable"
print "        contains alphabetic characters it is treated as 0 in arithmetic"
print "        functions or functions which require a numeric parameter."
print "        Variables which contain numeric data (like the number 100) can"
print "        be treated as strings in string functions like LEFT, RIGHT and"
print "        MID, etc."
print ""
print "        BozoL programs are limited to 256 defined variables and all"
print "        variables are retained when a new program is RUN.  A BozoL"
print "        program can be no more than 1000 lines in length.  There is"
print "        no effective limit to how many statements can occur on a single"
print "        line."
print ""
gosub pause
print "        A line of code in BozoL can contain multiple statements which"
print "        are separated by colons, but it may also contain statements"
print "        separated by carriage return-line feed pairs.  Each line in"
print "        the program can contain up to 32K of statements.  The entire"
print "        BozoL program cannot exceed 64K in size, unless, of course,"
print "        you modify the source code and DIM HUGE the array which contains"
print "        the program."
print ""
print "        Error checking is done by the PowerBASIC compiler except where"
print "        necessary.  If an error occurs, BozoL will display an error"
print "        message and ask if you wish to continue the program or exit to"
print "        DOS.  In the BozoL program, only the subroutine PROGRUN terminates."
print "        If you called PROGRUN from another program your program will"
print "        simply resume."
print ""
gosub pause
print "        Entering Statements"
print ""
print "        By default, BozoL begins in command line mode, like GWBASIC.  You"
print "        can enter direct statements, LOAD, or RUN a program.  When the"
print "        program ends BozoL will return you to the command line unless the"
print "        program is terminated with END or QUIT."
print ""
print "        If you preceed a direct statement with a line number from 1 to"
print "        1000, the statement will not be executed.  Instead it will be"
print "        entered into memory.  You can then type LIST to see all of the"
print "        lines currently in memory.  Any blank lines will not be displayed."
print ""
print "        To try it out, run BozoL and type these three lines:"
print ""
print "                1 PRINT " CHR 34 "This is the beginning!" CHR 34
print "                2 BE UNTIL LEN INKEY"
print "                3 PRINT " CHR 34 "This is the end!" CHR 34
print ""
gosub pause
print "        Then type LIST.  BozoL will re-display the lines that you entered."
print "        Then type the command RUN.  BozoL will print 'This is the beginning!'"
print "        and will wait for you to press any key.  After you press any key"
print "        BozoL will print 'This is the end!' and the program will terminate,"
print "        leaving you at the BozoL command prompt."
print ""
print "        Notice line 2, where we could have just said UNTIL LEN INKEY we"
print "        added the dummy word BE in front of it just because it makes the"
print "        purpose of the line a little more descriptive."
print ""
gosub pause
print "        Now if you typed SAVE " CHR 34 "PROG1" CHR 34 ", BozoL would write these three"
print "        lines to a file called " CHR 34 "PROG1" CHR 34 " in the current directory.  At any"
print "        time in the future you can type LOAD " CHR 34 "PROG1" CHR 34 " to reload the"
print "        program into memory, and then LIST or RUN, or you can just type"
print "        RUN " CHR 34 "PROG1" CHR 34 " to load and run the program.  You may have already"
print "        decided that it will be much less of a chore to write your"
print "        programs in an external text editor.  I thought about adding a"
print "        fullscreen editor to BozoL, but the best editor I have (PBWRITE)"
print "        is almost four times larger than all of BozoL by itself.  If"
print "        you want to add a text editor, do it yourself."
print ""
gosub pause
print "        You must remember that when you create a program using an editor"
print "        you may not use line numbers.  Line numbers can only be used to"
print "        enter a program at the BozoL command line.  Line numbers are"
print "        not retained by BozoL when a program is saved to disk."
print ""
print "        Assigning variables"
print ""
print "        To assign a value to a variable you can use the SET or LET"
print "        statements.  They both work the same way.  You can use either"
print "        depending on your favorite syntax."
print ""
print "                LET A BE EQUAL TO 1"
print "                SET NAME TO " CHR 34 "ERIK" CHR 34
print ""
print "        Notice the use of the " CHR 34 "dummy" CHR 34 " keywords BE EQUAL TO and TO in these"
print "        statements.  They are not necessary but can be used to provide"
print "        additional readablility in your source code."
print ""
gosub pause
print "        Using functions"
print ""
print "        Functions (like CHR, LEN, or UCASE) may require variables as"
print "        arguments. Since BozoL does not distinguish between numeric and"
print "        character data types you can use any kind of variable as an"
print "        argument to a function.  Unlike BASIC or any other language,"
print "        arguments to a function are not included in parenthesis."
print ""
print "        For example, to print ASCII code 1 in BASIC you would say"
print ""
print "                PRINT CHR$(1)"
print ""
print "        However in BozoL you would say"
print ""
print "                PRINT CHR 1"
print ""
gosub pause
print "        A statement like this in BASIC:"
print ""
print "                PRINT LTRIM$(RTRIM$(UCASE$(A$)))"
print ""
print "        Would look like this in BozoL:"
print ""
print "                PRINT LTRIM RTRIM UCASE A"
print ""
print "        Evaluating expressions"
print ""
print "        Unlike languages which employ recursive descent parsing, BozoL"
print "        does not naturally incorporate arithmetic into its syntax.  To"
print "        trigger an arithmetic evaluation you must use the CALC keyword."
print "        CALC has some synonyms which do the exact same thing but may"
print "        be preferred for better language readability.  The keywords"
print "        CALC, EVAL, WHAT, and CASE all do the same thing."
print ""
gosub pause
print "        If you want to use arithmetic (+-/*^<> or =) to evaluate an"
print "        expression you must tell BozoL to do so.  For example, if you"
print "        wanted to print 1+1, you must say"
print ""
print "                PRINT CALC 1+1"
print ""
print "        you could also say"
print ""
print "                PRINT EVAL 1+1  or PRINT WHAT 1+1 or PRINT CASE 1+1"
print ""
print "        in which case BozoL would print the number 2 on the screen.  If"
print "        you were to say"
print ""
print "                PRINT 1+1"
print ""
print "        then BozoL would print '1+1' on the screen.  The reason for doing"
print "        it this way greatly increases the speed of the interpreter.  It"
print "        also greatly reduces its complexity."
print ""
gosub pause
print "        Again, having four synonyms for CALC may seem unnecessary but they"
print "        come in handy when writing different kinds of statements.  For"
print "        example you could use the dummy word IS to make a statment that"
print "        goes like this"
print ""
print "                PRINT WHAT 1+1 IS"
print ""
print "        or you could make your source code more readable by using CASE"
print "        in conjunction with the IF statement, like"
print ""
print "                IF CASE A=B: PRINT " CHR 34 "They Match" CHR 34
print ""
gosub pause
print "        Program Logic"
print ""
print "        BozoL features the statements IF, WHILE, and UNTIL to embody its"
print "        logic.  You can add others if you like.  It's easy."
print ""
print "        When a WHILE or UNTIL statement is executed, the expression which"
print "        follows it is immediately evaluated.  If the expression is true,"
print "        UNTIL will cause BozoL to immediately abort the current line and"
print "        go on to the next one, or end the program if there are no more"
print "        statements.  WHILE is the exact opposite of UNTIL.  For example,"
print ""
print "                PRINT " CHR 34 "Hi There!" CHR 34 " UNTIL LEN INKEY"
print ""
print "        This statement will print 'Hi There!' over and over again on the"
print "        screen until the function INKEY returns something with a length."
print "        That is, until a key is pressed."
print ""
gosub pause
print "                PRINT " CHR 34 "Hi There!" CHR 34 " WHILE NOT LEN INKEY"
print ""
print "        will do the same thing.  As long as the expression remains true,"
print "        WHILE and UNTIL will continue to execute the entire line over"
print "        and over again."
print ""
print "        IF is similar.  When BozoL gets to the IF, the expression following"
print "        IF will be evaluated.  If the expression returns a non-zero value,"
print "        the remainder of the line will be executed.  If you are using"
print "        colons to delimit the individual statements on the line, this"
print "        means the remainder of the line following the IF statement.  If"
print "        you are not using colons to delimit the statements on the line"
print "        this refers to the statements which preceed the IF statements."
print ""
gosub pause
print "        In other words, the statement"
print ""
print "                IF EVAL A=B: PRINT " CHR 34 "They Match" CHR 34
print ""
print "        Will print " CHR 34 "They Match" CHR 34 "on the screen if A is equal to B.  Also,"
print "        the line"
print ""
print "                PRINT " CHR 34 "They Match" CHR 34 " IF EVAL A=B"
print ""
print "        will do the same thing."
print ""
gosub pause
print "        Program flow control"
print ""
print "        All of the program flow control in native BozoL is contained within"
print "        the simple GOTO and GOSUB...RETURN command sets.  At any point in"
print "        your program you may include a label which is on a line by itself"
print "        and is not a BozoL keyword.  Labels can be any word or words as long"
print "        as they are unique.  To jump to a label, just say GOTO ABC, where"
print "        ABC would be the label name."
print ""
print "        GOSUB works the same way, except BozoL remembers the line number"
print "        where you GOSUBed from.  At any later point you may execute a"
print "        RETURN statement and BozoL will resume program execution at the"
print "        next line following the GOSUB, unlike BASIC which will resume"
print "        execution at the next statement, which may be on the same line."
print ""
gosub pause
print "        You can GOSUB up to 32 times until you must return.  If you try"
print "        to GOSUB more than 32 times without ever returning BozoL will"
print "        give you an overflow error.  You can increase the size of the"
print "        GOSUB stack by modifying the source code, although it will"
print "        probably never be necessary."
print ""
print "        You can also GOTO or GOSUB to a line number, but this is not"
print "        advisable.  If you write BozoL programs in a text editor you"
print "        must not include line numbers.  If you have a GOTO 10 in your"
print "        program and then insert a line before line 10, GOTO 10 will"
print "        then go to the wrong line."
print ""
print "        Finally, you may GOTO or GOSUB to a line number which is"
print "        contained in a variable.  For example, you could say"
print ""
print "                SET A TO 100"
print "                GOTO A"
print ""
print ""
gosub pause
goto start

four:
cls with color 1,7
print "        4. HOW TO ADD COMMANDS AND FUNCTIONS"
print ""
print ""
print "        BozoL is kind of useless unless you intend to add your own"
print "        custom commands and functions.  That is, after all, the whole"
print "        point to having an interpreted language written in PowerBASIC."
print ""
print "        Adding commands and functions is easy.  You must be aware of"
print "        the difference between a command and a function.  A command"
print "        is a keyword which actually does something, like PRINT or"
print "        INPUT or LAUNCH THE MISSILES.  A function is a keyword which"
print "        may have parameters, operate on those parameters, and then"
print "        leave behind a return value to be acted on by another function"
print "        or a command."
print ""
gosub pause
print "        For example, CHR is a function.  CHR does not execute anything,"
print "        rather, it looks at the parameter which follows it and pushes"
print "        a new parameter onto the stack."
print ""
print "                CHR 1"
print ""
print "        This will do nothing."
print ""
print "                PRINT CHR 1"
print ""
print "        BozoL will look at the 1 and push it onto a special stack.  Then"
print "        it will look at CHR.  CHR will read the 1 off of the stack and"
print "        push a happy face back onto the stack.  PRINT will then see the"
print "        happy face on the stack and print it."
print ""
print "        Read that paragraph again and again if you didn't understand it."
print "        It can take a while to sink in if you're not familiar with the"
print "        concepts."
print ""
gosub pause
print "        To add a custom keyword you first need to think up a name for"
print "        the keyword, and then what it does.  Gee, that's kind of like"
print "        creating a new SUB or FUNCTION in PowerBASIC, isn't it?  It"
print "        is very similar."
print ""
print "        Lets start with an example.  BozoL does not have a NEW command,"
print "        which would erase the current program in memory and stop"
print "        execution.  Adding NEW to BozoL is easy."
print ""
print "        All of the commands in BozoL are broken up into a handful of"
print "        include files which have a .CMD extension.  These include"
print "        LOGIC.CMD, which contains IF, WHILE, and UNTIL, FUNCTION.CMD"
print "        which contains many rudamentary functions like ASC, CHR,"
print "        UCASE, LEFT, RIGHT, and MID, and others."
print ""
print "        LOAD, RUN, and other related commands are in the include file"
print "        LOADRUN.CMD.  If you look at this file you can see where the"
print "        guts of these commands are defined.  Each commands starts out"
print "        with a CASE statement (remember, we are in PowerBASIC now)."
print ""
gosub pause
print "        These files are included in the middle of a big SELECT CASE"
print "        loop which is in the subroutine EXEC in the file BOZOL.BAS."
print "        If you look at this file and sub you can see where all of the"
print "        *.CMD files are included."
print ""
print "        NEW would belong with the other commands in LOADRUN.CMD, although,"
print "        of course, you could put them anywhere.  Pull LOADRUN.CMD up into"
print "        the PowerBASIC editor and page down to the end of the file."
print ""
print "        Add a new item to this CASE structure.  Add a few spaces to the"
print "        end of the file and type in the line"
print ""
print "                CASE " CHR 34 "NEW" CHR 34
print ""
gosub pause
print "        This officially defines a new command in the BozoL language.  Now"
print "        all you need to do is enter some code to carry out what you want"
print "        the NEW command to do.  We want to erase the program and stop"
print "        execution of the program.  The program is stored in a shared array"
print "        called PROGRAM$(), so the next line would be this:"
print ""
print "                REDIM PROGRAM$(1000)"
print ""
print "        This would effectively erase the contents of the program array."
print "        Next you need to make sure the program stops.  BozoL thinks"
print "        that the program is running as long as the shared variable"
print "        PROG% is true.  Add the statement"
print ""
print "                PROG%=0"
print ""
print "        Now all you need to do is recompile BOZOL.BAS.  Try it out!"
print "        Enter a small program and type LIST.  Then type NEW.  Then"
print "        type LIST.  Voila!  It's gone!  You just added a new command"
print "        to BozoL!"
print ""
gosub pause
print "        Commands that use arguments"
print ""
print "        By the time BozoL gets to a command, all possible arguments are"
print "        on a special stack called the Argument Stack.  This is actually"
print "        a string array that can store up to 16 arguments at a time.  Since"
print "        mose functions and commands only require one or two arguments this"
print "        is quite adequate."
print ""
print "        You can ask for these arguments one at a time by using the"
print "        PowerBASIC function POPARG$.  For example, the print command"
print "        keeps printing whatever is returned by POPARG$ until it runs"
print "        out of arguments.  The shared variable ArgPtr% contains the"
print "        number of arguments currently on the stack.  You may find this"
print "        variable useful if you want to create commands and functions that"
print "        accept a variable number of arguments."
print ""
gosub pause
print "        Lets try adding a new command.  Fund the place in BOZOL.BAS"
print "        where all of the *.CMD files are included.  Add a new include"
print "        file called CUSTOM.CMD"
print ""
print "        Next, create CUSTOM.CMD."
print ""
print "        The first line of CUSTOM.CMD should be CASE something, where"
print "        something is the new command you want to add.  Lets add a"
print "        special purpose function which returns the entire contents of"
print "        a file.  this function does not really do anything by itself,"
print "        but it will be a keyword you can use in other expressions."
print ""
print "                CASE " CHR 34 "GETFILE" CHR 34
print "                        Buf% = FREEFILE"
print "                        OPEN POPARG$ FOR BINARY AS #Buf%"
print "                        GET #Buf%, LOF(Buf%), A$"
print "                        PUSHARG A$"
print "                        CLOSE #Buf%"
print ""
gosub pause
print "        After you have added these lines, recompile BozoL and run it."
print "        Try out this new command by typing in this direct statement"
print ""
print "                PRINT GETFILE " CHR 34 "\AUTOEXEC.BAT" CHR 34
print ""
print "        Your whole AUTOEXEC.BAT file should print out on the screen!"
print ""
print "        Notice that we used POPARG and PUSHARG to manipulate the BozoL"
print "        argument stack.  We didn't want to print " CHR 34 "GETFILE" CHR 34 ", we wanted"
print "        GETFILE to literally return the entire contents of a file,"
print "        so use used POPARG$ to find out what file name followed the"
print "        GETFILE keyword, opened the file, read the whole file into a"
print "        single variable, and then pushed the whole file onto the argument"
print "        stack.  Then PRINT looked at the argument stack to see what was"
print "        there and finds the entire contents of your AUTOEXEC.BAT.  PRINT"
print "        then prints it on the screen."
print ""
print ""
gosub pause
goto start


five:
cls with color 1,7
print "        5. CALLING BOZOL FROM YOUR OWN PROGRAMS"
print ""
print "        In addition to being able to custom the language, you will also"
print "        want to call the BozoL interpreter from your own programs.  BozoL"
print "        requires the DIM and SHARED statements which exist at the top of"
print "        BOZOL.BAS to be already defined in your own program.  Once you"
print "        have done this all you need to do is call the subroutine PROGRUN."
print "        PROGRUN requires an array as a parameter, preferably PROGRAM$(),"
print "        although you can pass it any other string array if you like.  You"
print "        must also specify whether or not you want BozoL to actually start"
print "        running the program in PROGRAM$ or to display a command prompt"
print "        and wait for someone to type RUN.  This is done by placing a"
print "        true or false value into the shared variable PROG%. If PROG% is"
print "        true then the program will run.  If it is false then PROGRUN"
print "        will just display an OK prompt and wait for a command to be"
print "        entered at the keyboard.  If you simply want to invoke the"
print "        interpeter, just call PROGRUN with prog% set to 0."
print ""
gosub pause
print "        If the program contained in PROGRAM$ ends without and explicit"
print "        END or QUIT statement, the user will be returned to a command"
print "        prompt.  END or QUIT exits the PROGRUN sub completely, returning"
print "        control to your program, or to DOS, depending on how you may"
print "        have it set up"
gosub pause
goto start


pause:
prompt "        ■ press ESC to quit or any other key to continue" in color 15,7 at locate 24,1
set temp to cwait
end if what ascii of temp is = 27
cls with color 1,7
locate 2,5:print "BozoL text file" in color 10,7
print            "===============" at locate 3,5
locate 5,1 in color 1,7:return