
yabasic, yet another basic for unix and win95

  Current Version: 2.003
  
   This document contains some information about my little
   basic-interpreter.
   
   In short it implements the most common (and simple) elements of the
   langugage plus some Grafic facilities; anyone, who has ever written
   basic-programs on a C64 should feel at home.
   
   This page is the html-description of the yabasic. There is no further
   documentation, neither a unix-man-page nor a win95-helpfile.
     _________________________________________________________________
                                      
   Covered issues are:
     * Unix: 
          + Usage,
          + options,
          + setting defaults 
     * Win95: 
          + Usage,
          + options,
          + setting defaults
     * Language Description by examples
          + rem,for,input,print,goto
          + gosub,on gosub,return
          + dim,read,data,restore
          + open,close
          + wait,bell,inkey$
          + Functions in examples
          + Grafics in examples
          + Printing
          + Internal Variables
     * Internals 
     * Copyleft 
       
     _________________________________________________________________
                                      
Unix

  Unix usage
  
   Invoking yabasic under Unix is simple:
   
     yabasic [options] [filename]
     
   Where filename is the name of the file, containing the basic-Program.
   
   If you type yabasic without any filename, the program will read from
   standard input until you type RETURN twice.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Under Unix the following options are supported:
  
   -h
          Prints out a short help message; -help or -? are accepted as
          well.
          
   -fg foreground-color
          Sets the foreground color for grafics. The usual X colornames
          like red, green are accepted.
          
   -bg background-color
          Sets the background color.
          
   -geometry geometry-string
          The usual X geometry-string will be accepted (e.g. +10+10), but
          any window size will be ignored.
          
   -display Name-of-Display
          Name of the Display, where the window should appear.
          
   -font Name-of-font
          Name of the font which will be used for grafics text.
          
   -i
          Sets the initial infolevel. This controls the amount of
          information one gets about the progress of program execution,
          Every level contains all lower levels (e.g. w contains f and
          e). and can be one of:
          
        d
                Set the inoflevel to diagnostic : This gives detailed
                debugging information; much more output than you'd like
                to read.
                
        n
                note : Useful information; e.g. about execution time and
                memory consumption.
                
        w
                warning : Gives you warnings, that something has gone
                wrong (e.g. division by zero); nevertheless execution
                proceeds.
                
        e
                error : There is a serious error (e.g. array boundary
                violation), stopping the program.
                
        f
                fatal : Something has gone wrong an cannot be ment; the
                interpreter exits immediately. Most often in the course
                of an arithmetic fault (floating point exception).
                
          The initial infolevel is w.
          
   Back to table of contents ...
     _________________________________________________________________
                                      
  Examples for for Unix
  
     yabasic -i d test.yab
     
   calls the interpreter to execute the file test.yab, reporting in
   detail about its work.
   
     yabasic test.yab
     
   The same as above, but with inolevel=warning (the default).
   
     yabasic
     
   Now You have to type in your program by hand. Press RETURN twice, when
   done.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Setting defaults under Unix
  
   The colors, the text-font and the window position should be set on the
   command-line , or specified in the users resource file; e.g. like:
   
  yabasic*foreground: blue
  yabasic*background: gold
  yabasic*geometry: +10+10
  yabasic*font: 9x15

   Back to table of contents ...
     _________________________________________________________________
                                      
Win95

  Usage under Win95
  
   After you have run the setup program, yabasic can be invoked in three
   ways:
     * Choose "yabasic" in the start-menu: This allows for typing in your
       program immediatly on the console-window.
     * Click with the right mousebutton on the root window. Choose 'new'
       in the context-menu appearing; this gives you a new icon on your
       desktop. Its context-menu has the two entries 'execute' and
       'edit'. Doubleclick executes the program.
     * Create a file containing your yabasic-program. This file should
       have the extension ".yab". Double-click on this file then invokes
       yabasic, executing your program.
       
   Back to table of contents ...
     _________________________________________________________________
                                      
  Options for Win95
  
   -h
          Prints out a short help message; -help or -? are accepted as
          well.
          
   -geometry geometry-string
          E.g. +10+10 will place the grafic-window 10 pixels below and
          left of the upper left corner of the screen.
          
   -font Name-of-font
          Name of the font which will be used for grafics text. Can be
          any of:
          decorative, dontcare, modern, roman, script, swiss
          
   -i
          Sets the initial infolevel. This controls the amount of
          information one gets about the progress of program execution,
          Every level contains all lower levels (e.g. w contains f and
          e). and can be one of:
          
        d
                Set the inoflevel to diagnostic : This gives detailed
                debugging information; much more output than you'd like
                to read.
                
        n
                note : Useful information; e.g. about execution time and
                memory consumption.
                
        w
                warning : Gives you warnings, that something has gone
                wrong (e.g. division by zero); nevertheless execution
                proceeds.
                
        e
                error : There is a serious error (e.g. array boundary
                violation), stopping the program.
                
        f
                fatal : Something has gone wrong an cannot be ment; the
                interpreter exits immediately. Most often in the course
                of an arithmetic fault (floating point exception).
                
          The initial infolevel is w.
          
   Back to table of contents ...
     _________________________________________________________________
                                      
  Customization under Win95
  
   To choose the default-values for grafic-font, fontsize and
   windowposition, You have to edit the registry
   
   Yabasic stores its defaults under:
   
     HKEY_LOCAL_MACHINE/SOFTWARE/yabasic
     
   Back to table of contents ...
     _________________________________________________________________
                                      
Language Description

   Instead of giving a detailed language description, which can be found
   in many books, I will reproduce here some simple Programs (all of them
   totally useless for themselves).
   
   The first one introduces half of the language:
   
rem  this is a simple test-program !
REM  This is a comment
# this is a comment too
label loop
  for a=1 to 100 step 2:print a:next a
  input "once more ? (y/n)" a$
if (a$="y" or a$="j") then goto loop
            else print "byebye" fi

   Among others, the following things can be seen:
     * The REM-statement is used to start comments, which extend til the
       end of the line. A hash ('#') has the same effect, except that it
       must appear as the very first character within a line. This
       feature is intended for Unix allowing a yabasic-program to specify
       yabasic as the appropriate interpreter (e.g. something like
       "#!/usr/bin/yabasic")
     * Command names are not case sensitive (variables and functions
       are).
     * There are no line numbers; if you want to jump to a specific
       location you have to put a label there.
     * The only loop is the for-loop. The step-part is optional, its got
       to be a plain number !
     * Commands are delimited by a colon (":") or the newline character.
     * There are two sorts of variables; double like a,b,LongName and
       strings like a$,b$ marked with a trailing Dollar sign.
     * The if statement has an optional else branch, and has to be ended
       with fi or endif
       
   Back to table of contents ...
     _________________________________________________________________
                                      
   The next example introduces the gosub statement
   
rem This Program is good for nothing ...
input "Please enter a number" num
on num gosub one,two,three,four,five,six,seven
end
label one:print "one":return
label two:print "two":return
rem
rem     guess you can imagine the rest ...
rem

   In fact, it shows the even cooler ON GOSUB statement; depending on the
   value of num the execution is continued at the labels one, two and so
   on. ON GOTO can be used as well. Furthermore you see, that the input
   statement can handle an optional prompt string (which is not separated
   by a comma)
   
   Back to table of contents ...
     _________________________________________________________________
                                      
   Now it's time for arrays and READ, DATA, RESTORE:
   
rem Show READ,DATA,RESTORE and ARRAYS !
restore table:read length
dim number(length),name$(length)
rem NOTE: number has length+1 elements !
rem       The index can start from zero !
for a=1 to length:read number(a),name$(a):next a

label table:rem here comes the data
data 4,1,"one",2,"two",3,"three",4,"four"

   The RESTORE statement comes with an optional label; DATA lines can
   appear anywhere in the code. As you see, every array has to be dimed
   before first use; there is no limit on array size but array dimension
   has to be less than 10.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
   The last example tells about I/O:
   
open 1,"numbers","w"
print #1 "one, two, three"
close 1

   Every file has to be opened; giving it:
     * A number for identification (here 1), which ranges from 1 to 9.
       This number is not related to the standard UNIX file numbers;
       especially 1 and 2 are not stdout or stderr.
     * A filename in usual UNIX convention.
     * A string giving the access mode. This string is directly used in
       the underlying C-call fopen(); so its meaning can be found in any
       C-book. Here is a selection:
          + r: read only.
          + w: overwrite file if it already exists, create and write
            otherwise.
          + a: append to file.
       
   In any print or input statement the file number has to appear preceded
   by a hash (#).
   The file is closed with close (guess you're not surprised).
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Other commands
  
   Right now these are the following three:
   
   wait seconds
          Waits a specified number of seconds, which can be any real
          number.
          pause will be understood as well.
          
   bell
          Ring the terminals bell.
          
   inkey$
          Returns any pressed key. The function waits until a key is
          pressed and accepts printable keys only.
          
   Back to table of contents ...
     _________________________________________________________________
                                      
  Functions in examples:
  
   sin,asin,cos,acos
          These are the trigonometric functions, operating in Radian;
          i.e. sin(3.14159) = -1.0. By the way: there is a predefined
          variable PI, so you might as well write sin(PI).
          
   tan,atan
          These are trigonometric functions too, but at least atan offers
          an additional feature: atan(x/y) can be replaced by atan(x,y);
          the latter comes from the C-function atan2() and has the
          advantage of giving the right angle in the full span from 0 to
          2*PI.
          
   exp,log
          These are exponential and logarithmic functions for the base
          2.71828 , which is predefined in the variable EULER
          
   sqrt
          Is the normal square root, i.e. sqrt(2)=1.41421.
          
   int, frac
          Give integer and fractional Part of an arithemtic expression:
          int(3.141)=3.0 and frac(3.141)=0.141.
          
   left$,right$,mid$
          Are the well known (I hope so) string-functions:
          left$("12345",2)="12"
          right$("12345",2)="56"
          mid$("12345",3,2)="34"
          
   len
          Gives the length of a string: len("123456")=6.0.
          
   val
          Tries to read a string as a number: val("12.0")=12.0 and
          val("Hello2.0")=0.0
          
   str$
          Just the opposit: str$(12.0)="12.000000"
          
   Back to table of contents ...
     _________________________________________________________________
                                      
  Grafics in examples:
  
   yabasic includes some rudimental grafics:
   
rem
rem All features of grafic
rem
print "Test of Grafic"
open window 400,400

line 200,0 to 200,400
line 0,200 to 400,200

text "test",120,120
text 100,100,"test" : rem      both variants work ...

input "press RETURN ..." a$
clear window
for a=0 to 400:dot a,200+100*sin((a-200)/30):next a

circle 200,200,150
input "Press RETURN ..." a$

clear window
close window

   As You can see from the listing, there are commands to open, clear and
   close a single window, to draw lines, circles, text and dots.
   open window takes three arguments, specifying the x,y-extension of the
   window to be created and the height of the font, used for printertext.
   
   You can just as well call open window with zero or two arguments.
   Missing data will be taken from the appropriate internal variables
   yabwinwidth, yabwinheight, yabfontheight. This is all there is for
   grafic !
   
   So, you can not change colors or any line properties, you can not open
   multiple windows and you can not erase any single dot. Some of these
   features might be added in the future ...
   
   The size of the window is specified in the open window command; any
   value given in the geometry-resource is ignored.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Printing
  
   Printing is simple (and identical under Win95 and Unix):
   
open printer "printeroutput"
open window 400,400
line 200,0 to 200,400
close printer
close window

   As you see, there are only two commands related with printing:
   
   open printer [filename]
          Opens filename and starts printing. From now on, every
          grafic-command will be executed on screen and paper.
          filename can be omitted, printer commands will then be send to
          the printer directly.
          
   close printer
          stops printing. If you print to file, the file will be closed.
          If you print to the printer directly, the page will be printed.
          
   Every grafic-command between open printer and close printer is
   mirrored to paper. The grafics well be scaled to fit on a
   DIN-A4-sheet.
   
   If you want to print without opening a window, you've got to tell the
   computer, how large the window would have been. Yabasic needs this
   info to scale the printer-output correctly. This information can be
   passed using the three internal variables yabwinwidth, yabwinheight,
   yabfontheight.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Internal variables
  
   Internal Variables can be read or assigned as any other variable (E.g.
   yabwinwidth=100). But their value influences the way, yabasic works.
   Every internal variable starts with yab.
   
   There are three internal variables connected with grafics:
     * yabwinwidth: specifies the the default width of the grafic window.
       This value will be used, if the call of open window doesn't
       specify this value. The initial value is 100.
     * yabwinheight: specifies the the default height of the grafic
       window. This is a fallback-value too. The initial value is 100.
     * yabfontheight: specifies the the default height of the graficfont.
       This is a fallback-value too. The initial value is 10.
       
   Finally, there are six variables to set the infolevel at runtime:
     * yabinfolevel set this to any of the next five variables, to change
       the infolevel during execution of the program.
     * yabfatal: fatal-infolevel.
     * yaberror: error-infolevel.
     * yabwarning: warning-infolevel.
     * yabnote: note-infolevel.
     * yabdiagnostic: diagnostic-infolevel.
       
   A valid assignement would be yabinfolevel=yabnote, setting the
   infolevel to note.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
Internals

   yabasic has been written in an attempt to learn Flex and Bison. Which
   are the prime tools used for its construction. 12322 Bytes of Flex and
   Bison instructions resulted in 106486 Bytes of C-code, which has to be
   compared with the 82717 Bytes C-code I wrote myself, coding the rest
   of yabasic. So most of the code has been generated by Flex and Bison !
   
   Although yabasic behaves mostly like an interpreter, in fact it is
   not; Rather it's a compiler: If you give it any basic-code for
   execution, the code is compiled yielding instructions for a simple
   stack-machine; these instructions are then interpreted immedeately, so
   that you will never get in touch with the stack-machine. You can find
   out the time needed for this process, if you invoke yabasic with
   infolevel set to note.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
Copyrights

   Yabasic is due to the GNU copyleft, which (in a nutshell) gives you
   every freedom, except the right to restrict other people's freedom. To
   get an idea of it I just reproduce the preamble of the GNU copyleft;
   the exact terms can be found in the file COPYING which comes along as
   part of the distribution, or can be obtained from the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
   
   Back to table of contents ...
     _________________________________________________________________
                                      
  Preamble
  
   The licenses for most software are designed to take away your freedom
   to share and change it. By contrast, the GNU General Public License is
   intended to guarantee your freedom to share and change free
   software--to make sure the software is free for all its users. This
   General Public License applies to most of the Free Software
   Foundation's software and to any other program whose authors commit to
   using it. (Some other Free Software Foundation software is covered by
   the GNU Library General Public License instead.) You can apply it to
   your programs, too.
   
   When we speak of free software, we are referring to freedom, not
   price. Our General Public Licenses are designed to make sure that you
   have the freedom to distribute copies of free software (and charge for
   this service if you wish), that you receive source code or can get it
   if you want it, that you can change the software or use pieces of it
   in new free programs; and that you know you can do these things.
   
   To protect your rights, we need to make restrictions that forbid
   anyone to deny you these rights or to ask you to surrender the rights.
   These restrictions translate to certain responsibilities for you if
   you distribute copies of the software, or if you modify it.
   
   For example, if you distribute copies of such a program, whether
   gratis or for a fee, you must give the recipients all the rights that
   you have. You must make sure that they, too, receive or can get the
   source code. And you must show them these terms so they know their
   rights.
   
   We protect your rights with two steps: (1) copyright the software, and
   (2) offer you this license which gives you legal permission to copy,
   distribute and/or modify the software.
   
   Also, for each author's protection and ours, we want to make certain
   that everyone understands that there is no warranty for this free
   software. If the software is modified by someone else and passed on,
   we want its recipients to know that what they have is not the
   original, so that any problems introduced by others will not reflect
   on the original authors' reputations.
   
   Finally, any free program is threatened constantly by software
   patents. We wish to avoid the danger that redistributors of a free
   program will individually obtain patent licenses, in effect making the
   program proprietary. To prevent this, we have made it clear that any
   patent must be licensed for everyone's free use or not licensed at
   all.
