Man Linux: Main Page and Category List

NAME

       yabasic - yet another Basic

SYNOPSIS

       yabasic [options] [filename [arguments]]

DESCRIPTION

       Yabasic  is  a  simple,  old  fashioned  basic  interpreter  with  some
       additional features  like  subroutines  and  libraries.   Graphics  and
       printing are limited but very easy to use.

       Yabasic is documented within the file yabasic.htm, which may or may not
       be present on your system; in any case this document can  be  found  on
       www.yabasic.de.

       However,  this  html-document  has been inserted as a preformatted text
       into this man page. Note, that you will at least need an  eighty-column
       terminal to read this text without ugly wrapped lines.

       Moreover,  this  man-page contains some chapters, that are specific for
       windows and do not directly apply to your system.

       Finally note, that this man-page (unlike the html-document it is  based
       upon)  does  not contain hyperlinks. In fact due to its large number of
       hyperlinks the html-document is much easier  to  read,  understand  and
       navigate than this man-page. However if you are determined to read this
       man-page, there are three especially  useful  ways  to  navigate;  each
       works by searching for specific strings:

       ·   To  go  to  a  specific  chapter (e.g. Chapter 5, "All commands and
           functions of yabasic"), you may look up the number of this  chapter
           in  the  table  of contents and search for the string "Chapter 5.";
           please note the uppercase "C" and the dot.

       ·   To go to the description of  a  specific  command  (e.g.  the  for-
           command),  you  may  search for its name followed by a single space
           and a double hyphen. In the example this would be "for --".

       ·   The description of functions  contain  the  name  of  the  function
           followed  by  parens  ("()"). Therefore, to find the description of
           the sine-function, you should search for "sin\(\) --".  Note,  that
           you  will  probably  need to escape those parens by prepending them
           with a backslash ("\").

  But now for the documentation itself:

  Yabasic
       _________________________________________________________________

     Table of Contents

     1. Introduction

          About this document
          About yabasic

     2. The yabasic-program under Windows

          Starting yabasic
          Options
          The context Menu

     3. The yabasic-program under Unix

          Starting yabasic
          Options
          Setting defaults

     4. Some features of yabasic, explained by topic

          print, input and others
          Control statements: loops, if and switch
          Drawing and painting
          Reading from and writing to files
          Subroutines and Libraries
          String processing
          Arithmetic
          Data and such
          Other interesting commands.

     5. All commands and functions of yabasic listed by topic

          Number processing and conversion
          Conditions and control structures
          Data keeping and processing
          String processing
          File operations and printing
          Subroutines and libraries
          Other commands
          Graphics and printing

     6. All commands and functions of yabasic grouped alphabetically

          A
          B
          C
          D
          E
          F
          G
          H
          I
          L
          M
          N
          O
          P
          R
          S
          T
          U
          V
          W
          X
          Special characters
          Reserved Words

     7. A grab-bag of some general concepts and terms

          Logical shortcuts
          Conditions and expressions
          References on arrays
          Specifying Filenames under Windows
          Escape-sequences
          Creating a standalone program from your yabasic-program

     8. A few example programs

          A very simple program
          The demo of yabasic

     9. The Copyright of yabasic

  Chapter 1. Introduction

     About this document
     About yabasic

  About this document

     This document describes yabasic. You will find information about the yabasic
     interpreter (the program yabasic under Unix or yabasic.exe under Windows) as
     well as the language (which is, of course, a sort of basic) itself.

     This document applies to version 2.760 of yabasic

     However, this document does not contain the latest news about yabasic or a
     FAQ. As such information tends to change rapidly, it is presented online
     only at www.yabasic.de.

     Although basic has its reputation as a language for beginning programmers,
     this is not an introduction to programming at large. Rather this text
     assumes, that the reader has some (moderate) experience with writing and
     starting computer programs.

  About yabasic

     yabasic is a traditional basic interpreter. It understands most of the
     typical basic-constructs, like goto, gosub, line numbers, read, data or
     string-variables with a trailing ’$’. But on the other hand, yabasic
     implements some more advanced programming-constructs like subroutines or
     libraries (but not objects). yabasic works much the same under Unix and
     Windows.

     yabasic puts emphasis on giving results quickly and easily; therefore simple
     commands are provided to open a graphic window, print the graphics or
     control the console screen and get keyboard or mouse information. The
     example below opens a window, draws a circle and prints the graphic:
  open window 100,100
  open printer
  circle 50,50,40
  text 10,50,"Press any key to get a printout"
  clear screen
  inkey$
  close printer
  close window

     This example has fewer lines, than it would have in many other programming
     languages. In the end however yabasic lacks behind more advanced and modern
     programming languages like C++ or Java. But as far as it goes it tends to
     give you results more quickly and easily.

  Chapter 2. The yabasic-program under Windows

     Starting yabasic
     Options
     The context Menu

  Starting yabasic

     Once, yabasic has been set up correctly, there are three ways to start it:
      1. Right click on your desktop: The desktop menu appears with a submenu
         named new. From this submenu choose yabasic. This will create a new icon
         on your desktop. If you right click on this icon, its context menu will
         appear; choose Execute to execute the program.
      2. As a variant of the way described above, you may simply create a file
         with the ending .yab (e.g. with your favorite editor). Everything else
         then works as described above.
      3. From the start-menu: Choose yabasic from your start-menu. A
         console-window will open and you will be asked to type in your program.
         Once you are finished, you need to type return twice, and yabasic will
         parse and execute your program.

  Note
         This is not the preferred way of starting yabasic ! Simply because the
         program, that you have typed, can not be saved and will be lost
         inevitably ! There is no such thing as a save-command and therefore no
         way to conserve the program, that you have typed. This mode is only
         intended for quick hacks, and short programs.

  Options

     Under Windows yabasic will mostly be invoked by double-clicking on an
     appropriate icon; this way you do not have a chance to specify any of the
     command line options below. However, advanced users may add some of those
     options to the appropriate entries in the registry.

     All the options below may be abbreviated, as long as the abbreviation does
     not become ambiguous. For example, you may write -e instead of -execute.

     -help or -?
            Prints a short help message, which itself describes two further
            help-options.

     -version
            Prints the version of yabasic.

     -geometry +X-POSITION+Y-POSITION
            Sets the position of the graphic window, that is opened by open
            window (the size of this window, of course, is specified within the
            open window-command). An example would be -geometry +20+10, which
            would place the graphic window 10 pixels below the upper border and
            20 pixels right of the left border of the screen. This value cannot
            be changed, once yabasic has been started.

     -font NAME-OF-FONT
            Name of the font, which will be used for graphic-text; can be any of
            decorative, dontcare, modern, roman, script, swiss. You may append a
            fontsize (measured in pixels) to any of those fontnames; for example
            -font swiss30 chooses a swiss-type font with a size of 30 pixels.

     -bind NAME-OF-STANDALONE-PROGRAM
            Create a standalone program (whose name is specified by
            NAME-OF-STANDALONE-PROGRAM) from the yabasic-program, that is
            specified on the command line. See the section about creating a
            standalone-program for details.

     -execute A-PROGRAM-AS-A-SINGLE-STRING
            With this option you may specify some yabasic-code to be executed
            rigth away.This is useful for very short programs, which you do not
            want to save within a file. If this option is given, yabasic will not
            read any code from a file. Let’s say, you have forgotten some of the
            square numbers between 1 and 10; in this case the command yabasic -e
            ’for a=1 to 10:print a*a:next a’ will give you the answer
            immediately.

     -infolevel INFOLEVEL
            Change the infolevel of yabasic, where INFOLEVEL can be one of debug,
            note, warning, error and fatal (the default is warning). This option
            changes the amount of debugging-information yabasic produces.
            However, normally only the author of yabasic (me !) would want to
            change this.

     -doc NAME-OF-A-PROGRAM
            Print the embedded documentation of the named program. The embedded
            documentation of a program consists of all the comments within the
            program, which start with the special keyword doc. This documentation
            can also be seen by choosing the corresponding entry from the
            context-menu of any yabasic-program.

     -librarypath DIRECTORY-WITH-LIBRARIES
            Change the directory, wherein libraries will be searched and imported
            (with the import-command). See also this entry for more information
            about the way, libraries are searched.

  The context Menu

     Like every other icon under Windows, the icon of every yabasic-program has a
     context menu offering the most frequent operations, that may be applied to a
     yabasic-program.

     Execute
            This will invoke yabasic to execute your program. The same happens,
            if you double click on the icon.

     Edit
            notepad will be invoked, allowing you to edit your program.

     View docu
            This will present the embedded documentation of your program.
            Embedded documentation is created with the special comment doc.

  Chapter 3. The yabasic-program under Unix

     Starting yabasic
     Options
     Setting defaults

  Starting yabasic

     If your system administrator (vulgo root) has installed yabasic correctly,
     there are three ways to start it:
      1. You may use your favorite editor (emacs, vi ?) to put your program into
         a file (e.g. foo). Make sure that the very first line starts with the
         characters ’#!’ followed by the full pathname of yabasic (e.g.
         ’#!/usr/local/bin/yabasic’). This she-bang-line ensures, that your Unix
         will invoke yabasic to execute your program (see also the entry for the
         hash-character). Moreover, you will need to change the permissions of
         your yabasic-program foo, e.g. chmod u+x foo. After that you may invoke
         yabasic to invoke your program by simply typing foo (without even
         mentioning yabasic). However, if your PATH-variable does not contain a
         single dot (’.’) you will have to type the full pathname of your
         program: e.g. /home/ihm/foo (or at least ./foo).
      2. Save your program into a file (e.g. foo) and type yabasic foo. This
         assumes, that the directory, where yabasic resides, is contained within
         your PATH-variable.
      3. Finally your may simply type yabasic (maybe it will be necessary to
         include its full pathname). This will make yabasic come up and you will
         be asked to type in your program. Once you are finished, you need to
         type return twice, and yabasic will parse and execute your program.

  Note
         This is not the preferred way of starting yabasic ! Simply because the
         program, that you have typed, can not be saved and will be lost
         inevitably ! There is no such thing as a save-command and therefore no
         way to conserve the program, that you have typed. This mode is only
         intended for quick hacks, and short programs, i.e. for using yabasic as
         some sort of fancy desktop calculator.

  Options

     yabasic accepts a number of options on the command line. All these options
     below may be abbreviated, as long as the abbreviation does not become
     ambiguous. For example you may write -e instead of -execute.

     -help or -?
            Prints a short help message, which itself describes two further
            help-options.

     -version
            Prints the version of yabasic.

     -fg FOREGROUND-COLOR or -foreground FOREGROUND-COLOR
            Define the foreground color for the graphics-window (that will be
            opened with open window). The usual X11 color names, like red, green,
            ... are accepted. This value cannot be changed, once yabasic has been
            started.

     -bg BACKGROUND-COLOR or -background BACKGROUND-COLOR
            Define the background color for the graphics-window. The usual X11
            color names are accepted. This value cannot be changed, once yabasic
            has been started.

     -geometry +X-POSITION+Y-POSITION
            Sets the position of the graphic window, that is opened by open
            window (the size of this window, of course, is specified with the
            open window-command). An example would be +20+10, which would place
            the graphic window 10 pixels below the upper border and 20 pixels
            right of the left border of the screen. Note, that the size of the
            window may not be specified here (well it may, but it will be ignored
            anyway). This value cannot be changed, once yabasic has been started.

     -display BACKGROUND-COLOR
            Specify the display, where the graphics window of yabasic should
            appear. Normally, however this value will be already present within
            the environment variable DISPLAY.

     -font NAME-OF-FONT
            Name of the font, which will be used for text within the graphics
            window.

     -execute A-PROGRAM-AS-A-SINGLE-STRING
            With this option you may specify some yabasic-code to be executed
            rigth away.This is useful for very short programs, which you do not
            want to save to a file. If this option is given, yabasic will not
            read any code from a file. E.g.

  yabasic -e ’for a=1 to 10:print a*a:next a’

            prints the square numbers from 1 to 10.

     -bind NAME-OF-STANDALONE-PROGRAM
            Create a standalone program (whose name is specified by
            NAME-OF-STANDALONE-PROGRAM) from the yabasic-program, that is
            specified on the command line. See the section about creating a
            standalone-program for details.

     -infolevel INFOLEVEL
            Change the infolevel of yabasic where INFOLEVEL can be one of debug,
            note, warning, error and fatal (the default is warning). This option
            changes the amount of debugging-information yabasic produces.
            However, normally only the author of yabasic (me !) would want to
            change this.

     -doc NAME-OF-A-PROGRAM
            Print the embedded documentation of the named program. The embedded
            documentation of a program consists of all the comments within the
            program, which start with the special keyword doc.

     -librarypath DIRECTORY-WITH-LIBRARIES
            Change the directory from which libraries will be imported (with the
            import-command). See also this entry for more information about the
            way, libraries will be searched.

  Setting defaults

     If you want to set some options once for all, you may put them into your
     X-Windows resource file. This is usually the file .Xresources or some such
     within your home directory (type man X for details).

     Here is a sample section, which may appear within this file:
  yabasic*foreground: blue
  yabasic*background: gold
  yabasic*geometry: +10+10
  yabasic*font: 9x15

     This will set the foreground color of the graphic-window to blue and the
     background color to gold. The window will appear at position 10,10 and the
     text font will be 9x15.

  Chapter 4. Some features of yabasic, explained by topic

     print, input and others
     Control statements: loops, if and switch
     Drawing and painting
     Reading from and writing to files
     Subroutines and Libraries
     String processing
     Arithmetic
     Data and such
     Other interesting commands.

     This chapter has sections for some of the major features of yabasic and
     names a few commands related with each area. So, depending on your interest,
     you find the most important commands of this area named; the other commands
     from this area may then be discovered through the links in the see
     also-section.

  print, input and others

     The print-command is used to put text on the text screen. Here, the term
     text screen stands for your terminal (under Unix) or the console window
     (under Windows).

     At the bottom line, print simply outputs its argument to the text window.
     However, once you have called clear screen you may use advanced features
     like printing colors or copying areas of text with getscreen$ or putscreen.

     You may ask the user for input with the input-command; use inkey$ to get
     each key as soon as it is pressed.

  Control statements: loops, if and switch

     Of course, yabasic has the goto- and gosub-statements; you may go to a label
     or a line number (which is just a special kind of label). goto, despite its
     bad reputation ([goto considered harmful]), has still its good uses; however
     in many cases you are probably better off with loops like repeat-until,
     while-wend or do-loop; you may leave any of these loops with the
     break-statement or start the next iteration immediately with continue.

     Decisions can be made with the if-statement, which comes either in a short
     and a long form. The short form has no then-keyword and extends up to the
     end of the line. The long form extends up to the final endif and may use
     some of the keywords then (which introduces the long form), else or elsif.

     If you want to test the result of an expression against many different
     values, you should probably use the switch-statement.

  Drawing and painting

     You need to call open window before you may draw anything with either line,
     circle, rectangle or triangle; all of these statements may be decorated with
     clear or fill. If you want to change the colour for drawing, use colour.
     Note however, that there can only be a single window open at any given
     moment in time.

     Everything you have drawn can be send to your printer too, if you use the
     open printer command.

     To allow for some (very) limited version of animated graphics, yabasic
     offers the commands getbit$ and putbit, which retrieve rectangular regions
     from the graphics-window into a string or vice versa.

     If you want to sense mouse-clicks, you may use the inkey$-function.

  Reading from and writing to files

     Before you may read or write a file, you need to open it; once you are done,
     you should close it. Each open file is designated by a simple number, which
     might be stored within a variable and must be supplied if you want to access
     the file. This is simply done by putting a hash (’#’) followed by the number
     of the file after the keyword input (for reading from) or print (for writing
     to a file) respectively.

     If you need more control, you may consider reading and writing one byte at a
     time, using the multi-purpose commands peek and poke.

  Subroutines and Libraries

     The best way to break any yabasic-program into smaller, more manageable
     chunks are subroutines and libraries. They are yabasic’s most advanced means
     of structuring a program.

     Subroutines are created with the command sub. they accept parameters and may
     return a value. Subroutines can be called much like any builtin function of
     yabasic; therefore they allow to extend the language itself.

     Once you have created a set of related subroutines and you feel that they
     could be useful in other programs too, you may collect them into a library.
     Such a library is contained within a separate file and may be included in
     any of your programs, using the keyword import.

  String processing

     yabasic has the usual functions to extract parts from a string: left$, mid$
     and right$. Note, that all of them can be assigned to, i.e. they may change
     part of a string.

     If you want to split a string into tokens you should use the functions token
     or split.

     There is quite a bunch of other string-processing functions like upper$
     (converting to upper case), instr (finding one string within the other),
     chr$ (converting an ascii-code into a character), glob (testing a string
     against a pattern) and more. Just follow the links.

  Arithmetic

     Yabasic handles numbers and arithmetic: You may calculate trigonometric
     functions like sin or atan, or logarithms (with log). Bitwise operations,
     like and or or are available as well min or max (calculate the minimum or
     maximum of its argument) or mod or int (reminder of a division or integer
     part or a number).

  Data and such

     You may store data within your program within data-statements; during
     execution you will probably want to read it into arrays, which must have
     been dimed before.

  Other interesting commands.

       * Yabasic programs may start other programs with the commands system and
         system$.
       * peek and poke allow to get and set internal information; either for the
         operating system (i.e. Unix or Windows) or yabasic itself.
       * The current time or date can be retrieved with (guess what !) time$ and
         date$.

  Chapter 5. All commands and functions of yabasic listed by topic

     Number processing and conversion
     Conditions and control structures
     Data keeping and processing
     String processing
     File operations and printing
     Subroutines and libraries
     Other commands
     Graphics and printing

  Number processing and conversion

     abs()
            returns the absolute value of its numeric argument

     acos()
            returns the arcus cosine of its numeric argument

     and()
            the bitwise arithmetic and

     asin()
            returns the arcus sine of its numeric argument

     atan()
            returns the arctangent of its numeric argument

     bin$()
            converts a number into a sequence of binary digits

     cos()
            return the cosine of its single argument

     dec()
            convert a base 2 or base 16 number into decimal form

     eor()
            compute the bitwise exclusive or of its two arguments

     euler
            another name for the constant 2.71828182864

     exp()
            compute the exponential function of its single argument

     frac()
            return the fractional part of its numeric argument

     int()
            return the integer part of its single numeric argument

     log()
            compute the natural logarithm

     max()
            return the larger of its two arguments

     min()
            return the smaller of its two arguments

     mod()
            compute the remainder of a division

     or()
            arithmetic or, used for bit-operations

     pi
            a constant with the value 3.14159

     ran()
            return a random number

     sig()
            return the sign of its argument

     sin()
            return the sine of its single argument

     sqr()
            compute the square of its argument

     sqrt()
            compute the square root of its argument

     tan()
            return the tangent of its argument

     xor()
            compute the exclusive or

     ** or ^
            raise its first argument to the power of its second

  Conditions and control structures

     and
            logical and, used in conditions

     break
            breaks out of a switch statement or a loop

     case
            mark the different cases within a switch-statement

     continue
            start the next iteration of a for-, do-, repeat- or while-loop

     default
            mark the default-branch within a switch-statement

     do
            start a (conditionless) do-loop

     else
            mark an alternative within an if-statement

     elsif
            starts an alternate condition within an if-statement

     end
            terminate your program

     endif
            ends an if-statement

     false
            a constant with the value of 0

     fi
            another name for endif

     for
            starts a for-loop

     gosub
            continue execution at another point within your program (and return
            later)

     goto
            continue execution at another point within your program (and never
            come back)

     if
            evaluate a condition and execute statements or not, depending on the
            result

     label
            mark a specific location within your program for goto, gosub or
            restore

     loop
            marks the end of an infinite loop

     next
            mark the end of a for loop

     not
            negate an expression; can be written as !

     on gosub
            jump to one of multiple gosub-targets

     on goto
            jump to one of many goto-targets

     on interrupt
            change reaction on keyboard interrupts

     logical or
            logical or, used in conditions

     pause
            pause, sleep, wait for the specified number of seconds

     repeat
            start a repeat-loop

     return
            return from a subroutine or a gosub

     sleep
            pause, sleep, wait for the specified number of seconds

     switch
            select one of many alternatives depending on a value

     then
            tell the long from the short form of the if-statement

     true
            a constant with the value of 1

     until
            end a repeat-loop

     wait
            pause, sleep, wait for the specified number of seconds

     wend
            end a while-loop

     while
            start a while-loop

     :
            separate commands from each other

  Data keeping and processing

     arraydim()
            returns the dimension of the array, which is passed as an array
            reference

     arraysize()
            returns the size of a dimension of an array

     data
            introduces a list of data-items

     dim
            create an array prior to its first use

     read
            read data from data-statements

     redim
            create an array prior to its first use. A synonym for dim

     restore
            reposition the data-pointer

  String processing

     asc()
            accepts a string and returns the position of its first character
            within the ascii charset

     chr$()
            accepts a number and returns the character at this position within
            the ascii charset

     glob()
            check if a string matches a simple pattern

     hex$()
            convert a number into hexadecimal

     instr()
            searches its second argument within the first; returns its position
            if found

     left$()
            return (or change) left end of a string

     len()
            return the length of a string

     lower$()
            convert a string to lower case

     ltrim$()
            trim spaces at the left end of a string

     mid$()
            return (or change) characters from within a string

     right$()
            return (or change) the right end of a string

     split()
            split a string into many strings

     str$()
            convert a number into a string

     token()
            split a string into multiple strings

     trim$()
            remove leading and trailing spaces from its argument

     upper$()
            convert a string to upper case

     val()
            converts a string to a number

  File operations and printing

     at()
            can be used in the print-command to place the output at a specified
            position

     beep
            ring the bell within your computer; a synonym for bell

     bell
            ring the bell within your computer (just as beep)

     clear screen
            erases the text window

     close
            close a file, which has been opened before

     close printer
            stops printing of graphics

     print color
            print with color

     print colour
            see print color

     eof
            check, if an open file contains data

     getscreen$()
            returns a string representing a rectangular section of the text
            terminal

     inkey$
            wait, until a key is pressed

     input
            read input from the user (or from a file) and assign it to a variable

     line input
            read in a whole line of text and assign it to a variable

     open
            open a file

     open printer
            open printer for printing graphics

     print
            Write to terminal or file

     putscreen
            draw a rectangle of characters into the text terminal

     reverse
            print reverse (background and foreground colors exchanged)

     screen
            as clear screen clears the text window

     seek()
            change the position within an open file

     tell
            get the current position within an open file

     using
            Specify the format for printing a number

     #
            either a comment or a marker for a file-number

     @
            synonymous to at

     ;
            suppress the implicit newline after a print-statement

  Subroutines and libraries

     end sub
            ends a subroutine definition

     export
            mark a function as globally visible

     import
            import a library

     local
            mark a variable as local to a subroutine

     numparams
            return the number of parameters, that have been passed to a
            subroutine

     return
            return from a subroutine or a gosub

     static
            preserves the value of a variable between calls to a subroutine

     step
            specifies the increment step in a for-loop

     sub
            declare a user defined subroutine

  Other commands

     bind()
            Binds a yabasic-program and the yabasic-interpreter together into a
            standalone program.

     compile
            compile a string with yabasic-code on the fly

     date$
            returns a string with various components of the current date

     doc
            special comment, which might be retrieved by the program itself

     docu$
            special array, containing the contents of all docu-statement within
            the program

     error
            raise an error and terminate your program

     execute$()
            execute a user defined subroutine, which must return a string

     execute()
            execute a user defined subroutine, which must return a number

     exit
            terminate your program

     pause
            pause, sleep, wait for the specified number of seconds

     peek
            retrieve various internal informations

     peek$
            retrieve various internal string-informations

     poke
            change selected internals of yabasic

     rem
            start a comment

     sleep
            pause, sleep, wait for the specified number of seconds

     system$()
            hand a statement over to your operating system and return its output

     system()
            hand a statement over to your operating system and return its
            exitcode

     time$
            return a string containing the current time

     to
            this keyword appears as part of other statements

     wait
            pause, sleep, wait for the specified number of seconds

     //
            starts a comment

     :
            separate commands from each other

  Graphics and printing

     backcolor
            specify the colour for subsequent drawing of the background

     box
            draw a rectangle. A synonym for rectangle

     circle
            draws a circle in the graphic-window

     clear
            Erase circles, rectangles or triangles

     clear window
            clear the graphic window and begin a new page, if printing is under
            way

     close curve
            close a curve, that has been drawn by the line-command

     close window
            close the graphics-window

     colour
            specify the colour for subsequent drawing

     dot
            draw a dot in the graphic-window

     fill
            draw a filled circles, rectangles or triangles

     getbit$()
            return a string representing the bit pattern of a rectangle within
            the graphic window

     line
            draw a line

     mouseb
            extract the state of the mousebuttons from a string returned by
            inkey$

     mousemod
            return the state of the modifier keys during a mouseclick

     mousex
            return the x-position of a mouseclick

     mousey
            return the y-position of a mouseclick

     new curve
            start a new curve, that will be drawn with the line-command

     open window
            open a graphic window

     putbit
            draw a rectangle of pixels into the graphic window

     rectangle
            draw a rectangle

     triangle
            draw a triangle

     text
            write text into your graphic-window

     window origin
            move the origin of a window

  Chapter 6. All commands and functions of yabasic grouped alphabetically

     A
     B
     C
     D
     E
     F
     G
     H
     I
     L
     M
     N
     O
     P
     R
     S
     T
     U
     V
     W
     X
     Special characters
     Reserved Words

  A

     abs() - returns the absolute value of its numeric argument
     acos() - returns the arcus cosine of its numeric argument
     and - logical and, used in conditions
     and() - the bitwise arithmetic and
     arraydim() - returns the dimension of the array, which is passed as an array
            reference

     arraysize() - returns the size of a dimension of an array
     asc() - accepts a string and returns the position of its first character
            within the ascii charset

     asin() - returns the arcus sine of its numeric argument
     at() - can be used in the print-command to place the output at a specified
            position

     atan() - returns the arctangent of its numeric argument

  Name

     abs() - returns the absolute value of its numeric argument

  Synopsis

  y=abs(x)

  Description

     If the argument of the abs-function is positive (e.g. 2) it is returned
     unchanged, if the argument is negative (e.g. -1) it is returned as a
     positive value (e.g. 1).

  Example

  print abs(-2),abs(2)

     This example will print 2 2

  See also

     sig
       _________________________________________________________________

  Name

     acos() - returns the arcus cosine of its numeric argument

  Synopsis

  x=acos(angle)

  Description

     acos is the arcus cosine-function, i.e. the inverse of the cos-function. Or,
     more elaborate: It Returns the angle (in radian, not degree !), which, fed
     to the cosine-function will produce the argument passed to the
     acos-function.

  Example

  print acos(0.5),acos(cos(pi))

     This example will print 1.0472 3.14159 which are pi/3 and pi respectively.

  See also

     cos, asin
       _________________________________________________________________

  Name

     and - logical and, used in conditions

  Synopsis

  if (a and b) ...
  while (a and b) ...

  Description

     Used in conditions (e.g within if, while or until) to join two expressions.
     Returns true, if and only if its left and right argument are both true and
     false otherwise.

     Note, that logical shortcuts may take place.

  Example

  input "Please enter a number" a
  if (a>=1 and a<=9) print "your input is between 1 and 9"

  See also

     or,not
       _________________________________________________________________

  Name

     and() - the bitwise arithmetic and

  Synopsis

  x=and(a,b)

  Description

     Used to compute the bitwise and of both its argument. Both arguments are
     treated as binary numbers (i.e. a series of 0 and 1); a bit of the resulting
     value will then be 1, if both arguments have a 1 at this position in their
     binary representation.

     Note, that both arguments are silently converted to integer values and that
     negative numbers have their own binary representation and may lead to
     unexpected results when passed to and.

  Example

  print and(6,3)

     This will print 2. This result is clear, if you note, that the binary
     representation of 6 and 3 are 110 and 011 respectively; this will yield 010
     in binary representation or 2 as decimal.

  See also

     or, eor and not
       _________________________________________________________________

  Name

     arraydim() - returns the dimension of the array, which is passed as an array
     reference

  Synopsis

  a=arraydim(b())

  Description

     If you apply the arraydim()-function on a one-dimensional array (i.e. a
     vector) it will return 1, on a two-dimensional array (i.e. a matrix) it will
     return 2, and so on.

     This is mostly used within subroutines, which expect an array among their
     parameters. Such subroutines tend to use the arraydim-function to check, if
     the array which has been passed, has the right dimension. E.g. a subroutine
     to multiply two matrices may want to check, if it really is invoked with two
     2-dimensional arrays.

  Example

  dim a(10,10),b(10)
  print arraydim(a()),arraydim(b())

     This will print 2 1, which are the dimension of the arrays a() and b(). You
     may check out the function arraysize for a full-fledged example.

  See also

     arraysize and dim.
       _________________________________________________________________

  Name

     arraysize() - returns the size of a dimension of an array

  Synopsis

  x=arraysize(a(),b)

  Description

     The arraysize-function computes the size of a specified dimension of a
     specified array. Here, size stands for the maximum number, that may be used
     as an index for this array. The first argument to this function must be an
     reference to an array, the second one specifies, which of the multiple
     dimensions of the array should be taken to calculate the size.

     An Example involving subroutines: Let’s say, an array has been declared as
     dim a(10,20) (that is a two-dimensional array or a matrix). If this array is
     passed as an array reference to a subroutine, this sub will not know, what
     sort of array has been passed. With the arraydim-function the sub will be
     able to find the dimension of the array, with the arraysize-function it will
     be able to find out the size of this array in its two dimensions, which will
     be 10 and 20 respectively.

     Our sample array is two dimensional; if you envision it as a matrix this
     matrix has 10 lines and 20 columns (see the dim-statement above. To state it
     more formally: The first dimension (lines) has a size of 10, the second
     dimension (columns) has a size of 20; these numbers are those returned by
     arraysize(a(),1) and arraysize(a(),2) respectively. Refer to the example
     below for a typical usage.

  Example

  rem
  rem  This program adds two matrices elementwise.
  rem

  dim a(10,20),b(10,20),c(10,20)

  rem  initialization of the arrays a() and b()
  for y=1 to 10:for x=1 to 20
     a(y,x)=int(ran(4)):b(y,x)=int(ran(4))
  next x:next y

  matadd(a(),b(),c())

  print "Result:"
  for x=1 to 20
     for y=10 to 1 step -1
        print c(y,x)," ";
     next y
     print
  next x

  sub matadd(m1(),m2(),r())

     rem  This sub will add the matrices m1() and m2()
     rem  elementwise and store the result within r()
     rem  This is not very useful but easy to implement.
     rem  However, this sub excels in checking its arguments
     rem  with arraydim() and arraysize()

     local x:local y

     if (arraydim(m1())<>2 or arraydim(m2())<>2 or arraydim(r())<>2) then
        error "Need two dimensional arrays as input"
     endif

     y=arraysize(m1(),1):x=arraysize(m1(),2)
     if (arraysize(m2(),1)<>y or arraysize(m2(),2)<>x) then
        error "The two matrices cannot be added elementwise"
     endif

     if (arraysize(r(),1)<>y or arraysize(r(),2)<>x) then
        error "The result cannot be stored in the third argument"
     endif

     local xx:local yy
     for xx=1 to x
        for yy=1 to y
           r(yy,xx)=m1(yy,xx)+m2(yy,xx)
        next yy
     next xx

   end sub

  See also

     arraydim and dim.
       _________________________________________________________________

  Name

     asc() - accepts a string and returns the position of its first character
     within the ascii charset

  Synopsis

  a=asc(char$)

  Description

     The asc-function accepts a string, takes its first character and looks it up
     within the ascii-charset; this position will be returned. The asc-function
     is the opposite of the chr$-function. There are valid uses for asc, however,
     comparing strings (i.e. to bring them into alphabetical sequence) is not
     among them; in such many cases you might consider to compare strings
     directly with <, = and > (rather than converting a string to a number and
     comparing this number).

  Example

  input "Please enter a letter between ’a’ and ’y’: " a$
  if (a$<"a" or a$>"y") print a$," is not in the proper range":end
  print "The letter after ",a$," is ",chr$(asc(a$)+1)

  See also

     chr$
       _________________________________________________________________

  Name

     asin() - returns the arcus sine of its numeric argument

  Synopsis

  angle=asin(x)

  Description

     acos is the arcus sine-function, i.e. the inverse of the sin-function. Or,
     more elaborate: It Returns the angle (in radian, not degree !), which, fed
     to the sine-function will produce the argument passed to the asin-function.

  Example

  print asin(0.5),asin(sin(pi))

     This will print 0.523599 -2.06823e-13 which is pi and almost 0 respectively.

  See also

     sin, acos
       _________________________________________________________________

  Name

     at() - can be used in the print-command to place the output at a specified
     position

  Synopsis

  clear screen
  ...
  print at(a,b)
  print @(a,b)

  Description

     The at-clause takes two numeric arguments (e.g. at(2,3)) and can be inserted
     after the print-keyword. at() can be used only if clear screen has been
     executed at least once within the program (otherwise you will get an error).

     The two numeric arguments of the at-function may range from 0 to the width
     of your terminal minus 1, and from 0 to the height of your terminal minus 1;
     if any argument exceeds these values, it will be truncated accordingly.
     However, yabasic has no influence on the size of your terminal (80x25 is a
     common, but not mandatory), the size of your terminal and the maximum values
     acceptable within the at-clause may vary. To get the size of your terminal
     you may use the peek-function: peek("screenwidth") returns the width of your
     terminal and peek("screenheight") its height.

  Example

  clear screen
  maxx=peek("screenwidth")-1:maxy=peek("screenheight")-1
  for x=0 to maxx
    print at(x,maxy*(0.5+sin(2*pi*x/maxx)/2)) "*"
  next x

     This example plots a full period of the sine-function across the screen.

  See also

     print, clear screen, color
       _________________________________________________________________

  Name

     atan() - returns the arctangent of its numeric argument

  Synopsis

  angle=atan(a,b)
  angle=atan(a)

  Description

     atan is the arctangent-function, i.e. the inverse of the tan-function. Or,
     more elaborate: It Returns the angle (in radian, not degree !), which, fed
     to the tan-function will produce the argument passed to the atan-function.

     The atan-function has a second form, which accepts two arguments: atan(a,b)
     which is (mostly) equivalent to atan(a/b) except for the fact, that the
     two-argument-form returns an angle in the range -pi to pi, whereas the
     one-argument-form returns an angle in the range -pi/2 to pi/2. To understand
     this you have to be good at math.

  Example

  print atan(1),atan(tan(pi)),atan(-0,-1),atan(-0,1)

     This will print 0.463648 2.06823e-13 -3.14159 3.14159 which is pi/4, almost
     0, -pi and pi respectively.

  See also

     tan, sin

  B

     backcolor - change color for background of graphic window
     backcolour - see backcolor
     beep - ring the bell within your computer; a synonym for bell
     bell - ring the bell within your computer (just as beep)
     bin$() - converts a number into a sequence of binary digits
     bind() - Binds a yabasic-program and the yabasic-interpreter together into a
            standalone program.

     box - draw a rectangle. A synonym for rectangle
     break - breaks out of a switch statement or a loop

  Name

     color - change color for background of graphic window

  Synopsis

  backcolour red,green,blue
  backcolour "red,green,blue"

  Description

     Change the color, that becomes visible, if any portion of the window is
     erased, e.g. after clear window or clear line. Note however, that parts of
     the window, that display the old background color will not change.

     As with the color-command, the new background color can either be specified
     as a triple of three numbers or as a single string, that contains those
     three numbers separated by commas.

  Example

  open window 255,255
  for x=10 to 235 step 10:for y=10 to 235 step 10
          backcolour x,y,0
          clear window
          sleep 1
  next y:next x

     This changes the background colour of the graphic window repeatedly and
     clears it every time, so that it is filled with the new background colour.

  See also

     open window, color, line, rectangle, triangle, circle
       _________________________________________________________________

  Name

     backcolour - see backcolor

  Synopsis

  backcolour red,green,blue
  backcolour "red,green,blue"

  See also

     color
       _________________________________________________________________

  Name

     beep - ring the bell within your computer; a synonym for bell

  Synopsis

  beep

  Description

     The bell-command rings the bell within your computer once. This command is
     not a sound-interface, so you can neither vary the length or the height of
     the sound (technically, it just prints \a). bell is exactly the same as
     beep.

  Example

  beep:print "This is a problem ..."

  See also

     beep
       _________________________________________________________________

  Name

     bell - ring the bell within your computer (just as beep)

  Synopsis

  bell

  Description

     The beep-command rings the bell within your computer once. beep is a synonym
     for bell.

  Example

  print "This is a problem ...":beep

  See also

     bell
       _________________________________________________________________

  Name

     bin$() - converts a number into a sequence of binary digits

  Synopsis

  hexadecimal$=bin$(decimal)

  Description

     The bin$-function takes a single numeric argument an converts it into a
     string of binary digits (i.e. zeroes and ones). If you pass a negative
     number to bin$, the resulting string will be preceded by a ’-’.

     If you want to convert the other way around (i.e. from binary to decimal)
     you may use the dec-function.

  Example

  for a=1 to 100
    print bin$(a)
  next a

     This example prints the binary representation of all digits between 1 and
     100.

  See also

     hex$, dec
       _________________________________________________________________

  Name

     bind() - Binds a yabasic-program and the yabasic-interpreter together into a
     standalone program.

  Synopsis

  bind("foo.exe")

  Description

     The bind-command combines your own yabasic-program (plus all the libraries
     it does import) and the interpreter by copying them into a new file, whose
     name is passed as an argument. This new program may then be executed on any
     computer, even if it does not have yabasic installed.

     Please see the section about creating a standalone-program for details.

  Example

  if (!peek("isbound")) then
    bind "foo"
    print "Successfully created the standalone executable ’foo’ !"
    exit
  endif

  print "Hello World !"

     This example creates a standalone program foo from itself.

  See also

     The section about creating a standalone-program, the peek-function and the
     command line options for Unix and Windows.
       _________________________________________________________________

  Name

     box - draw a rectangle. A synonym for rectangle

  Synopsis

  See the rectangle-command.

  Description

     The box-command does exactly the same as the rectangle-command; it is just a
     synonym. Therefore you should refer to the entry for the rectangle-command
     for further information.
       _________________________________________________________________

  Name

     break - breaks out of a switch statement or a loop

  Synopsis

  break

  Description

     break transfers control immediately outside the enclosing loop or switch
     statement. This is the preferred way of leaving a such a statement (rather
     than goto, which is still possible in most cases).

  Example

  for a=1 to 10
    break
    print "Hi"
  next a

  while(1)
    break
    print "Hi"
  wend

  repeat
    break
    print "Hi"
  until(0)

  switch 1
  case 1:break
  case 2:case 3:print "Hi"
  end switch

     This example prints nothing at all, because each of the loops (and the
     switch-statement) does an immediate break (before it could print any "Hi").

  See also

     for, while, repeat and switch.

  C

     case - mark the different cases within a switch-statement
     chr$() - accepts a number and returns the character at this position within
            the ascii charset

     circle - draws a circle in the graphic-window
     clear - Erase circles, rectangles or triangles
     clear screen - erases the text window
     clear window - clear the graphic window and begin a new page, if printing is
            under way

     close - close a file, which has been opened before
     close curve - close a curve, that has been drawn by the line-command
     close printer - stops printing of graphics
     close window - close the graphics-window
     color - change color for any subsequent drawing-command
     colour - see color
     compile - compile a string with yabasic-code on the fly
     continue - start the next iteration of a for-, do-, repeat- or while-loop
     cos() - return the cosine of its single argument

  Name

     case - mark the different cases within a switch-statement

  Synopsis

  switch a
    case 1
    case 2
    ...
  end switch

  ...

  switch a$
    case "a"
    case "b"
    ...
  end switch

  Description

     Please see the switch-statement.

  Example

  input a
  switch(a)
    case 1:print "one":break
    case 2:print "two":break
    default:print "more"
  end switch

     Depending on your input (a number is expected) this code will print one or
     two or otherwise more.

  See also

     switch
       _________________________________________________________________

  Name

     chr$() - accepts a number and returns the character at this position within
     the ascii charset

  Synopsis

  character$=chr$(ascii)

  Description

     The chr$-function is the opposite of the asc-function. It looks up and
     returns the character at the given position within the ascii-charset. It’s
     typical use is to construct nonprintable characters which do not occur on
     your keyboard.

     Nevertheless you won’t use chr$ as often as you might think, because the
     most important nonprintable characters can be constructed using
     escape-sequences using the \-character (e.g. you might use \n instead of
     chr$(10) wherever you want to use the newline-character).

  Example

  print "a",chr$(10),"b"

     This will print the letters ’a’ and ’b’ in different lines because of the
     intervening newline-character, which is returned by chr$(10).

  See also

     asc
       _________________________________________________________________

  Name

     circle - draws a circle in the graphic-window

  Synopsis

  circle x,y,r
  clear circle x,y,r
  fill circle x,y,r
  clear fill circle x,y,r

  Description

     The circle-command accepts three parameters: The x- and y-coordinates of the
     center and the radius of the circle.

     Some more observations related with the circle-command:
       * The graphic-window must have been opened already.
       * The circle may well extend over the boundaries of the window.
       * If you have issued open printer before, the circle will finally appear
         in the printed hard copy of the window.
       * fill circle will draw a filled (with black ink) circle.
       * clear circle will erase (or clear) the outline of the circle.
       * clear fill circle or fill clear circle will erase the full area of the
         circle.

  Example

  open window 200,200

  for n=1 to 2000
    x=ran(200)
    y=ran(200)
    fill circle x,y,10
    clear fill circle x,y,8
  next n

     This code will open a window and draw 2000 overlapping circles within. Each
     circle is drawn in two steps: First it is filled with black ink (fill circle
     x,y,10), then most of this circle is erased again (clear fill circle x,y,8).
     As a result each circle is drawn with an opaque white interior and a 2-pixel
     outline (2-pixel, because the radii differ by two).

  See also

     open window, open printer, line, rectangle, triangle
       _________________________________________________________________

  Name

     clear - Erase circles, rectangles or triangles

  Synopsis

  clear rectangle 10,10,90,90
  clear fill circle 50,50,20
  clear triangle 10,10,20,20,50,30

  Description

     May be used within the circle, rectangle or triangle command and causes
     these shapes to be erased (i.e. be drawn in the colour of the background).

     fill can be used in conjunction with and wherever the fill-clause may
     appear. Used alone, clear will erase the outline (not the interior) of the
     shape (circle, rectangle or triangle); together with fill the whole shape
     (including its interior) is erased.

  Example

  open window 200,200
  fill circle 100,100,50
  clear fill rectangle 10,10,90,90

     This opens a window and draws a pacman-like figure.

  See also

     clear, circle, rectangle, triangle
       _________________________________________________________________

  Name

     clear screen - erases the text window

  Synopsis

  clear screen

  Description

     clear screen erases the text window (the window where the output of print
     appears).

     It must be issued at least once, before some advanced screen-commands (e.g.
     print at or inkey$) may be called; this requirement is due to some
     limitations of the curses-library, which is used by yabasic under Unix for
     some commands.

  Example

  clear screen
  print "Please press a key : ";
  a$=inkey$
  print a$

     The clear screen command is essential here; if it would be omitted, yabasic
     would issue an error ("need to call ’clear screen’ first") while trying to
     execute the inkey$-function.

  See also

     inkey$
       _________________________________________________________________

  Name

     clear window - clear the graphic window and begin a new page, if printing is
     under way

  Synopsis

  clear window

  Description

     clear window clears the graphic window. If you have started printing the
     graphic via open printer, the clear window-command starts a new page as
     well.

  Example

  open window 200,200
  open printer "t.ps"

  for a=1 to 10
  if (a>1) clear window
  text 100,100,"Hallo "+str$(a)
  next a

  close printer
  close window

     This example prints 10 pages, with the text "Hello 1", "Hello 2", ... and so
     on. The clear screen-command clears the graphics window and starts a new
     page.

  See also

     open window, open printer
       _________________________________________________________________

  Name

     close - close a file, which has been opened before

  Synopsis

  close filenum
  close # filenum

  Description

     The close-command closes an open file. You should issue this command as soon
     as you are done with reading from or writing to a file.

  Example

  open "my.data" for reading as 1
  input #1 a
  print a
  close 1

     This program opens the file "my.data", reads a number from it, prints this
     number and closes the file again.

  See also

     open
       _________________________________________________________________

  Name

     close curve - close a curve, that has been drawn by the line-command

  Synopsis

  new curve
  line to x1,y1
  ...
  close curve

  Description

     The close curve-command closes a sequence of lines, that has been drawn by
     repeated line to-commands.

  Example

  open window 200,200
  new curve
  line to 100,50
  line to 150,150
  line to 50,150
  close curve

     This example draws a triangle: The three line to-commands draw two lines;
     the final line is however not drawn explicitly, but drawn by the close
     curve-command.

  See also

     line, new curve
       _________________________________________________________________

  Name

     close printer - stops printing of graphics

  Synopsis

  close printer

  Description

     The close printer-command ends the printing graphics. Between open printer
     and close printer everything you draw (e.g. circles, lines ...) is sent to
     your printer. close printer puts an end to printing and will make your
     printer eject the page.

  Example

  open window 200,200
  open printer
  circle 100,100,50
  close printer
  close window

     As soon as close printer is executed, your printer will eject a page with a
     circle on it.

  See also

     open printer
       _________________________________________________________________

  Name

     close window - close the graphics-window

  Synopsis

  close window

  Description

     The close window-command closes the graphics-window, i.e. it makes it
     disappear from your screen. It includes an implicit close printer, if a
     printer has been opened previously.

  Example

  open window 200,200
  circle 100,100,50
  close window

     This example will open a window, draw a circle and close the window again;
     all this without any pause or delay, so the window will be closed before you
     may regard the circle..

  See also

     open window
       _________________________________________________________________

  Name

     color - change color for any subsequent drawing-command

  Synopsis

  colour red,green,blue
  colour "red,green,blue"

  Description

     Change the color, in which lines, dots, circles, rectangles or triangles are
     drawn. The color-command accepts three numbers in the range 0 ... 255 (as in
     the first line of the synopsis above). Those numbers specify the intensity
     for the primary colors red, green and blue respectively. As an example
     255,0,0 is red and 255,255,0 is yellow.

     Alternatively you may specify the color with a single string (as in the
     second line of the synopsis above); this string should contain three
     numbers, separated by commas. As an example "255,0,255" would be violet.
     Using this variant of the colour-command, you may use symbolic names for
     colours:
  open window 100,100
  yellow$="255,255,0"
  color yellow$
  text 50,50,"Hallo"

     , which reads much clearer.

  Example

  open window 255,255
  for x=10 to 235 step 10:for y=10 to 235 step 10
          colour x,y,0
          fill rectangle x,y,x+10,y+10
  next y:next x

     This fills the window with colored rectangles. However, none of the used
     colours contains any shade of blue, because the color-command has always 0
     as a third argument.

  See also

     open window, backcolor, line, rectangle, triangle, circle
       _________________________________________________________________

  Name

     colour - see color

  Synopsis

  colour red,green,blue
  colour "red,green,blue"

  See also

     color
       _________________________________________________________________

  Name

     compile - compile a string with yabasic-code on the fly

  Synopsis

  compile(code$)

  Description

     This is an advanced command (closely related with the execute-command). It
     allows you to compile a string of yabasic-code (which is the only argument).
     Afterwards the compiled code is a normal part of your program.

     Note, that there is no way to remove the compiled code.

  Example

  compile("sub mysub(a):print a:end sub")
  mysub(2)

     This example creates a function named mysub, which simply prints its single
     argument.

  See also

     execute
       _________________________________________________________________

  Name

     continue - start the next iteration of a for-, do-, repeat- or while-loop

  Synopsis

  continue

  Description

     You may use continue within any loop to start the next iteration
     immediately. Depending on the type of the loop, the loop-condition will or
     will not be checked. Especially: for- and while-loops will evaluate their
     respective conditions, do- and repeat-loops will not.

     Remark: Another way to change the flow of execution within a loop, is the
     break-command.

  Example

  for a=1 to 100
    if mod(a,2)=0 continue
    print a
  next a

     This example will print all odd numbers between 1 and 100.

  See also

     for, do, repeat, while, break
       _________________________________________________________________

  Name

     cos() - return the cosine of its single argument

  Synopsis

  x=cos(angle)

  Description

     The cos-function expects an angle (in radian) and returns its cosine.

  Example

  print cos(pi)

     This example will print -1.

  See also

     acos, sin

  D

     data - introduces a list of data-items
     date$ - returns a string with various components of the current date
     dec() - convert a base 2 or base 16 number into decimal form
     default - mark the default-branch within a switch-statement
     dim - create an array prior to its first use
     do - start a (conditionless) do-loop
     doc - special comment, which might be retrieved by the program itself
     docu$ - special array, containing the contents of all docu-statement within
            the program

     dot - draw a dot in the graphic-window

  Name

     data - introduces a list of data-items

  Synopsis

  data 9,"world"
  ...
  read b,a$

  Description

     The data-keyword introduces a list of comma-separated list of strings or
     numbers, which may be retrieved with the read-command.

     The data-command itself does nothing; it just stores data. A single
     data-command may precede an arbitrarily long list of values, in which
     strings or numbers may be mixed at will.

     yabasic internally uses a data-pointer to keep track of the current location
     within the data-list; this pointer may be reset with the restore-command.

  Example

  do
    restore
    for a=1 to 4
      read num$,num
      print num$,"=",num
    next a
  loop
  data "eleven",11,"twelve",12,"thirteen",13,"fourteen",14

     This example just prints a series of lines eleven=11 up to fourteen=14 and
     so on without end.

     The restore-command ensures that the list of data-items is read from the
     start with every iteration.

  See also

     read, restore
       _________________________________________________________________

  Name

     date$ - returns a string with various components of the current date

  Synopsis

  a$=date$

  Description

     The date$-function (which must be called without parentheses; i.e. date$()
     would be an error) returns a string containing various components of a date;
     an example would be 4-05-27-2004-Thu-May. This string consists of various
     fields separated by hyphens ("-"):
       * The day within the week as a number in the range 0 (=Sunday) to 6
         (=Saturday) (in the example above: 4, i.e. Thursday).
       * The month as a number in the range 1 (=January) to 12 (=December) (in
         the example: 5 which stands for May).
       * The day within the month as a number in the range 1 to 31 (in the
         example: 27).
       * The full, 4-digit year (in the example: 2004, which reminds me that I
         should adjust the clock within my computer ...).
       * The abbreviated name of the day within the week (Mon to Sun).
       * The abbreviated name of the month (Jan to Dec).

     Therefore the whole example above (4-05-27-2004-Thu-May) would read: day 4
     in the week (counting from 0), May 27 in the year 2004, which is a Thursday
     in May.

     Note, that all fields within the string returned by date$ have a fixed with
     (numbers are padded with zeroes); therefore it is easy to extract the
     various fields of a date format with mid$.

  Example

  rem   Two ways to print the same ...

  print mid$(date$,3,10)

  dim fields$(6)
  a=split(date$,fields$(),"-")
  print fields$(2),"-",fields$(3),"-",fields$(4)

     This example shows two different techniques to extract components from the
     value returned by date$. The mid$-function is the preferred way, but you
     could just as well split the return-value of date$ at every "-" and store
     the result within an array of strings.

  See also

     time$
       _________________________________________________________________

  Name

     dec() - convert a base 2 or base 16 number into decimal form

  Synopsis

  a=dec(number$)
  a=dec(number$,base)

  Description

     The dec-function takes the string-representation of a base-2 or base-16
     (which is the default) number and converts it into a decimal number. The
     optional second argument (base) might be used to specify a base other than
     16. However, currently only base 2 or base 16 are supported.

  Example

  input "Please enter a binary number: " a$
  print a$," is ",dec(a$)

  See also

     bin$, hex$
       _________________________________________________________________

  Name

     default - mark the default-branch within a switch-statement

  Synopsis

  switch a+3
  case 1
    ...
  case 2
    ...
  default
    ...
  end switch

  Description

     The default-clause is an optional part of the switch-statement (see there
     for more information). It introduces a series of statements, that should be
     executed, if none of the cases matches, that have been specified before
     (each with its own case-clause).

     So default specifies a default to be executed, if none of the explicitly
     named cases matches; hence its name.

  Example

  print "Please enter a number between 0 and 6,"
  print "specifying a day in the week."
  input d
  switch d
  case 0:print "Monday":break
  case 1:print "Tuesday":break
  case 2:print "Wednesday":break
  case 3:print "Thursday":break
  case 4:print "Friday":break
  case 5:print "Saturday":break
  case 6:print "Sunday":break
  default:print "Hey you entered something invalid !"
  end switch

     This program translates a number between 0 and 6 into the name of a weekday;
     the default-case is used to detect (and complain about) invalid input.

  See also

     sub, case
       _________________________________________________________________

  Name

     dim - create an array prior to its first use

  Synopsis

  dim array(x,y)
  dim array$(x,y)

  Description

     The dim-command prepares one or more arrays (of either strings or numbers)
     for later use. This command can also be used to enlarges an existing array.

     When an array is created with the dim-statement, memory is allocated and all
     elements are initialized with either 0 (for numerical arrays) or "" (for
     string arrays).

     If the array already existed, and the dim-statement specifies a larger size
     than the current size, the array is enlarged and any old content is
     preserved.

     Note, that dim cannot be used to shrink an array: If you specify a size,
     that is smaller than the current size, the dim-command does nothing.

     Finally: To create an array, that is only known within a single subroutine,
     you should use the command local, which creates local variables as well as
     local arrays.

  Example

  dim a(5,5)
  for x=1 to 5:for y=1 to 5
    a(x,y)=int(ran(100))
  next y:next x
  printmatrix(a())
  dim a(7,7)
  printmatrix(a())

  sub printmatrix(ar())
    local x,y,p,q
    x=arraysize(ar(),1)
    y=arraysize(ar(),2)
    for q=1 to y
      for p=1 to y
        print ar(p,q),"\t";
      next p
      print
    next q
  end sub

     This example creates a 2-dimensional array (i.e. a matrix) with the
     dim-statement and fills it with random numbers. The second dim-statement
     enlarges the array, all new elements are filled with 0.

     The subroutine printmatrix just does, what its name says.

  See also

     arraysize, arraydim, local
       _________________________________________________________________

  Name

     do - start a (conditionless) do-loop

  Synopsis

  do
  ...
  loop

  Description

     Starts a loop, which is terminated by loop; everything between do and loop
     will be repeated forever. This loop has no condition, so it is an infinite
     loop; note however, that a break- or goto-statement might be used to leave
     this loop anytime.

  Example

  do
    a=a+1
    print a
    if (a>100) break
  loop

     This example prints the numbers between 1 and 101. The break-statement is
     used to leave the loop.

  See also

     loop, repeat, while, break
       _________________________________________________________________

  Name

     doc - special comment, which might be retrieved by the program itself

  Synopsis

  doc   This is a comment
  docu  This is another comment

  Description

     Introduces a comment, which spans up to the end of the line. But other than
     the rem-comment, any docu-comment is collected within the special
     docu$-array and might be retrieved later on. Moreover you might invoke
     yabasic -docu foo.yab on the command line to retrieve the embedded
     documentation within the program foo.yab.

     Instead of doc you may just as well write docu or even documentation.

  Example

  rem   Hi, this has been written by me
  rem
  doc   This program asks for a number and
  doc   prints this number multiplied with 2
  rem
  rem   Print out rhe above message
  for a=1 to arraysize(docu$()):print docu$(a):next a

  rem   Read and print the number
  input "Please input a number: " x
  print x*2

     This program uses the comments within its code to print out a help message
     for the user.

     The contents of the doc-lines are retrieved from the docu$-array; if you do
     not want a comment to be collected within this array, use the rem-statement
     instead.

  See also

     docu$, rem
       _________________________________________________________________

  Name

     docu$ - special array, containing the contents of all docu-statement within
     the program

  Synopsis

  a$=docu$(1)

  Description

     Before your program is executed, yabasic collects the content of all the
     doc-statements within your program within this 1-dimensional array (well
     only those within the main-program, libraries are skipped).

     You may use the arraysize function to find out, how many lines it contains.

  Example

  docu
  docu  This program reads two numbers
  docu  and adds them.
  docu

  rem retrieve and print the embedded documentation
  for a=1 to arraysize(docu$(),1)
    print docu$(a)
  next a

  input "First number: " b
  input "Second number: " c

  print "The sum of ",b," and ",c," is ",b+c

     This program uses the embedded documentation to issue a usage-message.

  See also

     arraydim, rem
       _________________________________________________________________

  Name

     dot - draw a dot in the graphic-window

  Synopsis

  dot x,y
  clear dot x,y

  Description

     Draws a dot at the specified coordinates within your graphic-window. If
     printing is in effect, the dot appears on your printout too.

     Use the functions peek("winheight") or peek("winwidth") to get the size of
     your window and hence the boundaries of the coordinates specified for the
     dot-command.

  Example

  open window 200,200
  circle 100,100,100
  do
    x=ran(200):y=ran(200)
    dot x,y
    total=total+1
    if (sqrt((x-100)^2+(y-100)^2)<100) in=in+1
    print 4*in/total
  loop

     This program uses a well known algorithm to compute pi.

  See also

     line, open window

  E

     else - mark an alternative within an if-statement
     elsif - starts an alternate condition within an if-statement
     end - terminate your program
     endif - ends an if-statement
     end sub - ends a subroutine definition
     eof - check, if an open file contains data
     eor() - compute the bitwise exclusive or of its two arguments
     error - raise an error and terminate your program
     euler - another name for the constant 2.71828182864
     execute$() - execute a user defined subroutine, which must return a string
     execute() - execute a user defined subroutine, which must return a number
     exit - terminate your program
     exp() - compute the exponential function of its single argument
     export - mark a function as globally visible

  Name

     else - mark an alternative within an if-statement

  Synopsis

  if (...) then
    ...
  else
    ...
  endif

  Description

     The else-statement introduces the alternate branch of an if-statement. I.e.
     it starts the sequence of statements, which is executed, if the condition of
     the if-statement is not true.

  Example

  input "Please enter a number: " a
  if (mod(a,2)=1) then
    print a," is odd."
  else
    print a," is even."
  endif

     This program detects, if the number you have entered is even or odd.

  See also

     if
       _________________________________________________________________

  Name

     elsif - starts an alternate condition within an if-statement

  Synopsis

  if (...) then
    ...
  elseif (...)
    ...
  elsif (...) then
    ...
  else
    ...
  endif

  Description

     The elsif-statement is used to select a single alternative among a series of
     choices.

     With each elsif-statement you may specify a condition, which is tested, if
     the main condition (specified with the if-statement) has failed. Note that
     elsif might be just as well written as elseif.

     Within the example below, two variables a and b are tested against a range
     of values. The variable a is tested with the elsif-statement. The very same
     tests are performed for the variable b too; but here an involved series of
     if-else-statements is employed, making the tests much more obscure.

  Example

  input "Please enter a number: " a
  if (a<0) then
    print "less than 0"
  elseif (a<=10) then
    print "between 0 and 10"
  elsif (a<=20)
    print "between 11 and 20"
  else
    print "over 20"
  endif

  input "Please enter another number: " b
  if (b<0) then
    print "less than 0"
  else
    if (b<=10) then
      print "between 0 and 10"
    else
      if (b<=20) then
        print "between 11 and 20"
      else
        print "over 20"
      endif
    endif
  endif

     Note, that the very same tests are performed for the variables a and b, but
     can be stated much more clearly with the elsif-statement.

     Note, that elsif might be written as elseif too, and that the keyword then
     is optional.

  See also

     if, else
       _________________________________________________________________

  Name

     end - terminate your program

  Synopsis

  end

  Description

     Terminate your program. Much (but not exactly) like the exit command.

     Note, that end may not end your program immediately; if you have opened a
     window or called clear screen, yabasic assumes, that your user wants to
     study the output of your program after it has ended; therefore it issues the
     line ---Program done, press RETURN--- and waits for a key to be pressed. If
     you do not like this behaviour, consider using exit.

  Example

  print "Do you want to continue ?"
  input "Please answer y(es) or n(o): " a$
  if (lower$(left$(a$,1))="n") then
    print "bye"
    end
  fi

  See also

     exit
       _________________________________________________________________

  Name

     endif - ends an if-statement

  Synopsis

  if (...) then
    ...
  endif

  Description

     The endif-statement closes (or ends) an if-statement.

     Note, that endif may be written in a variety of other ways: end if, end-if
     or even fi.

     The endif-statement must be omitted, if the if-statement does not contain
     the keyword then (see the example below). Such an if-statement without endif
     extends only over a single line.

  Example

  input "A number please: " a
  if (a<10) then
    print "Your number is less than 10."
  endif

  REM  and now without endif

  input "A number please: " a
  if (a<10) print "Your number is less than 10."

  See also

     if
       _________________________________________________________________

  Name

     end sub - ends a subroutine definition

  Synopsis

  sub foo(...)
    ...
  end sub

  Description

     Marks the end of a subroutine-definition (which starts with the
     sub-keyword). The whole concept of subroutines is explained within the entry
     for sub.

  Example

  print foo(3)

  sub foo(a)
    return a*2
  end sub

     This program prints out 6. The subroutine foo simply returns twice its
     argument.

  See also

     sub
       _________________________________________________________________

  Name

     eof - check, if an open file contains data

  Synopsis

  open 1,"foo.bar"
  if (eof(1)) then
     ...
  end if

  Description

     The eof-function checks, if there is still data left within an open file. As
     an argument it expects the file-number as returned by (or used within) the
     open-function (or statement).

  Example

  a=open("foo.bar")
  while(not eof(a))
    input #a,a$
    print a$
  end while

     This example will print the contents of the file "foo.bar". The eof-function
     will terminate the loop, if there is no more data left within the file.

  See also

     open
       _________________________________________________________________

  Name

     eor() - compute the bitwise exclusive or of its two arguments

  Synopsis

  print eor(a,b)

  Description

     The eor-function takes two arguments and computes their bitwise exclusive
     or. See your favorite introductory text on informatics for an explanation of
     this function.

     The xor-function is the same as the eor function; both are synonymous;
     however they have each their own description, so you may check out the entry
     of xor for a slightly different view.

  Example

  for a=0 to 3
    for b=0 to 3
      print fill$(bin$(a))," eor ",fill$(bin$(b))," = ",fill$(bin$(eor(a,b)))
    next b
  next a

  sub fill$(a$)
    return right$("0"+a$,2)
  end sub

     This example prints a table, from which you may figure, how the eor-function
     is computed.

  See also

     and, or
       _________________________________________________________________

  Name

     error - raise an error and terminate your program

  Synopsis

  error "Wrong, wrong, wrong !!"

  Description

     Produces the same kind or error messages, that yabasic itself produces (e.g.
     in case of a syntax-error). The single argument is issued along with the
     current line-number.

  Example

  input "Please enter a number between 1 and 10: " a
  if (a<1 or a>10) error "Oh no ..."

     This program is very harsh in checking the users input; instead of just
     asking again, the program terminates with an error, if the user enters
     something wrong.

     The error message would look like this:
  ---Error in t.yab, line 2: Oh no ...
  ---Error: Program stopped due to an error

  See also

     Well, there should be a corresponding called warning; unfortunately ther is
     none yet.
       _________________________________________________________________

  Name

     euler - another name for the constant 2.71828182864

  Synopsis

  foo=euler

  Description

     euler is the well known constant named after Leonard Euler; its value is
     2.71828182864. euler is not a function, so parens are not allowed (i.e.
     euler() will produce an error). Finally, you may not assign to euler; it
     wouldn’t sense anyway, because it is a constant.

  Example

  print euler

  See also

     pi
       _________________________________________________________________

  Name

     execute$() - execute a user defined subroutine, which must return a string

  Synopsis

  print execute$("foo$","arg1","arg2")

  Description

     execute$ can be used to execute a user defined subroutine, whose name may be
     specified as a string expression.

     This feature is the only way to execute a subroutine, whose name is not
     known by the time you write your program. This might happen, if you want to
     execute a subroutine, which is compiled (using the compile command) during
     the course of execution of your program.

     Note however, that the execute$-function is not the preferred method to
     execute a user defined subroutine; almost all cases you should just execute
     a subroutine by writing down its name within your yabasic program (see the
     example).

  Example

  print execute$("foo$","Hello","world !")
  sub foo$(a$,b$)
    return a$+" "+b$
  end sub

     The example simply prints Hello world !, which is the return value of the
     user defined subroutine foo$. The same could be achieved by executing:
  print foo$(a$,b$)

  See also

     compile, execute
       _________________________________________________________________

  Name

     execute() - execute a user defined subroutine, which must return a number

  Synopsis

  print execute("bar","arg1","arg2")

  Description

     The execute-function is the counterpart of the execute$-function (please see
     there for some caveats). execute executes subroutines, which returns a
     number.

  Example

  print execute("bar",2,3)
  sub bar(a,b)
    return a+b
  end sub

  See also

     compile, execute$
       _________________________________________________________________

  Name

     exit - terminate your program

  Synopsis

  exit
  exit 1

  Description

     Terminate your program and return any given value to the operating system.
     exit is similar to end, but it will terminate your program immediately, no
     matter what.

  Example

  print "Do you want to continue ?"
  input "Please answer y(es) or n(o): " a$
  if (lower$(left$(a$,1))="n") exit 1

  See also

     end
       _________________________________________________________________

  Name

     exp() - compute the exponential function of its single argument

  Synopsis

  foo=exp(bar)

  Description

     This function computes e to the power of its argument, where e is the well
     known euler constant 2.71828182864.

     The exp-function is the inverse of the log-function.

  Example

  open window 100,100
  for x=0 to 100
     dot x,100-100*exp(x/100)/euler
  next x

     This program plots part of the exp-function, however the range is rather
     small, so that you may not recognize the function from this plot.

  See also

     log
       _________________________________________________________________

  Name

     export - mark a function as globally visible

  Synopsis

  export sub foo(bar)
  ...
  end sub

  Description

     The export-statement is used within libraries to mark a user defined
     subroutine as visible outside the library wherein it is defined.
     Subroutines, which are not exported, must be qualified with the name of the
     library, e.g. foo.baz (where foo is the name of the library and baz the name
     of the subroutine); exported subroutines may be used without specifying the
     name of the library, e.g. bar.

     Therefore export may only be useful within libraries.

  Example

     The library foo.bar (which is listed below) defines two functions bar and
     baz, however only the function bar is exported and therefore visible even
     outside the library; baz is not exported and may only be used within the
     library foo.yab:
  export sub bar()
    print "Hello"
  end sub

  sub baz()
    print "World"
  end sub

     Now within your main program cux.yab (which imports the library foo.yab);
     note that this program produces an error:
  import foo

  print "Calling subroutine foo.bar (okay) ..."
  foo.bar()
  print "done."

  print "Calling subroutine bar (okay) ..."
  bar()
  print "done."

  print "Calling subroutine foo.baz (okay) ..."
  foo.baz()
  print "done."

  print "Calling subroutine baz (NOT okay) ..."
  baz()
  print "done."

     The output when executing yabasic foo.yab is this:
  Calling subroutine foo.bar (okay) ...
  Hello
  done.
  Calling subroutine bar (okay) ...
  Hello
  done.
  Calling subroutine foo.baz (okay) ...
  World
  done.
  Calling subroutine baz (NOT okay) ...
  ---Error in main.yab, line 16: can’t find subroutine ’baz’
  ---Dump: sub baz() called in main.yab,16
  ---Error: Program stopped due to an error

     As the error message above shows, the subroutine baz must be qualified with
     the name of the library, if used outside the library, wherein it is defined
     (e.g. foo.baz. I.e. outside the library foo.yab you need to write foo.baz.
     baz alone would be an error.

     The subroutine bar (without adding the name of the library) however may (and
     probably should) be used in any program, which imports the library foo.yab.

  Note

     In some sense the set of exported subroutines constitutes the interface of a
     library.

  See also

     sub, import

  F

     false - a constant with the value of 0
     fi - another name for endif
     fill - draw a filled circles, rectangles or triangles
     for - starts a for-loop
     frac() - return the fractional part of its numeric argument

  Name

     false - a constant with the value of 0

  Synopsis

  okay=false

  Description

     The constant false can be assigned to variables which later appear in
     conditions (e.g. within an if-statement.

     false may also be written as FALSE or even FaLsE.

  Example

  input "Please enter a number between 1 and 10: " a
  if (check_input(a)) print "Okay"

  sub check_input(x)
    if (x>10 or x<1) return false
    return true
  end sub

     The subroutine check_input checks its argument and returns true or false
     according to the outcome of the check..

  See also

     true
       _________________________________________________________________

  Name

     fi - another name for endif

  Synopsis

  if (...)
  ...
  fi

  Description

     fi marks the end of an if-statement and is exactly equivalent to endif,
     please see there for further information.

  Example

  input "A number please: " a
  if (a<10) then
    print "Your number is less than 10."
  fi

  See also

     endif
       _________________________________________________________________

  Name

     fill - draw a filled circles, rectangles or triangles

  Synopsis

  fill rectangle 10,10,90,90
  fill circle 50,50,20
  fill triangle 10,20,20,10,20,20

  Description

     The keyword fill may be used within the circle, rectangle or triangle
     command and causes these shapes to be filled.

     fill can be used in conjunction with and wherever the clear-clause may
     appear. Used alone, fill will fill the interior of the shape (circle,
     rectangle or triangle); together with clear the whole shape (including its
     interior) is erased.

  Example

  open window 200,200
  fill circle 100,100,50
  clear fill rectangle 10,10,90,90

     This opens a window and draws a pacman-like figure.

  See also

     clear, circle, rectangle, triangle
       _________________________________________________________________

  Name

     for - starts a for-loop

  Synopsis

  for a=1 to 100 step 2
    ...
  next a

  Description

     The for-loop lets its numerical variable (a in the synopsis) assume all
     values within the given range. The optional step-clause may specify a value
     (default: 1) by which the variable will be incremented (or decremented, if
     step is negative).

     Any for-statement can be replaced by a set of ifs and gotos; as you may
     infer from the example below this is normally not feasible. However if you
     want to know in detail how the for-statement works, you should study this
     example, which presents a for-statement and an exactly equivalent series of
     ifs and gotos.

  Example

  for a=1 to 10 step 2:print a:next

  a=1
  label check
  if (a>10) goto done
    print a
    a=a+2
  goto check
  label done

     This example simply prints the numbers 1, 3, 5, 7 and 9. It does this twice:
     First with a simple for-statement and then with ifs and gotos.

  See also

     step, next
       _________________________________________________________________

  Name

     frac() - return the fractional part of its numeric argument

  Synopsis

  x=frac(y)

  Description

     The frac-function takes its argument, removes all the digits to the left of
     the comma and just returns the digits right of the comma, i.e. the
     fractional part.

     Refer to the example to learn how to rewrite frac by employing the
     int-function.

  Example

  for a=1 to 10
    print frac(sqr(a))
    print sqr(a)-int(sqr(a))
  next a

     The example prints the fractional part of the square root of the numbers
     between 1 and 10. Each result is computed (and printed) twice: Once by
     employing the frac-function and once by employing the int-function.

  See also

     int

  G

     getbit$() - return a string representing the bit pattern of a rectangle
            within the graphic window

     getscreen$() - returns a string representing a rectangular section of the
            text terminal

     glob() - check if a string matches a simple pattern
     gosub - continue execution at another point within your program (and return
            later)

     goto - continue execution at another point within your program (and never
            come back)

  Name

     getbit$() - return a string representing the bit pattern of a rectangle
     within the graphic window

  Synopsis

  a$=getbit$(10,10,20,20)
  a$=getbit$(10,10 to 20,20)

  Description

     The function getbit returns a string, which contains the encoded bit-pattern
     of a rectangle within graphic window; the four arguments represent the
     borders of the rectangle. The string returned might later be fed to the
     putbit-command.

     The getbit$-function might be used for simple animations (as in the example
     below).

  Example

  open window 40,40
  fill circle 20,20,18
  circle$=getbit$(0,0,40,40)
  close window

  open window 200,200
  for x=1 to 200
    putbit circle$,x,80
  next x

     This example features a circle moving from left to right over the window.

  See also

     putbit
       _________________________________________________________________

  Name

     getscreen$() - returns a string representing a rectangular section of the
     text terminal

  Synopsis

  a$=getscreen$(2,2,20,20)

  Description

     The getscreen$ function returns a string representing the area of the screen
     as specified by its four arguments (which specify two corners). I.e.
     everything you have printed within this rectangle will be encoded in the
     string returned (including any colour-information).

     Like most other commands dealing with advanced text output, getscreen$
     requires, that you have called clear screen before.

  Example

  clear screen

  for a=1 to 1000:
          print color("red") "1";
          print color("green") "2";
          print color("blue") "3";
  next a
  screen$=getscreen$(10,10,40,10)
  print at(10,10) " Please Press ’y’ or ’n’ ! "
  a$=inkey$
  putscreen screen$,10,10

     This program fills the screen with colored digits and afterwards asks the
     user for a choice ( Please press ’y’ or ’n’ ! ). Afterwards the area of the
     screen, which has been overwritten by the question will be restored with its
     previous contents, whhch had been saved via getscreen$.

  See also

     putscreen$
       _________________________________________________________________

  Name

     glob() - check if a string matches a simple pattern

  Synopsis

  if (glob(string$,pattern$)) ...

  Description

     The glob-function takes two arguments, a string and a (glob-) pattern, and
     checks if the string matches the pattern. However glob does not employ the
     powerful rules of regular expressions; rather it has only two special
     characters: * (which matches any number (even zero) of characters) and ?
     (which matches exactly a single character).

  Example

  for a=1 to 10
    read string$,pattern$
    if (glob(string$,pattern$)) then
      print string$," matches ",pattern$
    else
      print string$," does not match ",pattern$
    endif
  next a

  data "abc","a*"
  data "abc","a?"
  data "abc","a??"
  data "abc","*b*"
  data "abc","*"
  data "abc","???"
  data "abc","?"
  data "abc","*c"
  data "abc","A*"
  data "abc","????"

     This program checks the string abc against various patterns and prints the
     result. The output is:
  abc matches a*
  abc does not match a?
  abc matches a??
  abc matches *b*
  abc matches *
  abc matches ???
  abc does not match ?
  abc matches *c
  abc does not match A*
  abc does not match ????

  See also

     There are no related commands.
       _________________________________________________________________

  Name

     gosub - continue execution at another point within your program (and return
     later)

  Synopsis

  gosub foo

  ...

  label foo
  ...
  return

  Description

     gosub remembers the current position within your program and then passes the
     flow of execution to another point (which is normally marked with a label).
     Later, when a return-statement is encountered, the execution is resumed at
     the previous location.

     gosub is the traditional command for calling code, which needs to be
     executed from various places within your program. However, with subroutines
     yabasic offers a much more flexible way to achieve this (and more).
     Therefore gosub must to be considered obsolete.

  Example

  print "Do you want to exit ? "
  gosub ask
  if (r$="y") exit

  label ask
  input "Please answer yes or no, by typing ’y’ or ’n’: ",r$
  return

  See also

     return, goto, sub, label, on gosub
       _________________________________________________________________

  Name

     goto - continue execution at another point within your program (and never
     come back)

  Synopsis

  goto foo

  ...

  label foo

  Description

     The goto-statement passes the flow of execution to another point within your
     program (which is normally marked with a label).

     goto is normally considered obsolete and harmful, however in yabasic it may
     be put to the good use of leaving loops (e.g. while or for) prematurely.
     Note however, that subroutines may not be left with the goto-statement.

  Example

  print "Please press any key to continue."
  print "(program will continue by itself within 10 seconds)"
  for a=1 to 10
    if (inkey$(1)<>"") then goto done
  next a
  label done
  print "Hello World !"

     Here the goto-statement is used to leave the for-loop prematurely.

  See also

     gosub, on goto

  H

     hex$() - convert a number into hexadecimal

  Name

     hex$() - convert a number into hexadecimal

  Synopsis

  print hex$(foo)

  Description

     The hex$-function converts a number into a string with its hexadecimal
     representation. hex$ is the inverse of the dec-function.

  Example

  open 1,"foo"
  while(!eof(1))
    print right$("0"+hex$(peek(1)),2)," ";
    i=i+1
    if (mod(i,10)=0) print
  end while
  print

     This program reads the file foo and prints its output as a hex-dump using
     the hex-function.

  See also

     decbin

  I

     if - evaluate a condition and execute statements or not, depending on the
            result

     import - import a library
     inkey$ - wait, until a key is pressed
     input - read input from the user (or from a file) and assign it to a
            variable

     instr() - searches its second argument within the first; returns its
            position if found

     int() - return the integer part of its single numeric argument

  Name

     if - evaluate a condition and execute statements or not, depending on the
     result

  Synopsis

  if (...) then
    ...
  endif

  if (...) ...

  if (...) then
    ...
  else
    ...
  endif

  if (...) then
    ...
  elsif (...)
    ...
  elsif (...) then
    ...
  else
    ...
  endif

  Description

     The if-statement is used to evaluate a conditions and take actions
     accordingly. (As an aside, please note that there is no real difference
     between conditions and expressions.)

     There are two major forms of the if-statement:
       * The one-line-form without the keyword then:
  if (...) ...
         This form evaluates the condition and if the result is true executes all
         commands (separated by colons) upt to the end of the line. There is
         neither an endif keyword nor an else-branch.
       * The multi-line-form with the keyword then:
  if (...) then ... elsif (...) ... else ... endif
         (where elsif and else are optional, whereas endif is not.
         According to the requirements of your program, you may specify:
            + elsif(...), which specifies a condition, that will be evaluated only
              if the condition(s) within if or any preceding elsif did not
              match.
            + else, which introduces a sequence of commands, that will be
              executed, if none of the conditions above did match.
            + endif is required and ends the if-statement.

  Example

  input "Please enter a number between 1 and 4: " a
  if (a<=1 or a>=4) error "Wrong, wrong !"
  if (a=1) then
    print "one"
  elsif (a=2)
    print "two"
  elsif (a=3)
    print "three"
  else
    print "four"
  endif

     The input-number between 1 and 4 is simply echoed as text (one, two, ...). The
     example demonstrates both forms (short and long) of the if-statement (Note
     however, that the same thing can be done, probably somewhat more elegant,
     with the switch-statement).

  See also

     else, elsif, endif, conditions and expressions.
       _________________________________________________________________

  Name

     import - import a library

  Synopsis

  import foo

  Description

     The import-statement imports a library. It expects a single argument, which
     must be the name of a library (without the trailing .yab). This library will
     then be read and parsed and its subroutines (and variables) will be made
     available within the main program.

     Libraries will first be searched within the current directory (i.e. the
     directory within which you have invoked yabasic), then within a special
     directory, whose exact location depends on your system. Typical values would
     be /usr/lib under Unix or C:\yabasic\lib under Windows. However only yabasic
     -help-usage may tell the truth. The location of this second directory may be
     changed with the option -library (either under Windows or Unix).

  Example

     Lets say you have a yabasic-program foo.yab, which imports a library
     lib.yab. foo.yab reads:
  import lib

  rem  This works ...
  lib.x(0)

  rem  This works too ..
  x(1)

  rem  And this.
  lib.y(2)

  rem  But this not !
  y(3)

     Now the library lib.yab reads:
  rem  Make the subroutine x easily available outside this library
  export sub x(a)
    print a
    return
  end sub

  rem  sub y must be referenced by its full name
  rem  outside this library
  sub y(a)
    print a
    return
  end sub

     This program produces an error:

  0
  1
  2
  ---Error in foo.yab, line 13: can’t find subroutine ’y’
  ---Dump: sub y() called in foo.yab,13
  ---Error: Program stopped due to an error

     As you may see from the error message, yabasic is unable to find the
     subroutine y without specifying the name of the library (i.e. lib.y). The
     reason for this is, that y, other than x, is not exported from the library
     lib.yab (using the export-statement).

  See also

     export, sub
       _________________________________________________________________

  Name

     inkey$ - wait, until a key is pressed

  Synopsis

  clear screen
  foo$=inkey$
  inkey$
  foo$=inkey$(bar)
  inkey$(bar)

  Description

     The inkeys$-function waits, until the user presses a key on the keyboard or
     a button of his mouse, and returns this very key. An optional argument
     specifies the number of seconds to wait; if omitted, inkey$ will wait
     indefinitely.

     inkey$ may only be used, if clear screen has been called at least once.

     For normal keys, yabasic simply returns the key, e.g. a, 1 or !. For
     function keys you will get f1, f2 and so on. Other special keys will return
     these strings respectively: enter, backspace, del, esc, scrnup (for screen
     up), scrndown and tab. Modifier keys (e.g. ctrl, alt or shift) by themselves
     can not be detected (e.g. if you simultaneously press shift and ’a’,
     inkey$ will return the letter ’A’ instead of ’a’ of course).

     If a graphical window has been opened (via open window) any mouseclick
     within this window will be returned by inkey$ too. The string returned (e.g.
     MB1d+0:0028,0061, MB2u+0:0028,0061 or MB1d+1:0028,0061) is constructed as
     follows:
       * Every string associated with a mouseclick will start with the fixed
         string MB
       * The next digit (1, 2 or 3) specifies the mousebutton pressed.
       * A single letter, d or u, specifies, if the mousebutton has been pressed
         or released: d stands for down, i.e. the mousebutton has been pressed; u
         means up, i.e. the mousebutton has been released.
       * The plus-sign (’+’), which follows is always fixed.
       * The next digit (in the range 0 to 7) encodes the modifier keys pressed,
         where 1 stands for shift, 2 stands for alt and 4 stands for ctrl.
       * The next four digits (e.g. 0028) contain the x-position, where the
         mousebutton has been pressed.
       * The comma to follow is always fixed.
       * The last four digits (e.g. 0061) contain the y-position, where the
         mousebutton has been pressed.

     All those fields are of fixed length, so you may use functions like mid$ to
     extract certain fields. However, note that with mousex, mousey, mouseb and
     mousemod there are specialized functions to return detailed information
     about the mouseclick. Finally it should be noted, that inkey$ will only
     register mouseclicks within the graphic-window; mouseclicks in the
     text-window cannot be detected.

     inkey$ accepts an optional argument, specifying a timeout in seconds; if no
     key has been pressed within this span of time, an empty string is returned.
     If the timeout-argument is omitted, inkey$ will wait for ever.

  Example

  clear screen
  open window 100,100
  print "Press any key or press ’q’ to stop."
  repeat
    a$=inkey$
    print a$
  until(a$="q")

     This program simply returns the key pressed. You may use it, to learn, which
     strings are returned for the special keys on your keyboard (e.g.
     function-keys).

  See also

     clear screen,mousex, mousey, mouseb, mousemod
       _________________________________________________________________

  Name

     input - read input from the user (or from a file) and assign it to a
     variable

  Synopsis

  input a
  input a,b,c
  input a$
  input "Hello" a
  input #1 a$

  Description

     input reads the new contents of one or many (numeric- or string-) variables,
     either from the keyboard (i.e. from you) or from a file. An optional first
     string-argument specifies a prompt, which will be issued before reading any
     contents.

     If you want to read from an open file, you need to specify a hash (’#’),
     followed by the number, under which the file has been opened.

     Note, that the input is split at spaces, i.e. if you enter a whole line
     consisting of many space-separated word, the first input-statement will only
     return the first word; the other words will only be returned on subsequent
     calls to input; the same applies, if a single input reads multiple
     variables: The first variable gets only the first word, the second one the
     second word, and so on. If you don’t like this behaviour, you may use line
     input, which returns a whole line (including embedded spaces) at once.

  Example

  input "Please enter the name of a file to read: " a$
  open 1,a$
  while(!eof(1))
    input #1 b$
    print b$
  wend

     If this program is stored within a file test.yab and you enter this name
     when prompted for a file to read, you will see this output:
  Please enter the name of a file to read: t.yab
  input
  "Please
  enter
  the
  name
  of
  a
  file
  to
  read:
  "
  a$
  open
  1,a$
  while(!eof(1))
  input
  #1
  b$
  print
  b$
  wend

  See also

     line input
       _________________________________________________________________

  Name

     instr() - searches its second argument within the first; returns its
     position if found

  Synopsis

  print instr(a$,b$)
  if (instr(a$,b$)) ...
  pos=instr(a$,b$,x)

  Description

     The instr-functions requires two string arguments and searches the second
     argument within the first. If the second argument can be found within the
     first, the position is returned (counting from one). If it can not be found,
     the instr-function returns 0; this makes this function usable within the
     condition of an if-statement (see the example below).

     If you supply a third, numeric argument to the instr-function, it will be
     used as a starting point for the search. Therefore
     instr("abcdeabcdeabcde","e",8) will return 10, because the search for an "e"
     starts at position 8 and finds the "e" at position 10 (and not the one at
     position 5).

  Example

  input "Please enter a text containing the string ’bumf’: " a$
  if (instr(a$,"bumf")) then
    print "Well done !"
  else
    print "not so well ..."
  endif

  See also

     rinstr
       _________________________________________________________________

  Name

     int() - return the integer part of its single numeric argument

  Synopsis

  print int(a)

  Description

     The int-function returns only the digits before the comma; int(2.5) returns
     2 and int(-2.3) returns -2.

  Example

  input "Please enter a whole number between 1 and 10: " a
  if (a=int(a) and a>=1 and a<=10) then
    print "Thanx !"
  else
    print "Never mind ..."
  endif

  See also

     frac

  L

     label - mark a specific location within your program for goto, gosub or
            restore

     left$() - return (or change) left end of a string
     len() - return the length of a string
     line - draw a line
     line input - read in a whole line of text and assign it to a variable
     local - mark a variable as local to a subroutine
     log() - compute the natural logarithm
     loop - marks the end of an infinite loop
     lower$() - convert a string to lower case
     ltrim$() - trim spaces at the left end of a string

  Name

     label - mark a specific location within your program for goto, gosub or
     restore

  Synopsis

  label foo

  ...

  goto foo

  Description

     The label-command can be used to give a name to a specific location within
     your program. Such a position might be referred from one of three commands:
     goto, gosub and restore.

     You may use labels safely within libraries, because a label (e.g. foo) does
     not collide with a label with the same name within the main program or
     within another library; yabasic will not mix them up.

     As an aside, please note, that line numbers are a special (however
     deprecated) case of labels; see the second example below.

  Example

  for a=1 to 100
    if (rand(10)>5) goto done
  next a
  label done

  10 for a=1 to 100
  20   if (rand(10)>5) goto 40
  30 next a
  40

     Within this example, the for-loop will probably be left prematurely with a
     goto-statement. This task is done twice: First with labels and then again
     with line numbers.

  See also

     gosub, goto.
       _________________________________________________________________

  Name

     left$() - return (or change) left end of a string

  Synopsis

  print left$(a$,2)
  left$(b$,3)="foobar"

  Description

     The left$-function accepts two arguments (a string and a number) and returns
     the part from the left end of the string, whose length is specified by its
     second argument. Loosely spoken, it simply returns the requested number of
     chars from the left end of the given string.

     Note, that the left$-function can be assigned to, i.e. it may appear on the
     left hand side of an assignment. In this way it is possible to change a part
     of the variable used within the left$-function. Note, that that way the
     length of the string cannot be changed, i.e. characters might be
     overwritten, but not added. For an example see below.

  Example

  input "Please answer yes or no: " a$
  l=len(a$):a$=lower$(a$):print "Your answer is ";
  if (left$("yes",l)=a$ and l>=1) then
    print "yes"
  elsif (left$("no",l)=a$ and l>=1) then
    print "no"
  else
    print "?"
  endif

     This example asks a simple yes/no question and goes some way to accept even
     incomplete input, while still being able to reject invalid input.

     This second example demonstrates the capability to assign to the
     left$-function.
  a$="Heiho World !"
  print a$
  left$(a$,5)="Hello"
  print a$

  See also

     right$, mid$
       _________________________________________________________________

  Name

     len() - return the length of a string

  Synopsis

  x=len(a$)

  Description

     The len-function returns the length of its single string argument.

  Example

  input "Please enter a password: " a$
  if (len(a$)<6) error "Password too short !"

     This example checks the length of the password, that the user has entered.

  See also

     left$, right$ and mid$,
       _________________________________________________________________

  Name

     line - draw a line

  Synopsis

  open window 100,100
  line 0,0,100,100
  line 0,0 to 100,100
  new curve
  line 100,100
  line to 100,100

  open window 100,100
  clear line 0,0,100,100
  clear line 0,0 to 100,100
  new curve
  clear line 100,100
  clear line to 100,100

  Description

     The line-command draws a line. Simple as this is, the line-command has a
     large variety of forms as they are listed in the synopsis above. Lets look
     at them a little closer:
       * A line has a starting and an end point; therefore the line-command
         (normally) needs four numbers as arguments, representing these two
         points. This is the first form appearing within the synopsis.
       * You may separate the two points with either ’,’ or to, which accounts
         for the second form of the line-command.
       * The line-command may be used to draw a connected sequence of lines with
         a sequence of commands like line x,y; Each command will draw a line from
         the point where the last line-command left off, to the point specified
         in the arguments. Note, that you need to use the command new curve
         before you may issue such a line-command. See the example below.
       * You may insert the word to for beauty: line to x,y, which does exactly
         the same as line x,y
       * Finally, you may choose not to draw, but to erase the lines; this can be
         done by prepending the phrase clear. This account for all the other
         forms of the line-command.

  Example

  open window 200,200
  line 10,10 to 10,190
  line 10,190 to 190,190
  new curve
  for a=0 to 360
    line to 10+a*180/360,100+60*sin(a*pi/180)
  next a

     This example draws a sine-curve (with an offset in x- and y-direction).
     Note, that the first line-command after new curve does not draw anything.
     Only the coordinates will be stored. The second iteration of the loop then
     uses these coordinates as a starting point for the first line.

  See also

     new curve, close curve, open window
       _________________________________________________________________

  Name

     line input - read in a whole line of text and assign it to a variable

  Synopsis

  line input a
  line input a$
  line input "Hello" a
  line input #1 a$

  Description

     In most respects line input is like the input-command: It reads the new
     contents of a variable, either from keyboard or from a file. However, line
     input always reads a complete line and assigns it to its variable. line
     input does not stop reading at spaces and is therefore the best way to read
     in a string which might contain whitespace. Note, that the final newline is
     stripped of.

  Example

  line input "Please enter your name (e.g. Frodo Beutelin): " a$
  print "Hello ",a$

     Note that the usage of line input is essential in this example; a simple
     input-statement would only return the string up to the first space, e.g.
     Frodo.

  See also

     input
       _________________________________________________________________

  Name

     local - mark a variable as local to a subroutine

  Synopsis

  sub foo()

    local a,b,c$,d(10),e$(5,5)

    ...

  end sub

  Description

     The local-command can (and should be) used to mark a variable (or array) as
     local to the containing subroutine. This means, that a local variable in
     your subroutine is totally different from a variable with the same name
     within your main program. Variables which are known everywhere within your
     program are called global in contrast.

     Declaring variables within the subroutine as local helps to avoid hard to
     find bugs; therefore local variables should be used whenever possible.

     Note, that the parameters of your subroutines are always local.

     As you may see from the example, local arrays may be created without using
     the keyword dim (which is required only for global arrays).

  Example

  a=1
  b=1
  print a,b
  foo()
  print a,b

  sub foo()
    local a
    a=2
    b=2
  end sub

     This example demonstrates the difference between local and global variables;
     it produces this output:

  1 1
  1 2

     As you may see, the content of the global variable a is unchanged after the
     subroutine foo; this is because the assignment a=2 within the subroutine
     affects the local variable a only and not the global one. However, the
     variable b is never declared local and therefore the subroutine changes the
     global variable, which is reflected in the output of the second
     print-statement.

  See also

     sub, static, dim
       _________________________________________________________________

  Name

     log() - compute the natural logarithm

  Synopsis

  a=log(x)
  a=log(x,base)

  Description

     The log-function computes the logarithm of its first argument. The optional
     second argument gives the base for the logarithm; if this second argument is
     omitted, the euler-constant 2.71828... will be taken as the base.

  Example

  open window 200,200
  for x=10 to 190 step 10:for y=10 to 190 step 10
    r=3*log(1+x,1+y)
    if (r>10) r=10
    if (r<1) r=1
    fill circle x,y,r
  next y:next x

     This draws another nice plot.

  See also

     exp
       _________________________________________________________________

  Name

     loop - marks the end of an infinite loop

  Synopsis

  do
    ...
  loop

  Description

     The loop-command marks the ends of a loop (which is started by do), wherein
     all statements within the loop are repeated forever. In this respect the do
     loop-loop is infinite, however, you may leave it anytime via break or goto.

  Example

  print "Hello, I will throw dice, until I get a 2 ..."
  do
    r=int(rand(6))+1
    print r
    if (r=2) break
  loop

  See also

     do, for, repeat, while, break
       _________________________________________________________________

  Name

     lower$() - convert a string to lower case

  Synopsis

  l$=lower$(a$)

  Description

     The lower$-function accepts a single string-argument and converts it to all
     lower case.

  Example

  input "Please enter a password: " a$
  if (a$=lower$(a$)) error "Your password is NOT mixed case !"

     This example prompts for a password and checks, if it is really lower case.

  See also

     upper$
       _________________________________________________________________

  Name

     ltrim$() - trim spaces at the left end of a string

  Synopsis

  a$=ltrim$(b$)

  Description

     The ltrim$-function removes all whitespace from the left end of a string and
     returns the result.

  Example

  input "Please answer ’yes’ or ’no’ : " a$
  a$=lower$(ltrim$(rtrim$(a$)))
  if (len(a$)>0 and a$=left$("yes",len(a$))) then
    print "Yes ..."
  else
    print "No ..."
  endif

     This example prompts for an answer and removes any spaces, which might
     precede the input; therefore it is even prepared for the (albeit somewhat
     pathological case, that the user first hits space before entering his
     answer.

  See also

     rtrim$, trim$

  M

     max() - return the larger of its two arguments
     mid$() - return (or change) characters from within a string
     min() - return the smaller of its two arguments
     mod() - compute the remainder of a division
     mouseb - extract the state of the mousebuttons from a string returned by
            inkey$

     mousemod - return the state of the modifier keys during a mouseclick
     mousex - return the x-position of a mouseclick
     mousey - return the y-position of a mouseclick

  Name

     max() - return the larger of its two arguments

  Synopsis

  print max(a,b)

  Description

     Return the maximum of its two arguments.

  Example

  dim m(10)
  for a=1 to 1000
    m=0
    For b=1 to 10
      m=max(m,ran(10))
    next b
    m(m)=m(m)+1
  next a

  for a=1 to 9
    print a,": ",m(a)
  next a

     Within the inner for-loop (the one with the loop-variable b), the example
     computes the maximum of 10 random numbers. The outer loop (with the loop
     variable a) now repeats this process 1000 times and counts, how often each
     maximum appears. The last loop finally reports the result.

     Now, the interesting question would be, which will be approached, when we
     increase the number of iterations from thousand to infinity. Well, maybe
     someone could just tell me :-)

  See also

     min
       _________________________________________________________________

  Name

     mid$() - return (or change) characters from within a string

  Synopsis

  print mid$(a$,2,1)
  print mid$(a$,2)
  mid$(a$,5,3)="foo"
  mid$(a$,5)="foo"

  Description

     The mid$-function requires three arguments: a string and two numbers, where
     the first number specifies a position within the string and the second one
     gives the number of characters to be returned; if you omit the second
     argument, the mid$-function returns all characters up to the end of the
     string.

     Note, that you may assign to the mid$-function, i.e. mid$ may appear on the
     left hand side of an assignment. In this way it is possible to change a part
     of the variable used within the mid$-function. Note, that that way the
     length of the string cannot be changed, i.e. characters might be
     overwritten, but not added. For an example see below.

  Example

  input "Please enter a string: " a$
  for a=1 to len(a$)
    if (instr("aeiou",lower$(mid$(a$,a,1)))) mid$(a$,a,1)="e"
  next a
  print "When you turn everything to lower case and"
  print "replace every vowel with ’e’, your input reads:"
  print
  print a$

     This example transforms the input string a bit, using the mid$-function to
     retrieve a character from within the string as well as to change it.

  See also

     left$ and right$.
       _________________________________________________________________

  Name

     min() - return the smaller of its two arguments

  Synopsis

  print min(a,b)

  Description

     Return the minimum of its two argument.

  Example

  dim m(10)
  for a=1 to 1000
    m=min(ran(10),ran(10))
    m(m)=m(m)+1
  next a

  for a=1 to 9
    print a,": ",m(a)
  next a

     For each iteration of the loop, the lower of two random number is recorded.
     The result is printed at the end.

  See also

     max
       _________________________________________________________________

  Name

     mod() - compute the remainder of a division

  Synopsis

  print mod(a,b)

  Description

     The mod-function divides its two arguments and computes the remainder. Note,
     that a/b-int(a/b) and mod(a,b) are always equal.

  Example

  clear screen
  print at(10,10) "Please wait ";
  p$="-\|/"
  for a=1 to 100
    rem  ... do something lengthy here, or simply sleep :-)
    pause(1)
    print at(22,10) mid$(p$,1+mod(a,4))
  next a

     This example executes some time consuming action within a loop (in fact, it
     simply sleeps) and gives the user some indication of progress by displaying
     a turning bar (thats where the mod()-function comes into play).

  See also

     int, frac
       _________________________________________________________________

  Name

     mouseb - extract the state of the mousebuttons from a string returned by
     inkey$

  Synopsis

  inkey$
  print mouseb()
  print mouseb
  a$=inkey$
  print mouseb(a$)

  Description

     The mouseb-function is a helper function for decoding part of the (rather
     complicated) strings, which are returned by the inkey$-function. If a
     mousebutton has been pressed, the mouseb-function returns the number (1,2 or
     3) of the mousebutton, when it is pressed and returns its negative (-1,-2 or
     -3), when it is released.

     The mouseb-function accepts zero or one arguments. A single argument should
     be a string returned by the inkey$-function; if mouseb is called without any
     arguments, it returns the values from the last call to inkey$, which are
     stored implicitly and internally by yabasic.

  Note

     Note however, that the value returned by the mouseb-function does not
     reflect the current state of the mousebuttons. It rather extracts the
     information from the string passed as an argument (or from the last call to
     the inkey$-function, if no argument is passed). So the value returned by
     mouseb reflects the state of the mousebuttons at the time the
     inkey$-function has been called; as opposed to the time the mouseb-function
     is called.

  Example

  open window 200,200
  clear screen
  print "Please draw lines; press (and keep it pressed)"
  print "the left mousebutton for the starting point,"
  print "release it for the end-point."
  do
    if (mouseb(release$)=1) press$=release$
    release$=inkey$
    if (mouseb(release$)=-1) then
      line mousex(press$),mousey(press$) to mousex(release$),mousey(release$)
    endif
  loop

     This is a maybe the most simplistic line-drawing program possible, catching
     presses as well as releases of the first mousebutton.

  See also

     inkey$, mousex, mousey and mousemod
       _________________________________________________________________

  Name

     mousemod - return the state of the modifier keys during a mouseclick

  Synopsis

  inkey$
  print mousemod()
  print mousemod
  a$=inkey$
  print mousemod(a$)

  Description

     The mousemod-function is a helper function for decoding part of the (rather
     complicated) strings, which are returned by the inkey$-function if a
     mousebutton has been pressed. It returns the state of the keyboard modifiers
     (shift, ctrl or alt): If the shift-key is pressed, mousemod returns 1, for
     the alt-key 2 and for the ctrl-key 4. If more than one key is pressed, the
     sum of these values is returned, e.g. mousemod returns 5, if shift and ctrl
     are pressed simultaneously.

     The mousemod-function accepts zero or one arguments. A single argument
     should be a string returned by the inkey$-function; if mousemod is called
     without any arguments, it returns the values from the last call to inkey$
     (which are stored implicitly and internally by yabasic).

  Note

     Please see also the Note within the mouseb-function.

  Example

  open window 200,200
  clear screen
  do
    a$=inkey$
    if (left$(a$,2)="MB") then
      x=mousex(a$)
      y=mousey(a$)
      if (mousemod(a$)=0) then
        circle x,y,20
      else
        fill circle x,y,20
      endif
    endif
  loop

     This program draws a circle, whenever a mousebutton is pressed; the circles
     are filled, when any modifier is pressed, and empty if not.

  See also

     inkey$, mousex, mousey and mouseb
       _________________________________________________________________

  Name

     mousex - return the x-position of a mouseclick

  Synopsis

  inkey$
  print mousex()
  print mousex
  a$=inkey$
  print mousex(a$)

  Description

     The mousex-function is a helper function for decoding part of the (rather
     complicated) strings, which are returned by the inkey$-function; It returns
     the x-position of the mouse as encoded within its argument.

     The mousex-function accepts zero or one arguments. A single argument should
     be a string returned by the inkey$-function; if mousex is called without any
     arguments, it returns the values from the last call to inkey$ (which are
     stored implicitly and internally by yabasic).

  Note

     Please see also the Note within the mouseb-function.

  Example

  open window 200,200
  clear screen
  do
    a$=inkey$
    if (left$(a$,2)="MB") then
      line mousex,0 to mousex,200
    endif
  loop

     This example draws vertical lines at the position, where the mousebutton has
     been pressed.

  See also

     inkey$, mousemod, mousey and mouseb
       _________________________________________________________________

  Name

     mousey - return the y-position of a mouseclick

  Synopsis

  inkey$
  print mousey()
  print mousey
  a$=inkey$
  print mousey(a$)

  Description

     The mousey-function is a helper function for decoding part of the (rather
     complicated) strings, which are returned by the inkey$-function. mousey
     returns the y-position of the mouse as encoded within its argument.

     The mousey-function accepts zero or one arguments. A single argument should
     be a string returned by the inkey$-function; if mousey is called without any
     arguments, it returns the values from the last call to inkey$ (which are
     stored implicitly and internally by yabasic).

  Note

     Please see also the Note within the mouseb-function.

  Example

  open window 200,200
  clear screen
  do
    a$=inkey$
    if (left$(a$,2)="MB") then
      line 0,mousey to 200,mousey
    endif
  loop

     This example draws horizontal lines at the position, where the mousebutton
     has been pressed.

  See also

     inkey$, mousemod, mousex and mouseb

  N

     new curve - start a new curve, that will be drawn with the line-command
     next - mark the end of a for loop
     not - negate an expression; can be written as !
     numparams - return the number of parameters, that have been passed to a
            subroutine

  Name

     new curve - start a new curve, that will be drawn with the line-command

  Synopsis

  new curve
  line to x,y

  Description

     The new curve-function starts a new sequence of lines, that will be drawn by
     repeated line to-commands.

  Example

  open window 200,200
  ellipse(100,50,30,60)
  ellipse(150,100,60,30)
  sub ellipse(x,y,xr,yr)
    new curve
    for a=0 to 2*pi step 0.2
      line to x+xr*cos(a),y+yr*sin(a)
    next a
    close curve
  end sub

     This example defines a subroutine ellipse that draws an ellipse. Within this
     subroutine, the ellipse is drawn as a sequence of lines started with the new
     curve command and closed with close curve.

  See also

     line, close curve
       _________________________________________________________________

  Name

     next - mark the end of a for loop

  Synopsis

  for a=1 to 10
  next a

  Description

     The next-keyword marks the end of a for-loop. All statements up to the
     next-keyword will be repeated as specified with the for-clause. Note, that
     the name of the variable is optional; so instead of next a you may write
     next.

  Example

  for a=1 to 300000
    for b=1 to 21+20*sin(pi*a/20)
      print "*";
    next b
    print
    sleep 0.1
  next a

     This example simply plots a sine-curve until you fall asleep.

  See also

     for
       _________________________________________________________________

  Name

     not - negate an expression; can be written as !

  Synopsis

  if (not a<b) then ...
  bad=!okay

  Description

     The keyword not (or ! for short) is mostly used within conditions (e.g.
     within if- or while-statements). There it is employed to negate the
     condition or expression (i.e. turn TRUE into FALSE and vice versa)

     However not can be used within arithmetic calculations too., simply because
     there is no difference between arithmetic and logical expressions.

  Example

  input "Please enter three ascending numbers: " a,b,c
  if (not (a<b and b<c)) error " the numbers you have entered are not ascending..."

  See also

     and,or
       _________________________________________________________________

  Name

     numparams - return the number of parameters, that have been passed to a
     subroutine

  Synopsis

  sub foo(a,b,c)
    if (numparams=1) ...
    ...
  end sub

  Description

     Within a subroutine the local variable numparam or numparams contains the
     number of parameters, that have been passed to the subroutine. This
     information can be useful, because the subroutine may have been called with
     fewer parameters than actually declared. The number of values that actually
     have been passed while calling the subroutine, can be found in numparams.

     Note, that arguments which are used in the definition of a subroutine but
     are left out during a call to it (thereby reducing the value of numparams)
     receive a value of 0 or "" (empty string) respectively.

  Example

  a$="123456789"
  print part$(a$,4)
  print part$(a$,3,7)

  sub part$(a$,f,t)
    if (numparams=2) then
      return mid$(a$,f)
    else
      return mid$(a$,f,t-f+1)
    end if
  end sub

     When you run this example, it will print 456789 and 34567. Take a look at
     the subroutine part$, which returns part of the string which has been passed
     as an argument. If (besides the string) two numbers are passed, they define
     the starting and end position of the substring, that will be returned.
     However, if only one number is passed, the rest of the string, starting from
     this position will be returned. Each of these cases is recognized with the
     help of the numparams variable.

  See also

     sub

  O

     on gosub - jump to one of multiple gosub-targets
     on goto - jump to one of many goto-targets
     on interrupt - change reaction on keyboard interrupts
     open - open a file
     open printer - open printer for printing graphics
     open window - open a graphic window
     logical or - logical or, used in conditions
     or() - arithmetic or, used for bit-operations

  Name

     on goto - jump to one of multiple gosub-targets

  Synopsis

  on a gosub foo,bar,baz
    ...
  label foo
    ...
  return

  label bar
    ...
  return

  label baz
    ...
  return

  Description

     The on gosub statement uses its numeric argument (the one between on and
     gosub) to select an element from the list of labels, which follows after the
     gosub-keyword: If the number is 1, the program does a gosub to the first
     label; if the number is 2, to the second and, so on. if the number is zero
     or less, the program continues at the position of the first label; if the
     number is larger than the total count of labels, the execution continues at
     the position of the last label; i.e. the first and last label in the list
     constitute some kind of fallback-slot.

     Note, that the on gosub-command can no longer be considered state of the
     art; people (not me !) may even start to mock you, if you use it.

  Example

  do
    print "Please enter a number between 1 and 3: "
    print
    input "Your choice " a
    on a gosub bad,one,two,three,bad
  loop

  label bad
    print "No. Please between 1 and 3"
  return

  label one
    print "one"
  return

  label two
    print "two"
  return

  label three
    print "three"
  return

     Note, how invalid input (a number less than 1, or larger than 3) is
     automatically detected.

  See also

     goto, on gosub/function>
       _________________________________________________________________

  Name

     on goto - jump to one of many goto-targets

  Synopsis

  on a goto foo,bar,baz
    ...
  label foo
    ...
  label bar
    ...
  label baz
    ...

  Description

     The on goto statement uses its numeric argument (the one between on and goto
     to select an element from the list of labels, which follows after the
     goto-keyword: If the number is 1, the execution continues at the first
     label; if the number is 2, at the second, and so on. if the number is zero
     or less, the program continues at the position of the first label; if the
     number is larger than the total count of labels, the execution continues at
     the position of the last label; i.e. the first and last label in the list
     constitute some kind of fallback-slot.

     Note, that (unlike the goto-command) the on goto-command can no longer be
     considered state of the art; people may (not me !) even start to mock you,
     if you use it.

  Example

  label over
  print "Please Select one of these choices: "
  print
  print "  1 -- show time"
  print "  2 -- show date"
  print "  3 -- exit"
  print
  input "Your choice " a
  on a goto over,show_time,show_date,terminate,over

  label show_time
    print time$()
  goto over

  label show_date
    print date$()
  goto over

  label terminate
  exit

     Note, how invalid input (a number less than 1, or larger than 3) is
     automatically detected; in such a case the question is simply issued again.

  See also

     goto, on gosub/function>
       _________________________________________________________________

  Name

     on interrupt - change reaction on keyboard interrupts

  Synopsis

  on interrupt break
  ...
  on interrupt continue

  Description

     With the on interrupt-command you may change the way, how yabasic reacts on
     a keyboard interrupt; it comes in two variants: on interrupt break and on
     interrupt continue. A keyboard interrupt is produced, if you press ctrl-C on
     your keyboard; normally (and certainly after you have called on interrupt
     break), yabasic will terminate with an error message. However after the
     command on interrupt continue yabasic ignores any keyboard interrupt. This
     may be useful, if you do not want your program being interruptible during
     certain critical operations (e.g. updating of files).

  Example

  print "Please stand by while writing a file with random data ..."
  on interrupt continue
  open "random.data" for writing as #1
  for a=1 to 100
    print #1 ran(100)
    print a," percent done."
    sleep 1
  next a
  close #1
  on interrupt continue

     This program writes a file with 100 random numbers. The on interrupt
     continue command insures, that the program will not be terminated on a
     keyboard interrupt and the file will be written entirely in any case. The
     sleep-command just stretches the process artificially to give you a chance
     to try a ctrl-C.

  See also

     There is no related command.
       _________________________________________________________________

  Name

     open - open a file

  Synopsis

  open a,"file","r"
  open #a,"file","w"
  open #a,printer
  open "file" for reading as a
  open "file" for writing as #a
  a=open("file")
  a=open("file","r")
  if (open(a,"file")) ...
  if (open(a,"file","w")) ...

  Description

     The open-command opens a file for reading or writing or a printer for
     printing text. open comes in a wide variety of ways; it requires these
     arguments:

     filenumber
            In the synopsis this is a or #a. In yabasic each file is associated
            with a number between 1 and a maximum value, which depends on the
            operating system. For historical reasons the filenumber can be
            preceded by a hash (’#’). Note, that specifying a filenumber is
            optional; if it is omitted, the open-function will return a
            filenumber, which should then be stored in a variable for later
            reference. This filenumber can be a simple number or an arbitrary
            complex arithmetic expression, in which case braces might be
            necessary to save yabasic from getting confused.

     filename
            In the synopsis above this is "file". This string specifies the name
            of the file to open (note the important caveat on specifying these
            filenames).

     accessmode
            In the synopsis this is "r", "w", for reading or for writing. This
            string or clause specifies the mode in which the file is opened; it
            may be one of:

          "r"
                  Open the file for reading (may also be written as for reading).
                  If the file does not exist, the command will fail. This mode is
                  the default, i.e. if no mode is specified with the
                  open-command, the file will be opened with this mode.

          "w"
                  Open the file for writing (may also be written as for writing).
                  If the file does not exist, it will be created.

          "a"
                  Open the file for appending, i.e. what you write to the file
                  will be appended after its initial contents. If the file does
                  not exist, it will be created.

          "b"
                  This letter may not appear alone, but may be combined with the
                  other letters (e.g. "rb") to open a file in binary mode (as
                  opposed to text mode).

     As you may see from the synopsis, the open-command may either be called as a
     command (without braces) or as a function (with braces). If called as a
     function, it will return the filenumber or zero if the operation fails.
     Therefore the open-function may be used within the condition of an
     if-statement.

     If the open-command fails, you may use peek("error") to retrieve the exact
     nature of the error.

     Furthermore note, that there is another, somewhat separate usage of the
     open-command; if you specify the bareword printer instead of a filename, the
     command opens a printer for printing text. Every text (and only text) you
     print to this file will appear on your printer. Note, that this is very
     different from printing graphics, as can be done with open printer.

     Finally you may read the description for peek("error") to learn which errors
     may have happened during an open-call.

  Example

  open "foo.bar" for writing as #1
  print #1 "Hallo !"
  close #1
  if (not open(1,"foo.bar")) error "Could not open ’foo.bar’ for reading"
  while(not eof(1))
    line input #1 a$
    print a$
  wend

     This example simply opens the file foo.bar, writes a single line, reopens it
     and reads its contents again.

  See also

     close, print, peek, peek("error") and open printer
       _________________________________________________________________

  Name

     open printer - open printer for printing graphics

  Synopsis

  open printer
  open printer "file"

  Description

     The open printer-command opens a printer for printing graphics. The command
     requires, that a graphic window has been opened before. Everything that is
     drawn into this window will then be sent to the printer too.

     A new piece of paper may be started with the clear window-command; the final
     (or only) page will appear after the close printer-command.

     Note, that you may specify a filename with open printer; in that case the
     printout will be sent to a filename instead to a printer. Your program or
     the user will be responsible for sending this file to the printer
     afterwards.

     If you use yabasic under Unix, you will need a postscript printer (because
     yabasic produces postscript output). Alternatively you may use ghostscript
     to transform the postscript file into a form suitable for your printer; but
     that is beyond the responsibility of yabasic.

  Example

  open window 200,200
  open printer
  line 0,0 to 200,200
  text 100,100,"Hallo"
  close window
  close printer

     This example will open a window, draw a line and print some text within;
     everything will appear on your printer too.

  See also

     close printer
       _________________________________________________________________

  Name

     open window - open a graphic window

  Synopsis

  open window x,y
  open window x,y,"font"

  Description

     The open window-command opens a window of the specified size. Only one
     window can be opened at any given moment of time.

     An optional third argument specifies a font to be used for any text within
     the window. It can however be changed with any subsequent text-command.

  Example

  for a=200 to 400 step 10
    open window a,a
    for b=0 to a
      line 0,b to a,b
      line b,0 to b,a
    sleep 0.1
    close window
  next a

  See also

     close window, text
       _________________________________________________________________

  Name

     or - logical or, used in conditions

  Synopsis

  if (a or b) ...
  while (a or b) ...

  Description

     Used in conditions (e.g within if or while) to join two expressions. Returns
     true, if either its left or its right or both arguments are true; returns
     false otherwise.

  Example

  input "Please enter a number"
  if (a>9 or a<1) print "a is not between 1 and 9"

  See also

     and,not
       _________________________________________________________________

  Name

     or() - arithmetic or, used for bit-operations

  Synopsis

  x=or(a,b)

  Description

     Used to compute the bitwise or of both its argument. Both arguments are
     treated as binary numbers (i.e. a series of 0 and 1); a bit of the resulting
     value will then be 1, if any of its arguments has 1 at this position in
     their binary representation.

     Note, that both arguments are silently converted to integer values and that
     negative numbers have their own binary representation and may lead to
     unexpected results when passed to or.

  Example

  print or(14,3)

     This will print 15. This result is clear, if you note, that the binary
     representation of 14 and 3 are 1110 and 0011 respectively; this will yield
     1111 in binary representation or 15 as decimal.

  See also

     oand, eor and not

  P

     pause - pause, sleep, wait for the specified number of seconds
     peek - retrieve various internal informations
     peek$ - retrieve various internal string-informations
     pi - a constant with the value 3.14159
     poke - change selected internals of yabasic
     print - Write to terminal or file
     print color - print with color
     print colour - see color
     putbit - draw a rectangle of pixels encoded within a string into the
            graphics window

     putscreen - draw a rectangle of characters into the text terminal

  Name

     pause - pause, sleep, wait for the specified number of seconds

  Synopsis

  pause 5

  Description

     The pause-command has many different names: You may write pause, sleep or
     wait interchangeably; whatever you write, yabasic will always do exactly the
     same.

     The pause-command will simply wait for the specified number of seconds. This
     may be a fractional number, so you may well wait less than a second.
     However, if you try to pause for a smaller and smaller interval (e.g. 0.1
     seconds, 0.01 seconds, 0.001 seconds and so on) you will find that at some
     point yabasic will not wait at all. The minimal interval that can be waited
     depends on the system (Unix, Windows) you are using.

     The pause-command cannot be interrupted. However, sometimes you may want the
     wait to be interruptible by simply pressing a key on the keyboard. In such
     cases you should consider using the inkey$-function, with a number of
     seconds as an argument).

  Example

  deg=0
  do
    maxx=44+40*sin(deg)
    for x=1 to maxx
      print "*";
    next x
    pause 0.1+(maxx*maxx/(4*84*84))
    print
    deg=deg+0.1
  loop

     This example draws a sine-curve; due to the pause-statement the speed of
     drawing varies in the same way as the speed of a ball might vary, if it
     would roll along this curve under the influence of gravity.

  See also

     sleep, wait
       _________________________________________________________________

  Name

     peek - retrieve various internal informations

  Synopsis

  print peek("foo")
  a=peek(#1)

  Description

     The peek-function has many different and mostly unrelated uses. It is a kind
     of grab-bag for retrieving all kinds of numerical information, internal to
     yabasic. The meaning of the numbers returned be the peek-function depends on
     the string or number passed as an argument.

     peek always returns a number, however the closely related peek$-function
     exists, which may be used to retrieve string information from among the
     internals of yabasic. Finally note, that some of the values which are
     retrieved with peek may even be changed, using the poke-function.

     There are two variants of the peek-function: One expects an integer,
     positive number and is described within the first entry of the list below.
     The other variant expects one of a well defined set of strings as described
     in the second and all the following entries of the list below.

     peek(a), peek(#a)
            Read a single character from the file a (which must be open of
            course).

     peek("winheight")
            Return the height of the graphic-window in pixels. If none is open,
            this peek will return the height of the last window opened or 100, if
            none has been opened yet.

     peek("winwidth")
            Return the width of the graphic-window in pixels. If none is open,
            this peek will return the width of the last window opened or 100, if
            none has been opened yet.

     peek("fontheight")
            Return the height of the font used within the graphic window. If none
            is open, this peek will return the height of the last font used or
            10, if no window has been opened yet.

     peek("screenheight")
            Return the height in characters of the window, wherein yabasic runs.
            If you have not called clear screen yet, this peek will return 0,
            regardless of the size of your terminal.

     peek("screenwidth")
            Return the width in characters of the window, wherein yabasic runs.
            If you have not called clear screen yet, this peek will return 0,
            regardless of the size of your terminal.

     peek("argument")
            Return the number of arguments, that have been passed to yabasic at
            invocation time. E.g. if yabasic has been called like this: yabasic
            foo.yab bar baz, then peek("argument") will return 2. This is because
            foo.yab is treated as the name of the program to run, whereas bar and
            baz are considered arguments to the program, which are passed on the
            command line. Note, that for windows-users, who tend to click on the
            icon (as opposed to starting yabasic on the command line), this
            peek will mostly return 0.

            The function peek("argument") can be written as peek("arguments")
            too.

            You will want to check out the corresponding function
            peek$("argument") to actually retrieve the arguments. Note, that each
            call to peek$("argument") reduces the number returned by
            peek("argument").

     peek("isbound")
            Return true, if the executing yabasic-program is part of a standalone
            program; see the section about creating a standalone-program for
            details.

     peek("version")
            Return the version number of yabasic (e.g. 2.72).

     peek("error")
            Return a number specifying the nature of the last error in an open-
            or seek-statement. Normally an error within an open-statement
            immediately terminates your program with an appropriate
            error-message, so there is no chance and no need to learn more about
            the nature of the error. However, if you use open as a condition
            (e.g. if (open(#1,"foo")) ...) the outcome (success or failure) of the
            open-operation will determine, if the condition evaluates to true or
            false. If now such an operation fails, your program will not be
            terminated and you might want to learn the reason for failure. This
            reason will be returned by peek("error") (as a number) or by
            peek$("error") (as a string)

            The table below shows the various error codes; the value returned by
            peek$("error") explains the nature of the error. Note, that the codes
            10,11 and 12 refer to the seek-command.

            Table 6.1. Error codes

     peek("error") peek$("error") Explanation
     2 Stream already in use Do not try to open one and the same filenumber
     twice; rather close it first.
     3 ’x’ is not a valid filemode The optional filemode argument, which may be
     passed to the open-function, has an invalid value
     4 could not open ’foo’ The open-call did not work, no further explanation is
     available.
     5 reached maximum number of open files You have opened more files than your
     operating system permits.
     6 cannot open printer: already printing graphics The commands open printer
     and open #1,printer both open a printer (refer to their description for the
     difference). However, only one can be active at a time; if you try to do
     both at the same time, you will receive this error.
     7 could not open line printer Well, it simply did not work.
     9 invalid stream number An attempt to use an invalid (e.g. negative) stream
     number; example: open(-1,"foo")
     10 could not position stream x to byte y seek did not work.
     11 stream x not open You have tried to seek within a stream, that has not
     been opened yet.
     12 seek mode ’x’ is none of begin,end,here The argument, which has been
     passed to seek is invalid.

  Example

  open "foo" for reading as #1
  open "bar" for writing as #2
  while(not eof(#1))
    poke #2,chr$(peek(#1));
  wend

     This program will copy the file foo byte by byte to bar.

     Note, that each peek does something entirely different, and only one has
     been demonstrated above. Therefore you need to make up examples yourself for
     all the other peeks.

  See also

     peek$, poke, open
       _________________________________________________________________

  Name

     peek$ - retrieve various internal string-informations

  Synopsis

  print peek$("foo")

  Description

     The peek$-function has many different and unrelated uses. It is a kind of
     grab-bag for retrieving all kinds of string information, internal to yabasic;
     the exact nature of the strings returned be the peek$-function depends on
     the string passed as an argument.

     peek$ always returns a string, however the closely related peek-function
     exists, which may be used to retrieve numerical information from among the
     internals of yabasic. Finally note, that some of the values which are
     retrieved with peek$ may even be changed, using the poke-function.

     The following list shows all possible arguments to peek$:

     peek$("infolevel")
            Returns either "debug", "note", "warning", "error" or "fatal",
            depending on the current infolevel. This value can be specified with
            an option (either under windows or unix) on the command line or
            changed during the execution of the program with the corresponding
            poke; however, normally only the author of yabasic (me !) would want
            to change this from its default value "warning".

     peek$("textalign")
            Returns one of nine possible strings, specifying the default
            alignment of text within the graphics-window. The alignment-string
            returned by this peek describes, how the text-command aligns its
            string-argument with respect to the coordinates supplied. However,
            this value does not apply, if the text-command explicitly specifies
            an alignment. Each of these strings is two characters long. The first
            character specifies the horizontal alignment and can be either l, r
            or c, which stand for left, right or center. The second character
            specifies the vertical alignment and can be one of t, b or c, which
            stand for top, bottom or center respectively.

            You may change this value with the corresponding command poke
            "textalign",...; the initial value is lb, which means the top of the
            left and the top edge if the text will be aligned with the
            coordinates, that are specified within the text-command.

     peek$("windoworigin")
            This peek returns a two character string, which specifies the
            position of the origin of the coordinate system of the window; this
            string might be changed with the corresponding command poke
            "windoworigin",x,y or specified as the argument of the origin
            command; see there for a detailed description of the string, which
            might be returned by this peek.

     peek$("error")
            Return a string describing the nature of the last error in an open-
            or seek-statement. See the corresponding peek("error") for a detailed
            description.

     peek$("library")
            Return the name of the library, this statement is contained in. See
            the import-command for a detailed description or for more about
            libraries.

     peek$("os")
            This peek returns the name of the operating system, where your
            program executes. This can be either windows or unix.

     peek$("font")
            Return the name of the font, which is used for text within the
            graphic window; this value can be specified as the third argument to
            the open window-command.

     peek$("env","NAME")
            Return the environment variable specified by NAME (which may be any
            string expression). Which kind of environment variables are available
            on your system depends, as well as their meaning, on your system;
            however typing env on the command line will produce a list (for
            Windows and Unix alike). Note, that peek$("env",...) can be written
            as peek$("environment",...) too.

     peek$("argument")
            Return one of the arguments, that have been passed to yabasic at
            invocation time (the next call will return the the second argument,
            and so on). E.g. if yabasic has been called like this: yabasic
            foo.yab bar baz, then the first call to peek$("argument") will return
            bar. This is because foo.yab is treated as the name of the program to
            run, whereas bar and baz are considered arguments to this program,
            which are passed on the command line. The second call to
            peek$("argument") will return baz. Note, that for windows-users, who
            tend to click on the icon (as opposed to starting yabasic on the
            command line), this peek will mostly return the empty string.

            Note, that peek$("argument") can be written as peek$("arguments").

            Finally you will want to check out the corresponding function
            peek("argument").

  Example

  print "You have supplied these arguments: "
  while(peek("argument"))
    print peek("argument"),peek$("argument")
  wend

     If you save this program in a file foo.yab and execute it via yabasic t.yab
     a b c (for windows users: please use the command line for this), your will
     get this output:
  3a
  2b
  1c

  See also

     peek, poke, open
       _________________________________________________________________

  Name

     pi - a constant with the value 3.14159

  Synopsis

  print pi

  Description

     pi is 3.14159265359 (well at least for yabasic); do not try to assign to pi
     (e.g. pi=22/7) this would not only be mathematically dubious, but would also
     result in a syntax error.

  Example

  for a=0 to 180
    print "The sine of ",a," degrees is ",sin(a*pi/180)
  next a

     This program uses pi to transform an angle from degrees into radians.

  See also

     euler
       _________________________________________________________________

  Name

     poke - change selected internals of yabasic

  Synopsis

  poke "foo","bar"
  poke "foo",baz
  poke #a,"bar"
  poke #a,baz

  Description

     The poke-command may be used to change details of yabasic’s behaviour. Like
     the related function peek, poke does many different things, depending on the
     arguments supplied.

     Here are the different things you can do with poke:

     poke "textalign","cc"
            This poke changes the default alignment of text with respect to the
            coordinates supplied within the text-command. However, this value
            does not apply, if the text-command explicitly specifies an
            alignment. The second argument ("cc" in the example) must always be
            two characters long; the first character can be one of l (left), r
            (right) or c (center); the second character can be either t (top), b
            (bottom) or c (center); see the corresponding peek$("textalign") for
            a detailed description of this argument.

     poke "windoworigin","lt"
            This poke moves the origin of the coordinate system of the window to
            the specified position. The second argument ("lt" in the example)
            must always be two characters long; the first character can be one of
            l (left), r (right) or c (center); the second character can be either
            t (top), b (bottom) or c (center). Together those two characters
            specify the new position of the coordinate-origin. See the
            corresponding peek$("windoworigin") for a more in depth description
            of this argument.

     poke "infolevel","debug"
            Change the amount of internal information, that yabasic outputs
            during execution.

            The second argument can be either "debug", "note", "warning", "error"
            or "fatal". However, normally you will not want to change this from
            its default value "warning".

            See also the related peek$("infolevel").

     poke #1,a
            Write the given byte (a in the example above) to the specified stream
            (#a in the example).

            See also the related function function peek(#1).

  Example

  print "Hello, now you will see, how much work"
  print "a simple for-loop involves ..."
  input "Please press return " a$
  poke "infolevel","debug"
  for a=1 to 10:next a

     This example only demonstrates one of the many pokes, which are described
     above: The program switches the infolevel to debug, which makes yabasic
     produce a lot of debug-messages during the subsequent for-loop.

  See also

     peek, peek$
       _________________________________________________________________

  Name

     print - Write to terminal or file

  Synopsis

  print "foo",a$,b
  print "foo","a$,b;
  print #a "foo",a$
  print #a "foo",a$;
  print foo using "##.###"
  print reverse "foo"
  print at(10,10) a$,b
  print @(10,10) a$,b
  print color("red","blue") a$,b
  print color("magenta") a$,b
  print color("green","yellow") at(5,5) a$,b

  Description

     The print-statement outputs strings or characters, either to your terminal
     (also known as console) or to an open file.

     To understand all those uses of the print-statement, let’s go through the
     various lines in the synopsis above:

     print "foo",a$,b
            Print the string foo as well as the contents of the variables a$ and
            b onto the screen, silently adding a newline.

     print "foo",a$,b;
            (Note the trailing semicolon !) This statement does the same as the
            one above; only the implicit newline is skipped, which means that the
            next print-statement will append seamlessly.

     print #a "foo",a$
            This is the way to write to files. The file with the number a must be
            open already, an implicit newline is added. Note the file-number #a,
            which starts with a hash (’#’) amd is separated from the rest of the
            statement by a space only. The file-number (contained in the variable
            a) must have been returned by a previous open-statement (e.g.
            a=open("bar")).

     print #a "foo",a$;
            The same as above, but without the implicit newline.

     print foo using "##.###"
            Print the number foo with as many digits before and after the decimal
            dot as given by the number of ’#’-signs. See the entries for using
            and str$ for a detailed description of this format.

     print reverse "foo"
            As all the print-variants to follow, this form of the print-statement
            can only be issued after clear screen has been called. The strings
            and numbers after the reverse-clause are simply printed inverse
            (compared to the normal print-statement).

     print at(10,10) a$,b
            Print at the specified (x,y)-position. This is only allowed after
            clear screen has been called. You may want to query
            peek$("screenwidth") or peek$("screenheight") to learn the actual
            size of your screen. You may add a semicolon to suppress the implicit
            newline.

     print @(10,10) a$,b
            This is exactly the same as above, however, at may be written as @.

     print color("red","blue") at(5,5) a$,b
            Print with the specified fore- ("red") and background ("blue") color
            (or colour). The possible values are "black", "white", "red", "blue",
            "green", "yellow", "cyan" or "magenta". Again, you need to call clear
            screen first and add a semicolon if you want to suppress the implicit
            newline.

     print color("magenta") a$,b
            You may specify the foreground color only.

     print color("green","yellow") a$,b
            A color and a position (in this sequence, not the other way around)
            may be specified at once.

  Example

  clear screen
  columns=peek("screenwidth")
  lines=peek("screenheight")
  dim col$(7)
  for a=0 to 7:read col$(a):next a
  data "black","white","red","blue","green","yellow","cyan","magenta"

  for a=0 to 2*pi step 0.1
    print colour(col$(mod(i,8))) at(columns*(0.8*sin(a)+0.9)/2,lines*(0.8*cos(a)+
  0.9)/2) "*"
    i=i+1
  next a

     This example draws a colored ellipse within the text window.

  See also

     at, print color, input, clear screen, using, ;
       _________________________________________________________________

  Name

     print color - print with color

  Synopsis

  print color(fore$) text$
  print color(fore$,back$) text$

  Description

     Not a separate command, but part of the print-command; may be included just
     after print and can only be issued after clear screen has been executed.

     color() takes one or two string-arguments, specifying the color of the text
     and (optionally) the background.

     The one or two strings passed to color() can be one of these: "black",
     "white", "red", "blue", "green", "yellow", "cyan" and "magenta" (which can
     be abbreviated as "bla", "whi", "red", "blu", "gre", "yel", "cya" and "mag"
     respectively).

     color() can only be used, if clear scren has been issued at least once.

     Note, that color() can be written as colour() too.

  Example

  clear screen
  dim col$(7):for a=0 to 7:read col$(a):next a
  do
    print color(col$(ran(7)),col$(ran(7))) " Hallo ";
    pause 0.01
  loop
  data "black","white","red","blue"
  data "green","yellow","cyan","magenta"

     This prints the word " Hallo " in all colors across your screen.

  See also

     print, clear screen, at
       _________________________________________________________________

  Name

     print colour - see color

  Synopsis

  print colour(fore$) text$
  print colour(fore$,back$) text$

  See also

     color
       _________________________________________________________________

  Name

     putbit - draw a rectangle of pixels encoded within a string into the
     graphics window

  Synopsis

  open window 200,200
  ...
  a$=getbit(20,20,50,50)
  ...
  putbit a$,30,30
  putbit a$ to 30,30
  putbit a$,30,30,"or"

  Description

     The putbit-command is the counterpart of the getbit-function. putbit
     requires a string as returned by the getbit-function. Such a string contains
     a rectangle from the graphic window; the putbit-function puts such a
     rectangular region back into the graphic-window.

     Note, that the putbit-command currently accepts a third argument. However
     only the string value "or" is supported here. The effect is, that only those
     pixel, which are set in the string will be set in the graphic window. Those
     pixels, which are not set in the string, will not change in the window (as
     opposed to being cleared).

     Note, that the format of the string returned by this function is due to
     change as soon as yabasic will learn, how to deal with colors.

  Example

  c$="rgb 21,21:0000000000000000000000000000000000000000000000000000000000000032c
  8000000000000000000000000000000000000000000000000000000000000000000000000000000
  0000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80000000
  000000000000000000000000000000000000000000000000000000032c80032c80032c80032c800
  32c80032c80032c80032c80032c80032c80032c80032c8000000000000000000000000000000000
  0000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032
  c80032c80032c80032c80032c80000000000000000000000000000000032c80032c80032c80032c
  80032c80032c80032c80032c8c8ff000032c80032c80032c80032c80032c80032c80032c8000000
  0000000000000000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c
  8ff00c8ff00c8ff000032c80032c80032c80032c80032c80000000000000000000032c80032c800
  32c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c8003
  2c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff
  00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c800000000000
  00032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00
  c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c
  8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c800
  32c80000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8f
  f00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032
  c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c
  80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00
  c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000
  032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8
  ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c80032c8c8f
  f00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80032
  c80000000000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff0
  0c8ff00c8ff000032c80032c80032c80032c80032c80000000000000000000000000032c80032c8
  0032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80
  032c80000000000000000000000000000000000000032c80032c80032c80032c80032c80032c800
  32c80032c80032c80032c80032c80032c80032c80032c80032c8000000000000000000000000000
  0000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032
  c80032c80000000000000000000000000000000000000000000000000000000000000000000032c
  80032c80032c80032c80032c80032c80032c80032c80032c8000000000000000000000000000000
  0000000000000000000000000000000000000000000000000000000000000000000000000000000
  00000000000000000000000000000000000000000000000000000"

  open window 200,200

  do
    x=ran(220)-10
    y=ran(220)-10
    putbit c$,x,y,"transparent"
  loop

     This program uses a precanned string (containing the image of a blue circle
     with a yellow centre) and draws it repeatedly into the graphic-window. The
     mode "transparent" ensures, that no pixels will be cleared.

     There are two possible values for the third argument of putbit. Both modes
     differ in the way, they replace (or not) any pixels from the window with
     pixels from the bitmap having the background colour.

     transparent or t
            With this mode the pixels from the window will be kept, if the bitmap
            contains pixels with background colour at this position; i.e. the
            bitmap is transparent

     solid or s
            With this mode the pixels from the window will be overpainted with
            the pixels from the bitmap in any case; i.e. the bitmap is solid

     If you omit this argument, the default transparent applies.

  See also

     getbit$, open window
       _________________________________________________________________

  Name

     putscreen - draw a rectangle of characters into the text terminal

  Synopsis

  clear screen
  ...
  a$=getscreen$(5,5,10,10)
  ...
  putscreen a$,7,7

  Description

     The putscreen-command is the counterpart of the getscreen$-function.
     putscreen requires a string as returned by the getscreen-function. Such a
     string contains a rectangular detail from the terminal; the
     putscreen-function puts such a region back into the terminal-window.

     Note, that clear screen must have been called before.

  Example

  clear screen
  for a=1 to 200
    print color("red") "Hallo !";
    print color("blue") "Welt !";
  next a
  r$=getscreen$(0,0,20,20)
  for x=0 to 60
    putscreen r$,x,0
    sleep 0.1
  next x

     This example prints the string "Hallo !Welt !" all over the screen and then
     moves a rectangle from one side to the other.

  See also

     getscreen$, clear screen

  R

     ran() - return a random number
     read - read data from data-statements
     rectangle - draw a rectangle
     redim - create an array prior to its first use. A synonym for dim
     rem - start a comment
     repeat - start a repeat-loop
     restore - reposition the data-pointer
     return - return from a subroutine or a gosub
     reverse - print reverse (background and foreground colors exchanged)
     right$() - return (or change) the right end of a string
     rinstr() - find the rightmost occurrence of one string within the other
     rtrim$() - trim spaces at the right end of a string

  Name

     ran() - return a random number

  Synopsis

  print ran()
  x=ran(y)

  Description

     The ran-function returns a random number. If no argument is given, the
     number returned is in the range from 0 to 1; where only 0 is a possible
     value; 1 will never be returned. If an argument is supplied, the number
     returned will be in the range from 0 up to this argument, whereas this
     argument itself is not a possible return value.

  Example

  clear screen
  c=peek("screenwidth")-1
  l=peek("screenheight")

  dim col$(8)
  for a=0 to 7:read col$(a):next a
  data "black","white","red","blue","green","yellow","cyan","magenta"

  do
    x=ran(c)
    y=l-ran(l*exp(-32*((x/c-1/2)**2)))
    i=i+1
    print color(col$(mod(i,8))) at(x,y) "*";
  loop

     This example will print a colored bell-curve.

  See also

     int
       _________________________________________________________________

  Name

     read - read data from data-statements

  Synopsis

  read a$,a
  ...
  data "Hello !",7

  Description

     The read-statement retrieves literal data, which is stored within
     data-statements elsewhere in your program.

  Example

  read num
  dim col$(num)
  for a=1 to num:read col$(a):next a
  clear screen
  print "These are the colours known to yabasic:\n"
  for a=1 to num
    print colour(col$(a)) col$(a)
  next a

  data 8,"black","white","red","blue"
  data "green","yellow","cyan","magenta"

     This program prints the names of the colors known to yabasic in those very
     colors.

  See also

     data, restore
       _________________________________________________________________

  Name

     rectangle - draw a rectangle

  Synopsis

  open window 100,100
  rectangle 10,10 to 90,90
  rectangle 20,20,80,80
  rect 20,20,80,80
  box 30,30,70,70
  clear rectangle 30,30,70,70
  fill rectangle 40,40,60,60
  clear fill rectangle 60,60,40,40

  Description

     The rectangle-command (also known as box or rect, for short) draws a
     rectangle; it accepts four parameters: The x- and y-coordinates of two
     facing corners of the rectangle. With the optional clauses clear and
     fill (which may appear in any sequence) the rectangle can be
     cleared and filled respectively.

  Example

  open window 200,200
  c=1
  do
    for phi=0 to pi step 0.1
      if (c) then
        rectangle 100+100*sin(phi),100+100*cos(phi) to 100-100*sin(phi),100-100*c
  os(phi)
      else
        clear rectangle 100+100*sin(phi),100+100*cos(phi) to 100-100*sin(phi),100
  -100*cos(phi)
      endif
      sleep 0.1
    next phi
    c=not c
  loop

     This example draws a nice animated pattern; watch it for a couple of hours,
     to see how it develops.

  See also

     open window, open printer, line, circle, triangle
       _________________________________________________________________

  Name

     redim - create an array prior to its first use. A synonym for dim

  Synopsis

  See the dim-command.

  Description

     The redim-command does exactly the same as the dim-command; it is just a
     synonym. redim has been around in older versions of basic (not even yabasic)
     for many years; therefore it is supported in yabasic for compatibility
     reasons.

     Please refer to the entry for the dim-command for further information.
       _________________________________________________________________

  Name

     rem - start a comment

  Synopsis

  rem  Hey, this is a comment
  #    this is a comment too
  // even this
  print "Not a comment" #    This is an error !!
  print "Not a comment"://   But this is again a valid comment
  print "Not a comment" //   even this.
  print "Not a comment" rem  and this !

  Description

     rem introduces a comment (like # or //), that extends up to the end of the
     line.

     Those comments do not even need a colon (’:’) in front of them; they (rem, #
     and //) all behave alike except for #, which may only appear at the very
     beginning of a line; therefore the fourth example in the synopsis above
     (print "Not a comment" # This is an error !!) is indeed an error.

     Note, that rem is an abbreviation for remark. remark however is not a valid
     command in yabasic.

     Finally note, that a comment introduced with ’#’ may have a special meaning
     under unix; see the entry for # for details.

  Example

  #
  rem   comments on data structures
  #     are more useful than
  //    comments on algorithms.
  rem

     This program does nothing, but in a splendid and well commented way.

  See also

     #, //
       _________________________________________________________________

  Name

     repeat - start a repeat-loop

  Synopsis

  repeat
    ...
  until (...)

  Description

     The repeat-loop executes all the statements up to the final until-keyword
     over and over. The loop is executed as long as the condition, which is
     specified with the until-clause, becomes true. By construction, the
     statements within the loop are executed at least once.

  Example

  x=0
  clear screen
  print "This program will print the numbers from 1 to 10"
  repeat
    x=x+1
    print x
    print "Press any key for the next number, or ’q’ to quit"
    if (inkey$="q") break
  until(x=10)

     This program is pretty much useless, but self-explanatory.

  See also

     until, break, while, do
       _________________________________________________________________

  Name

     restore - reposition the data-pointer

  Synopsis

  read a,b,c,d,e,f
  restore
  read g,h,i
  restore foo
  data 1,2,3
  label foo
  data 4,5,6

  Description

     The restore-command may be used to reset the reading of data-statements, so
     that the next read-statement will read data from the first data-statement.

     You may specify a label with the restore-command; in that case, the next
     read-statement will read data starting at the given label. If the label is
     omitted, reading data will begin with the first data-statement within your
     program.

  Example

  input "Which language (german/english) ? " l$
  if (instr("german",l$)>0) then
    restore german
  else
    restore english
  endif

  for a=1 to 3
    read x,x$
    print x,"=",x$
  next a

  label english
  data 1,"one",2,"two",3,"three"
  label german
  data 1,"eins",2,"zwei",3,"drei"

     This program asks to select one of those languages known to me (i.e. english
     or german) and then prints the numbers 1,2 and 3 and their textual
     equivalents in the chosen language.

  See also

     read, data, label
       _________________________________________________________________

  Name

     return - return from a subroutine or a gosub

  Synopsis

  gosub foo
  ...
  label foo
  ...
  return

  sub bar(baz)
    ...
    return quertz
  end sub

  Description

     The return-statement serves two different (albeit somewhat related)
     purposes. The probably more important use of return is to return control
     from within a subroutine to the place in your program, where the subroutine
     has been called. If the subroutine is declared to return a value, the
     return-statement might be accompanied by a string or number, which
     constitutes the return value of the subroutine.

     However, even if the subroutine should return a value, the return-statement
     need not carry a value; in that case the subroutine will return 0 or the
     empty string (depending on the type of the subroutine). Moreover, feel free
     to place multiple return-statements within your subroutine; it’s a nice way
     of controlling the flow of execution.

     The second (but historically first) use of return is to return to the
     position, where a prior gosub has left off. In that case return may not
     carry a value.

  Example

  do
    read a$
    if (a$="") then
      print
      end
    endif
    print mark$(a$)," ";
  loop

  data "The","quick","brown","fox","jumped"
  data "over","the","lazy","dog",""

  sub mark$(a$)
    if (instr(lower$(a$),"q")) return upper$(a$)
    return a$
  end sub

     This example features a subroutine mark$, that returns its argument in upper
     case, if it contains the letter "q", or unchanged otherwise. In the
     test-text the word quick will end up being marked as QUICK.

     The example above demonstrates return within subroutines; please see gosub
     for an example of how to use return in this context.

  See also

     sub, gosub
       _________________________________________________________________

  Name

     reverse - print reverse (background and foreground colors exchanged)

  Synopsis

  clear screen
  ...
  print reverse "foo"

  Description

     reverse may be used to print text in reverse. reverse is not a separate
     command, but part of the print-command; it may be included just after the
     print and can only be issued once that clear screen has been issued.

  Example

  clear screen

  print "1 ";
  c=3
  do
    prim=true
    for a=2 to sqrt(c)
      if (frac(c/a)=0) then
        prim=false
        break
      endif
    next a
    if (prim) then
      print
      print reverse c;
    else
      print c;
    endif
    print " ";
    c=c+1
  loop

     This program prints numbers from 1 on and marks each prime number in
     reverse.

  See also

     at, print color, print, clear screen
       _________________________________________________________________

  Name

     right$() - return (or change) the right end of a string

  Synopsis

  print right$(a$,2)
  right$(b$,2)="baz"

  Description

     The right$-function requires two arguments (a string and a number) and
     returns the part from the right end of the string, whose length is specified
     by its second argument. So, right$ simply returns the requested number of
     chars from the right end of the given string.

     Note, that the right$-function can be assigned to, i.e. it may appear on the
     left hand side of an assignment. In this way it is possible to change a part
     of the variable used within the right$-function. Note, that that way the
     length of the string cannot be changed, i.e. characters might be
     overwritten, but not added. For an example see below.

  Example

  print "Please enter a length either in inch or centimeter"
  print "please add ’in’ or ’cm’ to mark the unit."
  input "Length: " a$
  if (right$(a$,2)="in") then
     length=val(a$)*2.56
  elsif (right$(a$,2)="cm") then
     length=val(a$)
  else
     error "Invalid input: "+a$
  endif

     This program allows the user to enter a length qualified with a unit (either
     inch or centimeter).

     This second example demonstrates the capability to assign to the
     right$-function.
  a$="Heiho World !"
  print a$
  right$(a$,7)="dwarfs."
  print a$

  See also

     right$ and mid$
       _________________________________________________________________

  Name

     rinstr() - find the rightmost occurrence of one string within the other

  Synopsis

  pos=rinstr("Thequickbrownfox","equi")
  pos=rinstr(a$,b$,x)

  Description

     The rinstr-function accepts two string-arguments and tries to find the
     second within the first. However, unlike the instr, the rinstr-function
     finds the rightmost (or last) occurrence of the string; whereas the
     instr-function finds the leftmost (or first) occurrence. In any case
     however, the position is counted from the left.

     If you supply a third, numeric argument to the rinstr-function, it will be
     used as a starting point for the search. Therefore
     rinstr("abcdeabcdeabcde","e",8) will return 5, because the search for an "e"
     starts at position 8 and finds the first one at position 5.

  Example

  print rinstr("foofoofoobar","foo")

     This simple example will print 7, because it finds the rightmost among the
     three occurrences of foo within the string. Note, that
  print instr("foofoofoobar","foo")

     would have printed 1.

  See also

     instr
       _________________________________________________________________

  Name

     rtrim$() - trim spaces at the right end of a string

  Synopsis

  a$=rtrim$(b$)

  Description

     The rtrim$-function removes all whitespace from the right end of a string
     and returns the result.

  Example

  open 1,"foo"
  dim lines$(100)
  l=1
  while(not eof(1))
    input #1 a$
    a$=rtrim$(a$)
    if (right$(line$,1)="\\") then
      line$=line$+" "+a$
    else
      lines$(l)=line$
      l=l+1
      line$=a$
    endif
  end while
  print "Read ",l," lines"

     This example reads the file foo allowing for continuation lines, which are
     marked by a \, which appears as the last character on a line. For
     convenience whitespace at the right end of a line is trimmed with rtrim.

  See also

     ltrim$, trim$

  S

     screen - as clear screen clears the text window
     seek() - change the position within an open file
     sig() - return the sign of its argument
     sin() - return the sine of its single argument
     sleep - pause, sleep, wait for the specified number of seconds
     split() - split a string into many strings
     sqr() - compute the square of its argument
     sqrt() - compute the square root of its argument
     static - preserves the value of a variable between calls to a subroutine
     step - specifies the increment step in a for-loop
     str$() - convert a number into a string
     sub - declare a user defined subroutine
     switch - select one of many alternatives depending on a value
     system$() - hand a statement over to your operating system and return its
            output

     system() - hand a statement over to your operating system and return its
            exitcode

  Name

     screen - as clear screen clears the text window

  Synopsis

  clear screen

  Description

     The keyword screen appears only within the sequence clear screen; please see
     there for a description.

  See also

     clear screen
       _________________________________________________________________

  Name

     seek() - change the position within an open file

  Synopsis

  open 1,"foo"
  seek #1,q
  seek #1,x,"begin"
  seek #1,y,"end"
  seek #1,z,"here"

  Description

     The seek-command changes the position, where the next input (or peek)
     statement will read from an open file. Usually files are read from the
     beginning to the end sequentially; however sometimes you may want to depart
     from this simple scheme. This can be done with the seek-command, allowing
     you to change the position, where the next piece of data will be read from
     the file.

     seek accepts two or three arguments: The first one is the number of an
     already open file. The second one is the position where the next read from
     the file will start. The third argument is optional and specifies the the
     point from where the position (the second argument) will count. It can be
     one of:

     begin
            Count from the beginning of the file.

     end
            Count from the end of the file.

     here
            Count from the current position within the file.

  Example

  open #1,"count.dat","w"
  for a=1 to 10
    print #1,"00000000";
    if (a<10) print #1,";";
  next a

  dim count(10)
  do
    x=int(ran(10))
    i=i+1
    if (mod(i,1000)=0) print ".";
    count(x)=count(x)+1
    curr$=right$("00000000"+str$(count(x)),8)
    seek #1,9*x,"begin"
    print #1,curr$;
  loop

     This example increments randomly one of ten counters (in the array count());
     however, the result is always kept and updated within the file count.dat, so
     even in case of an unexpected interrupt, the result will not be lost.

  See also

     tell, open, print, peek
       _________________________________________________________________

  Name

     sig() - return the sign of its argument

  Synopsis

  a=sig(b)

  Description

     Return +1, -1 or 0, if the single argument is positive, negative or zero.

  Example

  clear screen
  dim c$(3):c$(1)="red":c$(2)="white":c$(3)="green"
  do
    num=ran(100)-50
    print color(c$(2+sig(num))) num
  loop

     This program prints an infinite sequence of random number; positive numbers
     are printed in green, negative numbers are printed red (an exact zero would
     be printed white). (With a little extra work, this program could be easily
     extended into a brokerage system)

  See also

     abs, int, frac
       _________________________________________________________________

  Name

     sin() - return the sine of its single argument

  Synopsis

  y=sin(angle)

  Description

     The sin-function expects an angle (in radian, not degree) and returns its
     sine.

  Example

  open window 200,200
  new curve
  for phi=0 to 2*pi step 0.1
    line to 100+90*sin(phi),100+90*cos(phi)
  next phi
  close curve

     This program draws a circle (ignoring the existence of the circle-command).

  See also

     asin, cos
       _________________________________________________________________

  Name

     sleep - pause, sleep, wait for the specified number of seconds

  Synopsis

  sleep 4

  Description

     The sleep command has many different names: You may write pause, sleep or
     wait interchangeable; whatever you write, yabasic will always do exactly the
     same.

     Therefore you should refer to the entry for the pause-function for further
     information.
       _________________________________________________________________

  Name

     split() - split a string into many strings

  Synopsis

  dim w$(10)
  ...
  num=split(a$,w$())
  num=split(a$,w$(),s$)

  Description

     The split-function requires a string (containing the text to be split), a
     reference to a string-array (which will receive the resulting strings, i.e.
     the tokens) and an optional string (with a set of characters, at which to
     split, i.e. the delimiters).

     The split-function regards its first argument (a string) as a list of tokens
     separated by delimiters and it will store the list of tokens within the
     array-reference you have supplied. Note, that the array, which is passed as
     a reference (w$() in the synopsis), will be resized accordingly, so that you
     don’t have to figure out the number of tokens in advance. The element at
     position zero (i.e. w$(0)) will not be used.

     normally (i.e. if you omit the third, which is the delimiter-argument) the
     function will regard space or tab as delimiters for tokens; however by
     supplying a third argument, you may split at any single of the characters
     within this string. E.g. if you supply ":;" as the third argument, then
     colon (:) or semicolon (;) will delimit tokens.

     Note, that a sequence of separator-characters will produce a sequence of
     empty tokens; that way, the number of tokens returned will always be one
     plus the number of separator characters contained within the string. Refer
     to the closely related token-function, if you do not like this behaviour. In
     some way, the split-function focuses on the separators (other than the
     token-function, which focuses on the tokens), hence its name.

     The second argument is a reference on a string-array, where the tokens will
     be stored; this array will be expanded (or shrunk) to have room for all
     tokens, if necessary.

     The first argument finally contains the text, that will be split into
     tokens. The split-function returns the number of tokens that have been
     found.

     Please see the examples below for some hints on the exact behaviour of the
     split-function and how it differs from the token-function:

  Example

  print "This program will help you to understand, how the"
  print "split()-function exactly works and how it behaves"
  print "in certain special cases."
  print
  print "Please enter a line containing tokens separated"
  print "by either ’=’ or ’-’"
  dim t$(10)
  do
    print
    input "Please enter a line: " l$
    num=split(l$,t$(),"=-")
    print num," Tokens: ";
    for a=1 to num
      if (t$(a)="") then
        print "(EMPTY)";
      else
        print t$(a);
      endif
      if (a<num) print ",";
    next a
    print
  loop

     This program prints the following output:

  Please enter a line: a
  1 Tokens: a

  Please enter a line:
  0 Tokens:

  Please enter a line: ab
  1 Tokens: ab

  Please enter a line: a=b
  2 Tokens: a,b

  Please enter a line: a-
  2 Tokens: a,(EMPTY)

  Please enter a line: a-=
  3 Tokens: a,(EMPTY),(EMPTY)

  Please enter a line: =a-
  3 Tokens: (EMPTY),a,(EMPTY)

  Please enter a line: a=-b
  3 Tokens: a,(EMPTY),b

  Please enter a line: a--b-
  4 Tokens: a,(EMPTY),b,(EMPTY)

  Please enter a line: -a==b-c==
  7 Tokens: (EMPTY),a,(EMPTY),b,c,(EMPTY),(EMPTY)

  See also

     token
       _________________________________________________________________

  Name

     sqr() - compute the square of its argument

  Synopsis

  a=sqr(b)

  Description

     The sqr-function computes the square of its numerical argument (i.e. it
     multiplies its argument with itself).

  Example

  for a=1 to 10
    print a,sqr(a),a**2
  next a

     As you may see from the output, sqr can be written as **2 (or ^2) too.

  See also

     sqrt, **, ^
       _________________________________________________________________

  Name

     sqrt() - compute the square root of its argument

  Synopsis

  to be written

  Description

     The sqrt-function computes the square root of its numerical argument.

  Example

  for a=1 to 5
    print a,sqrt(a),a**(1/2)
  next a

     As you may see from the output, sqrt can be written as **(1/2) (or ^(1/2))
     too.

  See also

     sqr, **, ^
       _________________________________________________________________

  Name

     static - preserves the value of a variable between calls to a subroutine

  Synopsis

  sub foo()

    static a

    ...

  end sub

  Description

     The static keyword can be used within subroutines to mark variables as
     static. This has two effects: First, the variable is local to the
     subroutine, i.e. its value is not know outside the subroutine (this is the
     effect of the local keyword). Second, the static-keyword arranges things, so
     that the variable keeps its value between invocations of the subroutine
     (this is different from the local-keyword).

  Example

  foo()
  foo()
  foo()

  sub foo()
    static a
    local b
    a=a+1
    b=b+1
    print a,b
  end sub

     This program shows the difference between static and local variables within
     a subroutine; it produces this output:

  1 1
  2 1
  3 1

     The output shows, that the static variable a keeps its value between
     subroutine calls, whereas b is initialized with the value 0 at every call to
     the subroutine foo.

  See also

     sub, local
       _________________________________________________________________

  Name

     step - specifies the increment step in a for-loop

  Synopsis

  for a=1 to 10 step 3
    ...
  next a

  Description

     Specify, by which amount the loop-variable of a for-loop will be incremented
     at each step.

     The step (as well as the lower and upper bound) are computed anew in each
     step; this is not common, but possible, as the example below demonstrates.

  Example

  for x=1 to 1000 step y
    y=x+y
    print x," ",y," ";
  next x
  print

     This program computes the fibonacci numbers between 1 and 1000.

  See also

     for
       _________________________________________________________________

  Name

     str$() - convert a number into a string

  Synopsis

  a$=str$(a)
  b$=str$(x,"##.###")
  b$=str$(x,"###,###.##")
  b$=str$(x,"###,###.##","_.")

  Description

     The str$-function accepts a numeric argument and returns it as a string.
     This conversion between number and string can be controlled with the
     optional third argument (the format argument). See the following table of
     examples to learn about valid values of this argument. Note, that those
     examples fall in one of two categories: C-style and basic-style; the first 4
     examples in the table below are C-style, the rest of the examples are
     basic-style. For more information on the C-style formats, you may refer to
     your favorite documentation on the C programming language. The basic-style
     formats are much simpler, they just depict the desired output, marking
     digits with ’#’; groups of (usually three) digits may be separated with
     colons (’,’), the decimal dot must be marked by a literal dot (’.’).
     Moreover these characters (colons and dot) may be replaced by other
     characters to satisfy the needs of non-english (e.g. german) languages; see
     the examples below.

     Note, that for clarity, each space in the result has been replaced by the
     letter ’x’, because it would be hard to figure out, how many spaces are
     produced exactly otherwise.

     Table 6.2. Examples for the format argument
     Example string Result for converting 1000*pi Description
     %2.5f 3141.59265 The ’2’ determines the minimum length of the output; but if
     needed (as in the example) the output can be longer. The ’5’ is the number
     of digits after the decimal point.
     %12.5f xx3141.59265 Two spaces (which appear as ’x’) are added to pad the
     output to the requested length of 12 characters.
     %012.5g 0000003141.6 The ’g’ requests, that the precision (’5’) specifies
     the overall number of digits (before and after the decimal point).
     %-12.5f 3141.59265xx The ’-’ requests the output to be left-centered
     (therefor the filling space appears at the right).
     #####.## x3141.59 Each ’#’ specifies a digit (either before or after the
     dot), the ’.’ specifies the position of the dot. As 1000*pi does not have
     enough digits, the 5 requested digits before the dot are filled up with a
     space (which shows up as an ’x’).
     ##,###.## x3,141.59 Nearly the same as above, but the colon from the format
     shows up within the result.
     ##,###.## and an additional argument of ".," x3.141,59 Similar to the
     example above, but colon and dot are replaced with dot and colon
     respectively.
     ##,###.## and an additional argument of "_," x3_141,59 Similar to the
     example above, but colon and dot are replaced with underscore and colon
     respectively.
     ##### x3142 The format string does not contain a dot, and therefore the
     result does not have any fractional digits.
     ##.### ##.### As 1000*pi has 4 digits in front of the decimal dot and the
     format only specifies 2, yabasic does not know what to do; therefore it
     chooses just to reproduce the format string.

  Example

  do
    input "Please enter a format string: " f$
    a$=str$(1000*pi,f$)
    for a=1 to len(a$)
      if (mid$(a$,a,1)=" ") mid$(a$,a,1)="x"
    next a
    print a$
  loop

     This is the program, that has been used to get the results shown in the
     table above.

  See also

     print, using
       _________________________________________________________________

  Name

     sub - declare a user defined subroutine

  Synopsis

  foo(2,"hello")

  ...

  sub foo(bar,baz$)
    ...
    return qux
    ...
  end sub

  Description

     The sub-keyword starts the definition of a user defined subroutine. With
     user defined subroutines you are able to somewhat extend yabasic with your
     own commands or functions. A subroutine accepts arguments (numbers or
     strings) and returns a number or a string (however, you are not required to
     assign the value returned to a variable).

     The name of the subroutine follows after the keyword sub. If the name (in
     the synopsis: foo) ends on a ’$’, the subroutine should return a string
     (with the return-statement), otherwise a number.

     After the name of the subroutine yabasic requires a pair of braces; within
     those braces you may specify a list of parameters, for which values can (but
     need not) be included when calling the subroutine. If you omit one of those
     parameters when calling such a subroutine, it assumes the value zero (for
     numeric parameters) or the empty string (for string-parameters). However
     from the special variable numparams you may find out, how many arguments
     have really been passed when calling the subroutine.

     Parameters of a subroutine are always local variables (see the keyword local
     for more explanation).

     From within the subroutine you may return any time with the keyword return;
     along with the return-keyword you may specify the return value. Note that
     more than one return is allowed within a single subroutine.

     Finally, the keyword end sub ends the subroutine definition. Note, that the
     definition of a subroutine need not appear within the program before the
     first call to this sub.

  Note

     As braces have two uses in yabasic (i.e. for supplying arguments to a
     subroutine as well as to list the indices of an array). yabasic can not tell
     apart an array from a subroutine with the same name. Therefore you cannot
     define a subroutine with the same name as an array !

  Example

  p=2
  do
    if (is_prime(p)) print p
    p=p+1
  loop

  sub is_prime(a)
    local b
    for b=2 to sqrt(a)
      if (frac(a/b)=0) return false
    next b
    return true
  end sub

     This example is not the recommended way to compute prime numbers. However it
     gives a nice demonstration of using a subroutine.

  See also

     local, static, peek
       _________________________________________________________________

  Name

     switch - select one of many alternatives depending on a value

  Synopsis

  switch a
    case 1
    case 2
    ...
  end switch

  ...

  switch a$
    case "a"
    case "b"
  end switch

  Description

     The switch-statement selects one of many codepaths depending on a numerical
     or string expression. I.e. it takes an expression (either numeric or string)
     and compares it with a series of values, each wrapped within a case-clause.
     If the expression equals the value given in a case-clause, the subsequent
     statements are executed.

     The default-clause allows to specify commands, which should be executed, if
     none of case-clauses matches.

     Note, that many case-clauses might be clustered (e.g. case "a":case "b":case
     "c"). Or put another way: You need a break-statement at the end of a
     case-branch, if you do not want to run into the next case.

  Example

  input "Please enter a single digit: " n
  switch n
    case 0:print "zero":break
    case 1:print "one":break
    case 2:print "two":break
    case 3:print "three":break
    case 4:print "four":break
    case 5:case 6: case 7:case 8:case 9
      print "Much !":break
    default:print "Hey ! That was more than a single digit !"
  end switch

     This example translates a single digit into a string; note, how the cases 5
     to 7 are clustered.

  See also

     switch, case, break
       _________________________________________________________________

  Name

     system$() - hand a statement over to your operating system and return its
     output

  Synopsis

  print system$("dir")

  Description

     The system$-command accepts a single string argument, specifying a command,
     that can be found and executed by your operating system. It returns the
     output of this command as one big string.

  Example

  input "Please enter the name of a directory: " d$
  print
  print "This is the contents of the ’"+d$+"’:"
  print system$("dir "+d$)

     This example lists the contents of a directory, employing the dir-command
     (which is about the only program, that is known under Unix as well as
     Windows).

  See also

     system
       _________________________________________________________________

  Name

     system() - hand a statement over to your operating system and return its
     exitcode

  Synopsis

  ret=system("foo")
  system("bar")

  Description

     The system-command accepts a single string argument, which specifies a
     command to be executed. The function will return the exitcode of the
     command; its output (if any) will be lost.

  Example

  print "Please enter the name of the file, that should be deleted."
  input f$
  if (system("rm "+f$+" >/dev/null 2>&1")) then
    print "Error !"
  else
    print "okay."
  endif

     This program is Unix-specific: It uses the Unix-command rm to remove a file.

  See also

     system$

  T

     tan() - return the tangent of its argument
     tell - get the current position within an open file
     text - write text into your graphic-window
     then - tell the long from the short form of the if-statement
     time$ - return a string containing the current time
     to - this keyword appears as part of other statements
     token() - split a string into multiple strings
     triangle - draw a triangle
     trim$() - remove leading and trailing spaces from its argument
     true - a constant with the value of 1

  Name

     tan() - return the tangent of its argument

  Synopsis

  foo=tan(bar)

  Description

     The tan-function computes the tangent of its arguments (which should be
     specified in radians).

  Example

  for a=0 to 45
    print tan(a*pi/180)
  next a

     This example simply prints the tangent of all angles between 0 and 45
     degrees.

  See also

     atan, sin
       _________________________________________________________________

  Name

     tell - get the current position within an open file

  Synopsis

  open #1,"foo"
    ...
  position=tell(#1)

  Description

     The tell-function requires the number of an open file as an argument. It
     returns the position (counted in bytes, starting from the beginning of the
     file) where the next read will start.

  Example

  open #1,"foo","w"
  print #1 "Hello World !"
  close #1

  open #1,"foo"
  seek #1,0,"end"
  print tell(#1)
  close 1

     This example (mis)uses tell to get the size of the file. The seek positions
     the file pointer at the end of the file, therefor the call to tell returns
     the total length of the file.

  See also

     tell, open
       _________________________________________________________________

  Name

     text - write text into your graphic-window

  Synopsis

  text x,y,"foo"
  text x,y,"foo","lb"
  text x,y,"foo","cc","font"
  text x,y,"foo","font","rt"

  Description

     The text-commands displays a text-string (the third argument) at the given
     position (the first two arguments) within an already opened window. The font
     to be used can be optionally specified as either the fourth or fifth
     argument ("font" in the example above). A font specified this way will also
     be used for any subsequent text-commands, as long as they do not specify a
     font themselves.

     The fourth or fifth optional argument ("lb" in the example above) can be
     used to specify the alignment of the text with respect to the specified
     position. This argument is always two characters long: The first character
     specifies the horizontal alignment and can be either l, r or c, which stand
     for left, right or center. The second character specifies the vertical
     alignment and can be one of t, b or c, which stand for top, bottom or center
     respectively. If you omit this alignment argument, the default "lb" applies;
     however this default may be changed with poke "textalign","xx"

  Example

  open window 500,200
  clear screen
  data "lt","lc","lb","ct","cc","cb","rt","rc","rb"
  for a=1 to 9
    read align$
    print "Alignment: ",align$
    line 50*a-15,100,50*a+15,100
    line 50*a,85,50*a,115
    text 50*a,100,"Test",align$
    inkey$
  next a

     This program draws nine crosses and writes the same text at each; however it
     goes through all possible nine alignment strings, showing their effect.

  See also

     open window, peek, poke
       _________________________________________________________________

  Name

     then - tell the long from the short form of the if-statement

  Synopsis

  if (a<b) then
    ...
  endif

  Description

     The keyword then is part of the if-statement; please see there for further
     explanations. However, not every if-statement requires the keyword then: If
     the keyword then is present, the if-clause may extend over more than one
     line, and the keyword endif is required to end it. If the keyword then is
     not present, the if-statement extends up to the end of the line, and any
     endif would be an error.

  Example

  if (1<2) then
    print "Hello ";
  endif

  if (2<3) print "world"
  if (2<1)
    print "!"

     This example prints Hello world. Note, that no exclamation mark (!) is
     printed, which might come as a surprise and may be changed in future
     versions of yabasic.

  See also

     if
       _________________________________________________________________

  Name

     time$ - return a string containing the current time

  Synopsis

  print time$
  print time$()

  Description

     The time$ function returns the current time in four fields separated by
     hyphens ’-’. The fields are:

       * The current hour in the range from 0 to 23, padded with zeroes (e.g. 00
         or 04) to a length of two characters.
       * The number of minutes, padded with zeroes.
       * The number of seconds, padded with zeroes.
       * The number of seconds, that have elapsed since the program has been
         started. This value increases as long as your program runs and is
         therefore unbound and not padded with zeroes.

     At the time of writing this documentation, time$ returns 22-58-53-0. Note,
     that the first three of the four fields returned by time$ have a fixed
     width; therefore it is easy to extract some fields with the usual
     string-functions mid$ (and others).

  Example

  print "Hello it is ",time$
  print "An empty for-loop with ten million iterations takes ";
  s=val(mid$(time$,10))
  for a=1 to 10000000:next a
  e=val(mid$(time$,10))
  print e-s," seconds"

     This program benchmarks the for-loop and uses the fourth field of the string
     returned by time$.

  See also

     date
       _________________________________________________________________

  Name

     to - this keyword appears as part of other statements

  Synopsis

  for a=1 to 100 step 2
    ...
  next a

  line x,y to a,b

  Description

     The to-keyword serves two purposes (which are not related at all):
       * within for-statements, to specify the upper bound of the loop.
       * Within any graphical command (e.g. line), that requires two points (i.e.
         four numbers) as arguments, a comma ’,’ might be replaced with the
         keyword to. I.e. instead of 100,100,200,200 you may write 100,100 to
         200,200 in such commands.

  Example

     Please see the command listed under "See also" for examples.

  See also

     for, line, rectangle
       _________________________________________________________________

  Name

     token() - split a string into multiple strings

  Synopsis

  dim w$(10)
  ...
  num=token(a$,w$())
  num=token(a$,w$(),s$)

  Description

     The token-function accepts a string (containing the text to be split), a
     reference to a string-array (which will receive the resulting strings, i.e.
     the tokens) and an optional string (with a set of characters, at which to
     split, i.e. the delimiters).

     The token-function regards its first argument as a list of tokens separated
     by delimiters and it will store the list of tokens within the
     array-reference that has been supplied. Note, that the array, which is
     passed as a reference (w$() in the synopsis), will be resized accordingly,
     so that you don’t have to figure out the number of tokens in advance. The
     element at position zero (i.e. w$(0)) will not be used.

     Normally (i.e. if you omit the third, the delimiter-argument) the function
     will regard space or tab as delimiters for tokens; however by supplying a
     third argument, you may split at any single of the characters within this
     string. E.g. if you supply ":;" as the third argument, then colon (:) or
     semicolon (;) will delimit tokens.

     Note, that token will never produce empty tokens, even if two or more
     separators follow in sequence. Refer to the closely related split-function,
     if you do not like this behaviour. In some way, the token-function focuses
     on the tokens and not on the separators (other than the split-function,
     which focuses on the separators).

     The second argument is a reference on a string-array, where the tokens will
     be stored; this array will be expanded (or shrunk) as necessary to have
     room for all tokens.

     The first argument finally contains the text, that will be split into
     tokens. The token-function returns the number of tokens, that have been
     found.

     Please see the examples below for some hints on the exact behaviour of the
     token-function and how it differs from the split-function:

  Example

  print "This program will help you to understand, how the"
  print "token()-function exactly works and how it behaves"
  print "in certain special cases."
  print
  print "Please enter a line containing tokens separated"
  print "by either ’=’ or ’-’"
  dim t$(10)
  do
    print
    input "Please enter a line: " l$
    num=token(l$,t$(),"=-")
    print num," Tokens: ";
    for a=1 to num
      if (t$(a)="") then
        print "(EMPTY)";
      else
        print t$(a);
      endif
      if (a<num) print ",";
    next a
    print
  loop

     This program prints the following output:

  Please enter a line: a
  1 Tokens: a

  Please enter a line:
  0 Tokens:

  Please enter a line: ab
  1 Tokens: ab

  Please enter a line: a=b
  2 Tokens: a,b

  Please enter a line: a-
  1 Tokens: a

  Please enter a line: a-=
  1 Tokens: a

  Please enter a line: =a-
  1 Tokens: a

  Please enter a line: a=-b
  2 Tokens: a,b

  Please enter a line: a--b-
  2 Tokens: a,b

  Please enter a line: -a==b-c==
  3 Tokens: a,b,c

  See also

     split
       _________________________________________________________________

  Name

     triangle - draw a triangle

  Synopsis

  open window 100,100
  triangle 100,100,50,50,100,50
  fill triangle 50,100,100,50,200,200
  clear fill triangle 20,20,10,10,200,200

  Description

     The triangle-command draws a triangle; it requires 6 parameters: The x- and
     y-coordinates of the three points making up the triangle. With the optional
     keywords clear and fill (which may appear both and in any sequence) the
     triangle can be cleared and filled respectively.

  Example

  open window 200,200
  do
    phi=phi+0.2
    i=i+2
    color mod(i,255),mod(85+2*i,255),mod(170+3*i,255)
    dx=100*sin(phi):dy=20*cos(phi)
    fill triangle 100+20*sin(phi),100+20*cos(phi),100-20*sin(phi),100-20*cos(phi)
  ,100-80*cos(phi),100+80*sin(phi)
    sleep 0.1
  loop

     This example draws a colored triangles until you get exhausted.

  See also

     open window, open printer, line, circle, rectangle
       _________________________________________________________________

  Name

     trim$() - remove leading and trailing spaces from its argument

  Synopsis

  a$=trim$(b$)

  Description

     The trim$-function removes all whitespace from the left and from the right
     end of a string and returns the result. Calling trim$ is equivalent to
     calling rtrim$(ltrim$()).

  Example

  do
    input "Continue ? Please answer yes or no: " a$
    a$=lower$(trim$(a$))
    if (len(a$)>0 and a$=left$("no",len(a$)) exit
  loop

     This example asks for an answer (yes or no) and removes spaces with trim$ to
     make the comparison with the string "no" more bulletproof.

  See also

     ltrim$, rtrim$
       _________________________________________________________________

  Name

     true - a constant with the value of 1

  Synopsis

  okay=true

  Description

     The constant true can be assigned to variables which will later appear in
     conditions (e.g. an if-statement.

     true may also be written as TRUE or even TrUe.

  Example

  input "Please enter a string of all upper letters: " a$
  if (is_upper(a$)) print "Okay"

  sub is_upper(a$)
    if (a$=upper$(a$)) return true
    return false
  end sub

  See also

     false

  U

     until - end a repeat-loop
     upper$() - convert a string to upper case
     using - Specify the format for printing a number

  Name

     until - end a repeat-loop

  Synopsis

  repeat
    ...
  until (...)

  Description

     The until-keyword ends a loop, which has been introduced by the
     repeat-keyword. until requires a condition in braces (or an expression, see
     here for details) as an argument; the loop will continue until this
     condition evaluates to true.

  Example

  c=1
  s=1
  repeat
    l=c
    s=-(s+sig(s))
    c=c+1/s
    print c
  until(abs(l-c)<0.000001)

     This program calculates the sequence 1/1-1/2+1/3-1/4+1/5-1/6+1/7-1/8+ ... ;
     please let me know, if you know against which value this converges.

  See also

     repeat
       _________________________________________________________________

  Name

     upper$() - convert a string to upper case

  Synopsis

  u$=upper$(a$)

  Description

     The upper$-function accepts a single string argument and converts it to all
     upper case.

  Example

  line input "Please enter a sentence without the letter ’e’: " l$
  p=instr(upper$(l$),"E")
  if (p) then
    l$=lower$(l$)
    mid$(l$,p,1)="E"
    print "Hey, you are wrong, see here!"
    print l$
  else
    print "Thanks."
  endif

     This program asks for a sentence and marks the first (if any) occurrence of
     the letter ’e’ by converting it to upper case (in contrast to the rest of the
     sentence, which is converted to lower case).

  See also

     lower$
       _________________________________________________________________

  Name

     using - Specify the format for printing a number

  Synopsis

  print a using "##.###"
  print a using("##.###",",.")

  Description

     The using-keyword may appear as part of the print-statement and specifies
     the format (e.g. the number of digits before and after the decimal dot),
     which should be used to print the number.

     The possible values for the format argument ("##.###" in the synopsis above)
     are described within the entry for the str$-function; especially the second
     line in the synopsis (print a using("##.###",",.")) will become clear after
     referring to str$. In fact the using clause is closely related to the
     str$-function; the former can always be rewritten using the latter; i.e.
     print foo using bar$ is always equivalent to print str$(foo,bar$). Therefore
     you should check out str$ to learn more.

  Example

  for a=1 to 10
    print sqrt(ran(10000*a)) using "#########.#####"
  next a

     This example prints a column of square roots of random number, nicely
     aligned at the decimal dot.

  See also

     print, str$

  V

     val() - converts a string to a number

  Name

     val() - converts a string to a number

  Synopsis

  x=val(x$)

  Description

     The val-function checks, if the start of its string argument forms a
     floating point number and then returns this number. The string therefore has
     to start with digits (only whitespace in front is allowed), otherwise the
     val-function returns zero.

  Example

  input "Please enter a length, either in inches (in) or centimeters (cm) " l$
  if (right$(l$,2)="in") then
    l=val(l$)*2.51
  else
    l=val(l$)
  print "You have entered ",l,"cm."

     This example queries for a length and checks, if it has been specified in
     inches or centimeters. The length is then converted to centimeters.

  See also

     str$

  W

     wait - pause, sleep, wait for the specified number of seconds
     wend - end a while-loop
     while - start a while-loop
     window origin - move the origin of a window

  Name

     wait - pause, sleep, wait for the specified number of seconds

  Synopsis

  wait 4

  Description

     The wait-command has many different names: You may write pause, sleep or
     wait interchangeably; whatever you write, yabasic will always do exactly the
     same.

     Therefore you should refer to the entry for the pause-function for further
     information.
       _________________________________________________________________

  Name

     wend - end a while-loop

  Synopsis

  while(a<b)
    ...
  wend

  Description

     The wend-keyword marks the end of a while-loop. Please see the while-keyword
     for more details.

     wend can be written as end while or even end-while.

  Example

  line input "Please enter a sentence: " a$
  p=instr(a$,"e")
  while(p)
    mid$(a$,p,1)="E"
    p=instr(a$,"e")
  wend
  print a$

     This example reads a sentence and converts every occurrence of the letter e
     into uppercase (E).

  See also

     while (which is just the following entry).
       _________________________________________________________________

  Name

     while - start a while-loop

  Synopsis

  while(...)
    ...
  wend

  Description

     The while-keyword starts a while-loop, i.e. a loop that is executed as long
     as the condition (which is specified in braces after the keyword while)
     evaluates to true.

     Note, that the body of such a while-loop will not be executed at all, if the
     condition following the while-keyword is not true initially.

     If you want to leave the loop prematurely, you may use the break-statement.

  Example

  open #1,"foo"
  while(!eof(1))
    line input #1 a$
    print a$
  wend

     This program reads the file foo and prints it line by line.

  See also

     until, break, wend, do
       _________________________________________________________________

  Name

     origin - move the origin of a window

  Synopsis

  open window 200,200
  origin "cc"

  Description

     The origin-command applies to graphic windows and moves the origin of the
     coordinate system to one of nine point within the window. The normal
     position of the origin is in the upper left corner of the window; however in
     some cases this is inconvenient and moving the origin may save you from
     subtracting a constant offset from all of your coordinates.

     However, you may not move the origin to an arbitrary position; in horizontal
     position there are only three positions: left, center and right, which are
     decoded by the letters l, c and r. In vertical position the allowed
     positions are top, center and bottom; encoded by the letters t, c and b.
     Taking the letters together, you arrive at a string, which might be passed
     as an argument to the command; e.g. "cc" or "rt".

  Example

     100,100
  open window 200,200
  window origin "cc"
  circle 0,0,60

     This example draws a circle, centered at the center of the window.

  See also

     open window

  X

     xor() - compute the exclusive or

  Name

     xor() - compute the exclusive or

  Synopsis

  x=xor(a,b)

  Description

     The xor computes the bitwise exclusive or of its two numeric arguments. To
     understand the result, both arguments should be viewed as binary numbers
     (i.e. a series of 0 and 1); a bit of the result will then be 1, if exactly
     one argument has a 1 and the other has a 0 at this position in their binary
     representation.

     Note, that both arguments are silently converted to integer values and that
     negative numbers have their own binary representation and may lead to
     unexpected results when passed to and.

  Example

  print xor(7,4)

     This will print 3. This result is obvious, if you note, that the binary
     representation of 7 and 4 are 111 and 100 respectively; this will yield 011
     in binary representation or 2 as decimal.

     The eor-function is the same as the xor function; both are synonymous;
     however they have each their own description, so you may check out the entry
     of eor for a slightly different view.

  See also

     and, or, eor, not

  Special characters

     # - either a comment or a marker for a file-number
     // - starts a comment
     @ - synonymous to at
     : - separate commands from each other
     ; - suppress the implicit newline after a print-statement
     ** or ^ - raise its first argument to the power of its second

  Name

     # - either a comment or a marker for a file-number

  Synopsis

  # This is a comment, but the line below not !
  open #1,"foo"

  Description

     The hash (’#’) has two totally unrelated uses:
       * A hash might appear in commands related with file-io. yabasic uses
         simple numbers to refer to open files (within input, print, peek or
         eof). In those commands the hash may precede the number, which species
         the file. Please see those commands for further information and
         examples; the rest of this entry is about the second use (as a comment).
       * As the very first character within a line, a hash introduces comments
         (similar to rem).

     ’#’ as a comment is common in most scripting languages and has a special use
     under Unix: If the very first line of any Unix-program begins with the
     character sequence ’#!’ ("she-bang", no spaces allowed), the rest of the
     line is taken as the program that should be used to execute the script. I.e.
     if your yabasic-program starts with ’#!/usr/local/bin/yabasic’, the program
     /usr/local/bin/yabasic will be invoked to execute the rest of the program.
     As a remark for windows-users: This mechanism ensures, that yabasic will be
     invoked to execute your program; the ending of the file (e.g. .yab) will be
     ignored by Unix.

  Example

  # This line is a valid comment
  print "Hello " : # But this is a syntax error, because
  print "World!" : # the hash is not the first character !

     Note, that this example will produce a syntax error and is not a valid
     program !

  See also

     input, print, peek or eof, //, rem
       _________________________________________________________________

  Name

     // - starts a comment

  Synopsis

  //  This is a comment !

  Description

     The double-slash (’//’) is (besides REM and ’#’) the third way to start a
     comment. ’//’ is the latest and greatest in the field of commenting and
     allows yabasic to catch up with such cool languages like C++ and Java.

  Example

  // Another comment.
  print "Hello world !" // Another comment

     Unlike the example given for ’#’ this example is syntactically correct and
     will not produce an error.

  See also

     #, rem
       _________________________________________________________________

  Name

     @ - synonymous to at

  Synopsis

  clear screen
  ...
  print @(a,b)

  Description

     As ’@’ is simply a synonym for at, please see at for further information.

  See also

     at
       _________________________________________________________________

  Name

     : - separate commands from each other

  Synopsis

  print "Hello ":print "World"

  Description

     The colon (’:’) separates multiple commands on a single line.

     The colon and the newline-character have mostly the same effect, only that
     the latter, well, starts a new line too. The only other difference is their
     effect within the (so-called) short if, which is an if-statement without the
     keyword then. Please see the entry for if for more details.

  Example

  if (a<10) print "Hello ":print "World !"

     This example demonstrates the difference between colon and newline as
     described above.

  See also

     if
       _________________________________________________________________

  Name

     ; - suppress the implicit newline after a print-statement

  Synopsis

  print "foo",bar;

  Description

     The semicolon (’;’) may only appear at the last position within a
     print-statement. It suppresses the implicit newline, which yabasic normally
     adds after each print-statement.

     Put another way: Normally the output of each print-statement appears on a
     line by itself. If you rather want the output of many print-statements to
     appear on a single line, you should end the print-statement with a
     semicolon.

  Example

  print "Hello ";:print "World !"

     This example prints Hello World ! in a single line.

  See also

     print
       _________________________________________________________________

  Name

     ** or ^ - raise its first argument to the power of its second

  Synopsis

  print 2**b
  print 3^4

  Description

     ** (or ^, which is an exact synonym), is the arithmetic operator of
     exponentiation; it requires one number to its left and a second one to its
     right; ** then raises the first argument to the power of the second and
     returns the result. The result will only be computed if it yields a real
     number (as opposed to a complex number); this means, that the power can not
     be computed, if the first argument is negative and the second one is
     fractional. On the other hand, the second argument can be fractional, if the
     first one ist positive; this means, that ** may be used to compute arbitrary
     roots: e.g. x**0.5 computes the square root of x.

  Example

  print 2**0.5

  See also

     sqrt

  Reserved Words

     Here is a list of all reserved words in yabasic. Please make sure, that you
     do not try to use one of them as the name of a variable or subroutine. Or,
     the other way around: If you get some mysterious error from yabasic and you
     just can’t figure out why, then you might be using one of the reserved words
     below, without knowing.

     Anyway, here is the list:
     ABS       ACOS          AND      ARRAYDIM   ARRAYDIMENSION
     ARRAYSIZE AS            ASC      ASIN       AT
     ATAN      BEEP          BELL     BIN$       BIND
     BITBLIT   BITBLIT$      BITBLT   BITBLT$    BOX
     BREAK     CASE          CHR$     CIRCLE     CLEAR
     CLOSE     COLOR         COLOUR   COMPILE    CONTINUE
     COS       CURVE         DATA     DATE$      DEC
     DEFAULT   DIM           DO       DOT        ELSE
     ELSEIF    ELSIF         END      ENDIF      EOF
     EOR       ERROR         EXECUTE  EXECUTE$   EXIT
     EXP       EXPORT        FI       FILL       FILLED
     FOR       FRAC          GETBIT$  GETSCREEN$ GLOB
     GOSUB     GOTO          HEX$     IF         INKEY$
     INPUT     INSTR         INT      INTERRUPT  LABEL
     LEFT$     LEN           LET      LINE       LOCAL
     LOG       LOOP          LOWER$   LTRIM$     MAX
     MID$      MIN           MOD      MOUSEB     MOUSEBUTTON
     MOUSEMOD  MOUSEMODIFIER MOUSEX   MOUSEY     NEW
     NEXT      NOT           NUMPARAM ON         OPEN
     OR        ORIGIN        PAUSE    PEEK       PEEK$
     POKE      PRINT         PRINTER  PUTBIT     PUTSCREEN
     RAN       READ          READING  RECT       RECTANGLE
     REDIM     REPEAT        RESTORE  RETURN     REVERSE
     RIGHT$    RINSTR        RTRIM$   SCREEN     SEEK
     SIG       SIN           SLEEP    SPLIT      SPLIT$
     SQR       SQRT          STATIC   STEP       STR$
     SUB       SUBROUTINE    SWITCH   SYSTEM     SYSTEM$
     TAN       TELL          TEXT     THEN       TIME$
     TO        TOKEN         TOKEN$   TRIANGLE   TRIM$
     UNTIL     UPPER$        USING    VAL        WAIT
     WEND      WHILE         WINDOW   WRITING    XOR

     Please see here for explanations on how to use these words in yabasic.

  Chapter 7. A grab-bag of some general concepts and terms

     Logical shortcuts
     Conditions and expressions
     References on arrays
     Specifying Filenames under Windows
     Escape-sequences
     Creating a standalone program from your yabasic-program

     This chapter presents some general concepts and terms, which deserve a
     description on their own, but are not associated with a single command or
     function in yabasic. Most of these topics do not lend themselves to be read
     alone, rather they might be read (or skimmed) as background material if an
     entry from the alphabetical list of commands refers to them.

  Logical shortcuts

     Logical shortcuts are no special language construct and there is no keyword
     for them; they are just a way to evaluate logical expressions. Logical
     expressions (i.e. a series of conditions or comparisons joined by and or or)
     are only evaluated until the final result of the expression can be
     determined. An example:
  if (a<>0 and b/a>2) print "b is at least twice as big as a"

     The logical expression a<>0 and b/a>2 consists of two comparisons, both of
     which must be true, if the print statement should be executed. Now, if the
     first comparison (a<>0) is false, the whole logical expression can never be
     true and the second comparison (b/a>2) need not be evaluated.

     This is exactly, how yabasic behaves: The evaluation of a composed logical
     expressions is terminated immediately, as soon as the final result can be
     deduced from the already evaluated parts.

     In practice, this has the following consequences:
       * If two or more comparisons are joined with and and one comparison
         results in false, the logical expression is evaluated no further and the
         overall result is false.
       * If two or more comparisons are joined with or and one comparison results
         in true, the logical expression is evaluated no further and the result
         is true.

     "Nice, but whats this good for ?", I hear you say. Well, just have another
     look at the example, especially the second comparison (b/a>2); dividing b by
     a is potentially hazardous: If a equals zero, the expression will cause an
     error and your program will terminate. To avoid this, the first part of the
     comparison (a<>0) checks, if the second one can be evaluated without risk.
     This pre-checking is the most common usage and primary motivation for
     logical shortcuts (and the reason why most programming languages implement
     them).

  Conditions and expressions

     Well, bottomline there is no difference or distinction between conditions
     and expressions, at least as yabasic is concerned. So you may assign the
     result of comparisons to variables or use an arithmetic expression or a
     simple variable within a condition (e.g. within an if-statement). So the
     constructs shown in the example below are all totally valid:
  input "Please enter a number between 1 and 10: " a

  rem   Assigning the result of a comparison to a variable
  okay=a>=1 and a<=10

  rem   Use a variable within an if-statement
  if (not okay) error "Wrong, wrong !"

     So conditions and expressions are really the same thing (at least as long as
     yabasic is concerned). Therefore the terms conditions and expression can
     really be used interchangeably, at least in theory. In reality the term
     condition is used in connection with if or while whereas the term expression
     tends to be used more often within arithmetic context.

  References on arrays

     References on arrays are the only way to refer to an array as a whole and to
     pass it to subroutines or functions like arraydim or arraysize. Whereas (for
     example) a(2) designates the second element of the array a, a() (with empty
     braces) refers to the array a itself. a() is called an array reference.

     If you pass an array reference to one of your own subroutines, you need to
     be aware, that the subroutine will be able to modify the array you have
     passed in. So passing an array reference does not create a copy of the
     array; this has some interesting consequences:
       * Speed and space: Creating a copy of an array would be a time (and
         resource) consuming operation; passing just a reference is cheap and
         fast.
       * Returning many values: A subroutine, that wants to give back more than
         one value, may require an array reference among its arguments and then
         store its many return values within this array. This is the only way to
         return more than one value from a subroutine.

  Specifying Filenames under Windows

     As you probably know, windows uses the character ’\’ to separate the
     directories within a pathname; an example would be C:\yabasic\yabasic.exe
     (the usual location of the yabasic executable). However, the very same
     character ’\’ is used to construct escape sequences, not only in yabasic but
     in most other programming languages.

     Therefore the string "C:\t.dat" does not specify the file t.dat within the
     directory C:; this is because the sequence ’\t’ is translated into the
     tab-character. To specify this filename, you need to use the string
     "C:\\t.dat" (note the double slash ’\\’).

  Escape-sequences

     Escape-sequences are the preferred way of specifying ’special’ characters.
     They are introduced by the ’\’-character and followed by one of a few
     regular letters, e.g. ’\n’ or ’\r’ (see the table below).

     Escape-sequences may occur within any string at any position; they are
     replaced at parsetime (opposed to runtime), i.e. as soon as yabasic
     discovers the string, with their corresponding special character. As a
     consequence of this len("\a") returns 1, because yabasic replaces "\a" with
     the matching special character just before the program executes.

     Table 7.1. Escape sequences
     Escape Sequence  Matching special character
     \n              newline
     \t              tabulator
     \v              vertical tabulator
     \b              backspace
     \r              carriage return
     \f              formfeed
     \a              alert (i.e. a beeping sound)
     \\              backslash
     \’              single quote
     \"              double quote
     \xHEX           chr$(HEX) (see below)

     Note, that an escape sequences of the form \xHEX allows to encode arbitrary
     characters as long as you know their position (as a hex-number) within the
     ascii-charset: For example \x012 is transformed into the character chr$(18)
     (or chr$(dec("12",16)). Note that \x requires a hexa-decimal number (and the
     hexa-decimal string "12" corresponds to the decimal number 18).

  Creating a standalone program from your yabasic-program

     Creating a standalone-program from the command line
     Creating a standalone-program from within your program
     Downsides of creating a standalone program
     See also

  Note

     The bind-feature, which is described below, is at an experimental stage
     right now. It works (at least for me !) under Windows and Linux, but I
     cannot even promise it for other variants of Unix. However, if it does not
     work for your Unix, I will at least try to make it work, if you give me
     sufficient information of your system.

     Sometimes you may want to give one of your yabasic-programs to other people.
     However, what if those other people do not have yabasic installed ? In that
     case you may create a standalone-program from your yabasic-program, i.e. an
     executable, that may be executed on its own, standalone, even (and
     especially !) on computers, that do not have yabasic installed. Having
     created a standalone program, you may pass it around like any other program
     (e.g. one written in C) and you can be sure that your program will execute
     right away.

     Such a standalone-program is simply created by copying the full
     yabasic-interpreter and your yabasic-program (plus all the libraries it does
     import) together into a single, new program, whose name might be chosen at
     will (under windows of course it should have the ending .exe). If you decide
     to create a standalone-program, there are three bits in yabasic, that you
     may use:
       * The bind-command, which does the actual job of creating the standalone
         program from the yabasic-interpreter and your program.
       * The command-line Option -bind (available under windows and Unix), which
         does the same from the command-line.
       * The special peek("isbound"), which may be used to check, if the
         yabasic-program containing this peek is bound to the interpreter as part
         of a standalone program.

     With these bits you know enough to create a standalone-program. Actually
     there are two ways to do this: on the command line and from within your
     program.

  Creating a standalone-program from the command line

     Let’s say you have the following very simple program within the file
     foo.yab:
  print "Hello World !"

     Normally you would start this yabasic-program by typing yabasic foo.yab and
     as a result the string Hello World ! would appear on your screen. However,
     to create a standalone-program from foo.yab you would type:

     yabasic -bind foo.exe foo.yab

     This command does not execute your program foo.yab but rather create a
     standalone-program foo.exe. Note: under Unix you would probably name the
     standalone program foo or such, omitting the windows-specific ending .exe.

     Yabasic will confirm by printing something like: ---Info: Successfully bound
     ’yabasic’ and ’foo.yab’ into ’foo.exe’.

     After that you will find a program foo.exe (which must be made executable
     with the chmod-command under Unix first). Now, executing this program
     foo.exe (or foo under Unix) will produce the output Hello World !.

     This newly created program foo.exe might be passed around to anyone, even if
     he does not have yabasic installed.

  Creating a standalone-program from within your program

     It is possible to write a yabasic-program, that binds itself to the
     yabasic-interpreter. Here is an example:
  if (!peek("isbound")) then
    bind "foo"
    print "Successfully created the standalone executable ’foo’ !"
    exit
  endif

  print "Hello World !"

     If you run this program (which may be saved in the file foo.yab) via yabasic
     foo.yab, the peek("isbound") in the first line will check, if the program is
     already part of a standalone-program. If not (i.e. if the
     yabasic-interpreter and the yabasic-program are separate files) the
     bind-command will create a standalone program foo containing both. As a
     result you would see the output Successfully created the standalone
     executable ’foo’ !. Note: Under Windows you would probably choose the
     filename foo.exe.

     Now, if you run this standalone executable foo (or foo.exe), the very same
     yabasic-program that is shown above will be executed again. However, this
     time the peek("isbound") will return TRUE and therefore the condition of the
     if-statement is false and the three lines after then are not executed.
     Rather the last print-statement will run, and you will see the output Hello
     World !.

     That way a yabasic-program may turn itself into a standalone-program.

  Downsides of creating a standalone program

     Now, before you go out and turn all your yabasic-programs into standalone
     programs, please take a second to consider the downsides of doing so:
       * The new standalone program will be at least as big as the interpreter
         itself, so you need to pass a few hundred kilobytes around, just to save
         people from having to install yabasic themselves.
       * There is no easy way to extract your yabasic-program from within the
         standalone program: If you ever want to change it, you need to have it
         around separately.
       * If a new version of yabasic becomes available, again you need to
         recreate all of your standalone programs to take advantage of bugfixes
         and improvements.

     So, being able to create a standalone program is certainly a good thing, but
     certainly not a silver bullet.

  See also

     The bind-command, the peek-function and the command line options for Unix and
     Windows.

  Chapter 8. A few example programs

     A very simple program
     The demo of yabasic

  A very simple program

     The program below is a very simple program:
  repeat
    input "Please enter the first number, to add " a
    input "Please enter the second number, to add " b
    print a+b
  until(a=0 and b=0)

     This program requests two numbers, which it than adds. The process is
     repeated until you enter zero (or nothing) twice.

  The demo of yabasic

     The listing below is the demo of yabasic. Note, that parts of this demo have
     been written before some of the more advanced features (e.g subroutines) of
     yabasic have been implemented. So please do not take this as a particular
     good example of yabasic-code.
  //
  //      This program demos yabasic
  //

  //      Check, if screen is large enough
  clear screen
  sw=peek("screenwidth"):sh=peek("screenheight")
  if (sw<78 or sh<24) then
    print
    print "  Sorry, but your screen is to small to run this demo !"
    print
    end
  endif
  sw=78:sh=24

  //  Initialize everything
  restore mmdata
  read mmnum:dim mmtext$(mmnum)
  for a=1 to mmnum:read mmtext$(a):next a

  //  Main loop selection of demo
  ysel=1
  label mainloop
  clear screen
  print colour("cyan","magenta") at(7,2) "################################"
  print colour("cyan","magenta") at(7,3) "################################"
  print colour("cyan","magenta") at(7,4) "################################"
  print colour("yellow","blue") at(8,3) " This is the demo for yabasic "
  yoff=7
  for a=1 to mmnum
    if (a=mmnum) then ydisp=1:else ydisp=0:fi
    if (a=ysel) then
      print colour("blue","green") at(5,yoff+ydisp+a) mmtext$(a);
    else
      print at(5,yoff+ydisp+a) mmtext$(a);
    endif
  next a
  print at(3,sh-3) "Move selection with CURSOR KEYS (or u and d),"
  print at(3,sh-2) "Press RETURN or SPACE to choose, ESC to quit."

  do    // loop for keys pressed
    rev=1
    do    // loop for blinking
      k$=inkey$(0.4)
      if (k$="") then
        if (ysel=mmnum) then
          if (rev=1) then
            print colour("blue","green") at(5,yoff+mmnum+1) mmtext$(mmnum);
            rev=0
          else
            print colour("yellow","red") at(5,yoff+mmnum+1) mmtext$(mmnum);
            rev=1
          endif
        endif
      else    // key has been pressed, leave loop
        break
      endif
    loop    // loop for blinking

    yalt=ysel
    if (k$="up" or k$="u") then
      if (ysel=1) then ysel=mmnum else ysel=ysel-1 fi
      redraw():heal():continue
    fi
    if (k$="down" or k$="d") then
      if (ysel=mmnum) then ysel=1 else ysel=ysel+1 fi
      redraw():heal():continue
    fi
    if (k$=" " or k$="enter" or k$="right") then
      on ysel gosub overview,bitmap,tetraeder,endit
      goto mainloop
    fi
    if (k$="esc") then
      endit()
    fi
    beep
    print at(3,sh-5) "Invalid key: ",k$,"         "
  loop    // loop for keys pressed

  //  redraw line
  sub redraw()
    if (yalt=mmnum) then ydisp=1:else ydisp=0:fi
    print at(5,yoff+yalt+ydisp) mmtext$(yalt);
    if (ysel=mmnum) then ydisp=1:else ydisp=0:fi
    print colour("blue","green") at(5,yoff+ysel+ydisp) mmtext$(ysel);
    return
  end sub

  //  erase a line
  sub heal()
    print at(3,sh-5) "                                                       "
    return
  end sub

  //  Go here to exit
  label endit
    print at(3,sh-8) "Hope you liked it ...\n   ";
    exit
  return

  //  Present a short overview
  label overview
    clear screen
    print
    print "  Yabasic is a quite traditional basic: It comes with"
    print "  print, input, for-next-loops, goto, gosub, while and"
    print "  repeat. It has user defined procedures and libraries,"
    print "  however, it is not object oriented.\n"
    print "  Yabasic makes it easy to open a window, draw lines"
    print "  and print the resulting picture.\n"
    print "  Yabasic programs are interpreted and run under Unix"
    print "  and Windows. The Yabasic interpreter (around 200K)"
    print "  and any Yabasic program can be glued together to"
    print "  form a standalone executable.\n"
    print "  Yabasic is free software, i.e. subject to the"
    print "  GNU copyright.\n"
    print "\n\n\n  While you read this, I am calculating prime numbers,\n"
    print "  Press any key to return to main menu ..."
    can=1
    print at(6,17) "This is a prime number: "
    label nextcan
    can=can+2
    for i=2 to sqrt(can):if (frac(can/i)=0) then goto notprime:fi:next i
    print at(32,17) can;
    label notprime
    if (lower$(inkey$(0))<>"") then
      print at(10,sh) "Wrapping around once ...";
      for x=1 to sw
        a$=getscreen$(0,0,1,sh-2)
        b$=getscreen$(1,0,sw-1,sh-2)
        putscreen b$,0,0
        putscreen a$,sw-1,0
      next x
      sleep 2
      return
    fi
  goto nextcan

  //  Show some animated bitmaps
  label bitmap
    clear screen
    print
    print "Yabasic offers some commands for drawing simple graphics."
    print reverse at(5,12) " Press any key to return to main menu ... "

    n=20
    open window 400,400

    for b=20 to 0 step -1
      color 255-b*12,0,b*12
      fill circle 200,200,b
    next b
    c$=getbit$(179,179,221,221)
    for a=1 to 2000
      color ran(255),ran(255),ran(255)
      x=ran(500)-100:y=ran(500)-100
      fill rectangle ran(500)-100,ran(500)-100,ran(500)-100,ran(500)-100
    next a

    x=200:y=200:phi=ran(2*pi):dx=2*sin(phi):dy=2*cos(phi)
    o$=""
    count=0
    label pong
      count=count+1
      if (o$<>"") putbit o$,xo-2,yo-2
      if (count>1000) then
        phi=ran(2*pi):dx=2*sin(phi):dy=2*cos(phi)
        sleep 2
        count=0
      endif
      xo=x:yo=y
      x=x+dx:y=y+dy
      o$=getbit$(x-2,y-2,x+46,y+46)
      putbit c$,x,y,"t"
      if (x<0 or x>360) dx=-dx
      if (y<0 or y>360) dy=-dy
      if (inkey$(0)<>"") then
        close window
        return
      endif
    goto pong
  return

  label tetraeder

  open window 400,400
  clear window
  clear screen
  print reverse at(5,12) " Press any key to return to main menu ... "

  dim opoints(4,3)
  restore points
  for n=1 to 4:for p=1 to 3:read opoints(n,p):next p:next n

  dim triangles(4,3)
  restore triangles
  for n=1 to 4:for p=1 to 3:read triangles(n,p):next p:next n

  phi=0:dphi=0.1:psi=0:dpsi=0.05
  dim points(4,3)

  r=60:g=20
  dr=0.5:dg=1.2:db=3
  label main

    phi=phi+dphi
    psi=psi+dpsi
    for n=1 to 4
      points(n,1)=opoints(n,1)*cos(phi)-opoints(n,2)*sin(phi)
      points(n,2)=opoints(n,2)*cos(phi)+opoints(n,1)*sin(phi)
      p2=          points(n,2)*cos(psi)-opoints(n,3)*sin(psi)
      points(n,3)=opoints(n,3)*cos(psi)+ points(n,2)*sin(psi)
      points(n,2)=p2
    next n

    r=r+dr:if (r<0 or r>60) dr=-dr
    g=g+dg:if (g<0 or g>60) dg=-dg
    b=b+db:if (b<0 or b>60) db=-db
    dm=dm+0.01
    m=120-80*sin(dm)
    for n=1 to 4
      p1=triangles(n,1)
      p2=triangles(n,2)
      p3=triangles(n,3)
      n1=points(p1,1)+points(p2,1)+points(p3,1)
      n2=points(p1,2)+points(p2,2)+points(p3,2)
      n3=points(p1,3)+points(p2,3)+points(p3,3)
      if (n3>0) then
        sp=n1*0.5-n2*0.7-n3*0.6
        color 60+r+30*sp,60+g+30*sp,60+b+30*sp
        fill triangle 200+m*points(p1,1),200+m*points(p1,2),200+m*points(p2,1),20
  0+m*points(p2,2),200+m*points(p3,1),200+m*points(p3,2)
      endif
    next n
    if (inkey$(0.1)<>"") close window:return
    clear window
  goto main

  label points
  data  -1,-1,+1,  +1,-1,-1,  +1,+1,+1,  -1,+1,-1
  label triangles
  data  1,2,4,  2,3,4,  1,3,4,  1,2,3

  //  Data section ...
  label mmdata
  //  Data for main menu: Number and text of entries in main menu
  data 4
  data "   Yabasic in a nutshell   "
  data "   Some graphics           "
  data "   A rotating Tetraeder    "
  data "   Exit this demo          "

  Chapter 9. The Copyright of yabasic

     yabasic may be copied only under the terms of the Artistic License or the
     GNU General Public License (GPL), both of which are distributed with
     yabasic.

     [Can’t you make up your mind ?!], I hear you say. Umm, well yes. In fact I
     do not want to read or try to understand them both, so I have put the burden
     on you (grin). However, I think that the Artistic License is more liberal
     and gives you more rights and you should choose it; on the other hand the
     GPL is more widely known and a lot of software is distributed under its
     terms.

     Here is a list of things that are possible under the terms of the Artistic
     License:
       * Put yabasic on your own homepage or CD and even charge for the service
         of distributing yabasic.
       * Write your own yabasic-programs, pack your program and yabasic into a
         package and sell the whole thing.
       * Modify yabasic and add or remove features, sell the modified version.

AUTHOR

       Marc-Oliver Ihm, with the input and suggestions from many others.

SEE ALSO

       yabasic.htm - for the hyperlinked version of the text that is presented
       above.

       www.yabasic.de - for further information about yabasic.

BUGS

       Still some.

                                                                    yabasic(1)