Provided by: yabasic_2.90.3-1_amd64 
NAME
yabasic - yet another Basic
SYNOPSIS
yabasic [OPTIONS] [FILENAME [ARGUMENTS]]
DESCRIPTION
Yabasic implements the most common and simple elements of the basic language. It comes with goto/gosub,
with various loops, with user defined subroutines and libraries. Yabasic does simple graphics and
printing. Yabasic runs under Unix and Windows, it is small, open source and free.
This man-page is derived from yabasic.htm, which too should be installed on your system; per default in
/usr/local/share/applications/yabasic/yabasic.htm.
The same information can also be found on www.yabasic.de
Here is its content:
\h'\n[lss]u'Yabasic
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Table of Contents
\h'\n[lss]u'1. Introduction
\h'\n[lss]u'About this document
\h'\n[lss]u'About yabasic
\h'\n[lss]u'2. The yabasic-program under Windows
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'Options
\h'\n[lss]u'The context Menu
\h'\n[lss]u'3. The yabasic-program under Unix
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'Options
\h'\n[lss]u'Setting defaults
\h'\n[lss]u'4. Command line options of yabasic
\h'\n[lss]u'5. Some features of yabasic, explained by topic
\h'\n[lss]u'print, input and others
\h'\n[lss]u'Control statements: loops, if and switch
\h'\n[lss]u'Drawing and painting
\h'\n[lss]u'Reading from and writing to files
\h'\n[lss]u'Subroutines and Libraries
\h'\n[lss]u'String processing
\h'\n[lss]u'Arithmetic and numbers
\h'\n[lss]u'Data and such
\h'\n[lss]u'Other interesting commands.
\h'\n[lss]u'6. All commands and functions of yabasic listed by topic
\h'\n[lss]u'Number processing and conversion
\h'\n[lss]u'Conditions and control structures
\h'\n[lss]u'Data keeping and processing
\h'\n[lss]u'String processing
\h'\n[lss]u'File operations and printing
\h'\n[lss]u'Subroutines and libraries
\h'\n[lss]u'Other commands
\h'\n[lss]u'Graphics and printing
\h'\n[lss]u'7. All commands and functions of yabasic grouped alphabetically
\h'\n[lss]u'A
\h'\n[lss]u'B
\h'\n[lss]u'C
\h'\n[lss]u'D
\h'\n[lss]u'E
\h'\n[lss]u'F
\h'\n[lss]u'G
\h'\n[lss]u'H
\h'\n[lss]u'I
\h'\n[lss]u'L
\h'\n[lss]u'M
\h'\n[lss]u'N
\h'\n[lss]u'O
\h'\n[lss]u'P
\h'\n[lss]u'R
\h'\n[lss]u'S
\h'\n[lss]u'T
\h'\n[lss]u'U
\h'\n[lss]u'V
\h'\n[lss]u'W
\h'\n[lss]u'X
\h'\n[lss]u'Special characters
\h'\n[lss]u'Reserved Words
\h'\n[lss]u'8. Some general concepts and terms
\h'\n[lss]u'Logical shortcuts
\h'\n[lss]u'Conditions and expressions
\h'\n[lss]u'References on arrays
\h'\n[lss]u'Specifying Filenames under Windows
\h'\n[lss]u'Escape-sequences
\h'\n[lss]u'Creating a standalone program from your yabasic-program
\h'\n[lss]u'9. A few example programs
\h'\n[lss]u'A very simple program
\h'\n[lss]u'The demo of yabasic
\h'\n[lss]u'10. The Copyright of yabasic
\h'\n[lss]u'Chapter 1. Introduction
\h'\n[lss]u'About this document
\h'\n[lss]u'About yabasic
\h'\n[lss]u'About this document
\h'\n[lss]u'This document describes yabasic. You will find information about the yabasic
\h'\n[lss]u'interpreter (the program yabasic under Unix or yabasic.exe under Windows) as
\h'\n[lss]u'well as the language (which is, of course, a sort of basic) itself.
\h'\n[lss]u'This document applies to version 2.82 of yabasic
\h'\n[lss]u'However, this document does not contain the latest news about yabasic or a FAQ.
\h'\n[lss]u'As such information tends to change rapidly, it is presented online only at
\h'\n[lss]u'www.yabasic.de.
\h'\n[lss]u'Although basic has its reputation as a language for beginning programmers, this
\h'\n[lss]u'is not an introduction to programming at large. Rather this text assumes, that
\h'\n[lss]u'the reader has some (moderate) experience with writing and starting computer
\h'\n[lss]u'programs.
\h'\n[lss]u'About yabasic
\h'\n[lss]u'yabasic is a traditional basic interpreter. It understands most of the typical
\h'\n[lss]u'basic-constructs, like goto, gosub, line numbers, read, data or
\h'\n[lss]u'string-variables with a trailing '$'. But on the other hand, yabasic implements
\h'\n[lss]u'some more advanced programming-constructs like subroutines or libraries (but
\h'\n[lss]u'not objects). yabasic works much the same under Unix and Windows.
\h'\n[lss]u'yabasic puts emphasis on giving results quickly and easily; therefore simple
\h'\n[lss]u'commands are provided to open a graphic window, print the graphics or control
\h'\n[lss]u'the console screen and get keyboard or mouse information. The example below
\h'\n[lss]u'opens a window, draws a circle and prints the graphic:
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'open printer
\h'\n[lss]u'circle 50,50,40
\h'\n[lss]u'text 10,50,"Press any key to get a printout"
\h'\n[lss]u'clear screen
\h'\n[lss]u'inkey$
\h'\n[lss]u'close printer
\h'\n[lss]u'close window
\h'\n[lss]u'This example has fewer lines, than it would have in many other programming
\h'\n[lss]u'languages. In the end however yabasic lacks behind more advanced and modern
\h'\n[lss]u'programming languages like C++ or Java. But as far as it goes it tends to give
\h'\n[lss]u'you results more quickly and easily.
\h'\n[lss]u'Chapter 2. The yabasic-program under Windows
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'Options
\h'\n[lss]u'The context Menu
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'Once, yabasic has been set up correctly, there are three ways to start it:
\h'\n[lss]u'1. Right click on your desktop: The desktop menu appears with a submenu named
\h'\n[lss]u'new. From this submenu choose yabasic. This will create a new icon on your
\h'\n[lss]u'desktop. If you right click on this icon, its context menu will appear;
\h'\n[lss]u'choose Execute to execute the program.
\h'\n[lss]u'2. As a variant of the way described above, you may simply create a file with
\h'\n[lss]u'the ending .yab (e.g. with your favorite editor). Everything else then
\h'\n[lss]u'works as described above.
\h'\n[lss]u'3. From the start-menu: Choose yabasic from your start-menu. A console-window
\h'\n[lss]u'will open and you will be asked to type in your program. Once you are
\h'\n[lss]u'finished, you need to type return twice, and yabasic will parse and execute
\h'\n[lss]u'your program.
\h'\n[lss]u'Note
\h'\n[lss]u'This is not the preferred way of starting yabasic ! Simply because the
\h'\n[lss]u'program, that you have typed, can not be saved and will be lost inevitably
\h'\n[lss]u'! There is no such thing as a save-command and therefore no way to conserve
\h'\n[lss]u'the program, that you have typed. This mode is only intended for quick
\h'\n[lss]u'hacks, and short programs.
\h'\n[lss]u'Options
\h'\n[lss]u'Under Windows yabasic will mostly be invoked by double-clicking on an
\h'\n[lss]u'appropriate icon; this way you do not have a chance to specify any of the
\h'\n[lss]u'command line options below. However, advanced users may change the librarypath
\h'\n[lss]u'in the registry, which has the same effect as specifying it as an option on the
\h'\n[lss]u'command line.
\h'\n[lss]u'See the chapter on options for a complete list of all options, either on Unix
\h'\n[lss]u'or Windows.
\h'\n[lss]u'The context Menu
\h'\n[lss]u'Like every other icon under Windows, the icon of every yabasic-program has a
\h'\n[lss]u'context menu offering the most frequent operations, that may be applied to a
\h'\n[lss]u'yabasic-program.
\h'\n[lss]u'Execute
\h'\n[lss]u'This will invoke yabasic to execute your program. The same happens, if you
\h'\n[lss]u'double click on the icon.
\h'\n[lss]u'Edit
\h'\n[lss]u'notepad will be invoked, allowing you to edit your program.
\h'\n[lss]u'View docu
\h'\n[lss]u'This will present the embedded documentation of your program. Embedded
\h'\n[lss]u'documentation is created with the special comment doc.
\h'\n[lss]u'Chapter 3. The yabasic-program under Unix
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'Options
\h'\n[lss]u'Setting defaults
\h'\n[lss]u'Starting yabasic
\h'\n[lss]u'If your system administrator (vulgo root) has installed yabasic correctly,
\h'\n[lss]u'there are three ways to start it:
\h'\n[lss]u'1. You may use your favorite editor (emacs, vi ?) to put your program into a
\h'\n[lss]u'file (e.g. foo). Make sure that the very first line starts with the
\h'\n[lss]u'characters '#!' followed by the full pathname of yabasic (e.g. '#!/usr/
\h'\n[lss]u'local/bin/yabasic'). This she-bang-line ensures, that your Unix will invoke
\h'\n[lss]u'yabasic to execute your program (see also the entry for the hash
\h'\n[lss]u'-character). Moreover, you will need to change the permissions of your
\h'\n[lss]u'yabasic-program foo, e.g. chmod u+x foo. After that you may invoke yabasic
\h'\n[lss]u'to invoke your program by simply typing foo (without even mentioning
\h'\n[lss]u'yabasic). However, if your PATH-variable does not contain a single dot
\h'\n[lss]u'('.') you will have to type the full pathname of your program: e.g. /home/
\h'\n[lss]u'ihm/foo (or at least ./foo).
\h'\n[lss]u'2. Save your program into a file (e.g. foo) and type yabasic foo. This
\h'\n[lss]u'assumes, that the directory, where yabasic resides, is contained within
\h'\n[lss]u'your PATH-variable.
\h'\n[lss]u'3. Finally your may simply type yabasic (maybe it will be necessary to include
\h'\n[lss]u'its full pathname). This will make yabasic come up and you will be asked to
\h'\n[lss]u'type in your program. Once you are finished, you need to type return twice,
\h'\n[lss]u'and yabasic will parse and execute your program.
\h'\n[lss]u'Note
\h'\n[lss]u'This is not the preferred way of starting yabasic ! Simply because the
\h'\n[lss]u'program, that you have typed, can not be saved and will be lost inevitably
\h'\n[lss]u'! There is no such thing as a save-command and therefore no way to conserve
\h'\n[lss]u'the program, that you have typed. This mode is only intended for quick
\h'\n[lss]u'hacks, and short programs, i.e. for using yabasic as some sort of fancy
\h'\n[lss]u'desktop calculator.
\h'\n[lss]u'Options
\h'\n[lss]u'yabasic accepts a number of options on the command line.
\h'\n[lss]u'See chapter on options for a complete list of all options, either on Unix or
\h'\n[lss]u'Windows.
\h'\n[lss]u'Setting defaults
\h'\n[lss]u'If you want to set some options once for all, you may put them into your
\h'\n[lss]u'X-Windows resource file. This is usually the file .Xresources or some such
\h'\n[lss]u'within your home directory (type man X for details).
\h'\n[lss]u'Here is a sample section, which may appear within this file:
\h'\n[lss]u'yabasic*foreground: blue
\h'\n[lss]u'yabasic*background: gold
\h'\n[lss]u'yabasic*geometry: +10+10
\h'\n[lss]u'yabasic*font: 9x15
\h'\n[lss]u'This will set the foreground color of the graphic-window to blue and the
\h'\n[lss]u'background color to gold. The window will appear at position 10,10 and the text
\h'\n[lss]u'font will be 9x15.
\h'\n[lss]u'Chapter 4. Command line options of yabasic
\h'\n[lss]u'Here are the options, that yabasic accepts on the command line (both under Unix
\h'\n[lss]u'and Windows).
\h'\n[lss]u'All the options below may be abbreviated (and one hyphen may be dropped), as
\h'\n[lss]u'long as the abbreviation does not become ambiguous. For example, you may write
\h'\n[lss]u'-e instead of --execute.
\h'\n[lss]u'--help or -?
\h'\n[lss]u'Prints a short help message, which itself describes two further
\h'\n[lss]u'help-options.
\h'\n[lss]u'--version
\h'\n[lss]u'Prints the version of yabasic.
\h'\n[lss]u'--infolevel INFOLEVEL
\h'\n[lss]u'Change the infolevel of yabasic, where INFOLEVEL can be one of debug, note,
\h'\n[lss]u'warning, error, fatal and bison (the default is warning). This option
\h'\n[lss]u'changes the amount of debugging-information yabasic produces. However,
\h'\n[lss]u'normally only the author of yabasic (me !) would want to change this.
\h'\n[lss]u'--execute A-PROGRAM-AS-A-SINGLE-STRING
\h'\n[lss]u'With this option you may specify some yabasic-code to be executed right
\h'\n[lss]u'away. This is useful for very short programs, which you do not want to save
\h'\n[lss]u'to a file. If this option is given, yabasic will not read any code from a
\h'\n[lss]u'file. E.g.
\h'\n[lss]u'yabasic -e 'for a=1 to 10:print a*a:next a'
\h'\n[lss]u'prints the square numbers from 1 to 10.
\h'\n[lss]u'--bind NAME-OF-STANDALONE-PROGRAM
\h'\n[lss]u'Create a standalone program (whose name is specified by
\h'\n[lss]u'NAME-OF-STANDALONE-PROGRAM) from the yabasic-program, that is specified on
\h'\n[lss]u'the command line. See the section about creating a standalone-program for
\h'\n[lss]u'details.
\h'\n[lss]u'--geometry +X-POSITION+Y-POSITION
\h'\n[lss]u'Sets the position of the graphic window, that is opened by open window (the
\h'\n[lss]u'size of this window, of course, is specified within the open
\h'\n[lss]u'window-command). An example would be -geometry +20+10, which would place
\h'\n[lss]u'the graphic window 10 pixels below the upper border and 20 pixels right of
\h'\n[lss]u'the left border of the screen. This value cannot be changed, once yabasic
\h'\n[lss]u'has been started.
\h'\n[lss]u'-fg FOREGROUND-COLOR or --foreground FOREGROUND-COLOR
\h'\n[lss]u'Unix only. Define the foreground color for the graphics-window (that will
\h'\n[lss]u'be opened with open window). The usual X11 color names, like red, green, ?
\h'\n[lss]u'are accepted. This value cannot be changed, once yabasic has been started.
\h'\n[lss]u'-bg BACKGROUND-COLOR or --background BACKGROUND-COLOR
\h'\n[lss]u'Unix only. Define the background color for the graphics-window. The usual
\h'\n[lss]u'X11 color names are accepted. This value cannot be changed, once yabasic
\h'\n[lss]u'has been started.
\h'\n[lss]u'--display X11-DISPLAY-SPECIFICATION
\h'\n[lss]u'Unix only. Specify the display, where the graphics window of yabasic should
\h'\n[lss]u'appear. Normally this value will be already present within the environment
\h'\n[lss]u'variable DISPLAY.
\h'\n[lss]u'--font NAME-OF-FONT
\h'\n[lss]u'Under Unix. Name of the font, which will be used for text within the
\h'\n[lss]u'graphics window.
\h'\n[lss]u'--font NAME-OF-FONT
\h'\n[lss]u'Under Windows. Name of the font, which will be used for graphic-text; can
\h'\n[lss]u'be any of decorative, dontcare, modern, roman, script, swiss. You may
\h'\n[lss]u'append a fontsize (measured in pixels) to any of those fontnames; for
\h'\n[lss]u'example -font swiss30 chooses a swiss-type font with a size of 30 pixels.
\h'\n[lss]u'--docu NAME-OF-A-PROGRAM
\h'\n[lss]u'Print the embedded documentation of the named program. The embedded
\h'\n[lss]u'documentation of a program consists of all the comments within the program,
\h'\n[lss]u'which start with the special keyword doc. This documentation can also be
\h'\n[lss]u'seen by choosing the corresponding entry from the context-menu of any
\h'\n[lss]u'yabasic-program.
\h'\n[lss]u'--check
\h'\n[lss]u'Check for possible compatibility problems within your yabasic-program. E.g.
\h'\n[lss]u'this option reports, if you are using a function, that has recently
\h'\n[lss]u'changed.
\h'\n[lss]u'--librarypath DIRECTORY-WITH-LIBRARIES
\h'\n[lss]u'Change the directory, wherein libraries will be searched and imported (with
\h'\n[lss]u'the import-command). See also import for more information about the way,
\h'\n[lss]u'libraries are searched.
\h'\n[lss]u'--
\h'\n[lss]u'Do not try to parse any further options; rather pass the subsequent words
\h'\n[lss]u'from the commandline to yabasic.
\h'\n[lss]u'Chapter 5. Some features of yabasic, explained by topic
\h'\n[lss]u'print, input and others
\h'\n[lss]u'Control statements: loops, if and switch
\h'\n[lss]u'Drawing and painting
\h'\n[lss]u'Reading from and writing to files
\h'\n[lss]u'Subroutines and Libraries
\h'\n[lss]u'String processing
\h'\n[lss]u'Arithmetic and numbers
\h'\n[lss]u'Data and such
\h'\n[lss]u'Other interesting commands.
\h'\n[lss]u'This chapter has sections for some of the major features of yabasic and names a
\h'\n[lss]u'few commands related with each area. So, depending on your interest, you find
\h'\n[lss]u'the most important commands of this area named; the other commands from this
\h'\n[lss]u'area may then be discovered through the links in the see also-section.
\h'\n[lss]u'print, input and others
\h'\n[lss]u'The print-command is used to put text on the text screen. Here, the term text
\h'\n[lss]u'screen stands for your terminal (under Unix) or the console window (under
\h'\n[lss]u'Windows).
\h'\n[lss]u'At the bottom line, print simply outputs its argument to the text window.
\h'\n[lss]u'However, once you have called clear screen you may use advanced features like
\h'\n[lss]u'printing colors or copying areas of text with getscreen$ or putscreen.
\h'\n[lss]u'You may ask the user for input with the input-command; use inkey$ to get each
\h'\n[lss]u'key as soon as it is pressed.
\h'\n[lss]u'Control statements: loops, if and switch
\h'\n[lss]u'Of course, yabasic has the goto- and gosub-statements; you may go to a label or
\h'\n[lss]u'a line number (which is just a special kind of label). goto, despite its bad
\h'\n[lss]u'reputation ([goto considered harmful]), has still its good uses; however in
\h'\n[lss]u'many cases you are probably better off with loops like repeat-until, while-wend
\h'\n[lss]u'or do-loop; you may leave any of these loops with the break-statement or start
\h'\n[lss]u'the next iteration immediately with continue.
\h'\n[lss]u'Decisions can be made with the if-statement, which comes either in a short and
\h'\n[lss]u'a long form. The short form has no then-keyword and extends up to the end of
\h'\n[lss]u'the line. The long form extends up to the final endif and may use some of the
\h'\n[lss]u'keywords then (which introduces the long form), else or elsif.
\h'\n[lss]u'If you want to test the result of an expression against many different values,
\h'\n[lss]u'you should probably use the switch-statement.
\h'\n[lss]u'Drawing and painting
\h'\n[lss]u'You need to call open window before you may draw anything with either line,
\h'\n[lss]u'circle, rectangle or triangle; all of these statements may be decorated with
\h'\n[lss]u'clear or fill. If you want to change the colour for drawing, use colour. Note
\h'\n[lss]u'however, that there can only be a single window open at any given moment in
\h'\n[lss]u'time.
\h'\n[lss]u'Everything you have drawn can be send to your printer too, if you use the open
\h'\n[lss]u'printer command.
\h'\n[lss]u'To allow for some (very) limited version of animated graphics, yabasic offers
\h'\n[lss]u'the commands getbit$ and putbit, which retrieve rectangular regions from the
\h'\n[lss]u'graphics-window into a string or vice versa.
\h'\n[lss]u'If you want to sense mouse-clicks, you may use the inkey$-function.
\h'\n[lss]u'Reading from and writing to files
\h'\n[lss]u'Before you may read or write a file, you need to open it; once you are done,
\h'\n[lss]u'you should close it. Each open file is designated by a simple number, which
\h'\n[lss]u'might be stored within a variable and must be supplied if you want to access
\h'\n[lss]u'the file. This is simply done by putting a hash ('#') followed by the number of
\h'\n[lss]u'the file after the keyword input (for reading from) or print (for writing to a
\h'\n[lss]u'file) respectively.
\h'\n[lss]u'If you need more control, you may consider reading and writing one byte at a
\h'\n[lss]u'time, using the multi-purpose commands peek and poke.
\h'\n[lss]u'Subroutines and Libraries
\h'\n[lss]u'The best way to break any yabasic-program into smaller, more manageable chunks
\h'\n[lss]u'are subroutines and libraries. They are yabasic's most advanced means of
\h'\n[lss]u'structuring a program.
\h'\n[lss]u'Subroutines are created with the command sub. they accept parameters and may
\h'\n[lss]u'return a value. Subroutines can be called much like any builtin function of
\h'\n[lss]u'yabasic; therefore they allow one to extend the language itself.
\h'\n[lss]u'Once you have created a set of related subroutines and you feel that they could
\h'\n[lss]u'be useful in other programs too, you may collect them into a library. Such a
\h'\n[lss]u'library is contained within a separate file and may be included in any of your
\h'\n[lss]u'programs, using the keyword import, which see.
\h'\n[lss]u'String processing
\h'\n[lss]u'yabasic has a set of functions to extract parts from a string: left$, mid$ and
\h'\n[lss]u'right$. Note, that all of them can be assigned to, i.e. they may change part of
\h'\n[lss]u'a string.
\h'\n[lss]u'If you want to split a string into tokens you should use the functions token or
\h'\n[lss]u'split.
\h'\n[lss]u'Some functions are handy for normalizing a string: upper$ and lower$ convert a
\h'\n[lss]u'string to all upper or lower case respectively, whereas chomp$ cuts of any
\h'\n[lss]u'trailing newline character, but only if present.
\h'\n[lss]u'chr$ and str$ convert a string into a number, both in different ways.
\h'\n[lss]u'To analyze a string use instr (finding one string within the other) or glob
\h'\n[lss]u'(testing a string against a simple pattern).
\h'\n[lss]u'To concatenate strings use the operator + like in a$ + b$.
\h'\n[lss]u'You may also see the complete list of a string processing functions.
\h'\n[lss]u'Arithmetic and numbers
\h'\n[lss]u'Yabasic handles numbers and arithmetic: You may calculate trigonometric
\h'\n[lss]u'functions like sin or atan, or logarithms (with log). Bitwise operations, like
\h'\n[lss]u'and or or are available as well min or max (calculate the minimum or maximum of
\h'\n[lss]u'its argument) or mod or int (reminder of a division or integer part or a
\h'\n[lss]u'number).
\h'\n[lss]u'Conversion between numerical bases can be done with hex$ and dec. And you may
\h'\n[lss]u'write hexadecimal constants in the usual way, e.g.
\h'\n[lss]u'print 0xff
\h'\n[lss]u'. All calculations in yabasic are done with double precision.
\h'\n[lss]u'Data and such
\h'\n[lss]u'You may store data within your program within data-statements; during execution
\h'\n[lss]u'you will probably want to read it into arrays, which must have been dimed
\h'\n[lss]u'before.
\h'\n[lss]u'Other interesting commands.
\h'\n[lss]u'* Yabasic programs may start other programs with the commands system and
\h'\n[lss]u'system$.
\h'\n[lss]u'* peek and poke allow one to get and set internal information; either for the
\h'\n[lss]u'operating system (i.e. Unix or Windows) or yabasic itself.
\h'\n[lss]u'* The current time or date can be retrieved with (guess what !) time$ and
\h'\n[lss]u'date$.
\h'\n[lss]u'Chapter 6. All commands and functions of yabasic listed by topic
\h'\n[lss]u'Number processing and conversion
\h'\n[lss]u'Conditions and control structures
\h'\n[lss]u'Data keeping and processing
\h'\n[lss]u'String processing
\h'\n[lss]u'File operations and printing
\h'\n[lss]u'Subroutines and libraries
\h'\n[lss]u'Other commands
\h'\n[lss]u'Graphics and printing
\h'\n[lss]u'Number processing and conversion
\h'\n[lss]u'abs()
\h'\n[lss]u'returns the absolute value of its numeric argument
\h'\n[lss]u'acos()
\h'\n[lss]u'returns the arcus cosine of its numeric argument
\h'\n[lss]u'and()
\h'\n[lss]u'the bitwise arithmetic and
\h'\n[lss]u'asin()
\h'\n[lss]u'returns the arcus sine of its numeric argument
\h'\n[lss]u'atan()
\h'\n[lss]u'returns the arctangent of its numeric argument
\h'\n[lss]u'bin$()
\h'\n[lss]u'converts a number into a sequence of binary digits
\h'\n[lss]u'cos()
\h'\n[lss]u'return the cosine of its single argument
\h'\n[lss]u'dec()
\h'\n[lss]u'convert a base 2 or base 16 number into decimal form
\h'\n[lss]u'eor()
\h'\n[lss]u'compute the bitwise exclusive or of its two arguments
\h'\n[lss]u'euler
\h'\n[lss]u'another name for the constant 2.71828182864
\h'\n[lss]u'exp()
\h'\n[lss]u'compute the exponential function of its single argument
\h'\n[lss]u'frac()
\h'\n[lss]u'return the fractional part of its numeric argument
\h'\n[lss]u'int()
\h'\n[lss]u'return the integer part of its single numeric argument
\h'\n[lss]u'ceil()
\h'\n[lss]u'return the smallest integral number, that is greater or equal than its
\h'\n[lss]u'argument
\h'\n[lss]u'floor()
\h'\n[lss]u'return the largest integral number, that is smaller or equal than its
\h'\n[lss]u'argument
\h'\n[lss]u'log()
\h'\n[lss]u'compute the natural logarithm
\h'\n[lss]u'max()
\h'\n[lss]u'return the larger of its two arguments
\h'\n[lss]u'min()
\h'\n[lss]u'return the smaller of its two arguments
\h'\n[lss]u'mod
\h'\n[lss]u'compute the remainder of a division
\h'\n[lss]u'or()
\h'\n[lss]u'arithmetic or, used for bit-operations
\h'\n[lss]u'pi
\h'\n[lss]u'a constant with the value 3.14159
\h'\n[lss]u'ran()
\h'\n[lss]u'return a random number
\h'\n[lss]u'sig()
\h'\n[lss]u'return the sign of its argument
\h'\n[lss]u'sin()
\h'\n[lss]u'return the sine of its single argument
\h'\n[lss]u'sqr()
\h'\n[lss]u'compute the square of its argument
\h'\n[lss]u'sqrt()
\h'\n[lss]u'compute the square root of its argument
\h'\n[lss]u'tan()
\h'\n[lss]u'return the tangent of its argument
\h'\n[lss]u'xor()
\h'\n[lss]u'compute the exclusive or
\h'\n[lss]u'** or ^
\h'\n[lss]u'raise its first argument to the power of its second
\h'\n[lss]u'Conditions and control structures
\h'\n[lss]u'and
\h'\n[lss]u'logical and, used in conditions
\h'\n[lss]u'break
\h'\n[lss]u'breaks out of a switch statement or a loop
\h'\n[lss]u'case
\h'\n[lss]u'mark the different cases within a switch-statement
\h'\n[lss]u'continue
\h'\n[lss]u'start the next iteration of a for-, do-, repeat- or while-loop
\h'\n[lss]u'default
\h'\n[lss]u'mark the default-branch within a switch-statement
\h'\n[lss]u'do
\h'\n[lss]u'start a (conditionless) do-loop
\h'\n[lss]u'else
\h'\n[lss]u'mark an alternative within an if-statement
\h'\n[lss]u'elsif
\h'\n[lss]u'starts an alternate condition within an if-statement
\h'\n[lss]u'end
\h'\n[lss]u'terminate your program
\h'\n[lss]u'endif
\h'\n[lss]u'ends an if-statement
\h'\n[lss]u'false
\h'\n[lss]u'a constant with the value of 0
\h'\n[lss]u'fi
\h'\n[lss]u'another name for endif
\h'\n[lss]u'for
\h'\n[lss]u'starts a for-loop
\h'\n[lss]u'gosub
\h'\n[lss]u'continue execution at another point within your program (and return later)
\h'\n[lss]u'goto
\h'\n[lss]u'continue execution at another point within your program (and never come
\h'\n[lss]u'back)
\h'\n[lss]u'if
\h'\n[lss]u'evaluate a condition and execute statements or not, depending on the result
\h'\n[lss]u'label
\h'\n[lss]u'mark a specific location within your program for goto, gosub or restore
\h'\n[lss]u'loop
\h'\n[lss]u'marks the end of an infinite loop
\h'\n[lss]u'next
\h'\n[lss]u'mark the end of a for loop
\h'\n[lss]u'not
\h'\n[lss]u'negate an expression; can be written as !
\h'\n[lss]u'on gosub
\h'\n[lss]u'jump to one of multiple gosub-targets
\h'\n[lss]u'on goto
\h'\n[lss]u'jump to one of many goto-targets
\h'\n[lss]u'on interrupt
\h'\n[lss]u'change reaction on keyboard interrupts
\h'\n[lss]u'logical or
\h'\n[lss]u'logical or, used in conditions
\h'\n[lss]u'pause
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'repeat
\h'\n[lss]u'start a repeat-loop
\h'\n[lss]u'return
\h'\n[lss]u'return from a subroutine or a gosub
\h'\n[lss]u'sleep
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'switch
\h'\n[lss]u'select one of many alternatives depending on a value
\h'\n[lss]u'then
\h'\n[lss]u'tell the long from the short form of the if-statement
\h'\n[lss]u'true
\h'\n[lss]u'a constant with the value of 1
\h'\n[lss]u'until
\h'\n[lss]u'end a repeat-loop
\h'\n[lss]u'wait
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'wend
\h'\n[lss]u'end a while-loop
\h'\n[lss]u'while
\h'\n[lss]u'start a while-loop
\h'\n[lss]u':
\h'\n[lss]u'separate commands from each other
\h'\n[lss]u'Data keeping and processing
\h'\n[lss]u'arraydim()
\h'\n[lss]u'returns the dimension of the array, which is passed as an array reference
\h'\n[lss]u'arraysize()
\h'\n[lss]u'returns the size of a dimension of an array
\h'\n[lss]u'data
\h'\n[lss]u'introduces a list of data-items
\h'\n[lss]u'dim
\h'\n[lss]u'create an array prior to its first use
\h'\n[lss]u'read
\h'\n[lss]u'read data from data-statements
\h'\n[lss]u'redim
\h'\n[lss]u'create an array prior to its first use. A synonym for dim
\h'\n[lss]u'restore
\h'\n[lss]u'reposition the data-pointer
\h'\n[lss]u'String processing
\h'\n[lss]u'asc()
\h'\n[lss]u'accepts a string and returns the position of its first character within the
\h'\n[lss]u'ascii charset
\h'\n[lss]u'chomp$()
\h'\n[lss]u'Chop of the trailing newline of its string-argument; if the string does not
\h'\n[lss]u'end in a newline, the string is returned unchanged
\h'\n[lss]u'chr$()
\h'\n[lss]u'accepts a number and returns the character at this position within the
\h'\n[lss]u'ascii charset
\h'\n[lss]u'glob()
\h'\n[lss]u'check if a string matches a simple pattern
\h'\n[lss]u'hex$()
\h'\n[lss]u'convert a number into hexadecimal
\h'\n[lss]u'instr()
\h'\n[lss]u'searches its second argument within the first; returns its position if
\h'\n[lss]u'found
\h'\n[lss]u'left$()
\h'\n[lss]u'return (or change) left end of a string
\h'\n[lss]u'len()
\h'\n[lss]u'return the length of a string
\h'\n[lss]u'lower$()
\h'\n[lss]u'convert a string to lower case
\h'\n[lss]u'ltrim$()
\h'\n[lss]u'trim spaces at the left end of a string
\h'\n[lss]u'mid$()
\h'\n[lss]u'return (or change) characters from within a string
\h'\n[lss]u'right$()
\h'\n[lss]u'return (or change) the right end of a string
\h'\n[lss]u'split()
\h'\n[lss]u'split a string into many strings
\h'\n[lss]u'str$()
\h'\n[lss]u'convert a number into a string
\h'\n[lss]u'token()
\h'\n[lss]u'split a string into multiple strings
\h'\n[lss]u'trim$()
\h'\n[lss]u'remove leading and trailing spaces from its argument
\h'\n[lss]u'upper$()
\h'\n[lss]u'convert a string to upper case
\h'\n[lss]u'val()
\h'\n[lss]u'converts a string to a number
\h'\n[lss]u'File operations and printing
\h'\n[lss]u'at()
\h'\n[lss]u'can be used in the print-command to place the output at a specified
\h'\n[lss]u'position
\h'\n[lss]u'beep
\h'\n[lss]u'ring the bell within your computer; a synonym for bell
\h'\n[lss]u'bell
\h'\n[lss]u'ring the bell within your computer (just as beep)
\h'\n[lss]u'clear screen
\h'\n[lss]u'erases the text window
\h'\n[lss]u'close
\h'\n[lss]u'close a file, which has been opened before
\h'\n[lss]u'close printer
\h'\n[lss]u'stops printing of graphics
\h'\n[lss]u'print color
\h'\n[lss]u'print with color
\h'\n[lss]u'print colour
\h'\n[lss]u'see print color
\h'\n[lss]u'eof
\h'\n[lss]u'check, if an open file contains data
\h'\n[lss]u'getscreen$()
\h'\n[lss]u'returns a string representing a rectangular section of the text terminal
\h'\n[lss]u'inkey$
\h'\n[lss]u'wait, until a key is pressed
\h'\n[lss]u'input
\h'\n[lss]u'read input from the user (or from a file) and assign it to a variable
\h'\n[lss]u'line input
\h'\n[lss]u'read in a whole line of text and assign it to a variable
\h'\n[lss]u'open
\h'\n[lss]u'open a file
\h'\n[lss]u'open printer
\h'\n[lss]u'open printer for printing graphics
\h'\n[lss]u'print
\h'\n[lss]u'Write to terminal or file
\h'\n[lss]u'putscreen
\h'\n[lss]u'draw a rectangle of characters into the text terminal
\h'\n[lss]u'reverse
\h'\n[lss]u'print reverse (background and foreground colors exchanged)
\h'\n[lss]u'screen
\h'\n[lss]u'as clear screen clears the text window
\h'\n[lss]u'seek()
\h'\n[lss]u'change the position within an open file
\h'\n[lss]u'tell
\h'\n[lss]u'get the current position within an open file
\h'\n[lss]u'using
\h'\n[lss]u'Specify the format for printing a number
\h'\n[lss]u'#
\h'\n[lss]u'either a comment or a marker for a file-number
\h'\n[lss]u'@
\h'\n[lss]u'synonymous to at
\h'\n[lss]u';
\h'\n[lss]u'suppress the implicit newline after a print-statement
\h'\n[lss]u'Subroutines and libraries
\h'\n[lss]u'end sub
\h'\n[lss]u'ends a subroutine definition
\h'\n[lss]u'export
\h'\n[lss]u'mark a function as globally visible
\h'\n[lss]u'import
\h'\n[lss]u'import a library
\h'\n[lss]u'local
\h'\n[lss]u'mark a variable as local to a subroutine
\h'\n[lss]u'numparams
\h'\n[lss]u'return the number of parameters, that have been passed to a subroutine
\h'\n[lss]u'return
\h'\n[lss]u'return from a subroutine or a gosub
\h'\n[lss]u'static
\h'\n[lss]u'preserves the value of a variable between calls to a subroutine
\h'\n[lss]u'step
\h'\n[lss]u'specifies the increment step in a for-loop
\h'\n[lss]u'sub
\h'\n[lss]u'declare a user defined subroutine
\h'\n[lss]u'Other commands
\h'\n[lss]u'bind()
\h'\n[lss]u'Binds a yabasic-program and the yabasic-interpreter together into a
\h'\n[lss]u'standalone program.
\h'\n[lss]u'compile
\h'\n[lss]u'compile a string with yabasic-code on the fly
\h'\n[lss]u'date$
\h'\n[lss]u'returns a string with various components of the current date
\h'\n[lss]u'doc
\h'\n[lss]u'special comment, which might be retrieved by the program itself
\h'\n[lss]u'docu$
\h'\n[lss]u'special array, containing the contents of all docu-statement within the
\h'\n[lss]u'program
\h'\n[lss]u'error
\h'\n[lss]u'raise an error and terminate your program
\h'\n[lss]u'execute$()
\h'\n[lss]u'execute a user defined subroutine, which must return a string
\h'\n[lss]u'execute()
\h'\n[lss]u'execute a user defined subroutine, which must return a number
\h'\n[lss]u'exit
\h'\n[lss]u'terminate your program
\h'\n[lss]u'pause
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'peek
\h'\n[lss]u'retrieve various internal information
\h'\n[lss]u'peek$
\h'\n[lss]u'retrieve various internal string-information
\h'\n[lss]u'poke
\h'\n[lss]u'change selected internals of yabasic
\h'\n[lss]u'rem
\h'\n[lss]u'start a comment
\h'\n[lss]u'sleep
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'system()
\h'\n[lss]u'hand a statement over to your operating system and return its exitcode
\h'\n[lss]u'system$()
\h'\n[lss]u'hand a statement over to your operating system and return its output
\h'\n[lss]u'time$
\h'\n[lss]u'return a string containing the current time
\h'\n[lss]u'to
\h'\n[lss]u'this keyword appears as part of other statements
\h'\n[lss]u'wait
\h'\n[lss]u'pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'//
\h'\n[lss]u'starts a comment
\h'\n[lss]u':
\h'\n[lss]u'separate commands from each other
\h'\n[lss]u'Graphics and printing
\h'\n[lss]u'backcolor
\h'\n[lss]u'specify the colour for subsequent drawing of the background
\h'\n[lss]u'box
\h'\n[lss]u'draw a rectangle. A synonym for rectangle
\h'\n[lss]u'circle
\h'\n[lss]u'draws a circle in the graphic-window
\h'\n[lss]u'clear
\h'\n[lss]u'Erase circles, rectangles or triangless
\h'\n[lss]u'clear window
\h'\n[lss]u'clear the graphic window and begin a new page, if printing is under way
\h'\n[lss]u'close curve
\h'\n[lss]u'close a curve, that has been drawn by the line-command
\h'\n[lss]u'close window
\h'\n[lss]u'close the graphics-window
\h'\n[lss]u'colour
\h'\n[lss]u'specify the colour for subsequent drawing
\h'\n[lss]u'dot
\h'\n[lss]u'draw a dot in the graphic-window
\h'\n[lss]u'fill
\h'\n[lss]u'draw a filled circles, rectangles or triangles
\h'\n[lss]u'getbit$()
\h'\n[lss]u'return a string representing the bit pattern of a rectangle within the
\h'\n[lss]u'graphic window
\h'\n[lss]u'line
\h'\n[lss]u'draw a line
\h'\n[lss]u'mouseb
\h'\n[lss]u'extract the state of the mousebuttons from a string returned by inkey$
\h'\n[lss]u'mousemod
\h'\n[lss]u'return the state of the modifier keys during a mouseclick
\h'\n[lss]u'mousex
\h'\n[lss]u'return the x-position of a mouseclick
\h'\n[lss]u'mousey
\h'\n[lss]u'return the y-position of a mouseclick
\h'\n[lss]u'new curve
\h'\n[lss]u'start a new curve, that will be drawn with the line-command
\h'\n[lss]u'open window
\h'\n[lss]u'open a graphic window
\h'\n[lss]u'putbit
\h'\n[lss]u'draw a rectangle of pixels into the graphic window
\h'\n[lss]u'rectangle
\h'\n[lss]u'draw a rectangle
\h'\n[lss]u'triangle
\h'\n[lss]u'draw a triangle
\h'\n[lss]u'text
\h'\n[lss]u'write text into your graphic-window
\h'\n[lss]u'window origin
\h'\n[lss]u'move the origin of a window
\h'\n[lss]u'Chapter 7. All commands and functions of yabasic grouped alphabetically
\h'\n[lss]u'A
\h'\n[lss]u'B
\h'\n[lss]u'C
\h'\n[lss]u'D
\h'\n[lss]u'E
\h'\n[lss]u'F
\h'\n[lss]u'G
\h'\n[lss]u'H
\h'\n[lss]u'I
\h'\n[lss]u'L
\h'\n[lss]u'M
\h'\n[lss]u'N
\h'\n[lss]u'O
\h'\n[lss]u'P
\h'\n[lss]u'R
\h'\n[lss]u'S
\h'\n[lss]u'T
\h'\n[lss]u'U
\h'\n[lss]u'V
\h'\n[lss]u'W
\h'\n[lss]u'X
\h'\n[lss]u'Special characters
\h'\n[lss]u'Reserved Words
\h'\n[lss]u'A
\h'\n[lss]u'abs() ? returns the absolute value of its numeric argument
\h'\n[lss]u'acos() ? returns the arcus cosine of its numeric argument
\h'\n[lss]u'and ? logical and, used in conditions
\h'\n[lss]u'and() ? the bitwise arithmetic and
\h'\n[lss]u'arraydim() ? returns the dimension of the array, which is passed as an array
\h'\n[lss]u'reference
\h'\n[lss]u'arraysize() ? returns the size of a dimension of an array
\h'\n[lss]u'asc() ? accepts a string and returns the position of its first character within
\h'\n[lss]u'the ascii charset
\h'\n[lss]u'asin() ? returns the arcus sine of its numeric argument
\h'\n[lss]u'at() ? can be used in the print-command to place the output at a specified
\h'\n[lss]u'position
\h'\n[lss]u'atan() ? returns the arctangent of its numeric argument
\h'\n[lss]u'Name
\h'\n[lss]u'abs() ? returns the absolute value of its numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'y=abs(x)
\h'\n[lss]u'Description
\h'\n[lss]u'If the argument of the abs-function is positive (e.g. 2) it is returned
\h'\n[lss]u'unchanged, if the argument is negative (e.g. -1) it is returned as a positive
\h'\n[lss]u'value (e.g. 1).
\h'\n[lss]u'Example
\h'\n[lss]u'print abs(-2),abs(2)
\h'\n[lss]u'This example will print 2 2
\h'\n[lss]u'See also
\h'\n[lss]u'sig
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'acos() ? returns the arcus cosine of its numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=acos(angle)
\h'\n[lss]u'Description
\h'\n[lss]u'acos is the arcus cosine-function, i.e. the inverse of the cos-function. Or,
\h'\n[lss]u'more elaborate: It Returns the angle (in radians, not degrees !), which, fed to
\h'\n[lss]u'the cosine-function will produce the argument passed to the acos-function.
\h'\n[lss]u'Example
\h'\n[lss]u'print acos(0.5),acos(cos(pi))
\h'\n[lss]u'This example will print 1.0472 3.14159 which are ?/3 and ? respectively.
\h'\n[lss]u'See also
\h'\n[lss]u'cos, asin
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'and ? logical and, used in conditions
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (a and b) ?
\h'\n[lss]u'while (a and b) ?
\h'\n[lss]u'Description
\h'\n[lss]u'Used in conditions (e.g within if, while or until) to join two expressions.
\h'\n[lss]u'Returns true, if and only if its left and right argument are both true and
\h'\n[lss]u'false otherwise.
\h'\n[lss]u'Note, that logical shortcuts may take place.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number" a
\h'\n[lss]u'if (a>=1 and a<=9) print "your input is between 1 and 9"
\h'\n[lss]u'See also
\h'\n[lss]u'or,not
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'and() ? the bitwise arithmetic and
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=and(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'Used to compute the bitwise and of both its argument. Both arguments are
\h'\n[lss]u'treated as binary numbers (i.e. a series of 0 and 1); a bit of the resulting
\h'\n[lss]u'value will then be 1, if both arguments have a 1 at this position in their
\h'\n[lss]u'binary representation.
\h'\n[lss]u'Note, that both arguments are silently converted to integer values and that
\h'\n[lss]u'negative numbers have their own binary representation and may lead to
\h'\n[lss]u'unexpected results when passed to and.
\h'\n[lss]u'Example
\h'\n[lss]u'print and(6,3)
\h'\n[lss]u'This will print 2. This result is clear, if you note, that the binary
\h'\n[lss]u'representation of 6 and 3 are 110 and 011 respectively; this will yield 010 in
\h'\n[lss]u'binary representation or 2 as decimal.
\h'\n[lss]u'See also
\h'\n[lss]u'or, eor and not
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'arraydim() ? returns the dimension of the array, which is passed as an array
\h'\n[lss]u'reference
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=arraydim(b())
\h'\n[lss]u'Description
\h'\n[lss]u'If you apply the arraydim()-function on a one-dimensional array (i.e. a vector)
\h'\n[lss]u'it will return 1, on a two-dimensional array (i.e. a matrix) it will return 2,
\h'\n[lss]u'and so on.
\h'\n[lss]u'This is mostly used within subroutines, which expect an array among their
\h'\n[lss]u'parameters. Such subroutines tend to use the arraydim-function to check, if the
\h'\n[lss]u'array which has been passed, has the right dimension. E.g. a subroutine to
\h'\n[lss]u'multiply two matrices may want to check, if it really is invoked with two
\h'\n[lss]u'2-dimensional arrays.
\h'\n[lss]u'Example
\h'\n[lss]u'dim a(10,10),b(10)
\h'\n[lss]u'print arraydim(a()),arraydim(b())
\h'\n[lss]u'This will print 2 1, which are the dimension of the arrays a() and b(). You may
\h'\n[lss]u'check out the function arraysize for a full-fledged example.
\h'\n[lss]u'See also
\h'\n[lss]u'arraysize and dim.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'arraysize() ? returns the size of a dimension of an array
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=arraysize(a(),b)
\h'\n[lss]u'Description
\h'\n[lss]u'The arraysize-function computes the size of a specified dimension of a
\h'\n[lss]u'specified array. Here, size stands for the maximum number, that may be used as
\h'\n[lss]u'an index for this array. The first argument to this function must be an
\h'\n[lss]u'reference to an array, the second one specifies, which of the multiple
\h'\n[lss]u'dimensions of the array should be taken to calculate the size.
\h'\n[lss]u'An Example involving subroutines: Let's say, an array has been declared as dim
\h'\n[lss]u'a(10,20) (that is a two-dimensional array or a matrix). If this array is passed
\h'\n[lss]u'as an array reference to a subroutine, this sub will not know, what sort of
\h'\n[lss]u'array has been passed. With the arraydim-function the sub will be able to find
\h'\n[lss]u'the dimension of the array, with the arraysize-function it will be able to find
\h'\n[lss]u'out the size of this array in its two dimensions, which will be 10 and 20
\h'\n[lss]u'respectively.
\h'\n[lss]u'Our sample array is two dimensional; if you envision it as a matrix this matrix
\h'\n[lss]u'has 10 lines and 20 columns (see the dim-statement above. To state it more
\h'\n[lss]u'formally: The first dimension (lines) has a size of 10, the second dimension
\h'\n[lss]u'(columns) has a size of 20; these numbers are those returned by arraysize(a
\h'\n[lss]u'(),1) and arraysize(a(),2) respectively. Refer to the example below for a
\h'\n[lss]u'typical usage.
\h'\n[lss]u'Example
\h'\n[lss]u'rem
\h'\n[lss]u'rem This program adds two matrices elementwise.
\h'\n[lss]u'rem
\h'\n[lss]u'dim a(10,20),b(10,20),c(10,20)
\h'\n[lss]u'rem initialization of the arrays a() and b()
\h'\n[lss]u'for y=1 to 10:for x=1 to 20
\h'\n[lss]u'a(y,x)=int(ran(4)):b(y,x)=int(ran(4))
\h'\n[lss]u'next x:next y
\h'\n[lss]u'matadd(a(),b(),c())
\h'\n[lss]u'print "Result:"
\h'\n[lss]u'for x=1 to 20
\h'\n[lss]u'for y=10 to 1 step -1
\h'\n[lss]u'print c(y,x)," ";
\h'\n[lss]u'next y
\h'\n[lss]u'print
\h'\n[lss]u'next x
\h'\n[lss]u'sub matadd(m1(),m2(),r())
\h'\n[lss]u'rem This sub will add the matrices m1() and m2()
\h'\n[lss]u'rem elementwise and store the result within r()
\h'\n[lss]u'rem This is not very useful but easy to implement.
\h'\n[lss]u'rem However, this sub excels in checking its arguments
\h'\n[lss]u'rem with arraydim() and arraysize()
\h'\n[lss]u'local x:local y
\h'\n[lss]u'if (arraydim(m1())<>2 or arraydim(m2())<>2 or arraydim(r())<>2) then
\h'\n[lss]u'error "Need two dimensional arrays as input"
\h'\n[lss]u'endif
\h'\n[lss]u'y=arraysize(m1(),1):x=arraysize(m1(),2)
\h'\n[lss]u'if (arraysize(m2(),1)<>y or arraysize(m2(),2)<>x) then
\h'\n[lss]u'error "The two matrices cannot be added elementwise"
\h'\n[lss]u'endif
\h'\n[lss]u'if (arraysize(r(),1)<>y or arraysize(r(),2)<>x) then
\h'\n[lss]u'error "The result cannot be stored in the third argument"
\h'\n[lss]u'endif
\h'\n[lss]u'local xx:local yy
\h'\n[lss]u'for xx=1 to x
\h'\n[lss]u'for yy=1 to y
\h'\n[lss]u'r(yy,xx)=m1(yy,xx)+m2(yy,xx)
\h'\n[lss]u'next yy
\h'\n[lss]u'next xx
\h'\n[lss]u'end sub
\h'\n[lss]u'See also
\h'\n[lss]u'arraydim and dim.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'asc() ? accepts a string and returns the position of its first character within
\h'\n[lss]u'the ascii charset
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=asc(char$)
\h'\n[lss]u'Description
\h'\n[lss]u'The asc-function accepts a string, takes its first character and looks it up
\h'\n[lss]u'within the ascii-charset; this position will be returned. The asc-function is
\h'\n[lss]u'the opposite of the chr$-function. There are valid uses for asc, however,
\h'\n[lss]u'comparing strings (i.e. to bring them into alphabetical sequence) is not among
\h'\n[lss]u'them; in such many cases you might consider to compare strings directly with <,
\h'\n[lss]u'= and > (rather than converting a string to a number and comparing this
\h'\n[lss]u'number).
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a letter between 'a' and 'y': " a$
\h'\n[lss]u'if (a$<"a" or a$>"y") print a$," is not in the proper range":end
\h'\n[lss]u'print "The letter after ",a$," is ",chr$(asc(a$)+1)
\h'\n[lss]u'See also
\h'\n[lss]u'chr$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'asin() ? returns the arcus sine of its numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'angle=asin(x)
\h'\n[lss]u'Description
\h'\n[lss]u'acos is the arcus sine-function, i.e. the inverse of the sin-function. Or, more
\h'\n[lss]u'elaborate: It Returns the angle (in radians, not degrees !), which, fed to the
\h'\n[lss]u'sine-function will produce the argument passed to the asin-function.
\h'\n[lss]u'Example
\h'\n[lss]u'print asin(0.5),asin(sin(pi))
\h'\n[lss]u'This will print 0.523599 -2.06823e-13 which is ? and almost 0 respectively.
\h'\n[lss]u'See also
\h'\n[lss]u'sin, acos
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'at() ? can be used in the print-command to place the output at a specified
\h'\n[lss]u'position
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'?
\h'\n[lss]u'print at(a,b)
\h'\n[lss]u'print @(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'The at-clause takes two numeric arguments (e.g. at(2,3)) and can be inserted
\h'\n[lss]u'after the print-keyword. at() can be used only if clear screen has been
\h'\n[lss]u'executed at least once within the program (otherwise you will get an error).
\h'\n[lss]u'The two numeric arguments of the at-function may range from 0 to the width of
\h'\n[lss]u'your terminal minus 1, and from 0 to the height of your terminal minus 1; if
\h'\n[lss]u'any argument exceeds these values, it will be truncated accordingly. However,
\h'\n[lss]u'yabasic has no influence on the size of your terminal (80x25 is a common, but
\h'\n[lss]u'not mandatory), the size of your terminal and the maximum values acceptable
\h'\n[lss]u'within the at-clause may vary. To get the size of your terminal you may use the
\h'\n[lss]u'peek-function: peek("screenwidth") returns the width of your terminal and peek
\h'\n[lss]u'("screenheight") its height.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'maxx=peek("screenwidth")-1:maxy=peek("screenheight")-1
\h'\n[lss]u'for x=0 to maxx
\h'\n[lss]u'print at(x,maxy*(0.5+sin(2*pi*x/maxx)/2)) "*"
\h'\n[lss]u'next x
\h'\n[lss]u'This example plots a full period of the sine-function across the screen.
\h'\n[lss]u'See also
\h'\n[lss]u'print, clear screen, color
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'atan() ? returns the arctangent of its numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'angle=atan(a,b)
\h'\n[lss]u'angle=atan(a)
\h'\n[lss]u'Description
\h'\n[lss]u'atan is the arctangent-function, i.e. the inverse of the tan-function. Or, more
\h'\n[lss]u'elaborate: It Returns the angle (in radians, not degrees !), which, fed to the
\h'\n[lss]u'tan-function will produce the argument passed to the atan-function.
\h'\n[lss]u'The atan-function has a second form, which accepts two arguments: atan(a,b)
\h'\n[lss]u'which is (mostly) equivalent to atan(a/b) except for the fact, that the
\h'\n[lss]u'two-argument-form returns an angle in the range -? to ?, whereas the
\h'\n[lss]u'one-argument-form returns an angle in the range -?/2 to ?/2. To understand this
\h'\n[lss]u'you have to be good at math.
\h'\n[lss]u'Example
\h'\n[lss]u'print atan(1),atan(tan(pi)),atan(-0,-1),atan(-0,1)
\h'\n[lss]u'This will print 0.463648 2.06823e-13 -3.14159 3.14159 which is ?/4, almost 0,
\h'\n[lss]u'-? and ? respectively.
\h'\n[lss]u'See also
\h'\n[lss]u'tan, sin
\h'\n[lss]u'B
\h'\n[lss]u'backcolor ? change color for background of graphic window
\h'\n[lss]u'backcolour ? see backcolor
\h'\n[lss]u'beep ? ring the bell within your computer; a synonym for bell
\h'\n[lss]u'bell ? ring the bell within your computer (just as beep)
\h'\n[lss]u'bin$() ? converts a number into a sequence of binary digits
\h'\n[lss]u'bind() ? Binds a yabasic-program and the yabasic-interpreter together into a
\h'\n[lss]u'standalone program.
\h'\n[lss]u'box ? draw a rectangle. A synonym for rectangle
\h'\n[lss]u'break ? breaks out of one or more loops or switch statements
\h'\n[lss]u'Name
\h'\n[lss]u'color ? change color for background of graphic window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'backcolour red,green,blue
\h'\n[lss]u'backcolour "red,green,blue"
\h'\n[lss]u'Description
\h'\n[lss]u'Change the color, that becomes visible, if any portion of the window is erased,
\h'\n[lss]u'e.g. after clear window or clear line. Note however, that parts of the window,
\h'\n[lss]u'that display the old background color will not change.
\h'\n[lss]u'As with the color-command, the new background color can either be specified as
\h'\n[lss]u'a triple of three numbers or as a single string, that contains those three
\h'\n[lss]u'numbers separated by commas.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 255,255
\h'\n[lss]u'for x=10 to 235 step 10:for y=10 to 235 step 10
\h'\n[lss]u'backcolour x,y,0
\h'\n[lss]u'clear window
\h'\n[lss]u'sleep 1
\h'\n[lss]u'next y:next x
\h'\n[lss]u'This changes the background colour of the graphic window repeatedly and clears
\h'\n[lss]u'it every time, so that it is filled with the new background colour.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, color, line, rectangle, triangle, circle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'backcolour ? see backcolor
\h'\n[lss]u'Synopsis
\h'\n[lss]u'backcolour red,green,blue
\h'\n[lss]u'backcolour "red,green,blue"
\h'\n[lss]u'See also
\h'\n[lss]u'color
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'beep ? ring the bell within your computer; a synonym for bell
\h'\n[lss]u'Synopsis
\h'\n[lss]u'beep
\h'\n[lss]u'Description
\h'\n[lss]u'The bell-command rings the bell within your computer once. This command is not
\h'\n[lss]u'a sound-interface, so you can neither vary the length or the height of the
\h'\n[lss]u'sound (technically, it just prints \a). bell is exactly the same as beep.
\h'\n[lss]u'Example
\h'\n[lss]u'beep:print "This is a problem ..."
\h'\n[lss]u'See also
\h'\n[lss]u'beep
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'bell ? ring the bell within your computer (just as beep)
\h'\n[lss]u'Synopsis
\h'\n[lss]u'bell
\h'\n[lss]u'Description
\h'\n[lss]u'The beep-command rings the bell within your computer once. beep is a synonym
\h'\n[lss]u'for bell.
\h'\n[lss]u'Example
\h'\n[lss]u'print "This is a problem ...":beep
\h'\n[lss]u'See also
\h'\n[lss]u'bell
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'bin$() ? converts a number into a sequence of binary digits
\h'\n[lss]u'Synopsis
\h'\n[lss]u'hexadecimal$=bin$(decimal)
\h'\n[lss]u'Description
\h'\n[lss]u'The bin$-function takes a single numeric argument an converts it into a string
\h'\n[lss]u'of binary digits (i.e. zeroes and ones). If you pass a negative number to bin$,
\h'\n[lss]u'the resulting string will be preceded by a '-'.
\h'\n[lss]u'If you want to convert the other way around (i.e. from binary to decimal) you
\h'\n[lss]u'may use the dec-function.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 100
\h'\n[lss]u'print bin$(a)
\h'\n[lss]u'next a
\h'\n[lss]u'This example prints the binary representation of all digits between 1 and 100.
\h'\n[lss]u'See also
\h'\n[lss]u'hex$, dec
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'bind() ? Binds a yabasic-program and the yabasic-interpreter together into a
\h'\n[lss]u'standalone program.
\h'\n[lss]u'Synopsis
\h'\n[lss]u'bind("foo.exe")
\h'\n[lss]u'Description
\h'\n[lss]u'The bind-command combines your own yabasic-program (plus all the libraries it
\h'\n[lss]u'does import) and the interpreter by copying them into a new file, whose name is
\h'\n[lss]u'passed as an argument. This new program may then be executed on any computer,
\h'\n[lss]u'even if it does not have yabasic installed.
\h'\n[lss]u'Please see the section about creating a standalone-program for details.
\h'\n[lss]u'Example
\h'\n[lss]u'if (!peek("isbound")) then
\h'\n[lss]u'bind "foo"
\h'\n[lss]u'print "Successfully created the standalone executable 'foo' !"
\h'\n[lss]u'exit
\h'\n[lss]u'endif
\h'\n[lss]u'print "Hello World !"
\h'\n[lss]u'This example creates a standalone program foo from itself.
\h'\n[lss]u'See also
\h'\n[lss]u'The section about creating a standalone-program, the peek-function and the
\h'\n[lss]u'command line options.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'box ? draw a rectangle. A synonym for rectangle
\h'\n[lss]u'Synopsis
\h'\n[lss]u'See the rectangle-command.
\h'\n[lss]u'Description
\h'\n[lss]u'The box-command does exactly the same as the rectangle-command; it is just a
\h'\n[lss]u'synonym. Therefore you should refer to the entry for the rectangle-command for
\h'\n[lss]u'further information.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'break ? breaks out of one or more loops or switch statements
\h'\n[lss]u'Synopsis
\h'\n[lss]u'break
\h'\n[lss]u'break 2
\h'\n[lss]u'Description
\h'\n[lss]u'break transfers control immediately outside the enclosing loop or switch
\h'\n[lss]u'statement. This is the preferred way of leaving a such a statement (rather than
\h'\n[lss]u'goto, which is still possible in most cases). An optional digit allows one to
\h'\n[lss]u'break out of multiple levels, e.g. to leave a loop from within a switch
\h'\n[lss]u'statement. Please note, that only a literal (e.g. 2) is allowed at this
\h'\n[lss]u'location.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'break
\h'\n[lss]u'print "Hi"
\h'\n[lss]u'next a
\h'\n[lss]u'while(1)
\h'\n[lss]u'break
\h'\n[lss]u'print "Hi"
\h'\n[lss]u'wend
\h'\n[lss]u'repeat
\h'\n[lss]u'break
\h'\n[lss]u'print "Hi"
\h'\n[lss]u'until(0)
\h'\n[lss]u'switch 1
\h'\n[lss]u'case 1:break
\h'\n[lss]u'case 2:case 3:print "Hi"
\h'\n[lss]u'end switch
\h'\n[lss]u'This example prints nothing at all, because each of the loops (and the
\h'\n[lss]u'switch-statement) does an immediate break (before it could print any "Hi").
\h'\n[lss]u'See also
\h'\n[lss]u'for, while, repeat and switch.
\h'\n[lss]u'C
\h'\n[lss]u'case ? mark the different cases within a switch-statement
\h'\n[lss]u'ceil() ? compute the ceiling for its (float) argument.
\h'\n[lss]u'chomp$() ? Remove a single trailing newline from its string-argument; if the
\h'\n[lss]u'string does not end in a newline, the string is returned unchanged.
\h'\n[lss]u'chr$() ? accepts a number and returns the character at this position within the
\h'\n[lss]u'ascii charset
\h'\n[lss]u'circle ? draws a circle in the graphic-window
\h'\n[lss]u'clear ? Erase circles, rectangles or triangles
\h'\n[lss]u'clear screen ? erases the text window
\h'\n[lss]u'clear window ? clear the graphic window and begin a new page, if printing is
\h'\n[lss]u'under way
\h'\n[lss]u'close ? close a file, which has been opened before
\h'\n[lss]u'close curve ? close a curve, that has been drawn by the line-command
\h'\n[lss]u'close printer ? stops printing of graphics
\h'\n[lss]u'close window ? close the graphics-window
\h'\n[lss]u'color ? change color for any subsequent drawing-command
\h'\n[lss]u'colour ? see color
\h'\n[lss]u'compile ? compile a string with yabasic-code on the fly
\h'\n[lss]u'continue ? start the next iteration of a for-, do-, repeat- or while-loop
\h'\n[lss]u'cos() ? return the cosine of its single argument
\h'\n[lss]u'Name
\h'\n[lss]u'case ? mark the different cases within a switch-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'switch a
\h'\n[lss]u'case 1
\h'\n[lss]u'case 2
\h'\n[lss]u'?
\h'\n[lss]u'end switch
\h'\n[lss]u'?
\h'\n[lss]u'switch a$
\h'\n[lss]u'case "a"
\h'\n[lss]u'case "b"
\h'\n[lss]u'?
\h'\n[lss]u'end switch
\h'\n[lss]u'Description
\h'\n[lss]u'Please see the switch-statement.
\h'\n[lss]u'Example
\h'\n[lss]u'input a
\h'\n[lss]u'switch(a)
\h'\n[lss]u'case 1:print "one":break
\h'\n[lss]u'case 2:print "two":break
\h'\n[lss]u'default:print "more"
\h'\n[lss]u'end switch
\h'\n[lss]u'Depending on your input (a number is expected) this code will print one or two
\h'\n[lss]u'or otherwise more.
\h'\n[lss]u'See also
\h'\n[lss]u'switch
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'ceil() ? compute the ceiling for its (float) argument.
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print ceil(x)
\h'\n[lss]u'Description
\h'\n[lss]u'The ceil-function returns the smallest integer number, that is larger or equal
\h'\n[lss]u'than its argument.
\h'\n[lss]u'Example
\h'\n[lss]u'print ceil(1.5),floor(1.5)
\h'\n[lss]u'print ceil(2),floor(2)
\h'\n[lss]u'Comparing functions ceil and floor, gives a first line of output (1 2), showing
\h'\n[lss]u'that ceil is less or equal than floor; but as the second line of output (2 2)
\h'\n[lss]u'shows, the two functions give equal results for integer arguments.
\h'\n[lss]u'See also
\h'\n[lss]u'floor, int, frac
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'chomp$() ? Remove a single trailing newline from its string-argument; if the
\h'\n[lss]u'string does not end in a newline, the string is returned unchanged.
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print chomp$("Hallo !\n")
\h'\n[lss]u'Description
\h'\n[lss]u'The chomp$-function checks, if its string-argument ends in a newline and
\h'\n[lss]u'removes it eventually; for this purpose chomp$ can replace an if-statement.
\h'\n[lss]u'This can be especially useful, when you deal with input from external sources
\h'\n[lss]u'like system$.
\h'\n[lss]u'You may apply chomp$ freely, as it only acts, if there is a newline to remove;
\h'\n[lss]u'note however, that user-input, that comes from the normal input-statement, does
\h'\n[lss]u'not need such a treatment, because it already comes without a newline.
\h'\n[lss]u'Example
\h'\n[lss]u'The following yabasic-program uses the unix-command whoami to get the username
\h'\n[lss]u'of the current user in order to greet him personally. This is done twice: First
\h'\n[lss]u'with the chomp$-function and then again with with an equivalent if-statement:
\h'\n[lss]u'print "Hello " + chomp$(system$("whoami")) + " !"
\h'\n[lss]u'user$ = system$("whoami")
\h'\n[lss]u'if (right$(user$,1)="\n") user$=left$(user$,len(user$)-1)
\h'\n[lss]u'print "Hello again " + user$ + " !"
\h'\n[lss]u'See also
\h'\n[lss]u'system$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'chr$() ? accepts a number and returns the character at this position within the
\h'\n[lss]u'ascii charset
\h'\n[lss]u'Synopsis
\h'\n[lss]u'character$=chr$(ascii)
\h'\n[lss]u'Description
\h'\n[lss]u'The chr$-function is the opposite of the asc-function. It looks up and returns
\h'\n[lss]u'the character at the given position within the ascii-charset. It's typical use
\h'\n[lss]u'is to construct nonprintable characters which do not occur on your keyboard.
\h'\n[lss]u'Nevertheless you won't use chr$ as often as you might think, because the most
\h'\n[lss]u'important nonprintable characters can be constructed using escape-sequences
\h'\n[lss]u'using the \-character (e.g. you might use \n instead of chr$(10) wherever you
\h'\n[lss]u'want to use the newline-character).
\h'\n[lss]u'Example
\h'\n[lss]u'print "a",chr$(10),"b"
\h'\n[lss]u'This will print the letters 'a' and 'b' in different lines because of the
\h'\n[lss]u'intervening newline-character, which is returned by chr$(10).
\h'\n[lss]u'See also
\h'\n[lss]u'asc
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'circle ? draws a circle in the graphic-window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'circle x,y,r
\h'\n[lss]u'clear circle x,y,r
\h'\n[lss]u'fill circle x,y,r
\h'\n[lss]u'clear fill circle x,y,r
\h'\n[lss]u'Description
\h'\n[lss]u'The circle-command accepts three parameters: The x- and y-coordinates of the
\h'\n[lss]u'center and the radius of the circle.
\h'\n[lss]u'Some more observations related with the circle-command:
\h'\n[lss]u'* The graphic-window must have been opened already.
\h'\n[lss]u'* The circle may well extend over the boundaries of the window.
\h'\n[lss]u'* If you have issued open printer before, the circle will finally appear in
\h'\n[lss]u'the printed hard copy of the window.
\h'\n[lss]u'* fill circle will draw a filled (with black ink) circle.
\h'\n[lss]u'* clear circle will erase (or clear) the outline of the circle.
\h'\n[lss]u'* clear fill circle or fill clear circle will erase the full area of the
\h'\n[lss]u'circle.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'for n=1 to 2000
\h'\n[lss]u'x=ran(200)
\h'\n[lss]u'y=ran(200)
\h'\n[lss]u'fill circle x,y,10
\h'\n[lss]u'clear fill circle x,y,8
\h'\n[lss]u'next n
\h'\n[lss]u'This code will open a window and draw 2000 overlapping circles within. Each
\h'\n[lss]u'circle is drawn in two steps: First it is filled with black ink (fill circle
\h'\n[lss]u'x,y,10), then most of this circle is erased again (clear fill circle x,y,8). As
\h'\n[lss]u'a result each circle is drawn with an opaque white interior and a 2-pixel
\h'\n[lss]u'outline (2-pixel, because the radii differ by two).
\h'\n[lss]u'See also
\h'\n[lss]u'open window, open printer, line, rectangle, triangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'clear ? Erase circles, rectangles or triangles
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear rectangle 10,10,90,90
\h'\n[lss]u'clear fill circle 50,50,20
\h'\n[lss]u'clear triangle 10,10,20,20,50,30
\h'\n[lss]u'Description
\h'\n[lss]u'May be used within the circle, rectangle or triangle command and causes these
\h'\n[lss]u'shapes to be erased (i.e. be drawn in the colour of the background).
\h'\n[lss]u'fill can be used in conjunction with and wherever the fill-clause may appear.
\h'\n[lss]u'Used alone, clear will erase the outline (not the interior) of the shape
\h'\n[lss]u'(circle, rectangle or triangle); together with fill the whole shape (including
\h'\n[lss]u'its interior) is erased.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'fill circle 100,100,50
\h'\n[lss]u'clear fill rectangle 10,10,90,90
\h'\n[lss]u'This opens a window and draws a pacman-like figure.
\h'\n[lss]u'See also
\h'\n[lss]u'clear, circle, rectangle, triangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'clear screen ? erases the text window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'Description
\h'\n[lss]u'clear screen erases the text window (the window where the output of print
\h'\n[lss]u'appears).
\h'\n[lss]u'It must be issued at least once, before some advanced screen-commands (e.g.
\h'\n[lss]u'print at or inkey$) may be called; this requirement is due to some limitations
\h'\n[lss]u'of the curses-library, which is used by yabasic under Unix for some commands.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'print "Please press a key : ";
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print a$
\h'\n[lss]u'The clear screen command is essential here; if it would be omitted, yabasic
\h'\n[lss]u'would issue an error ("need to call 'clear screen' first") while trying to
\h'\n[lss]u'execute the inkey$-function.
\h'\n[lss]u'See also
\h'\n[lss]u'inkey$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'clear window ? clear the graphic window and begin a new page, if printing is
\h'\n[lss]u'under way
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear window
\h'\n[lss]u'Description
\h'\n[lss]u'clear window clears the graphic window. If you have started printing the
\h'\n[lss]u'graphic via open printer, the clear window-command starts a new page as well.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'open printer "t.ps"
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'if (a>1) clear window
\h'\n[lss]u'text 100,100,"Hallo "+str$(a)
\h'\n[lss]u'next a
\h'\n[lss]u'close printer
\h'\n[lss]u'close window
\h'\n[lss]u'This example prints 10 pages, with the text "Hello 1", "Hello 2", ? and so on.
\h'\n[lss]u'The clear screen-command clears the graphics window and starts a new page.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, open printer
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'close ? close a file, which has been opened before
\h'\n[lss]u'Synopsis
\h'\n[lss]u'close filenum
\h'\n[lss]u'close # filenum
\h'\n[lss]u'Description
\h'\n[lss]u'The close-command closes an open file. You should issue this command as soon as
\h'\n[lss]u'you are done with reading from or writing to a file.
\h'\n[lss]u'Example
\h'\n[lss]u'open "my.data" for reading as 1
\h'\n[lss]u'input #1 a
\h'\n[lss]u'print a
\h'\n[lss]u'close 1
\h'\n[lss]u'This program opens the file "my.data", reads a number from it, prints this
\h'\n[lss]u'number and closes the file again.
\h'\n[lss]u'See also
\h'\n[lss]u'open
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'close curve ? close a curve, that has been drawn by the line-command
\h'\n[lss]u'Synopsis
\h'\n[lss]u'new curve
\h'\n[lss]u'line to x1,y1
\h'\n[lss]u'?
\h'\n[lss]u'close curve
\h'\n[lss]u'Description
\h'\n[lss]u'The close curve-command closes a sequence of lines, that has been drawn by
\h'\n[lss]u'repeated line to-commands.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'new curve
\h'\n[lss]u'line to 100,50
\h'\n[lss]u'line to 150,150
\h'\n[lss]u'line to 50,150
\h'\n[lss]u'close curve
\h'\n[lss]u'This example draws a triangle: The three line to-commands draw two lines; the
\h'\n[lss]u'final line is however not drawn explicitly, but drawn by the close
\h'\n[lss]u'curve-command.
\h'\n[lss]u'See also
\h'\n[lss]u'line, new curve
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'close printer ? stops printing of graphics
\h'\n[lss]u'Synopsis
\h'\n[lss]u'close printer
\h'\n[lss]u'Description
\h'\n[lss]u'The close printer-command ends the printing graphics. Between open printer and
\h'\n[lss]u'close printer everything you draw (e.g. circles, lines ?) is sent to your
\h'\n[lss]u'printer. close printer puts an end to printing and will make your printer eject
\h'\n[lss]u'the page.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'open printer
\h'\n[lss]u'circle 100,100,50
\h'\n[lss]u'close printer
\h'\n[lss]u'close window
\h'\n[lss]u'As soon as close printer is executed, your printer will eject a page with a
\h'\n[lss]u'circle on it.
\h'\n[lss]u'See also
\h'\n[lss]u'open printer
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'close window ? close the graphics-window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'close window
\h'\n[lss]u'Description
\h'\n[lss]u'The close window-command closes the graphics-window, i.e. it makes it disappear
\h'\n[lss]u'from your screen. It includes an implicit close printer, if a printer has been
\h'\n[lss]u'opened previously.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'circle 100,100,50
\h'\n[lss]u'close window
\h'\n[lss]u'This example will open a window, draw a circle and close the window again; all
\h'\n[lss]u'this without any pause or delay, so the window will be closed before you may
\h'\n[lss]u'regard the circle..
\h'\n[lss]u'See also
\h'\n[lss]u'open window
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'color ? change color for any subsequent drawing-command
\h'\n[lss]u'Synopsis
\h'\n[lss]u'colour red,green,blue
\h'\n[lss]u'colour "red,green,blue"
\h'\n[lss]u'Description
\h'\n[lss]u'Change the color, in which lines, dots, circles, rectangles or triangles are
\h'\n[lss]u'drawn. The color-command accepts three numbers in the range 0 ? 255 (as in the
\h'\n[lss]u'first line of the synopsis above). Those numbers specify the intensity for the
\h'\n[lss]u'primary colors red, green and blue respectively. As an example 255,0,0 is red
\h'\n[lss]u'and 255,255,0 is yellow.
\h'\n[lss]u'Alternatively you may specify the color with a single string (as in the second
\h'\n[lss]u'line of the synopsis above); this string should contain three numbers,
\h'\n[lss]u'separated by commas. As an example "255,0,255" would be violet. Using this
\h'\n[lss]u'variant of the colour-command, you may use symbolic names for colours:
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'yellow$="255,255,0"
\h'\n[lss]u'color yellow$
\h'\n[lss]u'text 50,50,"Hallo"
\h'\n[lss]u', which reads much clearer.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 255,255
\h'\n[lss]u'for x=10 to 235 step 10:for y=10 to 235 step 10
\h'\n[lss]u'colour x,y,0
\h'\n[lss]u'fill rectangle x,y,x+10,y+10
\h'\n[lss]u'next y:next x
\h'\n[lss]u'This fills the window with colored rectangles. However, none of the used
\h'\n[lss]u'colours contains any shade of blue, because the color-command has always 0 as a
\h'\n[lss]u'third argument.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, backcolor, line, rectangle, triangle, circle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'colour ? see color
\h'\n[lss]u'Synopsis
\h'\n[lss]u'colour red,green,blue
\h'\n[lss]u'colour "red,green,blue"
\h'\n[lss]u'See also
\h'\n[lss]u'color
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'compile ? compile a string with yabasic-code on the fly
\h'\n[lss]u'Synopsis
\h'\n[lss]u'compile(code$)
\h'\n[lss]u'Description
\h'\n[lss]u'This is an advanced command (closely related with the execute-command). It
\h'\n[lss]u'allows you to compile a string of yabasic-code (which is the only argument).
\h'\n[lss]u'Afterwards the compiled code is a normal part of your program.
\h'\n[lss]u'Note, that there is no way to remove the compiled code.
\h'\n[lss]u'Example
\h'\n[lss]u'compile("sub mysub(a):print a:end sub")
\h'\n[lss]u'mysub(2)
\h'\n[lss]u'This example creates a function named mysub, which simply prints its single
\h'\n[lss]u'argument.
\h'\n[lss]u'See also
\h'\n[lss]u'execute
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'continue ? start the next iteration of a for-, do-, repeat- or while-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'continue
\h'\n[lss]u'Description
\h'\n[lss]u'You may use continue within any loop to start the next iteration immediately.
\h'\n[lss]u'Depending on the type of the loop, the loop-condition will or will not be
\h'\n[lss]u'checked. Especially: for- and while-loops will evaluate their respective
\h'\n[lss]u'conditions, do- and repeat-loops will not.
\h'\n[lss]u'Remark: Another way to change the flow of execution within a loop, is the
\h'\n[lss]u'break-command.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 100
\h'\n[lss]u'if mod(a,2)=0 continue
\h'\n[lss]u'print a
\h'\n[lss]u'next a
\h'\n[lss]u'This example will print all odd numbers between 1 and 100.
\h'\n[lss]u'See also
\h'\n[lss]u'for, do, repeat, while, break
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'cos() ? return the cosine of its single argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=cos(angle)
\h'\n[lss]u'Description
\h'\n[lss]u'The cos-function expects an angle (in radians) and returns its cosine.
\h'\n[lss]u'Example
\h'\n[lss]u'print cos(pi)
\h'\n[lss]u'This example will print -1.
\h'\n[lss]u'See also
\h'\n[lss]u'acos, sin
\h'\n[lss]u'D
\h'\n[lss]u'data ? introduces a list of data-items
\h'\n[lss]u'date$ ? returns a string with various components of the current date
\h'\n[lss]u'dec() ? convert a base 2 or base 16 number into decimal form
\h'\n[lss]u'default ? mark the default-branch within a switch-statement
\h'\n[lss]u'dim ? create an array prior to its first use
\h'\n[lss]u'do ? start a (conditionless) do-loop
\h'\n[lss]u'doc ? special comment, which might be retrieved by the program itself
\h'\n[lss]u'docu$ ? special array, containing the contents of all docu-statement within the
\h'\n[lss]u'program
\h'\n[lss]u'dot ? draw a dot in the graphic-window
\h'\n[lss]u'Name
\h'\n[lss]u'data ? introduces a list of data-items
\h'\n[lss]u'Synopsis
\h'\n[lss]u'data 9,"world"
\h'\n[lss]u'?
\h'\n[lss]u'read b,a$
\h'\n[lss]u'Description
\h'\n[lss]u'The data-keyword introduces a list of comma-separated list of strings or
\h'\n[lss]u'numbers, which may be retrieved with the read-command.
\h'\n[lss]u'The data-command itself does nothing; it just stores data. A single
\h'\n[lss]u'data-command may precede an arbitrarily long list of values, in which strings
\h'\n[lss]u'or numbers may be mixed at will.
\h'\n[lss]u'yabasic internally uses a data-pointer to keep track of the current location
\h'\n[lss]u'within the data-list; this pointer may be reset with the restore-command.
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'restore
\h'\n[lss]u'for a=1 to 4
\h'\n[lss]u'read num$,num
\h'\n[lss]u'print num$,"=",num
\h'\n[lss]u'next a
\h'\n[lss]u'loop
\h'\n[lss]u'data "eleven",11,"twelve",12,"thirteen",13,"fourteen",14
\h'\n[lss]u'This example just prints a series of lines eleven=11 up to fourteen=14 and so
\h'\n[lss]u'on without end.
\h'\n[lss]u'The restore-command ensures that the list of data-items is read from the start
\h'\n[lss]u'with every iteration.
\h'\n[lss]u'See also
\h'\n[lss]u'read, restore
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'date$ ? returns a string with various components of the current date
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=date$
\h'\n[lss]u'Description
\h'\n[lss]u'The date$-function (which must be called without parentheses; i.e. date$()
\h'\n[lss]u'would be an error) returns a string containing various components of a date; an
\h'\n[lss]u'example would be 4-05-27-2004-Thu-May. This string consists of various fields
\h'\n[lss]u'separated by hyphens ("-"):
\h'\n[lss]u'* The day within the week as a number in the range 0 (=Sunday) to 6 (=
\h'\n[lss]u'Saturday) (in the example above: 4, i.e. Thursday).
\h'\n[lss]u'* The month as a number in the range 1 (=January) to 12 (=December) (in the
\h'\n[lss]u'example: 5 which stands for May).
\h'\n[lss]u'* The day within the month as a number in the range 1 to 31 (in the example:
\h'\n[lss]u'27).
\h'\n[lss]u'* The full, 4-digit year (in the example: 2004, which reminds me that I
\h'\n[lss]u'should adjust the clock within my computer ?).
\h'\n[lss]u'* The abbreviated name of the day within the week (Mon to Sun).
\h'\n[lss]u'* The abbreviated name of the month (Jan to Dec).
\h'\n[lss]u'Therefore the whole example above (4-05-27-2004-Thu-May) would read: day 4 in
\h'\n[lss]u'the week (counting from 0), May 27 in the year 2004, which is a Thursday in
\h'\n[lss]u'May.
\h'\n[lss]u'Note, that all fields within the string returned by date$ have a fixed with
\h'\n[lss]u'(numbers are padded with zeroes); therefore it is easy to extract the various
\h'\n[lss]u'fields of a date format with mid$.
\h'\n[lss]u'Example
\h'\n[lss]u'rem Two ways to print the same ...
\h'\n[lss]u'print mid$(date$,3,10)
\h'\n[lss]u'dim fields$(6)
\h'\n[lss]u'a=split(date$,fields$(),"-")
\h'\n[lss]u'print fields$(2),"-",fields$(3),"-",fields$(4)
\h'\n[lss]u'This example shows two different techniques to extract components from the
\h'\n[lss]u'value returned by date$. The mid$-function is the preferred way, but you could
\h'\n[lss]u'just as well split the return-value of date$ at every "-" and store the result
\h'\n[lss]u'within an array of strings.
\h'\n[lss]u'See also
\h'\n[lss]u'time$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'dec() ? convert a base 2 or base 16 number into decimal form
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=dec(number$)
\h'\n[lss]u'a=dec(number$,base)
\h'\n[lss]u'Description
\h'\n[lss]u'The dec-function takes the string-representation of a base-2 or base-16 (which
\h'\n[lss]u'is the default) number and converts it into a decimal number. The optional
\h'\n[lss]u'second argument (base) might be used to specify a base other than 16. However,
\h'\n[lss]u'currently only base 2 or base 16 are supported. Please note, that for base 16
\h'\n[lss]u'you may write literals in the usual way, by preceding them with 0x, e.g. like
\h'\n[lss]u'print 0xff
\h'\n[lss]u'; this may save you from applying the dec altogether.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a binary number: " a$
\h'\n[lss]u'print a$," is ",dec(a$)
\h'\n[lss]u'See also
\h'\n[lss]u'bin$, hex$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'default ? mark the default-branch within a switch-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'switch a+3
\h'\n[lss]u'case 1
\h'\n[lss]u'?
\h'\n[lss]u'case 2
\h'\n[lss]u'?
\h'\n[lss]u'default
\h'\n[lss]u'?
\h'\n[lss]u'end switch
\h'\n[lss]u'Description
\h'\n[lss]u'The default-clause is an optional part of the switch-statement (see there for
\h'\n[lss]u'more information). It introduces a series of statements, that should be
\h'\n[lss]u'executed, if none of the cases matches, that have been specified before (each
\h'\n[lss]u'with its own case-clause).
\h'\n[lss]u'So default specifies a default to be executed, if none of the explicitly named
\h'\n[lss]u'cases matches; hence its name.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Please enter a number between 0 and 6,"
\h'\n[lss]u'print "specifying a day in the week."
\h'\n[lss]u'input d
\h'\n[lss]u'switch d
\h'\n[lss]u'case 0:print "Monday":break
\h'\n[lss]u'case 1:print "Tuesday":break
\h'\n[lss]u'case 2:print "Wednesday":break
\h'\n[lss]u'case 3:print "Thursday":break
\h'\n[lss]u'case 4:print "Friday":break
\h'\n[lss]u'case 5:print "Saturday":break
\h'\n[lss]u'case 6:print "Sunday":break
\h'\n[lss]u'default:print "Hey you entered something invalid !"
\h'\n[lss]u'end switch
\h'\n[lss]u'This program translates a number between 0 and 6 into the name of a weekday;
\h'\n[lss]u'the default-case is used to detect (and complain about) invalid input.
\h'\n[lss]u'See also
\h'\n[lss]u'sub, case
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'dim ? create an array prior to its first use
\h'\n[lss]u'Synopsis
\h'\n[lss]u'dim array(x,y)
\h'\n[lss]u'dim array$(x,y)
\h'\n[lss]u'Description
\h'\n[lss]u'The dim-command prepares one or more arrays (of either strings or numbers) for
\h'\n[lss]u'later use. This command can also be used to enlarges an existing array.
\h'\n[lss]u'When an array is created with the dim-statement, memory is allocated and all
\h'\n[lss]u'elements are initialized with either 0 (for numerical arrays) or "" (for string
\h'\n[lss]u'arrays).
\h'\n[lss]u'If the array already existed, and the dim-statement specifies a larger size
\h'\n[lss]u'than the current size, the array is enlarged and any old content is preserved.
\h'\n[lss]u'Note, that dim cannot be used to shrink an array: If you specify a size, that
\h'\n[lss]u'is smaller than the current size, the dim-command does nothing.
\h'\n[lss]u'Finally: To create an array, that is only known within a single subroutine, you
\h'\n[lss]u'should use the command local, which creates local variables as well as local
\h'\n[lss]u'arrays.
\h'\n[lss]u'Example
\h'\n[lss]u'dim a(5,5)
\h'\n[lss]u'for x=1 to 5:for y=1 to 5
\h'\n[lss]u'a(x,y)=int(ran(100))
\h'\n[lss]u'next y:next x
\h'\n[lss]u'printmatrix(a())
\h'\n[lss]u'dim a(7,7)
\h'\n[lss]u'printmatrix(a())
\h'\n[lss]u'sub printmatrix(ar())
\h'\n[lss]u'local x,y,p,q
\h'\n[lss]u'x=arraysize(ar(),1)
\h'\n[lss]u'y=arraysize(ar(),2)
\h'\n[lss]u'for q=1 to y
\h'\n[lss]u'for p=1 to y
\h'\n[lss]u'print ar(p,q),"\t";
\h'\n[lss]u'next p
\h'\n[lss]u'print
\h'\n[lss]u'next q
\h'\n[lss]u'end sub
\h'\n[lss]u'This example creates a 2-dimensional array (i.e. a matrix) with the
\h'\n[lss]u'dim-statement and fills it with random numbers. The second dim-statement
\h'\n[lss]u'enlarges the array, all new elements are filled with 0.
\h'\n[lss]u'The subroutine printmatrix just does, what its name says.
\h'\n[lss]u'See also
\h'\n[lss]u'arraysize, arraydim, local
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'do ? start a (conditionless) do-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'do
\h'\n[lss]u'?
\h'\n[lss]u'loop
\h'\n[lss]u'Description
\h'\n[lss]u'Starts a loop, which is terminated by loop; everything between do and loop will
\h'\n[lss]u'be repeated forever. This loop has no condition, so it is an infinite loop;
\h'\n[lss]u'note however, that a break- or goto-statement might be used to leave this loop
\h'\n[lss]u'anytime.
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'a=a+1
\h'\n[lss]u'print a
\h'\n[lss]u'if (a>100) break
\h'\n[lss]u'loop
\h'\n[lss]u'This example prints the numbers between 1 and 101. The break-statement is used
\h'\n[lss]u'to leave the loop.
\h'\n[lss]u'See also
\h'\n[lss]u'loop, repeat, while, break
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'doc ? special comment, which might be retrieved by the program itself
\h'\n[lss]u'Synopsis
\h'\n[lss]u'doc This is a comment
\h'\n[lss]u'docu This is another comment
\h'\n[lss]u'Description
\h'\n[lss]u'Introduces a comment, which spans up to the end of the line. But other than the
\h'\n[lss]u'rem-comment, any docu-comment is collected within the special docu$-array and
\h'\n[lss]u'might be retrieved later on. Moreover you might invoke yabasic -docu foo.yab on
\h'\n[lss]u'the command line to retrieve the embedded documentation within the program
\h'\n[lss]u'foo.yab.
\h'\n[lss]u'Instead of doc you may just as well write docu or even documentation.
\h'\n[lss]u'Example
\h'\n[lss]u'rem Hi, this has been written by me
\h'\n[lss]u'rem
\h'\n[lss]u'doc This program asks for a number and
\h'\n[lss]u'doc prints this number multiplied with 2
\h'\n[lss]u'rem
\h'\n[lss]u'rem Print out rhe above message
\h'\n[lss]u'for a=1 to arraysize(docu$()):print docu$(a):next a
\h'\n[lss]u'rem Read and print the number
\h'\n[lss]u'input "Please input a number: " x
\h'\n[lss]u'print x*2
\h'\n[lss]u'This program uses the comments within its code to print out a help message for
\h'\n[lss]u'the user.
\h'\n[lss]u'The contents of the doc-lines are retrieved from the docu$-array; if you do not
\h'\n[lss]u'want a comment to be collected within this array, use the rem-statement
\h'\n[lss]u'instead.
\h'\n[lss]u'See also
\h'\n[lss]u'docu$, rem
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'docu$ ? special array, containing the contents of all docu-statement within the
\h'\n[lss]u'program
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=docu$(1)
\h'\n[lss]u'Description
\h'\n[lss]u'Before your program is executed, yabasic collects the content of all the
\h'\n[lss]u'doc-statements within your program within this 1-dimensional array (well only
\h'\n[lss]u'those within the main-program, libraries are skipped).
\h'\n[lss]u'You may use the arraysize function to find out, how many lines it contains.
\h'\n[lss]u'Example
\h'\n[lss]u'docu
\h'\n[lss]u'docu This program reads two numbers
\h'\n[lss]u'docu and adds them.
\h'\n[lss]u'docu
\h'\n[lss]u'rem retrieve and print the embedded documentation
\h'\n[lss]u'for a=1 to arraysize(docu$(),1)
\h'\n[lss]u'print docu$(a)
\h'\n[lss]u'next a
\h'\n[lss]u'input "First number: " b
\h'\n[lss]u'input "Second number: " c
\h'\n[lss]u'print "The sum of ",b," and ",c," is ",b+c
\h'\n[lss]u'This program uses the embedded documentation to issue a usage-message.
\h'\n[lss]u'See also
\h'\n[lss]u'arraydim, rem
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'dot ? draw a dot in the graphic-window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'dot x,y
\h'\n[lss]u'clear dot x,y
\h'\n[lss]u'Description
\h'\n[lss]u'Draws a dot at the specified coordinates within your graphic-window. If
\h'\n[lss]u'printing is in effect, the dot appears on your printout too.
\h'\n[lss]u'Use the functions peek("winheight") or peek("winwidth") to get the size of your
\h'\n[lss]u'window and hence the boundaries of the coordinates specified for the
\h'\n[lss]u'dot-command.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'circle 100,100,100
\h'\n[lss]u'do
\h'\n[lss]u'x=ran(200):y=ran(200)
\h'\n[lss]u'dot x,y
\h'\n[lss]u'total=total+1
\h'\n[lss]u'if (sqrt((x-100)^2+(y-100)^2)<100) in=in+1
\h'\n[lss]u'print 4*in/total
\h'\n[lss]u'loop
\h'\n[lss]u'This program uses a well known algorithm to compute ?.
\h'\n[lss]u'See also
\h'\n[lss]u'line, open window
\h'\n[lss]u'E
\h'\n[lss]u'else ? mark an alternative within an if-statement
\h'\n[lss]u'elsif ? starts an alternate condition within an if-statement
\h'\n[lss]u'end ? terminate your program
\h'\n[lss]u'endif ? ends an if-statement
\h'\n[lss]u'end sub ? ends a subroutine definition
\h'\n[lss]u'eof ? check, if an open file contains data
\h'\n[lss]u'eor() ? compute the bitwise exclusive or of its two arguments
\h'\n[lss]u'error ? raise an error and terminate your program
\h'\n[lss]u'euler ? another name for the constant 2.71828182864
\h'\n[lss]u'execute$() ? execute a user defined subroutine, which must return a string
\h'\n[lss]u'execute() ? execute a user defined subroutine, which must return a number
\h'\n[lss]u'exit ? terminate your program
\h'\n[lss]u'exp() ? compute the exponential function of its single argument
\h'\n[lss]u'export ? mark a function as globally visible
\h'\n[lss]u'Name
\h'\n[lss]u'else ? mark an alternative within an if-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'else
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'Description
\h'\n[lss]u'The else-statement introduces the alternate branch of an if-statement. I.e. it
\h'\n[lss]u'starts the sequence of statements, which is executed, if the condition of the
\h'\n[lss]u'if-statement is not true.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number: " a
\h'\n[lss]u'if (mod(a,2)=1) then
\h'\n[lss]u'print a," is odd."
\h'\n[lss]u'else
\h'\n[lss]u'print a," is even."
\h'\n[lss]u'endif
\h'\n[lss]u'This program detects, if the number you have entered is even or odd.
\h'\n[lss]u'See also
\h'\n[lss]u'if
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'elsif ? starts an alternate condition within an if-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'elseif (?)
\h'\n[lss]u'?
\h'\n[lss]u'elsif (?) then
\h'\n[lss]u'?
\h'\n[lss]u'else
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'Description
\h'\n[lss]u'The elsif-statement is used to select a single alternative among a series of
\h'\n[lss]u'choices.
\h'\n[lss]u'With each elsif-statement you may specify a condition, which is tested, if the
\h'\n[lss]u'main condition (specified with the if-statement) has failed. Note that elsif
\h'\n[lss]u'might be just as well written as elseif.
\h'\n[lss]u'Within the example below, two variables a and b are tested against a range of
\h'\n[lss]u'values. The variable a is tested with the elsif-statement. The very same tests
\h'\n[lss]u'are performed for the variable b too; but here an involved series of
\h'\n[lss]u'if-else-statements is employed, making the tests much more obscure.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number: " a
\h'\n[lss]u'if (a<0) then
\h'\n[lss]u'print "less than 0"
\h'\n[lss]u'elseif (a<=10) then
\h'\n[lss]u'print "between 0 and 10"
\h'\n[lss]u'elsif (a<=20)
\h'\n[lss]u'print "between 11 and 20"
\h'\n[lss]u'else
\h'\n[lss]u'print "over 20"
\h'\n[lss]u'endif
\h'\n[lss]u'input "Please enter another number: " b
\h'\n[lss]u'if (b<0) then
\h'\n[lss]u'print "less than 0"
\h'\n[lss]u'else
\h'\n[lss]u'if (b<=10) then
\h'\n[lss]u'print "between 0 and 10"
\h'\n[lss]u'else
\h'\n[lss]u'if (b<=20) then
\h'\n[lss]u'print "between 11 and 20"
\h'\n[lss]u'else
\h'\n[lss]u'print "over 20"
\h'\n[lss]u'endif
\h'\n[lss]u'endif
\h'\n[lss]u'endif
\h'\n[lss]u'Note, that the very same tests are performed for the variables a and b, but can
\h'\n[lss]u'be stated much more clearly with the elsif-statement.
\h'\n[lss]u'Note, that elsif might be written as elseif too, and that the keyword then is
\h'\n[lss]u'optional.
\h'\n[lss]u'See also
\h'\n[lss]u'if, else
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'end ? terminate your program
\h'\n[lss]u'Synopsis
\h'\n[lss]u'end
\h'\n[lss]u'Description
\h'\n[lss]u'Terminate your program. Much (but not exactly) like the exit command.
\h'\n[lss]u'Note, that end may not end your program immediately; if you have opened a
\h'\n[lss]u'window or called clear screen, yabasic assumes, that your user wants to study
\h'\n[lss]u'the output of your program after it has ended; therefore it issues the line
\h'\n[lss]u'---Program done, press RETURN--- and waits for a key to be pressed. If you do
\h'\n[lss]u'not like this behaviour, consider using exit.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Do you want to continue ?"
\h'\n[lss]u'input "Please answer y(es) or n(o): " a$
\h'\n[lss]u'if (lower$(left$(a$,1))="n") then
\h'\n[lss]u'print "bye"
\h'\n[lss]u'end
\h'\n[lss]u'fi
\h'\n[lss]u'See also
\h'\n[lss]u'exit
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'endif ? ends an if-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'Description
\h'\n[lss]u'The endif-statement closes (or ends) an if-statement.
\h'\n[lss]u'Note, that endif may be written in a variety of other ways: end if, end-if or
\h'\n[lss]u'even fi.
\h'\n[lss]u'The endif-statement must be omitted, if the if-statement does not contain the
\h'\n[lss]u'keyword then (see the example below). Such an if-statement without endif
\h'\n[lss]u'extends only over a single line.
\h'\n[lss]u'Example
\h'\n[lss]u'input "A number please: " a
\h'\n[lss]u'if (a<10) then
\h'\n[lss]u'print "Your number is less than 10."
\h'\n[lss]u'endif
\h'\n[lss]u'REM and now without endif
\h'\n[lss]u'input "A number please: " a
\h'\n[lss]u'if (a<10) print "Your number is less than 10."
\h'\n[lss]u'See also
\h'\n[lss]u'if
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'end sub ? ends a subroutine definition
\h'\n[lss]u'Synopsis
\h'\n[lss]u'sub foo(?)
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'Marks the end of a subroutine-definition (which starts with the sub-keyword).
\h'\n[lss]u'The whole concept of subroutines is explained within the entry for sub.
\h'\n[lss]u'Example
\h'\n[lss]u'print foo(3)
\h'\n[lss]u'sub foo(a)
\h'\n[lss]u'return a*2
\h'\n[lss]u'end sub
\h'\n[lss]u'This program prints out 6. The subroutine foo simply returns twice its
\h'\n[lss]u'argument.
\h'\n[lss]u'See also
\h'\n[lss]u'sub
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'eof ? check, if an open file contains data
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open 1,"foo.bar"
\h'\n[lss]u'if (eof(1)) then
\h'\n[lss]u'?
\h'\n[lss]u'end if
\h'\n[lss]u'Description
\h'\n[lss]u'The eof-function checks, if there is still data left within an open file. As an
\h'\n[lss]u'argument it expects the file-number as returned by (or used within) the
\h'\n[lss]u'open-function (or statement).
\h'\n[lss]u'Example
\h'\n[lss]u'a=open("foo.bar")
\h'\n[lss]u'while(not eof(a))
\h'\n[lss]u'input #a,a$
\h'\n[lss]u'print a$
\h'\n[lss]u'end while
\h'\n[lss]u'This example will print the contents of the file "foo.bar". The eof-function
\h'\n[lss]u'will terminate the loop, if there is no more data left within the file.
\h'\n[lss]u'See also
\h'\n[lss]u'open
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'eor() ? compute the bitwise exclusive or of its two arguments
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print eor(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'The eor-function takes two arguments and computes their bitwise exclusive or.
\h'\n[lss]u'See your favorite introductory text on informatics for an explanation of this
\h'\n[lss]u'function.
\h'\n[lss]u'The xor-function is the same as the eor function; both are synonymous; however
\h'\n[lss]u'they have each their own description, so you may check out the entry of xor for
\h'\n[lss]u'a slightly different view.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=0 to 3
\h'\n[lss]u'for b=0 to 3
\h'\n[lss]u'print fill$(bin$(a))," eor ",fill$(bin$(b))," = ",fill$(bin$(eor(a,b)))
\h'\n[lss]u'next b
\h'\n[lss]u'next a
\h'\n[lss]u'sub fill$(a$)
\h'\n[lss]u'return right$("0"+a$,2)
\h'\n[lss]u'end sub
\h'\n[lss]u'This example prints a table, from which you may figure, how the eor-function is
\h'\n[lss]u'computed.
\h'\n[lss]u'See also
\h'\n[lss]u'and, or
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'error ? raise an error and terminate your program
\h'\n[lss]u'Synopsis
\h'\n[lss]u'error "Wrong, wrong, wrong !!"
\h'\n[lss]u'Description
\h'\n[lss]u'Produces the same kind or error messages, that yabasic itself produces (e.g. in
\h'\n[lss]u'case of a syntax-error). The single argument is issued along with the current
\h'\n[lss]u'line-number.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number between 1 and 10: " a
\h'\n[lss]u'if (a<1 or a>10) error "Oh no ..."
\h'\n[lss]u'This program is very harsh in checking the users input; instead of just asking
\h'\n[lss]u'again, the program terminates with an error, if the user enters something
\h'\n[lss]u'wrong.
\h'\n[lss]u'The error message would look like this:
\h'\n[lss]u'---Error in t.yab, line 2: Oh no ...
\h'\n[lss]u'---Error: Program stopped due to an error
\h'\n[lss]u'See also
\h'\n[lss]u'Well, there should be a corresponding called warning; unfortunately ther is
\h'\n[lss]u'none yet.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'euler ? another name for the constant 2.71828182864
\h'\n[lss]u'Synopsis
\h'\n[lss]u'foo=euler
\h'\n[lss]u'Description
\h'\n[lss]u'euler is the well known constant named after Leonard Euler; its value is
\h'\n[lss]u'2.71828182864. euler is not a function, so parens are not allowed (i.e. euler()
\h'\n[lss]u'will produce an error). Finally, you may not assign to euler; it wouldn't sense
\h'\n[lss]u'anyway, because it is a constant.
\h'\n[lss]u'Example
\h'\n[lss]u'print euler
\h'\n[lss]u'See also
\h'\n[lss]u'pi
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'execute$() ? execute a user defined subroutine, which must return a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print execute$("foo$","arg1","arg2")
\h'\n[lss]u'Description
\h'\n[lss]u'execute$ can be used to execute a user defined subroutine, whose name may be
\h'\n[lss]u'specified as a string expression.
\h'\n[lss]u'This feature is the only way to execute a subroutine, whose name is not known
\h'\n[lss]u'by the time you write your program. This might happen, if you want to execute a
\h'\n[lss]u'subroutine, which is compiled (using the compile command) during the course of
\h'\n[lss]u'execution of your program.
\h'\n[lss]u'Note however, that the execute$-function is not the preferred method to execute
\h'\n[lss]u'a user defined subroutine; in almost all cases you should just execute a
\h'\n[lss]u'subroutine by writing down its name within your yabasic program (see the
\h'\n[lss]u'example).
\h'\n[lss]u'Example
\h'\n[lss]u'print execute$("foo$","Hello","world !")
\h'\n[lss]u'sub foo$(a$,b$)
\h'\n[lss]u'return a$+" "+b$
\h'\n[lss]u'end sub
\h'\n[lss]u'The example simply prints Hello world !, which is the return value of the user
\h'\n[lss]u'defined subroutine foo$. The same could be achieved by executing:
\h'\n[lss]u'print foo$(a$,b$)
\h'\n[lss]u'See also
\h'\n[lss]u'compile, execute
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'execute() ? execute a user defined subroutine, which must return a number
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print execute("bar","arg1","arg2")
\h'\n[lss]u'Description
\h'\n[lss]u'The execute-function is the counterpart of the execute$-function (please see
\h'\n[lss]u'there for some caveats). execute executes subroutines, which returns a number.
\h'\n[lss]u'Example
\h'\n[lss]u'print execute("bar",2,3)
\h'\n[lss]u'sub bar(a,b)
\h'\n[lss]u'return a+b
\h'\n[lss]u'end sub
\h'\n[lss]u'See also
\h'\n[lss]u'compile, execute$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'exit ? terminate your program
\h'\n[lss]u'Synopsis
\h'\n[lss]u'exit
\h'\n[lss]u'exit 1
\h'\n[lss]u'Description
\h'\n[lss]u'Terminate your program and return any given value to the operating system. exit
\h'\n[lss]u'is similar to end, but it will terminate your program immediately, no matter
\h'\n[lss]u'what.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Do you want to continue ?"
\h'\n[lss]u'input "Please answer y(es) or n(o): " a$
\h'\n[lss]u'if (lower$(left$(a$,1))="n") exit 1
\h'\n[lss]u'See also
\h'\n[lss]u'end
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'exp() ? compute the exponential function of its single argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'foo=exp(bar)
\h'\n[lss]u'Description
\h'\n[lss]u'This function computes e to the power of its argument, where e is the well
\h'\n[lss]u'known euler constant 2.71828182864.
\h'\n[lss]u'The exp-function is the inverse of the log-function.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'for x=0 to 100
\h'\n[lss]u'dot x,100-100*exp(x/100)/euler
\h'\n[lss]u'next x
\h'\n[lss]u'This program plots part of the exp-function, however the range is rather small,
\h'\n[lss]u'so that you may not recognize the function from this plot.
\h'\n[lss]u'See also
\h'\n[lss]u'log
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'export ? mark a function as globally visible
\h'\n[lss]u'Synopsis
\h'\n[lss]u'export sub foo(bar)
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'The export-statement is used within libraries to mark a user defined subroutine
\h'\n[lss]u'as visible outside the library wherein it is defined. Subroutines, which are
\h'\n[lss]u'not exported, must be qualified with the name of the library, e.g. foo.baz
\h'\n[lss]u'(where foo is the name of the library and baz the name of the subroutine);
\h'\n[lss]u'exported subroutines may be used without specifying the name of the library,
\h'\n[lss]u'e.g. bar.
\h'\n[lss]u'Therefore export may only be useful within libraries.
\h'\n[lss]u'Example
\h'\n[lss]u'The library foo.bar (which is listed below) defines two functions bar and baz,
\h'\n[lss]u'however only the function bar is exported and therefore visible even outside
\h'\n[lss]u'the library; baz is not exported and may only be used within the library
\h'\n[lss]u'foo.yab:
\h'\n[lss]u'export sub bar()
\h'\n[lss]u'print "Hello"
\h'\n[lss]u'end sub
\h'\n[lss]u'sub baz()
\h'\n[lss]u'print "World"
\h'\n[lss]u'end sub
\h'\n[lss]u'Now within your main program cux.yab (which imports the library foo.yab); note
\h'\n[lss]u'that this program produces an error:
\h'\n[lss]u'import foo
\h'\n[lss]u'print "Calling subroutine foo.bar (okay) ..."
\h'\n[lss]u'foo.bar()
\h'\n[lss]u'print "done."
\h'\n[lss]u'print "Calling subroutine bar (okay) ..."
\h'\n[lss]u'bar()
\h'\n[lss]u'print "done."
\h'\n[lss]u'print "Calling subroutine foo.baz (okay) ..."
\h'\n[lss]u'foo.baz()
\h'\n[lss]u'print "done."
\h'\n[lss]u'print "Calling subroutine baz (NOT okay) ..."
\h'\n[lss]u'baz()
\h'\n[lss]u'print "done."
\h'\n[lss]u'The output when executing yabasic foo.yab is this:
\h'\n[lss]u'Calling subroutine foo.bar (okay) ...
\h'\n[lss]u'Hello
\h'\n[lss]u'done.
\h'\n[lss]u'Calling subroutine bar (okay) ...
\h'\n[lss]u'Hello
\h'\n[lss]u'done.
\h'\n[lss]u'Calling subroutine foo.baz (okay) ...
\h'\n[lss]u'World
\h'\n[lss]u'done.
\h'\n[lss]u'Calling subroutine baz (NOT okay) ...
\h'\n[lss]u'---Error in main.yab, line 16: can't find subroutine 'baz'
\h'\n[lss]u'---Dump: sub baz() called in main.yab,16
\h'\n[lss]u'---Error: Program stopped due to an error
\h'\n[lss]u'As the error message above shows, the subroutine baz must be qualified with the
\h'\n[lss]u'name of the library, if used outside the library, wherein it is defined (e.g.
\h'\n[lss]u'foo.baz. I.e. outside the library foo.yab you need to write foo.baz. baz alone
\h'\n[lss]u'would be an error.
\h'\n[lss]u'The subroutine bar (without adding the name of the library) however may (and
\h'\n[lss]u'probably should) be used in any program, which imports the library foo.yab.
\h'\n[lss]u'Note
\h'\n[lss]u'In some sense the set of exported subroutines constitutes the interface of a
\h'\n[lss]u'library.
\h'\n[lss]u'See also
\h'\n[lss]u'sub, import
\h'\n[lss]u'F
\h'\n[lss]u'false ? a constant with the value of 0
\h'\n[lss]u'fi ? another name for endif
\h'\n[lss]u'fill ? draw a filled circles, rectangles or triangles
\h'\n[lss]u'floor() ? compute the floor for its (float) argument.
\h'\n[lss]u'for ? starts a for-loop
\h'\n[lss]u'frac() ? return the fractional part of its numeric argument
\h'\n[lss]u'Name
\h'\n[lss]u'false ? a constant with the value of 0
\h'\n[lss]u'Synopsis
\h'\n[lss]u'okay=false
\h'\n[lss]u'Description
\h'\n[lss]u'The constant false can be assigned to variables which later appear in
\h'\n[lss]u'conditions (e.g. within an if-statement.
\h'\n[lss]u'false may also be written as FALSE or even FaLsE.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number between 1 and 10: " a
\h'\n[lss]u'if (check_input(a)) print "Okay"
\h'\n[lss]u'sub check_input(x)
\h'\n[lss]u'if (x>10 or x<1) return false
\h'\n[lss]u'return true
\h'\n[lss]u'end sub
\h'\n[lss]u'The subroutine check_input checks its argument and returns true or false
\h'\n[lss]u'according to the outcome of the check..
\h'\n[lss]u'See also
\h'\n[lss]u'true
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'fi ? another name for endif
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (?)
\h'\n[lss]u'?
\h'\n[lss]u'fi
\h'\n[lss]u'Description
\h'\n[lss]u'fi marks the end of an if-statement and is exactly equivalent to endif, please
\h'\n[lss]u'see there for further information.
\h'\n[lss]u'Example
\h'\n[lss]u'input "A number please: " a
\h'\n[lss]u'if (a<10) then
\h'\n[lss]u'print "Your number is less than 10."
\h'\n[lss]u'fi
\h'\n[lss]u'See also
\h'\n[lss]u'endif
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'fill ? draw a filled circles, rectangles or triangles
\h'\n[lss]u'Synopsis
\h'\n[lss]u'fill rectangle 10,10,90,90
\h'\n[lss]u'fill circle 50,50,20
\h'\n[lss]u'fill triangle 10,20,20,10,20,20
\h'\n[lss]u'Description
\h'\n[lss]u'The keyword fill may be used within the circle, rectangle or triangle command
\h'\n[lss]u'and causes these shapes to be filled.
\h'\n[lss]u'fill can be used in conjunction with and wherever the clear-clause may appear.
\h'\n[lss]u'Used alone, fill will fill the interior of the shape (circle, rectangle or
\h'\n[lss]u'triangle); together with clear the whole shape (including its interior) is
\h'\n[lss]u'erased.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'fill circle 100,100,50
\h'\n[lss]u'clear fill rectangle 10,10,90,90
\h'\n[lss]u'This opens a window and draws a pacman-like figure.
\h'\n[lss]u'See also
\h'\n[lss]u'clear, circle, rectangle, triangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'floor() ? compute the floor for its (float) argument.
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print floor(x)
\h'\n[lss]u'Description
\h'\n[lss]u'The floor-function returns the largest integer number, that is smaller or equal
\h'\n[lss]u'than its argument. For positive numbers x, floor(x) is the same as int(x); for
\h'\n[lss]u'negaive numbers it can be different (see the example below).
\h'\n[lss]u'Example
\h'\n[lss]u'print int(-1.5),floor(-1.5)
\h'\n[lss]u'print int(-1),floor(-1)
\h'\n[lss]u'print int(1.5),floor(1.5)
\h'\n[lss]u'This example compares the functions int and floor, starting with -1 -2, then -1
\h'\n[lss]u'-1 and ending with 1 1, which shows the different behaviour of both functions.
\h'\n[lss]u'See also
\h'\n[lss]u'ceil, int, frac
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'for ? starts a for-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'for a=1 to 100 step 2
\h'\n[lss]u'?
\h'\n[lss]u'next a
\h'\n[lss]u'Description
\h'\n[lss]u'The for-loop lets its numerical variable (a in the synopsis) assume all values
\h'\n[lss]u'within the given range. The optional step-clause may specify a value (default:
\h'\n[lss]u'1) by which the variable will be incremented (or decremented, if step is
\h'\n[lss]u'negative).
\h'\n[lss]u'Any for-statement can be replaced by a set of ifs and gotos; as you may infer
\h'\n[lss]u'from the example below this is normally not feasible. However if you want to
\h'\n[lss]u'know in detail how the for-statement works, you should study this example,
\h'\n[lss]u'which presents a for-statement and an exactly equivalent series of ifs and
\h'\n[lss]u'gotos.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10 step 2:print a:next
\h'\n[lss]u'a=1
\h'\n[lss]u'label check
\h'\n[lss]u'if (a>10) goto done
\h'\n[lss]u'print a
\h'\n[lss]u'a=a+2
\h'\n[lss]u'goto check
\h'\n[lss]u'label done
\h'\n[lss]u'This example simply prints the numbers 1, 3, 5, 7 and 9. It does this twice:
\h'\n[lss]u'First with a simple for-statement and then with ifs and gotos.
\h'\n[lss]u'See also
\h'\n[lss]u'step, next
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'frac() ? return the fractional part of its numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=frac(y)
\h'\n[lss]u'Description
\h'\n[lss]u'The frac-function takes its argument, removes all the digits to the left of the
\h'\n[lss]u'comma and just returns the digits right of the comma, i.e. the fractional part.
\h'\n[lss]u'Refer to the example to learn how to rewrite frac by employing the int-function
\h'\n[lss]u'(which is not suggested anyway).
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'print frac(sqr(a))
\h'\n[lss]u'print sqr(a)-int(sqr(a))
\h'\n[lss]u'next a
\h'\n[lss]u'The example prints the fractional part of the square root of the numbers
\h'\n[lss]u'between 1 and 10. Each result is computed (and printed) twice: Once by
\h'\n[lss]u'employing the frac-function and once by employing the int-function.
\h'\n[lss]u'See also
\h'\n[lss]u'int, floor, ceil
\h'\n[lss]u'G
\h'\n[lss]u'getbit$() ? return a string representing the bit pattern of a rectangle within
\h'\n[lss]u'the graphic window
\h'\n[lss]u'getscreen$() ? returns a string representing a rectangular section of the text
\h'\n[lss]u'terminal
\h'\n[lss]u'glob() ? check if a string matches a simple pattern
\h'\n[lss]u'gosub ? continue execution at another point within your program (and return
\h'\n[lss]u'later)
\h'\n[lss]u'goto ? continue execution at another point within your program (and never come
\h'\n[lss]u'back)
\h'\n[lss]u'Name
\h'\n[lss]u'getbit$() ? return a string representing the bit pattern of a rectangle within
\h'\n[lss]u'the graphic window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=getbit$(10,10,20,20)
\h'\n[lss]u'a$=getbit$(10,10 to 20,20)
\h'\n[lss]u'Description
\h'\n[lss]u'The function getbit returns a string, which contains the encoded bit-pattern of
\h'\n[lss]u'a rectangle within graphic window; the four arguments specify two opposite
\h'\n[lss]u'corners of the rectangle. The string returned might later be fed to the putbit
\h'\n[lss]u'-command.
\h'\n[lss]u'The getbit$-function might be used for simple animations (as in the example
\h'\n[lss]u'below).
\h'\n[lss]u'Example
\h'\n[lss]u'open window 40,40
\h'\n[lss]u'fill circle 20,20,18
\h'\n[lss]u'circle$=getbit$(0,0,40,40)
\h'\n[lss]u'close window
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'for x=1 to 200
\h'\n[lss]u'putbit circle$,x,80
\h'\n[lss]u'next x
\h'\n[lss]u'This example features a circle moving from left to right over the window.
\h'\n[lss]u'See also
\h'\n[lss]u'putbit
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'getscreen$() ? returns a string representing a rectangular section of the text
\h'\n[lss]u'terminal
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=getscreen$(2,2,20,20)
\h'\n[lss]u'Description
\h'\n[lss]u'The getscreen$ function returns a string representing the area of the screen as
\h'\n[lss]u'specified by its four arguments (which specify two opposite corners). I.e.
\h'\n[lss]u'everything you have printed within this rectangle will be encoded in the string
\h'\n[lss]u'returned (including any colour-information).
\h'\n[lss]u'Like most other commands dealing with advanced text output, getscreen$
\h'\n[lss]u'requires, that you have called clear screen before.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'for a=1 to 1000:
\h'\n[lss]u'print color("red") "1";
\h'\n[lss]u'print color("green") "2";
\h'\n[lss]u'print color("blue") "3";
\h'\n[lss]u'next a
\h'\n[lss]u'screen$=getscreen$(10,10,40,10)
\h'\n[lss]u'print at(10,10) " Please Press 'y' or 'n' ! "
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'putscreen screen$,10,10
\h'\n[lss]u'This program fills the screen with colored digits and afterwards asks the user
\h'\n[lss]u'for a choice ( Please press 'y' or 'n' ! ). Afterwards the area of the screen,
\h'\n[lss]u'which has been overwritten by the question will be restored with its previous
\h'\n[lss]u'contents, whhch had been saved via getscreen$.
\h'\n[lss]u'See also
\h'\n[lss]u'putscreen$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'glob() ? check if a string matches a simple pattern
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (glob(string$,pattern$)) ?
\h'\n[lss]u'Description
\h'\n[lss]u'The glob-function takes two arguments, a string and a (glob-) pattern, and
\h'\n[lss]u'checks if the string matches the pattern. However glob does not employ the
\h'\n[lss]u'powerful rules of regular expressions; rather it has only two special
\h'\n[lss]u'characters: * (which matches any number (even zero) of characters) and ? (which
\h'\n[lss]u'matches exactly a single character).
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'read string$,pattern$
\h'\n[lss]u'if (glob(string$,pattern$)) then
\h'\n[lss]u'print string$," matches ",pattern$
\h'\n[lss]u'else
\h'\n[lss]u'print string$," does not match ",pattern$
\h'\n[lss]u'endif
\h'\n[lss]u'next a
\h'\n[lss]u'data "abc","a*"
\h'\n[lss]u'data "abc","a?"
\h'\n[lss]u'data "abc","a??"
\h'\n[lss]u'data "abc","*b*"
\h'\n[lss]u'data "abc","*"
\h'\n[lss]u'data "abc","???"
\h'\n[lss]u'data "abc","?"
\h'\n[lss]u'data "abc","*c"
\h'\n[lss]u'data "abc","A*"
\h'\n[lss]u'data "abc","????"
\h'\n[lss]u'This program checks the string abc against various patterns and prints the
\h'\n[lss]u'result. The output is:
\h'\n[lss]u'abc matches a*
\h'\n[lss]u'abc does not match a?
\h'\n[lss]u'abc matches a??
\h'\n[lss]u'abc matches *b*
\h'\n[lss]u'abc matches *
\h'\n[lss]u'abc matches ???
\h'\n[lss]u'abc does not match ?
\h'\n[lss]u'abc matches *c
\h'\n[lss]u'abc does not match A*
\h'\n[lss]u'abc does not match ????
\h'\n[lss]u'See also
\h'\n[lss]u'There are no related commands.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'gosub ? continue execution at another point within your program (and return
\h'\n[lss]u'later)
\h'\n[lss]u'Synopsis
\h'\n[lss]u'gosub foo
\h'\n[lss]u'?
\h'\n[lss]u'label foo
\h'\n[lss]u'?
\h'\n[lss]u'return
\h'\n[lss]u'Description
\h'\n[lss]u'gosub remembers the current position within your program and then passes the
\h'\n[lss]u'flow of execution to another point (which is normally marked with a label).
\h'\n[lss]u'Later, when a return-statement is encountered, the execution is resumed at the
\h'\n[lss]u'previous location.
\h'\n[lss]u'gosub is the traditional command for calling code, which needs to be executed
\h'\n[lss]u'from various places within your program. However, with subroutines yabasic
\h'\n[lss]u'offers a much more flexible way to achieve this (and more). Therefore gosub
\h'\n[lss]u'must to be considered obsolete.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Do you want to exit ? "
\h'\n[lss]u'gosub ask
\h'\n[lss]u'if (r$="y") exit
\h'\n[lss]u'label ask
\h'\n[lss]u'input "Please answer yes or no, by typing 'y' or 'n': ",r$
\h'\n[lss]u'return
\h'\n[lss]u'See also
\h'\n[lss]u'return, goto, sub, label, on gosub
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'goto ? continue execution at another point within your program (and never come
\h'\n[lss]u'back)
\h'\n[lss]u'Synopsis
\h'\n[lss]u'goto foo
\h'\n[lss]u'?
\h'\n[lss]u'label foo
\h'\n[lss]u'Description
\h'\n[lss]u'The goto-statement passes the flow of execution to another point within your
\h'\n[lss]u'program (which is normally marked with a label).
\h'\n[lss]u'goto is normally considered obsolete and harmful, however in yabasic it may be
\h'\n[lss]u'put to the good use of leaving loops (e.g. while or for) prematurely. Note
\h'\n[lss]u'however, that subroutines may not be left with the goto-statement.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Please press any key to continue."
\h'\n[lss]u'print "(program will continue by itself within 10 seconds)"
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'if (inkey$(1)<>"") then goto done
\h'\n[lss]u'next a
\h'\n[lss]u'label done
\h'\n[lss]u'print "Hello World !"
\h'\n[lss]u'Here the goto-statement is used to leave the for-loop prematurely.
\h'\n[lss]u'See also
\h'\n[lss]u'gosub, on goto
\h'\n[lss]u'H
\h'\n[lss]u'hex$() ? convert a number into hexadecimal
\h'\n[lss]u'Name
\h'\n[lss]u'hex$() ? convert a number into hexadecimal
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print hex$(foo)
\h'\n[lss]u'Description
\h'\n[lss]u'The hex$-function converts a number into a string with its hexadecimal
\h'\n[lss]u'representation. hex$ is the inverse of the dec-function.
\h'\n[lss]u'Example
\h'\n[lss]u'open 1,"foo"
\h'\n[lss]u'while(!eof(1))
\h'\n[lss]u'print right$("0"+hex$(peek(1)),2)," ";
\h'\n[lss]u'i=i+1
\h'\n[lss]u'if (mod(i,10)=0) print
\h'\n[lss]u'end while
\h'\n[lss]u'print
\h'\n[lss]u'This program reads the file foo and prints its output as a hex-dump using the
\h'\n[lss]u'hex-function.
\h'\n[lss]u'See also
\h'\n[lss]u'decbin
\h'\n[lss]u'I
\h'\n[lss]u'if ? evaluate a condition and execute statements or not, depending on the
\h'\n[lss]u'result
\h'\n[lss]u'import ? import a library
\h'\n[lss]u'inkey$ ? wait, until a key is pressed
\h'\n[lss]u'input ? read input from the user (or from a file) and assign it to a variable
\h'\n[lss]u'instr() ? searches its second argument within the first; returns its position
\h'\n[lss]u'if found
\h'\n[lss]u'int() ? return the integer part of its single numeric argument
\h'\n[lss]u'Name
\h'\n[lss]u'if ? evaluate a condition and execute statements or not, depending on the
\h'\n[lss]u'result
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'if (?) ?
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'else
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'if (?) then
\h'\n[lss]u'?
\h'\n[lss]u'elsif (?)
\h'\n[lss]u'?
\h'\n[lss]u'elsif (?) then
\h'\n[lss]u'?
\h'\n[lss]u'else
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'Description
\h'\n[lss]u'The if-statement is used to evaluate a conditions and take actions accordingly.
\h'\n[lss]u'(As an aside, please note that there is no real difference between conditions
\h'\n[lss]u'and expressions.)
\h'\n[lss]u'There are two major forms of the if-statement:
\h'\n[lss]u'* The one-line-form without the keyword then:
\h'\n[lss]u'if (?) ?
\h'\n[lss]u'This form evaluates the condition and if the result is true executes all
\h'\n[lss]u'commands (separated by colons) upt to the end of the line. There is neither
\h'\n[lss]u'an endif keyword nor an else-branch.
\h'\n[lss]u'* The multi-line-form with the keyword then:
\h'\n[lss]u'if (?) then ? elsif (?) ? else ? endif
\h'\n[lss]u'(where elsif and else are optional, whereas endif is not.
\h'\n[lss]u'According to the requirements of your program, you may specify:
\h'\n[lss]u'+ elsif(?), which specifies a condition, that will be evaluated only if
\h'\n[lss]u'the condition(s) within if or any preceding elsif did not match.
\h'\n[lss]u'+ else, which introduces a sequence of commands, that will be executed,
\h'\n[lss]u'if none of the conditions above did match.
\h'\n[lss]u'+ endif is required and ends the if-statement.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number between 1 and 4: " a
\h'\n[lss]u'if (a<=1 or a>=4) error "Wrong, wrong !"
\h'\n[lss]u'if (a=1) then
\h'\n[lss]u'print "one"
\h'\n[lss]u'elsif (a=2)
\h'\n[lss]u'print "two"
\h'\n[lss]u'elsif (a=3)
\h'\n[lss]u'print "three"
\h'\n[lss]u'else
\h'\n[lss]u'print "four"
\h'\n[lss]u'endif
\h'\n[lss]u'The input-number between 1 and 4 is simply echoed as text (one, two, ?). The
\h'\n[lss]u'example demonstrates both forms (short and long) of the if-statement (Note
\h'\n[lss]u'however, that the same thing can be done, probably somewhat more elegant, with
\h'\n[lss]u'the switch-statement).
\h'\n[lss]u'See also
\h'\n[lss]u'else, elsif, endif, conditions and expressions.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'import ? import a library
\h'\n[lss]u'Synopsis
\h'\n[lss]u'import foo
\h'\n[lss]u'Description
\h'\n[lss]u'The import-statement imports a library. It expects a single argument, which
\h'\n[lss]u'must be the name of a library (without the trailing .yab). This library will
\h'\n[lss]u'then be read and parsed and its subroutines (and variables) will be made
\h'\n[lss]u'available within the importing program. Most of the time this will be the main
\h'\n[lss]u'program, but libraries my also import and use other libraries.
\h'\n[lss]u'Libraries will first be searched in three locations in order:
\h'\n[lss]u'* The current directory, i.e. the directory from which you have invoked
\h'\n[lss]u'yabasic)
\h'\n[lss]u'* The directory, where your main program lives. This can be different from
\h'\n[lss]u'the first directory, if you specify a path for your main program, e.g. like
\h'\n[lss]u'yabasic foo/bar.yab.
\h'\n[lss]u'* Finally, libraries are searched within a special directory, whose exact
\h'\n[lss]u'location depends on your system or options when invoking yabasic. Typical
\h'\n[lss]u'values would be /usr/lib under Unix or C:\yabasic\lib under Windows.
\h'\n[lss]u'Invoking yabasic --help will show the correct directory. The location of
\h'\n[lss]u'this directory may be changed with the option --librarypath (see options).
\h'\n[lss]u'Example
\h'\n[lss]u'Lets say you have a yabasic-program foo.yab, which imports a library lib.yab.
\h'\n[lss]u'foo.yab; this would read:
\h'\n[lss]u'import lib
\h'\n[lss]u'rem This works
\h'\n[lss]u'lib.x(0)
\h'\n[lss]u'rem This works too
\h'\n[lss]u'x(1)
\h'\n[lss]u'rem And this
\h'\n[lss]u'lib.y(2)
\h'\n[lss]u'rem But this not !
\h'\n[lss]u'y(3)
\h'\n[lss]u'Now the library lib.yab reads:
\h'\n[lss]u'rem Make the subroutine x easily available outside this library
\h'\n[lss]u'export sub x(a)
\h'\n[lss]u'print a
\h'\n[lss]u'return
\h'\n[lss]u'end sub
\h'\n[lss]u'rem sub y must be referenced by its full name
\h'\n[lss]u'rem outside this library
\h'\n[lss]u'sub y(a)
\h'\n[lss]u'print a
\h'\n[lss]u'return
\h'\n[lss]u'end sub
\h'\n[lss]u'This program produces an error:
\h'\n[lss]u'0
\h'\n[lss]u'1
\h'\n[lss]u'2
\h'\n[lss]u'---Error in foo.yab, line 13: can't find subroutine 'y'
\h'\n[lss]u'---Dump: sub y() called in foo.yab,13
\h'\n[lss]u'---Error: Program stopped due to an error
\h'\n[lss]u'As you may see from the error message, yabasic is unable to find the subroutine
\h'\n[lss]u'y without specifying the name of the library (i.e. lib.y). The reason for this
\h'\n[lss]u'is, that y, other than x, is not exported from the library lib.yab (using the
\h'\n[lss]u'export-statement).
\h'\n[lss]u'See also
\h'\n[lss]u'export, sub
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'inkey$ ? wait, until a key is pressed
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'foo$=inkey$
\h'\n[lss]u'inkey$
\h'\n[lss]u'foo$=inkey$(bar)
\h'\n[lss]u'inkey$(bar)
\h'\n[lss]u'Description
\h'\n[lss]u'The inkeys$-function waits, until the user presses a key on the keyboard or a
\h'\n[lss]u'button of his mouse, and returns this very key. An optional argument specifies
\h'\n[lss]u'the number of seconds to wait; if omitted, inkey$ will wait indefinitely.
\h'\n[lss]u'inkey$ may only be used, if clear screen has been called at least once.
\h'\n[lss]u'For normal keys, yabasic simply returns the key, e.g. a, 1 or !. For function
\h'\n[lss]u'keys you will get f1, f2 and so on. Other special keys will return these
\h'\n[lss]u'strings respectively: enter, backspace, del, esc, scrnup (for screen up),
\h'\n[lss]u'scrndown and tab. Modifier keys (e.g. ctrl, alt or shift) by themselves can not
\h'\n[lss]u'be detected (e.g. if you simultaneously press shift and 'a', inkey$ will return
\h'\n[lss]u'the letter 'A' instead of 'a' of course).
\h'\n[lss]u'If a graphical window has been opened (via open window) any mouseclick within
\h'\n[lss]u'this window will be returned by inkey$ too. The string returned (e.g.
\h'\n[lss]u'MB1d+0:0028,0061, MB2u+0:0028,0061 or MB1d+1:0028,0061) is constructed as
\h'\n[lss]u'follows:
\h'\n[lss]u'* Every string associated with a mouseclick will start with the fixed string
\h'\n[lss]u'MB
\h'\n[lss]u'* The next digit (1, 2 or 3) specifies the mousebutton pressed.
\h'\n[lss]u'* A single letter, d or u, specifies, if the mousebutton has been pressed or
\h'\n[lss]u'released: d stands for down, i.e. the mousebutton has been pressed; u means
\h'\n[lss]u'up, i.e. the mousebutton has been released.
\h'\n[lss]u'* The plus-sign ('+'), which follows is always fixed.
\h'\n[lss]u'* The next digit (in the range 0 to 7) encodes the modifier keys pressed,
\h'\n[lss]u'where 1 stands for shift, 2 stands for alt and 4 stands for ctrl.
\h'\n[lss]u'* The next four digits (e.g. 0028) contain the x-position, where the
\h'\n[lss]u'mousebutton has been pressed.
\h'\n[lss]u'* The comma to follow is always fixed.
\h'\n[lss]u'* The last four digits (e.g. 0061) contain the y-position, where the
\h'\n[lss]u'mousebutton has been pressed.
\h'\n[lss]u'All those fields are of fixed length, so you may use functions like mid$ to
\h'\n[lss]u'extract certain fields. However, note that with mousex, mousey, mouseb and
\h'\n[lss]u'mousemod there are specialized functions to return detailed information about
\h'\n[lss]u'the mouseclick. Finally it should be noted, that inkey$ will only register
\h'\n[lss]u'mouseclicks within the graphic-window; mouseclicks in the text-window cannot be
\h'\n[lss]u'detected.
\h'\n[lss]u'inkey$ accepts an optional argument, specifying a timeout in seconds; if no key
\h'\n[lss]u'has been pressed within this span of time, an empty string is returned. If the
\h'\n[lss]u'timeout-argument is omitted, inkey$ will wait for ever.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'print "Press any key or press 'q' to stop."
\h'\n[lss]u'repeat
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print a$
\h'\n[lss]u'until(a$="q")
\h'\n[lss]u'This program simply returns the key pressed. You may use it, to learn, which
\h'\n[lss]u'strings are returned for the special keys on your keyboard (e.g.
\h'\n[lss]u'function-keys).
\h'\n[lss]u'See also
\h'\n[lss]u'clear screen,mousex, mousey, mouseb, mousemod
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'input ? read input from the user (or from a file) and assign it to a variable
\h'\n[lss]u'Synopsis
\h'\n[lss]u'input a
\h'\n[lss]u'input a,b,c
\h'\n[lss]u'input a$
\h'\n[lss]u'input "Hello" a
\h'\n[lss]u'input #1 a$
\h'\n[lss]u'Description
\h'\n[lss]u'input reads the new contents of one or many (numeric- or string-) variables,
\h'\n[lss]u'either from the keyboard (i.e. from you) or from a file. An optional first
\h'\n[lss]u'string-argument specifies a prompt, which will be issued before reading any
\h'\n[lss]u'contents.
\h'\n[lss]u'If you want to read from an open file, you need to specify a hash ('#'),
\h'\n[lss]u'followed by the number, under which the file has been opened.
\h'\n[lss]u'Note, that the input is split at spaces, i.e. if you enter a whole line
\h'\n[lss]u'consisting of many space-separated word, the first input-statement will only
\h'\n[lss]u'return the first word; the other words will only be returned on subsequent
\h'\n[lss]u'calls to input; the same applies, if a single input reads multiple variables:
\h'\n[lss]u'The first variable gets only the first word, the second one the second word,
\h'\n[lss]u'and so on. If you don't like this behaviour, you may use line input, which
\h'\n[lss]u'returns a whole line (including embedded spaces) at once.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter the name of a file to read: " a$
\h'\n[lss]u'open 1,a$
\h'\n[lss]u'while(!eof(1))
\h'\n[lss]u'input #1 b$
\h'\n[lss]u'print b$
\h'\n[lss]u'wend
\h'\n[lss]u'If this program is stored within a file test.yab and you enter this name when
\h'\n[lss]u'prompted for a file to read, you will see this output:
\h'\n[lss]u'Please enter the name of a file to read: t.yab
\h'\n[lss]u'input
\h'\n[lss]u'"Please
\h'\n[lss]u'enter
\h'\n[lss]u'the
\h'\n[lss]u'name
\h'\n[lss]u'of
\h'\n[lss]u'a
\h'\n[lss]u'file
\h'\n[lss]u'to
\h'\n[lss]u'read:
\h'\n[lss]u'"
\h'\n[lss]u'a$
\h'\n[lss]u'open
\h'\n[lss]u'1,a$
\h'\n[lss]u'while(!eof(1))
\h'\n[lss]u'input
\h'\n[lss]u'#1
\h'\n[lss]u'b$
\h'\n[lss]u'print
\h'\n[lss]u'b$
\h'\n[lss]u'wend
\h'\n[lss]u'See also
\h'\n[lss]u'line input
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'instr() ? searches its second argument within the first; returns its position
\h'\n[lss]u'if found
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print instr(a$,b$)
\h'\n[lss]u'if (instr(a$,b$)) ?
\h'\n[lss]u'pos=instr(a$,b$,x)
\h'\n[lss]u'Description
\h'\n[lss]u'The instr-functions requires two string arguments and searches the second
\h'\n[lss]u'argument within the first. If the second argument can be found within the
\h'\n[lss]u'first, the position is returned (counting from one). If it can not be found,
\h'\n[lss]u'the instr-function returns 0; this makes this function usable within the
\h'\n[lss]u'condition of an if-statement (see the example below).
\h'\n[lss]u'If you supply a third, numeric argument to the instr-function, it will be used
\h'\n[lss]u'as a starting point for the search. Therefore instr("abcdeabcdeabcde","e",8)
\h'\n[lss]u'will return 10, because the search for an "e" starts at position 8 and finds
\h'\n[lss]u'the "e" at position 10 (and not the one at position 5).
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a text containing the string 'cat': " a$
\h'\n[lss]u'if (instr(a$,"cat")) then
\h'\n[lss]u'print "Well done !"
\h'\n[lss]u'else
\h'\n[lss]u'print "No cat in your input ..."
\h'\n[lss]u'endif
\h'\n[lss]u'See also
\h'\n[lss]u'rinstr
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'int() ? return the integer part of its single numeric argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print int(a)
\h'\n[lss]u'Description
\h'\n[lss]u'The int-function returns only the digits before the comma; int(2.5) returns 2
\h'\n[lss]u'and int(-2.3) returns -2.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a whole number between 1 and 10: " a
\h'\n[lss]u'if (a=int(a) and a>=1 and a<=10) then
\h'\n[lss]u'print "Thanx !"
\h'\n[lss]u'else
\h'\n[lss]u'print "Never mind ..."
\h'\n[lss]u'endif
\h'\n[lss]u'See also
\h'\n[lss]u'frac, floor, ceil
\h'\n[lss]u'L
\h'\n[lss]u'label ? mark a specific location within your program for goto, gosub or restore
\h'\n[lss]u'left$() ? return (or change) left end of a string
\h'\n[lss]u'len() ? return the length of a string
\h'\n[lss]u'line ? draw a line
\h'\n[lss]u'line input ? read in a whole line of text and assign it to a variable
\h'\n[lss]u'local ? mark a variable as local to a subroutine
\h'\n[lss]u'log() ? compute the natural logarithm
\h'\n[lss]u'loop ? marks the end of an infinite loop
\h'\n[lss]u'lower$() ? convert a string to lower case
\h'\n[lss]u'ltrim$() ? trim spaces at the left end of a string
\h'\n[lss]u'Name
\h'\n[lss]u'label ? mark a specific location within your program for goto, gosub or restore
\h'\n[lss]u'Synopsis
\h'\n[lss]u'label foo
\h'\n[lss]u'?
\h'\n[lss]u'goto foo
\h'\n[lss]u'Description
\h'\n[lss]u'The label-command can be used to give a name to a specific location within your
\h'\n[lss]u'program. Such a position might be referred from one of three commands: goto,
\h'\n[lss]u'gosub and restore.
\h'\n[lss]u'You may use labels safely within libraries, because a label (e.g. foo) does not
\h'\n[lss]u'collide with a label with the same name within the main program or within
\h'\n[lss]u'another library; yabasic will not mix them up.
\h'\n[lss]u'As an aside, please note, that line numbers are a special (however deprecated)
\h'\n[lss]u'case of labels; see the second example below.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 100
\h'\n[lss]u'if (ran(10)>5) goto done
\h'\n[lss]u'next a
\h'\n[lss]u'label done
\h'\n[lss]u'10 for a=1 to 100
\h'\n[lss]u'20 if (ran(10)>5) goto 40
\h'\n[lss]u'30 next a
\h'\n[lss]u'40
\h'\n[lss]u'Within this example, the for-loop will probably be left prematurely with a
\h'\n[lss]u'goto-statement. This task is done twice: First with labels and then again with
\h'\n[lss]u'line numbers.
\h'\n[lss]u'See also
\h'\n[lss]u'gosub, goto.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'left$() ? return (or change) left end of a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print left$(a$,2)
\h'\n[lss]u'left$(b$,3)="foobar"
\h'\n[lss]u'Description
\h'\n[lss]u'The left$-function accepts two arguments (a string and a number) and returns
\h'\n[lss]u'the part from the left end of the string, whose length is specified by its
\h'\n[lss]u'second argument. Loosely spoken, it simply returns the requested number of
\h'\n[lss]u'chars from the left end of the given string.
\h'\n[lss]u'Note, that the left$-function can be assigned to, i.e. it may appear on the
\h'\n[lss]u'left hand side of an assignment. In this way it is possible to change a part of
\h'\n[lss]u'the variable used within the left$-function. Note, that that way the length of
\h'\n[lss]u'the string cannot be changed, i.e. characters might be overwritten, but not
\h'\n[lss]u'added. For an example see below.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please answer yes or no: " a$
\h'\n[lss]u'l=len(a$):a$=lower$(a$):print "Your answer is ";
\h'\n[lss]u'if (left$("yes",l)=a$ and l>=1) then
\h'\n[lss]u'print "yes"
\h'\n[lss]u'elsif (left$("no",l)=a$ and l>=1) then
\h'\n[lss]u'print "no"
\h'\n[lss]u'else
\h'\n[lss]u'print "?"
\h'\n[lss]u'endif
\h'\n[lss]u'This example asks a simple yes/no question and goes some way to accept even
\h'\n[lss]u'incomplete input, while still being able to reject invalid input.
\h'\n[lss]u'This second example demonstrates the capability to assign to the
\h'\n[lss]u'left$-function.
\h'\n[lss]u'a$="Heiho World !"
\h'\n[lss]u'print a$
\h'\n[lss]u'left$(a$,5)="Hello"
\h'\n[lss]u'print a$
\h'\n[lss]u'See also
\h'\n[lss]u'right$, mid$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'len() ? return the length of a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=len(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The len-function returns the length of its single string argument.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a password: " a$
\h'\n[lss]u'if (len(a$)<6) error "Password too short !"
\h'\n[lss]u'This example checks the length of the password, that the user has entered.
\h'\n[lss]u'See also
\h'\n[lss]u'left$, right$ and mid$,
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'line ? draw a line
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'line 0,0,100,100
\h'\n[lss]u'line 0,0 to 100,100
\h'\n[lss]u'new curve
\h'\n[lss]u'line 100,100
\h'\n[lss]u'line to 100,100
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'clear line 0,0,100,100
\h'\n[lss]u'clear line 0,0 to 100,100
\h'\n[lss]u'new curve
\h'\n[lss]u'clear line 100,100
\h'\n[lss]u'clear line to 100,100
\h'\n[lss]u'Description
\h'\n[lss]u'The line-command draws a line. Simple as this is, the line-command has a large
\h'\n[lss]u'variety of forms as they are listed in the synopsis above. Lets look at them a
\h'\n[lss]u'little closer:
\h'\n[lss]u'* A line has a starting and an end point; therefore the line-command
\h'\n[lss]u'(normally) needs four numbers as arguments, representing these two points.
\h'\n[lss]u'This is the first form appearing within the synopsis.
\h'\n[lss]u'* You may separate the two points with either ',' or to, which accounts for
\h'\n[lss]u'the second form of the line-command.
\h'\n[lss]u'* The line-command may be used to draw a connected sequence of lines with a
\h'\n[lss]u'sequence of commands like line x,y; Each command will draw a line from the
\h'\n[lss]u'point where the last line-command left off, to the point specified in the
\h'\n[lss]u'arguments. Note, that you need to use the command new curve before you may
\h'\n[lss]u'issue such a line-command. See the example below.
\h'\n[lss]u'* You may insert the word to for beauty: line to x,y, which does exactly the
\h'\n[lss]u'same as line x,y
\h'\n[lss]u'* Finally, you may choose not to draw, but to erase the lines; this can be
\h'\n[lss]u'done by prepending the phrase clear. This account for all the other forms
\h'\n[lss]u'of the line-command.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'line 10,10 to 10,190
\h'\n[lss]u'line 10,190 to 190,190
\h'\n[lss]u'new curve
\h'\n[lss]u'for a=0 to 360
\h'\n[lss]u'line to 10+a*180/360,100+60*sin(a*pi/180)
\h'\n[lss]u'next a
\h'\n[lss]u'This example draws a sine-curve (with an offset in x- and y-direction). Note,
\h'\n[lss]u'that the first line-command after new curve does not draw anything. Only the
\h'\n[lss]u'coordinates will be stored. The second iteration of the loop then uses these
\h'\n[lss]u'coordinates as a starting point for the first line.
\h'\n[lss]u'See also
\h'\n[lss]u'new curve, close curve, open window
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'line input ? read in a whole line of text and assign it to a variable
\h'\n[lss]u'Synopsis
\h'\n[lss]u'line input a
\h'\n[lss]u'line input a$
\h'\n[lss]u'line input "Hello" a
\h'\n[lss]u'line input #1 a$
\h'\n[lss]u'Description
\h'\n[lss]u'In most respects line input is like the input-command: It reads the new
\h'\n[lss]u'contents of a variable, either from keyboard or from a file. However, line
\h'\n[lss]u'input always reads a complete line and assigns it to its variable. line input
\h'\n[lss]u'does not stop reading at spaces and is therefore the best way to read in a
\h'\n[lss]u'string which might contain whitespace. Note, that the final newline is stripped
\h'\n[lss]u'of.
\h'\n[lss]u'Example
\h'\n[lss]u'line input "Please enter your name (e.g. Frodo Beutelin): " a$
\h'\n[lss]u'print "Hello ",a$
\h'\n[lss]u'Note that the usage of line input is essential in this example; a simple
\h'\n[lss]u'input-statement would only return the string up to the first space, e.g. Frodo.
\h'\n[lss]u'See also
\h'\n[lss]u'input
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'local ? mark a variable as local to a subroutine
\h'\n[lss]u'Synopsis
\h'\n[lss]u'sub foo()
\h'\n[lss]u'local a,b,c$,d(10),e$(5,5)
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'The local-command can (and should be) used to mark a variable (or array) as
\h'\n[lss]u'local to the containing subroutine. This means, that a local variable in your
\h'\n[lss]u'subroutine is totally different from a variable with the same name within your
\h'\n[lss]u'main program. Variables which are known everywhere within your program are
\h'\n[lss]u'called global in contrast.
\h'\n[lss]u'Declaring variables within the subroutine as local helps to avoid hard to find
\h'\n[lss]u'bugs; therefore local variables should be used whenever possible.
\h'\n[lss]u'Note, that the parameters of your subroutines are always local.
\h'\n[lss]u'As you may see from the example, local arrays may be created without using the
\h'\n[lss]u'keyword dim (which is required only for global arrays).
\h'\n[lss]u'Example
\h'\n[lss]u'a=1
\h'\n[lss]u'b=1
\h'\n[lss]u'print a,b
\h'\n[lss]u'foo()
\h'\n[lss]u'print a,b
\h'\n[lss]u'sub foo()
\h'\n[lss]u'local a
\h'\n[lss]u'a=2
\h'\n[lss]u'b=2
\h'\n[lss]u'end sub
\h'\n[lss]u'This example demonstrates the difference between local and global variables; it
\h'\n[lss]u'produces this output:
\h'\n[lss]u'1 1
\h'\n[lss]u'1 2
\h'\n[lss]u'As you may see, the content of the global variable a is unchanged after the
\h'\n[lss]u'subroutine foo; this is because the assignment a=2 within the subroutine
\h'\n[lss]u'affects the local variable a only and not the global one. However, the variable
\h'\n[lss]u'b is never declared local and therefore the subroutine changes the global
\h'\n[lss]u'variable, which is reflected in the output of the second print-statement.
\h'\n[lss]u'See also
\h'\n[lss]u'sub, static, dim
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'log() ? compute the natural logarithm
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=log(x)
\h'\n[lss]u'a=log(x,base)
\h'\n[lss]u'Description
\h'\n[lss]u'The log-function computes the logarithm of its first argument. The optional
\h'\n[lss]u'second argument gives the base for the logarithm; if this second argument is
\h'\n[lss]u'omitted, the euler-constant 2.71828? will be taken as the base.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'for x=10 to 190 step 10:for y=10 to 190 step 10
\h'\n[lss]u'r=3*log(1+x,1+y)
\h'\n[lss]u'if (r>10) r=10
\h'\n[lss]u'if (r<1) r=1
\h'\n[lss]u'fill circle x,y,r
\h'\n[lss]u'next y:next x
\h'\n[lss]u'This draws another nice plot.
\h'\n[lss]u'See also
\h'\n[lss]u'exp
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'loop ? marks the end of an infinite loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'do
\h'\n[lss]u'?
\h'\n[lss]u'loop
\h'\n[lss]u'Description
\h'\n[lss]u'The loop-command marks the ends of a loop (which is started by do), wherein all
\h'\n[lss]u'statements within the loop are repeated forever. In this respect the do
\h'\n[lss]u'loop-loop is infinite, however, you may leave it anytime via break or goto.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Hello, I will throw dice, until I get a 2 ..."
\h'\n[lss]u'do
\h'\n[lss]u'r=int(ran(6))+1
\h'\n[lss]u'print r
\h'\n[lss]u'if (r=2) break
\h'\n[lss]u'loop
\h'\n[lss]u'See also
\h'\n[lss]u'do, for, repeat, while, break
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'lower$() ? convert a string to lower case
\h'\n[lss]u'Synopsis
\h'\n[lss]u'l$=lower$(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The lower$-function accepts a single string-argument and converts it to all
\h'\n[lss]u'lower case.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a password: " a$
\h'\n[lss]u'if (a$=lower$(a$)) error "Your password is NOT mixed case !"
\h'\n[lss]u'This example prompts for a password and checks, if it is really lower case.
\h'\n[lss]u'See also
\h'\n[lss]u'upper$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'ltrim$() ? trim spaces at the left end of a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=ltrim$(b$)
\h'\n[lss]u'Description
\h'\n[lss]u'The ltrim$-function removes all whitespace from the left end of a string and
\h'\n[lss]u'returns the result.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please answer 'yes' or 'no' : " a$
\h'\n[lss]u'a$=lower$(ltrim$(rtrim$(a$)))
\h'\n[lss]u'if (len(a$)>0 and a$=left$("yes",len(a$))) then
\h'\n[lss]u'print "Yes ..."
\h'\n[lss]u'else
\h'\n[lss]u'print "No ..."
\h'\n[lss]u'endif
\h'\n[lss]u'This example prompts for an answer and removes any spaces, which might precede
\h'\n[lss]u'the input; therefore it is even prepared for the (albeit somewhat pathological
\h'\n[lss]u'case, that the user first hits space before entering his answer.
\h'\n[lss]u'See also
\h'\n[lss]u'rtrim$, trim$
\h'\n[lss]u'M
\h'\n[lss]u'max() ? return the larger of its two arguments
\h'\n[lss]u'mid$() ? return (or change) characters from within a string
\h'\n[lss]u'min() ? return the smaller of its two arguments
\h'\n[lss]u'mod ? compute the remainder of a division
\h'\n[lss]u'mouseb ? extract the state of the mousebuttons from a string returned by inkey$
\h'\n[lss]u'mousemod ? return the state of the modifier keys during a mouseclick
\h'\n[lss]u'mousex ? return the x-position of a mouseclick
\h'\n[lss]u'mousey ? return the y-position of a mouseclick
\h'\n[lss]u'Name
\h'\n[lss]u'max() ? return the larger of its two arguments
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print max(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'Return the maximum of its two arguments.
\h'\n[lss]u'Example
\h'\n[lss]u'dim m(10)
\h'\n[lss]u'for a=1 to 1000
\h'\n[lss]u'm=0
\h'\n[lss]u'For b=1 to 10
\h'\n[lss]u'm=max(m,ran(10))
\h'\n[lss]u'next b
\h'\n[lss]u'm(m)=m(m)+1
\h'\n[lss]u'next a
\h'\n[lss]u'for a=1 to 9
\h'\n[lss]u'print a,": ",m(a)
\h'\n[lss]u'next a
\h'\n[lss]u'Within the inner for-loop (the one with the loop-variable b), the example
\h'\n[lss]u'computes the maximum of 10 random numbers. The outer loop (with the loop
\h'\n[lss]u'variable a) now repeats this process 1000 times and counts, how often each
\h'\n[lss]u'maximum appears. The last loop finally reports the result.
\h'\n[lss]u'Now, the interesting question would be, which will be approached, when we
\h'\n[lss]u'increase the number of iterations from thousand to infinity. Well, maybe
\h'\n[lss]u'someone could just tell me :-)
\h'\n[lss]u'See also
\h'\n[lss]u'min
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mid$() ? return (or change) characters from within a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print mid$(a$,2,1)
\h'\n[lss]u'print mid$(a$,2)
\h'\n[lss]u'mid$(a$,5,3)="foo"
\h'\n[lss]u'mid$(a$,5)="foo"
\h'\n[lss]u'Description
\h'\n[lss]u'The mid$-function requires three arguments: a string and two numbers, where the
\h'\n[lss]u'first number specifies a position within the string and the second one gives
\h'\n[lss]u'the number of characters to be returned; if you omit the second argument, the
\h'\n[lss]u'mid$-function returns all characters up to the end of the string.
\h'\n[lss]u'Note, that you may assign to the mid$-function, i.e. mid$ may appear on the
\h'\n[lss]u'left hand side of an assignment. In this way it is possible to change a part of
\h'\n[lss]u'the variable used within the mid$-function. Note, that that way the length of
\h'\n[lss]u'the string cannot be changed, i.e. characters might be overwritten, but not
\h'\n[lss]u'added. For an example see below.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a string: " a$
\h'\n[lss]u'for a=1 to len(a$)
\h'\n[lss]u'if (instr("aeiou",lower$(mid$(a$,a,1)))) mid$(a$,a,1)="e"
\h'\n[lss]u'next a
\h'\n[lss]u'print "When you turn everything to lower case and"
\h'\n[lss]u'print "replace every vowel with 'e', your input reads:"
\h'\n[lss]u'print
\h'\n[lss]u'print a$
\h'\n[lss]u'This example transforms the input string a bit, using the mid$-function to
\h'\n[lss]u'retrieve a character from within the string as well as to change it.
\h'\n[lss]u'See also
\h'\n[lss]u'left$ and right$.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'min() ? return the smaller of its two arguments
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print min(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'Return the minimum of its two argument.
\h'\n[lss]u'Example
\h'\n[lss]u'dim m(10)
\h'\n[lss]u'for a=1 to 1000
\h'\n[lss]u'm=min(ran(10),ran(10))
\h'\n[lss]u'm(m)=m(m)+1
\h'\n[lss]u'next a
\h'\n[lss]u'for a=1 to 9
\h'\n[lss]u'print a,": ",m(a)
\h'\n[lss]u'next a
\h'\n[lss]u'For each iteration of the loop, the lower of two random number is recorded. The
\h'\n[lss]u'result is printed at the end.
\h'\n[lss]u'See also
\h'\n[lss]u'max
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mod ? compute the remainder of a division
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print mod(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'The mod-function divides its two arguments and computes the remainder. Note,
\h'\n[lss]u'that a/b-int(a/b) and mod(a,b) are always equal.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'print at(10,10) "Please wait ";
\h'\n[lss]u'p$="-\|/"
\h'\n[lss]u'for a=1 to 100
\h'\n[lss]u'rem ... do something lengthy here, or simply sleep :-)
\h'\n[lss]u'pause(1)
\h'\n[lss]u'print at(22,10) mid$(p$,1+mod(a,4))
\h'\n[lss]u'next a
\h'\n[lss]u'This example executes some time consuming action within a loop (in fact, it
\h'\n[lss]u'simply sleeps) and gives the user some indication of progress by displaying a
\h'\n[lss]u'turning bar (that's where the mod-function comes into play).
\h'\n[lss]u'See also
\h'\n[lss]u'int, frac
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mouseb ? extract the state of the mousebuttons from a string returned by inkey$
\h'\n[lss]u'Synopsis
\h'\n[lss]u'inkey$
\h'\n[lss]u'print mouseb()
\h'\n[lss]u'print mouseb
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print mouseb(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The mouseb-function is a helper function for decoding part of the (rather
\h'\n[lss]u'complicated) strings, which are returned by the inkey$-function. If a
\h'\n[lss]u'mousebutton has been pressed, the mouseb-function returns the number (1,2 or 3)
\h'\n[lss]u'of the mousebutton, when it is pressed and returns its negative (-1,-2 or -3),
\h'\n[lss]u'when it is released.
\h'\n[lss]u'The mouseb-function accepts zero or one arguments. A single argument should be
\h'\n[lss]u'a string returned by the inkey$-function; if mouseb is called without any
\h'\n[lss]u'arguments, it returns the values from the last call to inkey$, which are stored
\h'\n[lss]u'implicitly and internally by yabasic.
\h'\n[lss]u'Note
\h'\n[lss]u'Note however, that the value returned by the mouseb-function does not reflect
\h'\n[lss]u'the current state of the mousebuttons. It rather extracts the information from
\h'\n[lss]u'the string passed as an argument (or from the last call to the inkey$-function,
\h'\n[lss]u'if no argument is passed). So the value returned by mouseb reflects the state
\h'\n[lss]u'of the mousebuttons at the time the inkey$-function has been called; as opposed
\h'\n[lss]u'to the time the mouseb-function is called.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'clear screen
\h'\n[lss]u'print "Please draw lines; press (and keep it pressed)"
\h'\n[lss]u'print "the left mousebutton for the starting point,"
\h'\n[lss]u'print "release it for the end-point."
\h'\n[lss]u'do
\h'\n[lss]u'if (mouseb(release$)=1) press$=release$
\h'\n[lss]u'release$=inkey$
\h'\n[lss]u'if (mouseb(release$)=-1) then
\h'\n[lss]u'line mousex(press$),mousey(press$) to mousex(release$),mousey(release$)
\h'\n[lss]u'endif
\h'\n[lss]u'loop
\h'\n[lss]u'This is a maybe the most simplistic line-drawing program possible, catching
\h'\n[lss]u'presses as well as releases of the first mousebutton.
\h'\n[lss]u'See also
\h'\n[lss]u'inkey$, mousex, mousey and mousemod
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mousemod ? return the state of the modifier keys during a mouseclick
\h'\n[lss]u'Synopsis
\h'\n[lss]u'inkey$
\h'\n[lss]u'print mousemod()
\h'\n[lss]u'print mousemod
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print mousemod(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The mousemod-function is a helper function for decoding part of the (rather
\h'\n[lss]u'complicated) strings, which are returned by the inkey$-function if a
\h'\n[lss]u'mousebutton has been pressed. It returns the state of the keyboard modifiers
\h'\n[lss]u'(shift, ctrl or alt): If the shift-key is pressed, mousemod returns 1, for the
\h'\n[lss]u'alt-key 2 and for the ctrl-key 4. If more than one key is pressed, the sum of
\h'\n[lss]u'these values is returned, e.g. mousemod returns 5, if shift and ctrl are
\h'\n[lss]u'pressed simultaneously.
\h'\n[lss]u'The mousemod-function accepts zero or one arguments. A single argument should
\h'\n[lss]u'be a string returned by the inkey$-function; if mousemod is called without any
\h'\n[lss]u'arguments, it returns the values from the last call to inkey$ (which are stored
\h'\n[lss]u'implicitly and internally by yabasic).
\h'\n[lss]u'Note
\h'\n[lss]u'Please see also the Note within the mouseb-function.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'clear screen
\h'\n[lss]u'do
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'if (left$(a$,2)="MB") then
\h'\n[lss]u'x=mousex(a$)
\h'\n[lss]u'y=mousey(a$)
\h'\n[lss]u'if (mousemod(a$)=0) then
\h'\n[lss]u'circle x,y,20
\h'\n[lss]u'else
\h'\n[lss]u'fill circle x,y,20
\h'\n[lss]u'endif
\h'\n[lss]u'endif
\h'\n[lss]u'loop
\h'\n[lss]u'This program draws a circle, whenever a mousebutton is pressed; the circles are
\h'\n[lss]u'filled, when any modifier is pressed, and empty if not.
\h'\n[lss]u'See also
\h'\n[lss]u'inkey$, mousex, mousey and mouseb
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mousex ? return the x-position of a mouseclick
\h'\n[lss]u'Synopsis
\h'\n[lss]u'inkey$
\h'\n[lss]u'print mousex()
\h'\n[lss]u'print mousex
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print mousex(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The mousex-function is a helper function for decoding part of the (rather
\h'\n[lss]u'complicated) strings, which are returned by the inkey$-function; It returns the
\h'\n[lss]u'x-position of the mouse as encoded within its argument.
\h'\n[lss]u'The mousex-function accepts zero or one arguments. A single argument should be
\h'\n[lss]u'a string returned by the inkey$-function; if mousex is called without any
\h'\n[lss]u'arguments, it returns the values from the last call to inkey$ (which are stored
\h'\n[lss]u'implicitly and internally by yabasic).
\h'\n[lss]u'Note
\h'\n[lss]u'Please see also the Note within the mouseb-function.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'clear screen
\h'\n[lss]u'do
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'if (left$(a$,2)="MB") then
\h'\n[lss]u'line mousex,0 to mousex,200
\h'\n[lss]u'endif
\h'\n[lss]u'loop
\h'\n[lss]u'This example draws vertical lines at the position, where the mousebutton has
\h'\n[lss]u'been pressed.
\h'\n[lss]u'See also
\h'\n[lss]u'inkey$, mousemod, mousey and mouseb
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'mousey ? return the y-position of a mouseclick
\h'\n[lss]u'Synopsis
\h'\n[lss]u'inkey$
\h'\n[lss]u'print mousey()
\h'\n[lss]u'print mousey
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'print mousey(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The mousey-function is a helper function for decoding part of the (rather
\h'\n[lss]u'complicated) strings, which are returned by the inkey$-function. mousey returns
\h'\n[lss]u'the y-position of the mouse as encoded within its argument.
\h'\n[lss]u'The mousey-function accepts zero or one arguments. A single argument should be
\h'\n[lss]u'a string returned by the inkey$-function; if mousey is called without any
\h'\n[lss]u'arguments, it returns the values from the last call to inkey$ (which are stored
\h'\n[lss]u'implicitly and internally by yabasic).
\h'\n[lss]u'Note
\h'\n[lss]u'Please see also the Note within the mouseb-function.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'clear screen
\h'\n[lss]u'do
\h'\n[lss]u'a$=inkey$
\h'\n[lss]u'if (left$(a$,2)="MB") then
\h'\n[lss]u'line 0,mousey to 200,mousey
\h'\n[lss]u'endif
\h'\n[lss]u'loop
\h'\n[lss]u'This example draws horizontal lines at the position, where the mousebutton has
\h'\n[lss]u'been pressed.
\h'\n[lss]u'See also
\h'\n[lss]u'inkey$, mousemod, mousex and mouseb
\h'\n[lss]u'N
\h'\n[lss]u'new curve ? start a new curve, that will be drawn with the line-command
\h'\n[lss]u'next ? mark the end of a for loop
\h'\n[lss]u'not ? negate an expression; can be written as !
\h'\n[lss]u'numparams ? return the number of parameters, that have been passed to a
\h'\n[lss]u'subroutine
\h'\n[lss]u'Name
\h'\n[lss]u'new curve ? start a new curve, that will be drawn with the line-command
\h'\n[lss]u'Synopsis
\h'\n[lss]u'new curve
\h'\n[lss]u'line to x,y
\h'\n[lss]u'Description
\h'\n[lss]u'The new curve-function starts a new sequence of lines, that will be drawn by
\h'\n[lss]u'repeated line to-commands.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'ellipse(100,50,30,60)
\h'\n[lss]u'ellipse(150,100,60,30)
\h'\n[lss]u'sub ellipse(x,y,xr,yr)
\h'\n[lss]u'new curve
\h'\n[lss]u'for a=0 to 2*pi step 0.2
\h'\n[lss]u'line to x+xr*cos(a),y+yr*sin(a)
\h'\n[lss]u'next a
\h'\n[lss]u'close curve
\h'\n[lss]u'end sub
\h'\n[lss]u'This example defines a subroutine ellipse that draws an ellipse. Within this
\h'\n[lss]u'subroutine, the ellipse is drawn as a sequence of lines started with the new
\h'\n[lss]u'curve command and closed with close curve.
\h'\n[lss]u'See also
\h'\n[lss]u'line, close curve
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'next ? mark the end of a for loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'next a
\h'\n[lss]u'Description
\h'\n[lss]u'The next-keyword marks the end of a for-loop. All statements up to the
\h'\n[lss]u'next-keyword will be repeated as specified with the for-clause. Note, that the
\h'\n[lss]u'name of the variable is optional; so instead of next a you may write next.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 300000
\h'\n[lss]u'for b=1 to 21+20*sin(pi*a/20)
\h'\n[lss]u'print "*";
\h'\n[lss]u'next b
\h'\n[lss]u'print
\h'\n[lss]u'sleep 0.1
\h'\n[lss]u'next a
\h'\n[lss]u'This example simply plots a sine-curve until you fall asleep.
\h'\n[lss]u'See also
\h'\n[lss]u'for
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'not ? negate an expression; can be written as !
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (not a<b) then ?
\h'\n[lss]u'bad=!okay
\h'\n[lss]u'Description
\h'\n[lss]u'The keyword not (or ! for short) is mostly used within conditions (e.g. within
\h'\n[lss]u'if- or while-statements). There it is employed to negate the condition or
\h'\n[lss]u'expression (i.e. turn TRUE into FALSE and vice versa)
\h'\n[lss]u'However not can be used within arithmetic calculations too., simply because
\h'\n[lss]u'there is no difference between arithmetic and logical expressions.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter three ascending numbers: " a,b,c
\h'\n[lss]u'if (not (a<b and b<c)) error " the numbers you have entered are not ascending ..."
\h'\n[lss]u'See also
\h'\n[lss]u'and,or
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'numparams ? return the number of parameters, that have been passed to a
\h'\n[lss]u'subroutine
\h'\n[lss]u'Synopsis
\h'\n[lss]u'sub foo(a,b,c)
\h'\n[lss]u'if (numparams=1) ?
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'Within a subroutine the local variable numparam or numparams contains the
\h'\n[lss]u'number of parameters, that have been passed to the subroutine. This information
\h'\n[lss]u'can be useful, because the subroutine may have been called with fewer
\h'\n[lss]u'parameters than actually declared. The number of values that actually have been
\h'\n[lss]u'passed while calling the subroutine, can be found in numparams.
\h'\n[lss]u'Note, that arguments which are used in the definition of a subroutine but are
\h'\n[lss]u'left out during a call to it (thereby reducing the value of numparams) receive
\h'\n[lss]u'a value of 0 or "" (empty string) respectively.
\h'\n[lss]u'Example
\h'\n[lss]u'a$="123456789"
\h'\n[lss]u'print part$(a$,4)
\h'\n[lss]u'print part$(a$,3,7)
\h'\n[lss]u'sub part$(a$,f,t)
\h'\n[lss]u'if (numparams=2) then
\h'\n[lss]u'return mid$(a$,f)
\h'\n[lss]u'else
\h'\n[lss]u'return mid$(a$,f,t-f+1)
\h'\n[lss]u'end if
\h'\n[lss]u'end sub
\h'\n[lss]u'When you run this example, it will print 456789 and 34567. Take a look at the
\h'\n[lss]u'subroutine part$, which returns part of the string which has been passed as an
\h'\n[lss]u'argument. If (besides the string) two numbers are passed, they define the
\h'\n[lss]u'starting and end position of the substring, that will be returned. However, if
\h'\n[lss]u'only one number is passed, the rest of the string, starting from this position
\h'\n[lss]u'will be returned. Each of these cases is recognized with the help of the
\h'\n[lss]u'numparams variable.
\h'\n[lss]u'See also
\h'\n[lss]u'sub
\h'\n[lss]u'O
\h'\n[lss]u'on gosub ? jump to one of multiple gosub-targets
\h'\n[lss]u'on goto ? jump to one of many goto-targets
\h'\n[lss]u'on interrupt ? change reaction on keyboard interrupts
\h'\n[lss]u'open ? open a file
\h'\n[lss]u'open printer ? open printer for printing graphics
\h'\n[lss]u'open window ? open a graphic window
\h'\n[lss]u'logical or ? logical or, used in conditions
\h'\n[lss]u'or() ? arithmetic or, used for bit-operations
\h'\n[lss]u'Name
\h'\n[lss]u'on goto ? jump to one of multiple gosub-targets
\h'\n[lss]u'Synopsis
\h'\n[lss]u'on a gosub foo,bar,baz
\h'\n[lss]u'?
\h'\n[lss]u'label foo
\h'\n[lss]u'?
\h'\n[lss]u'return
\h'\n[lss]u'label bar
\h'\n[lss]u'?
\h'\n[lss]u'return
\h'\n[lss]u'label baz
\h'\n[lss]u'?
\h'\n[lss]u'return
\h'\n[lss]u'Description
\h'\n[lss]u'The on gosub statement uses its numeric argument (the one between on and gosub)
\h'\n[lss]u'to select an element from the list of labels, which follows after the
\h'\n[lss]u'gosub-keyword: If the number is 1, the program does a gosub to the first label;
\h'\n[lss]u'if the number is 2, to the second and, so on. if the number is zero or less,
\h'\n[lss]u'the program continues at the position of the first label; if the number is
\h'\n[lss]u'larger than the total count of labels, the execution continues at the position
\h'\n[lss]u'of the last label; i.e. the first and last label in the list constitute some
\h'\n[lss]u'kind of fallback-slot.
\h'\n[lss]u'Note, that the on gosub-command can no longer be considered state of the art;
\h'\n[lss]u'people (not me !) may even start to mock you, if you use it.
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'print "Please enter a number between 1 and 3: "
\h'\n[lss]u'print
\h'\n[lss]u'input "Your choice " a
\h'\n[lss]u'on a gosub bad,one,two,three,bad
\h'\n[lss]u'loop
\h'\n[lss]u'label bad
\h'\n[lss]u'print "No. Please between 1 and 3"
\h'\n[lss]u'return
\h'\n[lss]u'label one
\h'\n[lss]u'print "one"
\h'\n[lss]u'return
\h'\n[lss]u'label two
\h'\n[lss]u'print "two"
\h'\n[lss]u'return
\h'\n[lss]u'label three
\h'\n[lss]u'print "three"
\h'\n[lss]u'return
\h'\n[lss]u'Note, how invalid input (a number less than 1, or larger than 3) is
\h'\n[lss]u'automatically detected.
\h'\n[lss]u'See also
\h'\n[lss]u'goto, on gosub/function>
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'on goto ? jump to one of many goto-targets
\h'\n[lss]u'Synopsis
\h'\n[lss]u'on a goto foo,bar,baz
\h'\n[lss]u'?
\h'\n[lss]u'label foo
\h'\n[lss]u'?
\h'\n[lss]u'label bar
\h'\n[lss]u'?
\h'\n[lss]u'label baz
\h'\n[lss]u'?
\h'\n[lss]u'Description
\h'\n[lss]u'The on goto statement uses its numeric argument (the one between on and goto to
\h'\n[lss]u'select an element from the list of labels, which follows after the
\h'\n[lss]u'goto-keyword: If the number is 1, the execution continues at the first label;
\h'\n[lss]u'if the number is 2, at the second, and so on. if the number is zero or less,
\h'\n[lss]u'the program continues at the position of the first label; if the number is
\h'\n[lss]u'larger than the total count of labels, the execution continues at the position
\h'\n[lss]u'of the last label; i.e. the first and last label in the list constitute some
\h'\n[lss]u'kind of fallback-slot.
\h'\n[lss]u'Note, that (unlike the goto-command) the on goto-command can no longer be
\h'\n[lss]u'considered state of the art; people may (not me !) even start to mock you, if
\h'\n[lss]u'you use it.
\h'\n[lss]u'Example
\h'\n[lss]u'label over
\h'\n[lss]u'print "Please Select one of these choices: "
\h'\n[lss]u'print
\h'\n[lss]u'print " 1 -- show time"
\h'\n[lss]u'print " 2 -- show date"
\h'\n[lss]u'print " 3 -- exit"
\h'\n[lss]u'print
\h'\n[lss]u'input "Your choice " a
\h'\n[lss]u'on a goto over,show_time,show_date,terminate,over
\h'\n[lss]u'label show_time
\h'\n[lss]u'print time$()
\h'\n[lss]u'goto over
\h'\n[lss]u'label show_date
\h'\n[lss]u'print date$()
\h'\n[lss]u'goto over
\h'\n[lss]u'label terminate
\h'\n[lss]u'exit
\h'\n[lss]u'Note, how invalid input (a number less than 1, or larger than 3) is
\h'\n[lss]u'automatically detected; in such a case the question is simply issued again.
\h'\n[lss]u'See also
\h'\n[lss]u'goto, on gosub/function>
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'on interrupt ? change reaction on keyboard interrupts
\h'\n[lss]u'Synopsis
\h'\n[lss]u'on interrupt break
\h'\n[lss]u'?
\h'\n[lss]u'on interrupt continue
\h'\n[lss]u'Description
\h'\n[lss]u'With the on interrupt-command you may change the way, how yabasic reacts on a
\h'\n[lss]u'keyboard interrupt; it comes in two variants: on interrupt break and on
\h'\n[lss]u'interrupt continue. A keyboard interrupt is produced, if you press ctrl-C on
\h'\n[lss]u'your keyboard; normally (and certainly after you have called on interrupt
\h'\n[lss]u'break), yabasic will terminate with an error message. However after the command
\h'\n[lss]u'on interrupt continue yabasic ignores any keyboard interrupt. This may be
\h'\n[lss]u'useful, if you do not want your program being interruptible during certain
\h'\n[lss]u'critical operations (e.g. updating of files).
\h'\n[lss]u'Example
\h'\n[lss]u'print "Please stand by while writing a file with random data ..."
\h'\n[lss]u'on interrupt continue
\h'\n[lss]u'open "random.data" for writing as #1
\h'\n[lss]u'for a=1 to 100
\h'\n[lss]u'print #1 ran(100)
\h'\n[lss]u'print a," percent done."
\h'\n[lss]u'sleep 1
\h'\n[lss]u'next a
\h'\n[lss]u'close #1
\h'\n[lss]u'on interrupt continue
\h'\n[lss]u'This program writes a file with 100 random numbers. The on interrupt continue
\h'\n[lss]u'command insures, that the program will not be terminated on a keyboard
\h'\n[lss]u'interrupt and the file will be written entirely in any case. The sleep-command
\h'\n[lss]u'just stretches the process artificially to give you a chance to try a ctrl-C.
\h'\n[lss]u'See also
\h'\n[lss]u'There is no related command.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'open ? open a file
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open a,"file","r"
\h'\n[lss]u'open #a,"file","w"
\h'\n[lss]u'open #a,printer
\h'\n[lss]u'open "file" for reading as a
\h'\n[lss]u'open "file" for writing as #a
\h'\n[lss]u'a=open("file")
\h'\n[lss]u'a=open("file","r")
\h'\n[lss]u'if (open(a,"file")) ?
\h'\n[lss]u'if (open(a,"file","w")) ?
\h'\n[lss]u'Description
\h'\n[lss]u'The open-command opens a file for reading or writing or a printer for printing
\h'\n[lss]u'text. open comes in a wide variety of ways; it requires these arguments:
\h'\n[lss]u'filenumber
\h'\n[lss]u'In the synopsis this is a or #a. In yabasic each file is associated with a
\h'\n[lss]u'number between 1 and a maximum value, which depends on the operating
\h'\n[lss]u'system. For historical reasons the filenumber can be preceded by a hash ('#
\h'\n[lss]u''). Note, that specifying a filenumber is optional; if it is omitted, the
\h'\n[lss]u'open-function will return a filenumber, which should then be stored in a
\h'\n[lss]u'variable for later reference. This filenumber can be a simple number or an
\h'\n[lss]u'arbitrary complex arithmetic expression, in which case braces might be
\h'\n[lss]u'necessary to save yabasic from getting confused.
\h'\n[lss]u'filename
\h'\n[lss]u'In the synopsis above this is "file". This string specifies the name of the
\h'\n[lss]u'file to open (note the important caveat on specifying these filenames).
\h'\n[lss]u'accessmode
\h'\n[lss]u'In the synopsis this is "r", "w", for reading or for writing. This string
\h'\n[lss]u'or clause specifies the mode in which the file is opened; it may be one of:
\h'\n[lss]u'"r"
\h'\n[lss]u'Open the file for reading (may also be written as for reading). If the
\h'\n[lss]u'file does not exist, the command will fail. This mode is the default,
\h'\n[lss]u'i.e. if no mode is specified with the open-command, the file will be
\h'\n[lss]u'opened with this mode.
\h'\n[lss]u'"w"
\h'\n[lss]u'Open the file for writing (may also be written as for writing). If the
\h'\n[lss]u'file does not exist, it will be created.
\h'\n[lss]u'"a"
\h'\n[lss]u'Open the file for appending, i.e. what you write to the file will be
\h'\n[lss]u'appended after its initial contents. If the file does not exist, it
\h'\n[lss]u'will be created.
\h'\n[lss]u'"b"
\h'\n[lss]u'This letter may not appear alone, but may be combined with the other
\h'\n[lss]u'letters (e.g. "rb") to open a file in binary mode (as opposed to text
\h'\n[lss]u'mode).
\h'\n[lss]u'As you may see from the synopsis, the open-command may either be called as a
\h'\n[lss]u'command (without braces) or as a function (with braces). If called as a
\h'\n[lss]u'function, it will return the filenumber or zero if the operation fails.
\h'\n[lss]u'Therefore the open-function may be used within the condition of an
\h'\n[lss]u'if-statement.
\h'\n[lss]u'If the open-command fails, you may use peek("error") to retrieve the exact
\h'\n[lss]u'nature of the error.
\h'\n[lss]u'Furthermore note, that there is another, somewhat separate usage of the
\h'\n[lss]u'open-command; if you specify the bareword printer instead of a filename, the
\h'\n[lss]u'command opens a printer for printing text. Every text (and only text) you print
\h'\n[lss]u'to this file will appear on your printer. Note, that this is very different
\h'\n[lss]u'from printing graphics, as can be done with open printer.
\h'\n[lss]u'Example
\h'\n[lss]u'open "foo.bar" for writing as #1
\h'\n[lss]u'print #1 "Hallo !"
\h'\n[lss]u'close #1
\h'\n[lss]u'if (not open(1,"foo.bar")) error "Could not open 'foo.bar' for reading"
\h'\n[lss]u'while(not eof(1))
\h'\n[lss]u'line input #1 a$
\h'\n[lss]u'print a$
\h'\n[lss]u'wend
\h'\n[lss]u'This example simply opens the file foo.bar, writes a single line, reopens it
\h'\n[lss]u'and reads its contents again.
\h'\n[lss]u'See also
\h'\n[lss]u'close, print, peek, peek("error") and open printer
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'open printer ? open printer for printing graphics
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open printer
\h'\n[lss]u'open printer "file"
\h'\n[lss]u'Description
\h'\n[lss]u'The open printer-command opens a printer for printing graphics. The command
\h'\n[lss]u'requires, that a graphic window has been opened before. Everything that is
\h'\n[lss]u'drawn into this window will then be sent to the printer too.
\h'\n[lss]u'A new piece of paper may be started with the clear window-command; the final
\h'\n[lss]u'(or only) page will appear after the close printer-command.
\h'\n[lss]u'Note, that you may specify a filename with open printer; in that case the
\h'\n[lss]u'printout will be sent to a filename instead to a printer. Your program or the
\h'\n[lss]u'user will be responsible for sending this file to the printer afterwards.
\h'\n[lss]u'If you use yabasic under Unix, you will need a postscript printer (because
\h'\n[lss]u'yabasic produces postscript output). Alternatively you may use ghostscript to
\h'\n[lss]u'transform the postscript file into a form suitable for your printer; but that
\h'\n[lss]u'is beyond the responsibility of yabasic.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'open printer
\h'\n[lss]u'line 0,0 to 200,200
\h'\n[lss]u'text 100,100,"Hallo"
\h'\n[lss]u'close window
\h'\n[lss]u'close printer
\h'\n[lss]u'This example will open a window, draw a line and print some text within;
\h'\n[lss]u'everything will appear on your printer too.
\h'\n[lss]u'See also
\h'\n[lss]u'close printer
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'open window ? open a graphic window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window x,y
\h'\n[lss]u'open window x,y,"font"
\h'\n[lss]u'Description
\h'\n[lss]u'The open window-command opens a window of the specified size. Only one window
\h'\n[lss]u'can be opened at any given moment of time.
\h'\n[lss]u'An optional third argument specifies a font to be used for any text within the
\h'\n[lss]u'window. It can however be changed with any subsequent text-command.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=200 to 400 step 10
\h'\n[lss]u'open window a,a
\h'\n[lss]u'for b=0 to a
\h'\n[lss]u'line 0,b to a,b
\h'\n[lss]u'line b,0 to b,a
\h'\n[lss]u'sleep 0.1
\h'\n[lss]u'close window
\h'\n[lss]u'next a
\h'\n[lss]u'See also
\h'\n[lss]u'close window, text
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'or ? logical or, used in conditions
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (a or b) ?
\h'\n[lss]u'while (a or b) ?
\h'\n[lss]u'Description
\h'\n[lss]u'Used in conditions (e.g within if or while) to join two expressions. Returns
\h'\n[lss]u'true, if either its left or its right or both arguments are true; returns false
\h'\n[lss]u'otherwise.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a number"
\h'\n[lss]u'if (a>9 or a<1) print "a is not between 1 and 9"
\h'\n[lss]u'See also
\h'\n[lss]u'and,not
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'or() ? arithmetic or, used for bit-operations
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=or(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'Used to compute the bitwise or of both its argument. Both arguments are treated
\h'\n[lss]u'as binary numbers (i.e. a series of 0 and 1); a bit of the resulting value will
\h'\n[lss]u'then be 1, if any of its arguments has 1 at this position in their binary
\h'\n[lss]u'representation.
\h'\n[lss]u'Note, that both arguments are silently converted to integer values and that
\h'\n[lss]u'negative numbers have their own binary representation and may lead to
\h'\n[lss]u'unexpected results when passed to or.
\h'\n[lss]u'Example
\h'\n[lss]u'print or(14,3)
\h'\n[lss]u'This will print 15. This result is clear, if you note, that the binary
\h'\n[lss]u'representation of 14 and 3 are 1110 and 0011 respectively; this will yield 1111
\h'\n[lss]u'in binary representation or 15 as decimal.
\h'\n[lss]u'See also
\h'\n[lss]u'oand, eor and not
\h'\n[lss]u'P
\h'\n[lss]u'pause ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'peek ? retrieve various internal information
\h'\n[lss]u'peek$ ? retrieve various internal string-information
\h'\n[lss]u'pi ? a constant with the value 3.14159
\h'\n[lss]u'poke ? change selected internals of yabasic
\h'\n[lss]u'print ? Write to terminal or file
\h'\n[lss]u'print color ? print with color
\h'\n[lss]u'print colour ? see print color
\h'\n[lss]u'putbit ? draw a rectangle of pixels encoded within a string into the graphics
\h'\n[lss]u'window
\h'\n[lss]u'putscreen ? draw a rectangle of characters into the text terminal
\h'\n[lss]u'Name
\h'\n[lss]u'pause ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'Synopsis
\h'\n[lss]u'pause 5
\h'\n[lss]u'Description
\h'\n[lss]u'The pause-command has many different names: You may write pause, sleep or wait
\h'\n[lss]u'interchangeably; whatever you write, yabasic will always do exactly the same.
\h'\n[lss]u'The pause-command will simply wait for the specified number of seconds. This
\h'\n[lss]u'may be a fractional number, so you may well wait less than a second. However,
\h'\n[lss]u'if you try to pause for a smaller and smaller interval (e.g. 0.1 seconds, 0.01
\h'\n[lss]u'seconds, 0.001 seconds and so on) you will find that at some point yabasic will
\h'\n[lss]u'not wait at all. The minimal interval that can be waited depends on the system
\h'\n[lss]u'(Unix, Windows) you are using.
\h'\n[lss]u'The pause-command cannot be interrupted. However, sometimes you may want the
\h'\n[lss]u'wait to be interruptible by simply pressing a key on the keyboard. In such
\h'\n[lss]u'cases you should consider using the inkey$-function, with a number of seconds
\h'\n[lss]u'as an argument).
\h'\n[lss]u'Example
\h'\n[lss]u'deg=0
\h'\n[lss]u'do
\h'\n[lss]u'maxx=44+40*sin(deg)
\h'\n[lss]u'for x=1 to maxx
\h'\n[lss]u'print "*";
\h'\n[lss]u'next x
\h'\n[lss]u'pause 0.1+(maxx*maxx/(4*84*84))
\h'\n[lss]u'print
\h'\n[lss]u'deg=deg+0.1
\h'\n[lss]u'loop
\h'\n[lss]u'This example draws a sine-curve; due to the pause-statement the speed of
\h'\n[lss]u'drawing varies in the same way as the speed of a ball might vary, if it would
\h'\n[lss]u'roll along this curve under the influence of gravity.
\h'\n[lss]u'See also
\h'\n[lss]u'sleep, wait
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'peek ? retrieve various internal information
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print peek("foo")
\h'\n[lss]u'a=peek(#1)
\h'\n[lss]u'Description
\h'\n[lss]u'The peek-function has many different and mostly unrelated uses. It is a kind of
\h'\n[lss]u'grab-bag for retrieving all kinds of numerical information, internal to yabasic
\h'\n[lss]u'. The meaning of the numbers returned be the peek-function depends on the
\h'\n[lss]u'string or number passed as an argument.
\h'\n[lss]u'peek always returns a number, however the closely related peek$-function
\h'\n[lss]u'exists, which may be used to retrieve string information from among the
\h'\n[lss]u'internals of yabasic. Finally note, that some of the values which are retrieved
\h'\n[lss]u'with peek may even be changed, using the poke-function.
\h'\n[lss]u'There are two variants of the peek-function: One expects an integer, positive
\h'\n[lss]u'number and is described within the first entry of the list below. The other
\h'\n[lss]u'variant expects one of a well defined set of strings as described in the second
\h'\n[lss]u'and all the following entries of the list below.
\h'\n[lss]u'peek(a)
\h'\n[lss]u'Read a single character from the file a (which must be open of course).
\h'\n[lss]u'peek("argument")
\h'\n[lss]u'Return the number of arguments, that have been passed to yabasic at
\h'\n[lss]u'invocation time. E.g. if yabasic has been called like this: yabasic foo.yab
\h'\n[lss]u'bar baz, then peek("argument") will return 2. This is because foo.yab is
\h'\n[lss]u'treated as the name of the program to run, whereas bar and baz are
\h'\n[lss]u'considered arguments to the program, which are passed on the command line.
\h'\n[lss]u'Note, that for windows-users, who tend to click on the icon (as opposed to
\h'\n[lss]u'starting yabasic on the command line), this peekwill mostly return 0.
\h'\n[lss]u'The function peek("argument") can be written as peek("arguments") too.
\h'\n[lss]u'You will want to check out the corresponding function peek$("argument") to
\h'\n[lss]u'actually retrieve the arguments. Note, that each call to peek$("argument")
\h'\n[lss]u'reduces the number returned by peek("argument").
\h'\n[lss]u'peek("error")
\h'\n[lss]u'Return a number specifying the nature of the last error in an open- or
\h'\n[lss]u'seek-statement. Normally an error within an open-statement immediately
\h'\n[lss]u'terminates your program with an appropriate error-message, so there is no
\h'\n[lss]u'chance and no need to learn more about the nature of the error. However, if
\h'\n[lss]u'you use open as a condition (e.g. if (open(#1,"foo")) ?) the outcome
\h'\n[lss]u'(success or failure) of the open-operation will determine, if the condition
\h'\n[lss]u'evaluates to true or false. If now such an operation fails, your program
\h'\n[lss]u'will not be terminated and you might want to learn the reason for failure.
\h'\n[lss]u'This reason will be returned by peek("error") (as a number) or by peek$
\h'\n[lss]u'("error") (as a string)
\h'\n[lss]u'The table below shows the various error codes; the value returned by peek$
\h'\n[lss]u'("error") explains the nature of the error. Note, that the codes 10,11 and
\h'\n[lss]u'12 refer to the seek-command.
\h'\n[lss]u'Table 7.1. Error codes
\h'\n[lss]u'+-------------------------------------------------------------------------+
\h'\n[lss]u'| peek |peek$("error")| Explanation |
\h'\n[lss]u'|("error")| | |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| 2 |Stream already|Do not try to open one and the same filenumber |
\h'\n[lss]u'| |in use |twice; rather close it first. |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| |'x' is not a |The optional filemode argument, which may be |
\h'\n[lss]u'| 3 |valid filemode|passed to the open-function, has an invalid |
\h'\n[lss]u'| | |value |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| 4 |could not open|The open-call did not work, no further |
\h'\n[lss]u'| |'foo' |explanation is available. |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| |reached |You have opened more files than your operating |
\h'\n[lss]u'| 5 |maximum number|system permits. |
\h'\n[lss]u'| |of open files | |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| |cannot open |The commands open printer and open #1,printer |
\h'\n[lss]u'| |printer: |both open a printer (refer to their description |
\h'\n[lss]u'| 6 |already |for the difference). However, only one can be |
\h'\n[lss]u'| |printing |active at a time; if you try to do both at the |
\h'\n[lss]u'| |graphics |same time, you will receive this error. |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| 7 |could not open|Well, it simply did not work. |
\h'\n[lss]u'| |line printer | |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| 9 |invalid stream|An attempt to use an invalid (e.g. negative) |
\h'\n[lss]u'| |number |stream number; example: open(-1,"foo") |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| |could not | |
\h'\n[lss]u'| 10 |position |seek did not work. |
\h'\n[lss]u'| |stream x to | |
\h'\n[lss]u'| |byte y | |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| 11 |stream x not |You have tried to seek within a stream, that has|
\h'\n[lss]u'| |open |not been opened yet. |
\h'\n[lss]u'|---------+--------------+------------------------------------------------|
\h'\n[lss]u'| |seek mode 'x' |The argument, which has been passed to seek is |
\h'\n[lss]u'| 12 |is none of |invalid. |
\h'\n[lss]u'| |begin,end,here| |
\h'\n[lss]u'+-------------------------------------------------------------------------+
\h'\n[lss]u'peek("fontheight")
\h'\n[lss]u'Return the height of the font used within the graphic window. If none is
\h'\n[lss]u'open, this peek will return the height of the last font used or 10, if no
\h'\n[lss]u'window has been opened yet.
\h'\n[lss]u'peek("screenheight")
\h'\n[lss]u'Return the height in characters of the window, wherein yabasic runs. If you
\h'\n[lss]u'have not called clear screen yet, this peekwill return 0, regardless of the
\h'\n[lss]u'size of your terminal.
\h'\n[lss]u'peek("screenwidth")
\h'\n[lss]u'Return the width in characters of the window, wherein yabasic runs. If you
\h'\n[lss]u'have not called clear screen yet, this peekwill return 0, regardless of the
\h'\n[lss]u'size of your terminal.
\h'\n[lss]u'peek("secondsrunning")
\h'\n[lss]u'Return the number of seconds that have passed since the start of yabasic.
\h'\n[lss]u'peek("millisrunning")
\h'\n[lss]u'Return the number of milliseconds, that have passed since the start of
\h'\n[lss]u'yabasic.
\h'\n[lss]u'peek("version")
\h'\n[lss]u'Return the version number of yabasic, e.g. 2.77. See also the related peek$
\h'\n[lss]u'("version"), which returns nearly the same information (plus the
\h'\n[lss]u'patchlevel) as a string, e.g. "2.77.1".
\h'\n[lss]u'peek("winheight")
\h'\n[lss]u'Return the height of the graphic-window in pixels. If none is open, this
\h'\n[lss]u'peek will return the height of the last window opened or 100, if none has
\h'\n[lss]u'been opened yet.
\h'\n[lss]u'peek("winwidth")
\h'\n[lss]u'Return the width of the graphic-window in pixels. If none is open, this
\h'\n[lss]u'peek will return the width of the last window opened or 100, if none has
\h'\n[lss]u'been opened yet.
\h'\n[lss]u'peek("isbound")
\h'\n[lss]u'Return true, if the executing yabasic-program is part of a standalone
\h'\n[lss]u'program; see the section about creating a standalone-program for details.
\h'\n[lss]u'peek("version")
\h'\n[lss]u'Return the version number of yabasic (e.g. 2.72).
\h'\n[lss]u'Example
\h'\n[lss]u'open "foo" for reading as #1
\h'\n[lss]u'open "bar" for writing as #2
\h'\n[lss]u'while(not eof(#1))
\h'\n[lss]u'poke #2,chr$(peek(#1));
\h'\n[lss]u'wend
\h'\n[lss]u'This program will copy the file foo byte by byte to bar.
\h'\n[lss]u'Note, that each peek does something entirely different, and only one has been
\h'\n[lss]u'demonstrated above. Therefore you need to make up examples yourself for all the
\h'\n[lss]u'other peeks.
\h'\n[lss]u'See also
\h'\n[lss]u'peek$, poke, open
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'peek$ ? retrieve various internal string-information
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print peek$("foo")
\h'\n[lss]u'Description
\h'\n[lss]u'The peek$-function has many different and unrelated uses. It is a kind of
\h'\n[lss]u'grab-bag for retrieving all kinds of string information, internal to yabasic;
\h'\n[lss]u'the exact nature of the strings returned be the peek$-function depends on the
\h'\n[lss]u'string passed as an argument.
\h'\n[lss]u'peek$ always returns a string, however the closely related peek-function
\h'\n[lss]u'exists, which may be used to retrieve numerical information from among the
\h'\n[lss]u'internals of yabasic. Finally note, that some of the values which are retrieved
\h'\n[lss]u'with peek$ may even be changed, using the poke-function.
\h'\n[lss]u'The following list shows all possible arguments to peek$:
\h'\n[lss]u'peek$("infolevel")
\h'\n[lss]u'Returns either "debug", "note", "warning", "error" or "fatal", depending on
\h'\n[lss]u'the current infolevel. This value can be specified with an option on the
\h'\n[lss]u'command line or changed during the execution of the program with the
\h'\n[lss]u'corresponding poke; however, normally only the author of yabasic (me !)
\h'\n[lss]u'would want to change this from its default value "warning".
\h'\n[lss]u'peek$("textalign")
\h'\n[lss]u'Returns one of nine possible strings, specifying the default alignment of
\h'\n[lss]u'text within the graphics-window. The alignment-string returned by this peek
\h'\n[lss]u'describes, how the text-command aligns its string-argument with respect to
\h'\n[lss]u'the coordinates supplied. However, this value does not apply, if the
\h'\n[lss]u'text-command explicitly specifies an alignment. Each of these strings is
\h'\n[lss]u'two characters long. The first character specifies the horizontal alignment
\h'\n[lss]u'and can be either l, r or c, which stand for left, right or center. The
\h'\n[lss]u'second character specifies the vertical alignment and can be one of t, b or
\h'\n[lss]u'c, which stand for top, bottom or center respectively.
\h'\n[lss]u'You may change this value with the corresponding command poke
\h'\n[lss]u'"textalign",?; the initial value is lb, which means the top of the left and
\h'\n[lss]u'the top edge if the text will be aligned with the coordinates, that are
\h'\n[lss]u'specified within the text-command.
\h'\n[lss]u'peek$("windoworigin")
\h'\n[lss]u'This peek returns a two character string, which specifies the position of
\h'\n[lss]u'the origin of the coordinate system of the window; this string might be
\h'\n[lss]u'changed with the corresponding command poke "windoworigin",x,y or specified
\h'\n[lss]u'as the argument of the origin command; see there for a detailed description
\h'\n[lss]u'of the string, which might be returned by this peek.
\h'\n[lss]u'peek$("program_name")
\h'\n[lss]u'Returns the name of the yabasic-program that is currently executing;
\h'\n[lss]u'typically this is the name, that you have specified on the commandline, but
\h'\n[lss]u'without any path-components. So this peek$ might return foo.yab. As a
\h'\n[lss]u'special case when yabasic has been invoked without the name of a program to
\h'\n[lss]u'be executed this peek will return the literal strings standard input or,
\h'\n[lss]u'when also the option -e has been specified, command line. See also peek$
\h'\n[lss]u'("program_file_name") and peek$("interpreter_path") for related
\h'\n[lss]u'information.
\h'\n[lss]u'peek$("program_file_name")
\h'\n[lss]u'Returns the full file-name of the yabasic-program that is currently
\h'\n[lss]u'executing; typically this is the name, that you have specified on the
\h'\n[lss]u'commandline, including any path-components. For the special case, that you
\h'\n[lss]u'have bound your yabasic-program with the interpreter to a single standalone
\h'\n[lss]u'executable, this peek$ will return its name. See also peek$("program_name")
\h'\n[lss]u'and peek$("interpreter_path") for related information.
\h'\n[lss]u'peek$("interpreter_path")
\h'\n[lss]u'Return the full file-name of the yabasic-interpreter that is currently
\h'\n[lss]u'executing your program; typically this will end on yabasic or yabasic.exe
\h'\n[lss]u'depending on your platform and the path will be where you installed yabasic
\h'\n[lss]u'. For bound programs (see creating a standalone-program) however, this may
\h'\n[lss]u'be different and will include whatever you specified during the bind
\h'\n[lss]u'-command.
\h'\n[lss]u'See also peek$("program_name") and peek$("program_file_name") for related
\h'\n[lss]u'information. Employing these, it would be possible for a yabasic-program to
\h'\n[lss]u'start itself: system(peek$("interpreter_path") + " " + peek$
\h'\n[lss]u'("program_file_name")). Of course, in this simple form this would be a bad
\h'\n[lss]u'idea, because this would start concurrent instances of yabasic without end.
\h'\n[lss]u'peek$("error")
\h'\n[lss]u'Return a string describing the nature of the last error in an open- or
\h'\n[lss]u'seek-statement. See the corresponding peek("error") for a detailed
\h'\n[lss]u'description.
\h'\n[lss]u'peek$("library")
\h'\n[lss]u'Return the name of the library, this statement is contained in. See the
\h'\n[lss]u'import-command for a detailed description or for more about libraries.
\h'\n[lss]u'peek$("version")
\h'\n[lss]u'Version of yabasic as a string; e.g. 2.77.1. See also the related peek
\h'\n[lss]u'("version"), which returns nearly the same information (minus the
\h'\n[lss]u'patchlevel) as a number, e.g. 2.77.
\h'\n[lss]u'peek$("os")
\h'\n[lss]u'This peek returns the name of the operating system, where your program
\h'\n[lss]u'executes. This can be either windows or unix.
\h'\n[lss]u'peek$("font")
\h'\n[lss]u'Return the name of the font, which is used for text within the graphic
\h'\n[lss]u'window; this value can be specified as the third argument to the open
\h'\n[lss]u'window-command.
\h'\n[lss]u'peek$("env","NAME")
\h'\n[lss]u'Return the environment variable specified by NAME (which may be any string
\h'\n[lss]u'expression). Which kind of environment variables are available on your
\h'\n[lss]u'system depends, as well as their meaning, on your system; however typing
\h'\n[lss]u'env on the command line will produce a list (for Windows and Unix alike).
\h'\n[lss]u'Note, that peek$("env",...) can be written as peek$("environment",...) too.
\h'\n[lss]u'peek$("argument")
\h'\n[lss]u'Return one of the arguments, that have been passed to yabasic at invocation
\h'\n[lss]u'time (the next call will return the the second argument, and so on). E.g.
\h'\n[lss]u'if yabasic has been called like this: yabasic foo.yab bar baz, then the
\h'\n[lss]u'first call to peek$("argument") will return bar. This is because foo.yab is
\h'\n[lss]u'treated as the name of the program to run, whereas bar and baz are
\h'\n[lss]u'considered arguments to this program, which are passed on the command line.
\h'\n[lss]u'The second call to peek$("argument") will return baz. Note, that for
\h'\n[lss]u'windows-users, who tend to click on the icon (as opposed to starting
\h'\n[lss]u'yabasic on the command line), this peekwill mostly return the empty string.
\h'\n[lss]u'Note, that peek$("argument") can be written as peek$("arguments").
\h'\n[lss]u'Finally you will want to check out the corresponding function peek
\h'\n[lss]u'("argument").
\h'\n[lss]u'Example
\h'\n[lss]u'print "You have supplied these arguments: "
\h'\n[lss]u'while(peek("argument"))
\h'\n[lss]u'print peek("argument"),peek$("argument")
\h'\n[lss]u'wend
\h'\n[lss]u'If you save this program in a file foo.yab and execute it via yabasic t.yab a b
\h'\n[lss]u'c (for windows users: please use the command line for this), your will get this
\h'\n[lss]u'output:
\h'\n[lss]u'3a
\h'\n[lss]u'2b
\h'\n[lss]u'1c
\h'\n[lss]u'See also
\h'\n[lss]u'peek, poke, open
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'pi ? a constant with the value 3.14159
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print pi
\h'\n[lss]u'Description
\h'\n[lss]u'pi is 3.14159265359 (well at least for yabasic); do not try to assign to pi
\h'\n[lss]u'(e.g. pi=22/7) this would not only be mathematically dubious, but would also
\h'\n[lss]u'result in a syntax error.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=0 to 180
\h'\n[lss]u'print "The sine of ",a," degrees is ",sin(a*pi/180)
\h'\n[lss]u'next a
\h'\n[lss]u'This program uses pi to transform an angle from degrees into radians.
\h'\n[lss]u'See also
\h'\n[lss]u'euler
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'poke ? change selected internals of yabasic
\h'\n[lss]u'Synopsis
\h'\n[lss]u'poke "foo","bar"
\h'\n[lss]u'poke "foo",baz
\h'\n[lss]u'poke #a,"bar"
\h'\n[lss]u'poke #a,baz
\h'\n[lss]u'Description
\h'\n[lss]u'The poke-command may be used to change details of yabasic's behaviour. Like the
\h'\n[lss]u'related function peek, poke does many different things, depending on the
\h'\n[lss]u'arguments supplied.
\h'\n[lss]u'Here are the different things you can do with poke:
\h'\n[lss]u'poke 5,a
\h'\n[lss]u'Write the given byte (a in the example above) to the specified stream (5#a
\h'\n[lss]u'in the example).
\h'\n[lss]u'See also the related function function peek(1).
\h'\n[lss]u'poke "dump","filename.dump"
\h'\n[lss]u'Dump the internal form of your basic-program to the named file; this is
\h'\n[lss]u'only useful for debugging the internals of yabasic itself.
\h'\n[lss]u'The second argument ("filename.dump" in the example) should be the name of
\h'\n[lss]u'a file, that gets overwritten with the dump, please be careful.
\h'\n[lss]u'poke "fontheight",12
\h'\n[lss]u'This poke changes the default fontheight. This can only have an effect, if
\h'\n[lss]u'the fonts given in the commands text or open window do not specify a
\h'\n[lss]u'fontheight on their own.
\h'\n[lss]u'poke "font","fontname"
\h'\n[lss]u'This poke specifies the default font. This can only have an effect, if you
\h'\n[lss]u'do not supply a fontname with the commands text or open window.
\h'\n[lss]u'poke "infolevel","debug"
\h'\n[lss]u'Change the amount of internal information, that yabasic outputs during
\h'\n[lss]u'execution.
\h'\n[lss]u'The second argument can be either "debug", "note", "warning", "error" or
\h'\n[lss]u'"fatal". However, normally you will not want to change this from its
\h'\n[lss]u'default value "warning".
\h'\n[lss]u'See also the related peek$("infolevel").
\h'\n[lss]u'poke "random_seed",42
\h'\n[lss]u'Set the seed for the random number generator; if you do this, the ran
\h'\n[lss]u'-function will return the same sequence of numbers every time the program
\h'\n[lss]u'is started.
\h'\n[lss]u'poke "stdout","some text"
\h'\n[lss]u'Send the given text to standard output. Normally one would use print for
\h'\n[lss]u'this purpose; however, sending e.g. control characters to your terminal is
\h'\n[lss]u'easier with this poke.
\h'\n[lss]u'poke "textalign","cc"
\h'\n[lss]u'This poke changes the default alignment of text with respect to the
\h'\n[lss]u'coordinates supplied within the text-command. However, this value does not
\h'\n[lss]u'apply, if the text-command explicitly specifies an alignment. The second
\h'\n[lss]u'argument ("cc" in the example) must always be two characters long; the
\h'\n[lss]u'first character can be one of l (left), r (right) or c (center); the second
\h'\n[lss]u'character can be either t (top), b (bottom) or c (center); see the
\h'\n[lss]u'corresponding peek$("textalign") for a detailed description of this
\h'\n[lss]u'argument.
\h'\n[lss]u'poke "windoworigin","lt"
\h'\n[lss]u'This poke moves the origin of the coordinate system of the window to the
\h'\n[lss]u'specified position. The second argument ("lt" in the example) must always
\h'\n[lss]u'be two characters long; the first character can be one of l (left), r (
\h'\n[lss]u'right) or c (center); the second character can be either t (top), b (bottom
\h'\n[lss]u') or c (center). Together those two characters specify the new position of
\h'\n[lss]u'the coordinate-origin. See the corresponding peek$("windoworigin") for a
\h'\n[lss]u'more in depth description of this argument.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Hello, now you will see, how much work"
\h'\n[lss]u'print "a simple for-loop involves ..."
\h'\n[lss]u'input "Please press return " a$
\h'\n[lss]u'poke "infolevel","debug"
\h'\n[lss]u'for a=1 to 10:next a
\h'\n[lss]u'This example only demonstrates one of the many pokes, which are described
\h'\n[lss]u'above: The program switches the infolevel to debug, which makes yabasic produce
\h'\n[lss]u'a lot of debug-messages during the subsequent for-loop.
\h'\n[lss]u'See also
\h'\n[lss]u'peek, peek$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'print ? Write to terminal or file
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print "foo",a$,b
\h'\n[lss]u'print "foo",a$,b;
\h'\n[lss]u'print #a "foo",a$
\h'\n[lss]u'print #a "foo",a$;
\h'\n[lss]u'print foo using "##.###"
\h'\n[lss]u'print reverse "foo"
\h'\n[lss]u'print at(10,10) a$,b
\h'\n[lss]u'print @(10,10) a$,b
\h'\n[lss]u'print color("red","blue") a$,b
\h'\n[lss]u'print color("magenta") a$,b
\h'\n[lss]u'print color("green","yellow") at(5,5) a$,b
\h'\n[lss]u'Description
\h'\n[lss]u'The print-statement outputs strings or characters, either to your terminal
\h'\n[lss]u'(also known as console) or to an open file.
\h'\n[lss]u'To understand all those uses of the print-statement, let's go through the
\h'\n[lss]u'various lines in the synopsis above:
\h'\n[lss]u'print "foo",a$,b
\h'\n[lss]u'Print the string foo as well as the contents of the variables a$ and b onto
\h'\n[lss]u'the screen, silently adding a newline.
\h'\n[lss]u'print "foo",a$,b;
\h'\n[lss]u'(Note the trailing semicolon !) This statement does the same as the one
\h'\n[lss]u'above; only the implicit newline is skipped, which means that the next
\h'\n[lss]u'print-statement will append seamlessly.
\h'\n[lss]u'print #a "foo",a$
\h'\n[lss]u'This is the way to write to files. The file with the number a must be open
\h'\n[lss]u'already, an implicit newline is added. Note the file-number #a, which
\h'\n[lss]u'starts with a hash ('#') amd is separated from the rest of the statement by
\h'\n[lss]u'a space only. The file-number (contained in the variable a) must have been
\h'\n[lss]u'returned by a previous open-statement (e.g. a=open("bar")).
\h'\n[lss]u'print #a "foo",a$;
\h'\n[lss]u'The same as above, but without the implicit newline.
\h'\n[lss]u'print foo using "##.###"
\h'\n[lss]u'Print the number foo with as many digits before and after the decimal dot
\h'\n[lss]u'as given by the number of '#'-signs. See the entries for using and str$ for
\h'\n[lss]u'a detailed description of this format.
\h'\n[lss]u'print reverse "foo"
\h'\n[lss]u'As all the print-variants to follow, this form of the print-statement can
\h'\n[lss]u'only be issued after clear screen has been called. The strings and numbers
\h'\n[lss]u'after the reverse-clause are simply printed inverse (compared to the normal
\h'\n[lss]u'print-statement).
\h'\n[lss]u'print at(10,10) a$,b
\h'\n[lss]u'Print at the specified (x,y)-position. This is only allowed after clear
\h'\n[lss]u'screen has been called. You may want to query peek$("screenwidth") or peek$
\h'\n[lss]u'("screenheight") to learn the actual size of your screen. You may add a
\h'\n[lss]u'semicolon to suppress the implicit newline.
\h'\n[lss]u'print @(10,10) a$,b
\h'\n[lss]u'This is exactly the same as above, however, at may be written as @.
\h'\n[lss]u'print color("red","blue") at(5,5) a$,b
\h'\n[lss]u'Print with the specified fore- ("red") and background ("blue") color (or
\h'\n[lss]u'colour). The possible values are "black", "white", "red", "blue", "green",
\h'\n[lss]u'"yellow", "cyan" or "magenta". Again, you need to call clear screen first
\h'\n[lss]u'and add a semicolon if you want to suppress the implicit newline.
\h'\n[lss]u'print color("magenta") a$,b
\h'\n[lss]u'You may specify the foreground color only.
\h'\n[lss]u'print color("green","yellow") a$,b
\h'\n[lss]u'A color and a position (in this sequence, not the other way around) may be
\h'\n[lss]u'specified at once.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'columns=peek("screenwidth")
\h'\n[lss]u'lines=peek("screenheight")
\h'\n[lss]u'dim col$(7)
\h'\n[lss]u'for a=0 to 7:read col$(a):next a
\h'\n[lss]u'data "black","white","red","blue","green","yellow","cyan","magenta"
\h'\n[lss]u'for a=0 to 2*pi step 0.1
\h'\n[lss]u'print colour(col$(mod(i,8))) at(columns*(0.8*sin(a)+0.9)/2,lines*(0.8*cos(a)+0.9)/2) "*"
\h'\n[lss]u'i=i+1
\h'\n[lss]u'next a
\h'\n[lss]u'This example draws a colored ellipse within the text window.
\h'\n[lss]u'See also
\h'\n[lss]u'at, print color, input, clear screen, using, ;
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'print color ? print with color
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print color(fore$) text$
\h'\n[lss]u'print color(fore$,back$) text$
\h'\n[lss]u'Description
\h'\n[lss]u'Not a separate command, but part of the print-command; may be included just
\h'\n[lss]u'after print and can only be issued after clear screen has been executed.
\h'\n[lss]u'color() takes one or two string-arguments, specifying the color of the text and
\h'\n[lss]u'(optionally) the background.
\h'\n[lss]u'The one or two strings passed to color() can be one of these: "black", "white",
\h'\n[lss]u'"red", "blue", "green", "yellow", "cyan" and "magenta" (which can be
\h'\n[lss]u'abbreviated as "bla", "whi", "red", "blu", "gre", "yel", "cya" and "mag"
\h'\n[lss]u'respectively).
\h'\n[lss]u'color() can only be used, if clear scren has been issued at least once.
\h'\n[lss]u'Note, that color() can be written as colour() too.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'dim col$(7):for a=0 to 7:read col$(a):next a
\h'\n[lss]u'do
\h'\n[lss]u'print color(col$(ran(7)),col$(ran(7))) " Hallo ";
\h'\n[lss]u'pause 0.01
\h'\n[lss]u'loop
\h'\n[lss]u'data "black","white","red","blue"
\h'\n[lss]u'data "green","yellow","cyan","magenta"
\h'\n[lss]u'This prints the word " Hallo " in all colors across your screen.
\h'\n[lss]u'See also
\h'\n[lss]u'print, clear screen, at
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'print colour ? see print color
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print colour(fore$) text$
\h'\n[lss]u'print colour(fore$,back$) text$
\h'\n[lss]u'See also
\h'\n[lss]u'color
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'putbit ? draw a rectangle of pixels encoded within a string into the graphics
\h'\n[lss]u'window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'?
\h'\n[lss]u'a$=getbit(20,20,50,50)
\h'\n[lss]u'?
\h'\n[lss]u'putbit a$,30,30
\h'\n[lss]u'putbit a$ to 30,30
\h'\n[lss]u'putbit a$,30,30,"or"
\h'\n[lss]u'Description
\h'\n[lss]u'The putbit-command is the counterpart of the getbit$-function. putbit requires
\h'\n[lss]u'a string as returned by the getbit-function. Such a string contains a rectangle
\h'\n[lss]u'from the graphic window; the putbit-function puts such a rectangular region
\h'\n[lss]u'back into the graphic-window.
\h'\n[lss]u'Note, that the putbit-command currently accepts a fourth argument. However only
\h'\n[lss]u'the string value "or" is supported here. The effect is, that only those pixel,
\h'\n[lss]u'which are set in the string will be set in the graphic window. Those pixels,
\h'\n[lss]u'which are not set in the string, will not change in the window (as opposed to
\h'\n[lss]u'being cleared).
\h'\n[lss]u'Example
\h'\n[lss]u'c$="rgb 21,21:0000000000000000000000000000000000000000000000000000000000000032c80000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c8c8ff000032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80032c80000000000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80032c80000000000000000000032c80032c80032c80032c80032c8c8ff00c8ff00c8ff00c8ff00c8ff00c8ff00c8ff000032c80032c80032c80032c80032c80000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80032c80000000000000000000000000000000000000000000000000000000000000000000032c80032c80032c80032c80032c80032c80032c80032c80032c8000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000"
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'do
\h'\n[lss]u'x=ran(220)-10
\h'\n[lss]u'y=ran(220)-10
\h'\n[lss]u'putbit c$,x,y,"transparent"
\h'\n[lss]u'loop
\h'\n[lss]u'This program uses a precanned string (containing the image of a blue circle
\h'\n[lss]u'with a yellow centre) and draws it repeatedly into the graphic-window. The mode
\h'\n[lss]u'"transparent" ensures, that no pixels will be cleared.
\h'\n[lss]u'There are two possible values for the third argument of putbit. Both modes
\h'\n[lss]u'differ in the way, they replace (or not) any pixels from the window with pixels
\h'\n[lss]u'from the bitmap having the background colour.
\h'\n[lss]u'transparent or t
\h'\n[lss]u'With this mode the pixels from the window will be kept, if the bitmap
\h'\n[lss]u'contains pixels with background colour at this position; i.e. the bitmap is
\h'\n[lss]u'transparent
\h'\n[lss]u'solid or s
\h'\n[lss]u'With this mode the pixels from the window will be overpainted with the
\h'\n[lss]u'pixels from the bitmap in any case; i.e. the bitmap is solid
\h'\n[lss]u'If you omit this argument, the default transparent applies.
\h'\n[lss]u'See also
\h'\n[lss]u'getbit$, open window
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'putscreen ? draw a rectangle of characters into the text terminal
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'?
\h'\n[lss]u'a$=getscreen$(5,5,10,10)
\h'\n[lss]u'?
\h'\n[lss]u'putscreen a$,7,7
\h'\n[lss]u'Description
\h'\n[lss]u'The putscreen-command is the counterpart of the getscreen$-function. putscreen
\h'\n[lss]u'requires a string as returned by the getscreen-function. Such a string contains
\h'\n[lss]u'a rectangular detail from the terminal; the putscreen-function puts such a
\h'\n[lss]u'region back into the terminal-window.
\h'\n[lss]u'Note, that clear screen must have been called before.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'for a=1 to 200
\h'\n[lss]u'print color("red") "Hallo !";
\h'\n[lss]u'print color("blue") "Welt !";
\h'\n[lss]u'next a
\h'\n[lss]u'r$=getscreen$(0,0,20,20)
\h'\n[lss]u'for x=0 to 60
\h'\n[lss]u'putscreen r$,x,0
\h'\n[lss]u'sleep 0.1
\h'\n[lss]u'next x
\h'\n[lss]u'This example prints the string "Hallo !Welt !" all over the screen and then
\h'\n[lss]u'moves a rectangle from one side to the other.
\h'\n[lss]u'See also
\h'\n[lss]u'getscreen$, clear screen
\h'\n[lss]u'R
\h'\n[lss]u'ran() ? return a random number
\h'\n[lss]u'read ? read data from data-statements
\h'\n[lss]u'rectangle ? draw a rectangle
\h'\n[lss]u'redim ? create an array prior to its first use. A synonym for dim
\h'\n[lss]u'rem ? start a comment
\h'\n[lss]u'repeat ? start a repeat-loop
\h'\n[lss]u'restore ? reposition the data-pointer
\h'\n[lss]u'return ? return from a subroutine or a gosub
\h'\n[lss]u'reverse ? print reverse (background and foreground colors exchanged)
\h'\n[lss]u'right$() ? return (or change) the right end of a string
\h'\n[lss]u'rinstr() ? find the rightmost occurrence of one string within the other
\h'\n[lss]u'rtrim$() ? trim spaces at the right end of a string
\h'\n[lss]u'Name
\h'\n[lss]u'ran() ? return a random number
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print ran()
\h'\n[lss]u'x=ran(y)
\h'\n[lss]u'Description
\h'\n[lss]u'The ran-function returns a random number. If no argument is given, the number
\h'\n[lss]u'returned is in the range from 0 to 1; where only 0 is a possible value; 1 will
\h'\n[lss]u'never be returned. If an argument is supplied, the number returned will be in
\h'\n[lss]u'the range from 0 up to this argument, whereas this argument itself is not a
\h'\n[lss]u'possible return value. Regardless of the range, ran is guaranteed to have
\h'\n[lss]u'exactly 2**30 different return values.
\h'\n[lss]u'If you call ran multiple times during your program, the sequence of random
\h'\n[lss]u'numbers will be different each time you invoke your program; however, if, e.g.
\h'\n[lss]u'for testing you prefer to always have the same sequence of random numbers you
\h'\n[lss]u'may issue poke "random_seed",123.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'c=peek("screenwidth")-1
\h'\n[lss]u'l=peek("screenheight")
\h'\n[lss]u'dim col$(8)
\h'\n[lss]u'for a=0 to 7:read col$(a):next a
\h'\n[lss]u'data "black","white","red","blue","green","yellow","cyan","magenta"
\h'\n[lss]u'do
\h'\n[lss]u'x=ran(c)
\h'\n[lss]u'y=l-ran(l*exp(-32*((x/c-1/2)**2)))
\h'\n[lss]u'i=i+1
\h'\n[lss]u'print color(col$(mod(i,8))) at(x,y) "*";
\h'\n[lss]u'loop
\h'\n[lss]u'This example will print a colored bell-curve.
\h'\n[lss]u'See also
\h'\n[lss]u'int
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'read ? read data from data-statements
\h'\n[lss]u'Synopsis
\h'\n[lss]u'read a$,a
\h'\n[lss]u'?
\h'\n[lss]u'data "Hello !",7
\h'\n[lss]u'Description
\h'\n[lss]u'The read-statement retrieves literal data, which is stored within
\h'\n[lss]u'data-statements elsewhere in your program.
\h'\n[lss]u'Example
\h'\n[lss]u'read num
\h'\n[lss]u'dim col$(num)
\h'\n[lss]u'for a=1 to num:read col$(a):next a
\h'\n[lss]u'clear screen
\h'\n[lss]u'print "These are the colours known to yabasic:\n"
\h'\n[lss]u'for a=1 to num
\h'\n[lss]u'print colour(col$(a)) col$(a)
\h'\n[lss]u'next a
\h'\n[lss]u'data 8,"black","white","red","blue"
\h'\n[lss]u'data "green","yellow","cyan","magenta"
\h'\n[lss]u'This program prints the names of the colors known to yabasic in those very
\h'\n[lss]u'colors.
\h'\n[lss]u'See also
\h'\n[lss]u'data, restore
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'rectangle ? draw a rectangle
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'rectangle 10,10 to 90,90
\h'\n[lss]u'rectangle 20,20,80,80
\h'\n[lss]u'rect 20,20,80,80
\h'\n[lss]u'box 30,30,70,70
\h'\n[lss]u'clear rectangle 30,30,70,70
\h'\n[lss]u'fill rectangle 40,40,60,60
\h'\n[lss]u'clear fill rectangle 60,60,40,40
\h'\n[lss]u'Description
\h'\n[lss]u'The rectangle-command (also known as box or rect, for short) draws a rectangle;
\h'\n[lss]u'it accepts four parameters: The x- and y-coordinates of two facing corners of
\h'\n[lss]u'the rectangle. With the optional clauses clear and fill (which may appear
\h'\n[lss]u'together and in any sequence) the rectangle can be cleared and filled
\h'\n[lss]u'respectively.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'c=1
\h'\n[lss]u'do
\h'\n[lss]u'for phi=0 to pi step 0.1
\h'\n[lss]u'if (c) then
\h'\n[lss]u'rectangle 100+100*sin(phi),100+100*cos(phi) to 100-100*sin(phi),100-100*cos(phi)
\h'\n[lss]u'else
\h'\n[lss]u'clear rectangle 100+100*sin(phi),100+100*cos(phi) to 100-100*sin(phi),100-100*cos(phi)
\h'\n[lss]u'endif
\h'\n[lss]u'sleep 0.1
\h'\n[lss]u'next phi
\h'\n[lss]u'c=not c
\h'\n[lss]u'loop
\h'\n[lss]u'This example draws a nice animated pattern; watch it for a couple of hours, to
\h'\n[lss]u'see how it develops.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, open printer, line, circle, triangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'redim ? create an array prior to its first use. A synonym for dim
\h'\n[lss]u'Synopsis
\h'\n[lss]u'See the dim-command.
\h'\n[lss]u'Description
\h'\n[lss]u'The redim-command does exactly the same as the dim-command; it is just a
\h'\n[lss]u'synonym. redim has been around in older versions of basic (not even yabasic)
\h'\n[lss]u'for many years; therefore it is supported in yabasic for compatibility reasons.
\h'\n[lss]u'Please refer to the entry for the dim-command for further information.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'rem ? start a comment
\h'\n[lss]u'Synopsis
\h'\n[lss]u'rem Hey, this is a comment
\h'\n[lss]u'# the hash-sign too (at beginning of line)
\h'\n[lss]u'// even the double slash
\h'\n[lss]u'' and the single quote (at beginning of line)
\h'\n[lss]u'print "Not a comment" # This is an error !!
\h'\n[lss]u'print "Not a comment":// But this is again a valid comment
\h'\n[lss]u'print "Not a comment" // even this.
\h'\n[lss]u'print "Not a comment" rem and this !
\h'\n[lss]u'Description
\h'\n[lss]u'rem introduces a comment (like # or //), that extends up to the end of the
\h'\n[lss]u'line.
\h'\n[lss]u'Those comments do not even need a colon (':') in front of them; they (rem, #, '
\h'\n[lss]u'(single quite) and //) all behave alike except for # and ', which may only
\h'\n[lss]u'appear at the very beginning of a line; therefore the fourth example in the
\h'\n[lss]u'synopsis above (print "Not a comment" # This is an error !!) is indeed an
\h'\n[lss]u'error.
\h'\n[lss]u'Note, that rem is an abbreviation for remark. remark however is not a valid
\h'\n[lss]u'command in yabasic.
\h'\n[lss]u'Finally note, that a comment introduced with '#' may have a special meaning
\h'\n[lss]u'under unix; see the entry for # for details.
\h'\n[lss]u'Example
\h'\n[lss]u'#
\h'\n[lss]u'rem comments on data structures
\h'\n[lss]u'# are more useful than
\h'\n[lss]u'// comments on algorithms.
\h'\n[lss]u'rem
\h'\n[lss]u'This program does nothing, but in a splendid and well commented way.
\h'\n[lss]u'See also
\h'\n[lss]u'#, //
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'repeat ? start a repeat-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'repeat
\h'\n[lss]u'?
\h'\n[lss]u'until (?)
\h'\n[lss]u'Description
\h'\n[lss]u'The repeat-loop executes all the statements up to the final until-keyword over
\h'\n[lss]u'and over. The loop is executed as long as the condition, which is specified
\h'\n[lss]u'with the until-clause, becomes true. By construction, the statements within the
\h'\n[lss]u'loop are executed at least once.
\h'\n[lss]u'Example
\h'\n[lss]u'x=0
\h'\n[lss]u'clear screen
\h'\n[lss]u'print "This program will print the numbers from 1 to 10"
\h'\n[lss]u'repeat
\h'\n[lss]u'x=x+1
\h'\n[lss]u'print x
\h'\n[lss]u'print "Press any key for the next number, or 'q' to quit"
\h'\n[lss]u'if (inkey$="q") break
\h'\n[lss]u'until(x=10)
\h'\n[lss]u'This program is pretty much useless, but self-explanatory.
\h'\n[lss]u'See also
\h'\n[lss]u'until, break, while, do
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'restore ? reposition the data-pointer
\h'\n[lss]u'Synopsis
\h'\n[lss]u'read a,b,c,d,e,f
\h'\n[lss]u'restore
\h'\n[lss]u'read g,h,i
\h'\n[lss]u'restore foo
\h'\n[lss]u'data 1,2,3
\h'\n[lss]u'label foo
\h'\n[lss]u'data 4,5,6
\h'\n[lss]u'Description
\h'\n[lss]u'The restore-command may be used to reset the reading of data-statements, so
\h'\n[lss]u'that the next read-statement will read data from the first data-statement.
\h'\n[lss]u'You may specify a label with the restore-command; in that case, the next
\h'\n[lss]u'read-statement will read data starting at the given label. If the label is
\h'\n[lss]u'omitted, reading data will begin with the first data-statement within your
\h'\n[lss]u'program.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Which language (german/english) ? " l$
\h'\n[lss]u'if (instr("german",l$)>0) then
\h'\n[lss]u'restore german
\h'\n[lss]u'else
\h'\n[lss]u'restore english
\h'\n[lss]u'endif
\h'\n[lss]u'for a=1 to 3
\h'\n[lss]u'read x,x$
\h'\n[lss]u'print x,"=",x$
\h'\n[lss]u'next a
\h'\n[lss]u'label english
\h'\n[lss]u'data 1,"one",2,"two",3,"three"
\h'\n[lss]u'label german
\h'\n[lss]u'data 1,"eins",2,"zwei",3,"drei"
\h'\n[lss]u'This program asks to select one of those languages known to me (i.e. english or
\h'\n[lss]u'german) and then prints the numbers 1,2 and 3 and their textual equivalents in
\h'\n[lss]u'the chosen language.
\h'\n[lss]u'See also
\h'\n[lss]u'read, data, label
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'return ? return from a subroutine or a gosub
\h'\n[lss]u'Synopsis
\h'\n[lss]u'gosub foo
\h'\n[lss]u'?
\h'\n[lss]u'label foo
\h'\n[lss]u'?
\h'\n[lss]u'return
\h'\n[lss]u'sub bar(baz)
\h'\n[lss]u'?
\h'\n[lss]u'return quertz
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'The return-statement serves two different (albeit somewhat related) purposes.
\h'\n[lss]u'The probably more important use of return is to return control from within a
\h'\n[lss]u'subroutine to the place in your program, where the subroutine has been called.
\h'\n[lss]u'If the subroutine is declared to return a value, the return-statement might be
\h'\n[lss]u'accompanied by a string or number, which constitutes the return value of the
\h'\n[lss]u'subroutine.
\h'\n[lss]u'However, even if the subroutine should return a value, the return-statement
\h'\n[lss]u'need not carry a value; in that case the subroutine will return 0 or the empty
\h'\n[lss]u'string (depending on the type of the subroutine). Moreover, feel free to place
\h'\n[lss]u'multiple return-statements within your subroutine; it's a nice way of
\h'\n[lss]u'controlling the flow of execution.
\h'\n[lss]u'The second (but historically first) use of return is to return to the position,
\h'\n[lss]u'where a prior gosub has left off. In that case return may not carry a value.
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'read a$
\h'\n[lss]u'if (a$="") then
\h'\n[lss]u'print
\h'\n[lss]u'end
\h'\n[lss]u'endif
\h'\n[lss]u'print mark$(a$)," ";
\h'\n[lss]u'loop
\h'\n[lss]u'data "The","quick","brown","fox","jumped"
\h'\n[lss]u'data "over","the","lazy","dog",""
\h'\n[lss]u'sub mark$(a$)
\h'\n[lss]u'if (instr(lower$(a$),"q")) return upper$(a$)
\h'\n[lss]u'return a$
\h'\n[lss]u'end sub
\h'\n[lss]u'This example features a subroutine mark$, that returns its argument in upper
\h'\n[lss]u'case, if it contains the letter "q", or unchanged otherwise. In the test-text
\h'\n[lss]u'the word quick will end up being marked as QUICK.
\h'\n[lss]u'The example above demonstrates return within subroutines; please see gosub for
\h'\n[lss]u'an example of how to use return in this context.
\h'\n[lss]u'See also
\h'\n[lss]u'sub, gosub
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'reverse ? print reverse (background and foreground colors exchanged)
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'?
\h'\n[lss]u'print reverse "foo"
\h'\n[lss]u'Description
\h'\n[lss]u'reverse may be used to print text in reverse. reverse is not a separate
\h'\n[lss]u'command, but part of the print-command; it may be included just after the print
\h'\n[lss]u'and can only be issued once that clear screen has been issued.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'print "1 ";
\h'\n[lss]u'c=3
\h'\n[lss]u'do
\h'\n[lss]u'prim=true
\h'\n[lss]u'for a=2 to sqrt(c)
\h'\n[lss]u'if (frac(c/a)=0) then
\h'\n[lss]u'prim=false
\h'\n[lss]u'break
\h'\n[lss]u'endif
\h'\n[lss]u'next a
\h'\n[lss]u'if (prim) then
\h'\n[lss]u'print
\h'\n[lss]u'print reverse c;
\h'\n[lss]u'else
\h'\n[lss]u'print c;
\h'\n[lss]u'endif
\h'\n[lss]u'print " ";
\h'\n[lss]u'c=c+1
\h'\n[lss]u'loop
\h'\n[lss]u'This program prints numbers from 1 on and marks each prime number in reverse.
\h'\n[lss]u'See also
\h'\n[lss]u'at, print color, print, clear screen
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'right$() ? return (or change) the right end of a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print right$(a$,2)
\h'\n[lss]u'right$(b$,2)="baz"
\h'\n[lss]u'Description
\h'\n[lss]u'The right$-function requires two arguments (a string and a number) and returns
\h'\n[lss]u'the part from the right end of the string, whose length is specified by its
\h'\n[lss]u'second argument. So, right$ simply returns the requested number of chars from
\h'\n[lss]u'the right end of the given string.
\h'\n[lss]u'Note, that the right$-function can be assigned to, i.e. it may appear on the
\h'\n[lss]u'left hand side of an assignment. In this way it is possible to change a part of
\h'\n[lss]u'the variable used within the right$-function. Note, that that way the length of
\h'\n[lss]u'the string cannot be changed, i.e. characters might be overwritten, but not
\h'\n[lss]u'added. For an example see below.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Please enter a length either in inch or centimeter"
\h'\n[lss]u'print "please add 'in' or 'cm' to mark the unit."
\h'\n[lss]u'input "Length: " a$
\h'\n[lss]u'if (right$(a$,2)="in") then
\h'\n[lss]u'length=val(a$)*2.56
\h'\n[lss]u'elsif (right$(a$,2)="cm") then
\h'\n[lss]u'length=val(a$)
\h'\n[lss]u'else
\h'\n[lss]u'error "Invalid input: "+a$
\h'\n[lss]u'endif
\h'\n[lss]u'This program allows the user to enter a length qualified with a unit (either
\h'\n[lss]u'inch or centimeter).
\h'\n[lss]u'This second example demonstrates the capability to assign to the
\h'\n[lss]u'right$-function.
\h'\n[lss]u'a$="Heiho World !"
\h'\n[lss]u'print a$
\h'\n[lss]u'right$(a$,7)="dwarfs."
\h'\n[lss]u'print a$
\h'\n[lss]u'See also
\h'\n[lss]u'right$ and mid$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'rinstr() ? find the rightmost occurrence of one string within the other
\h'\n[lss]u'Synopsis
\h'\n[lss]u'pos=rinstr("Thequickbrownfox","equi")
\h'\n[lss]u'pos=rinstr(a$,b$,x)
\h'\n[lss]u'Description
\h'\n[lss]u'The rinstr-function accepts two string-arguments and tries to find the second
\h'\n[lss]u'within the first. However, unlike the instr, the rinstr-function finds the
\h'\n[lss]u'rightmost (or last) occurrence of the string; whereas the instr-function finds
\h'\n[lss]u'the leftmost (or first) occurrence. In any case however, the position is
\h'\n[lss]u'counted from the left.
\h'\n[lss]u'If you supply a third, numeric argument to the rinstr-function, it will be used
\h'\n[lss]u'as a starting point for the search. Therefore rinstr("abcdeabcdeabcde","e",8)
\h'\n[lss]u'will return 5, because the search for an "e" starts at position 8 and finds the
\h'\n[lss]u'first one at position 5.
\h'\n[lss]u'Example
\h'\n[lss]u'print rinstr("foofoofoobar","foo")
\h'\n[lss]u'This simple example will print 7, because it finds the rightmost among the
\h'\n[lss]u'three occurrences of foo within the string. Note, that
\h'\n[lss]u'print instr("foofoofoobar","foo")
\h'\n[lss]u'would have printed 1.
\h'\n[lss]u'See also
\h'\n[lss]u'instr
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'rtrim$() ? trim spaces at the right end of a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=rtrim$(b$)
\h'\n[lss]u'Description
\h'\n[lss]u'The rtrim$-function removes all whitespace from the right end of a string and
\h'\n[lss]u'returns the result.
\h'\n[lss]u'Example
\h'\n[lss]u'open 1,"foo"
\h'\n[lss]u'dim lines$(100)
\h'\n[lss]u'l=1
\h'\n[lss]u'while(not eof(1))
\h'\n[lss]u'input #1 a$
\h'\n[lss]u'a$=rtrim$(a$)
\h'\n[lss]u'if (right$(line$,1)="\\") then
\h'\n[lss]u'line$=line$+" "+a$
\h'\n[lss]u'else
\h'\n[lss]u'lines$(l)=line$
\h'\n[lss]u'l=l+1
\h'\n[lss]u'line$=a$
\h'\n[lss]u'endif
\h'\n[lss]u'end while
\h'\n[lss]u'print "Read ",l," lines"
\h'\n[lss]u'This example reads the file foo allowing for continuation lines, which are
\h'\n[lss]u'marked by a \, which appears as the last character on a line. For convenience
\h'\n[lss]u'whitespace at the right end of a line is trimmed with rtrim.
\h'\n[lss]u'See also
\h'\n[lss]u'ltrim$, trim$
\h'\n[lss]u'S
\h'\n[lss]u'screen ? as clear screen clears the text window
\h'\n[lss]u'seek() ? change the position within an open file
\h'\n[lss]u'sig() ? return the sign of its argument
\h'\n[lss]u'sin() ? return the sine of its single argument
\h'\n[lss]u'sleep ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'split() ? split a string into many strings
\h'\n[lss]u'sqr() ? compute the square of its argument
\h'\n[lss]u'sqrt() ? compute the square root of its argument
\h'\n[lss]u'static ? preserves the value of a variable between calls to a subroutine
\h'\n[lss]u'step ? specifies the increment step in a for-loop
\h'\n[lss]u'str$() ? convert a number into a string
\h'\n[lss]u'sub ? declare a user defined subroutine
\h'\n[lss]u'switch ? select one of many alternatives depending on a value
\h'\n[lss]u'system() ? hand a statement over to your operating system and return its
\h'\n[lss]u'exitcode
\h'\n[lss]u'system$() ? hand a statement over to your operating system and return its
\h'\n[lss]u'output
\h'\n[lss]u'Name
\h'\n[lss]u'screen ? as clear screen clears the text window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'Description
\h'\n[lss]u'The keyword screen appears only within the sequence clear screen; please see
\h'\n[lss]u'there for a description.
\h'\n[lss]u'See also
\h'\n[lss]u'clear screen
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'seek() ? change the position within an open file
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open 1,"foo"
\h'\n[lss]u'seek #1,q
\h'\n[lss]u'seek #1,x,"begin"
\h'\n[lss]u'seek #1,y,"end"
\h'\n[lss]u'seek #1,z,"here"
\h'\n[lss]u'Description
\h'\n[lss]u'The seek-command changes the position, where the next input (or peek) statement
\h'\n[lss]u'will read from an open file. Usually files are read from the beginning to the
\h'\n[lss]u'end sequentially; however sometimes you may want to depart from this simple
\h'\n[lss]u'scheme. This can be done with the seek-command, allowing you to change the
\h'\n[lss]u'position, where the next piece of data will be read from the file.
\h'\n[lss]u'seek accepts two or three arguments: The first one is the number of an already
\h'\n[lss]u'open file. The second one is the position where the next read from the file
\h'\n[lss]u'will start. The third argument is optional and specifies the the point from
\h'\n[lss]u'where the position (the second argument) will count. It can be one of:
\h'\n[lss]u'begin
\h'\n[lss]u'Count from the beginning of the file.
\h'\n[lss]u'end
\h'\n[lss]u'Count from the end of the file.
\h'\n[lss]u'here
\h'\n[lss]u'Count from the current position within the file.
\h'\n[lss]u'Example
\h'\n[lss]u'open #1,"count.dat","w"
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'print #1,"00000000";
\h'\n[lss]u'if (a<10) print #1,";";
\h'\n[lss]u'next a
\h'\n[lss]u'dim count(10)
\h'\n[lss]u'do
\h'\n[lss]u'x=int(ran(10))
\h'\n[lss]u'i=i+1
\h'\n[lss]u'if (mod(i,1000)=0) print ".";
\h'\n[lss]u'count(x)=count(x)+1
\h'\n[lss]u'curr$=right$("00000000"+str$(count(x)),8)
\h'\n[lss]u'seek #1,9*x,"begin"
\h'\n[lss]u'print #1,curr$;
\h'\n[lss]u'loop
\h'\n[lss]u'This example increments randomly one of ten counters (in the array count());
\h'\n[lss]u'however, the result is always kept and updated within the file count.dat, so
\h'\n[lss]u'even in case of an unexpected interrupt, the result will not be lost.
\h'\n[lss]u'See also
\h'\n[lss]u'tell, open, print, peek
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sig() ? return the sign of its argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=sig(b)
\h'\n[lss]u'Description
\h'\n[lss]u'Return +1, -1 or 0, if the single argument is positive, negative or zero.
\h'\n[lss]u'Example
\h'\n[lss]u'clear screen
\h'\n[lss]u'dim c$(3):c$(1)="red":c$(2)="white":c$(3)="green"
\h'\n[lss]u'do
\h'\n[lss]u'num=ran(100)-50
\h'\n[lss]u'print color(c$(2+sig(num))) num
\h'\n[lss]u'loop
\h'\n[lss]u'This program prints an infinite sequence of random number; positive numbers are
\h'\n[lss]u'printed in green, negative numbers are printed red (an exact zero would be
\h'\n[lss]u'printed white). (With a little extra work, this program could be easily
\h'\n[lss]u'extended into a brokerage system)
\h'\n[lss]u'See also
\h'\n[lss]u'abs, int, frac
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sin() ? return the sine of its single argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'y=sin(angle)
\h'\n[lss]u'Description
\h'\n[lss]u'The sin-function expects an angle (in radians, not degrees) and returns its
\h'\n[lss]u'sine.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'new curve
\h'\n[lss]u'for phi=0 to 2*pi step 0.1
\h'\n[lss]u'line to 100+90*sin(phi),100+90*cos(phi)
\h'\n[lss]u'next phi
\h'\n[lss]u'close curve
\h'\n[lss]u'This program draws a circle (ignoring the existence of the circle-command).
\h'\n[lss]u'See also
\h'\n[lss]u'asin, cos
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sleep ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'Synopsis
\h'\n[lss]u'sleep 4
\h'\n[lss]u'Description
\h'\n[lss]u'The sleep-command has many different names: You may write pause, sleep or wait
\h'\n[lss]u'interchangeably; whatever you write, yabasic will always do exactly the same.
\h'\n[lss]u'Therefore you should refer to the entry for the pause-function for further
\h'\n[lss]u'information.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'split() ? split a string into many strings
\h'\n[lss]u'Synopsis
\h'\n[lss]u'dim w$(10)
\h'\n[lss]u'?
\h'\n[lss]u'num=split(a$,w$())
\h'\n[lss]u'num=split(a$,w$(),s$)
\h'\n[lss]u'Description
\h'\n[lss]u'The split-function requires a string (containing the text to be split), a
\h'\n[lss]u'reference to a string-array (which will receive the resulting strings, i.e. the
\h'\n[lss]u'tokens) and an optional string (with a set of characters, at which to split,
\h'\n[lss]u'i.e. the delimiters).
\h'\n[lss]u'The split-function regards its first argument (a string) as a list of tokens
\h'\n[lss]u'separated by delimiters and it will store the list of tokens within the
\h'\n[lss]u'array-reference you have supplied. Note, that the array, which is passed as a
\h'\n[lss]u'reference (w$() in the synopsis), will be resized accordingly, so that you
\h'\n[lss]u'don't have to figure out the number of tokens in advance. The element at
\h'\n[lss]u'position zero (i.e. w$(0)) will not be used.
\h'\n[lss]u'normally (i.e. if you omit the third, which is the delimiter-argument) the
\h'\n[lss]u'function will regard space or tab as delimiters for tokens; however by
\h'\n[lss]u'supplying a third argument, you may split at any single of the characters
\h'\n[lss]u'within this string. E.g. if you supply ":;" as the third argument, then colon
\h'\n[lss]u'(:) or semicolon (;) will delimit tokens.
\h'\n[lss]u'Note, that a sequence of separator-characters will produce a sequence of empty
\h'\n[lss]u'tokens; that way, the number of tokens returned will always be one plus the
\h'\n[lss]u'number of separator characters contained within the string. Refer to the
\h'\n[lss]u'closely related token-function, if you do not like this behaviour. In some way,
\h'\n[lss]u'the split-function focuses on the separators (other than the token-function,
\h'\n[lss]u'which focuses on the tokens), hence its name.
\h'\n[lss]u'The second argument is a reference on a string-array, where the tokens will be
\h'\n[lss]u'stored; this array will be expanded (or shrunk) to have room for all tokens, if
\h'\n[lss]u'necessary.
\h'\n[lss]u'The first argument finally contains the text, that will be split into tokens.
\h'\n[lss]u'The split-function returns the number of tokens that have been found.
\h'\n[lss]u'Please see the examples below for some hints on the exact behaviour of the
\h'\n[lss]u'split-function and how it differs from the token-function:
\h'\n[lss]u'Example
\h'\n[lss]u'print "This program will help you to understand, how the"
\h'\n[lss]u'print "split()-function exactly works and how it behaves"
\h'\n[lss]u'print "in certain special cases."
\h'\n[lss]u'print
\h'\n[lss]u'print "Please enter a line containing tokens separated"
\h'\n[lss]u'print "by either '=' or '-'"
\h'\n[lss]u'dim t$(10)
\h'\n[lss]u'do
\h'\n[lss]u'print
\h'\n[lss]u'input "Please enter a line: " l$
\h'\n[lss]u'num=split(l$,t$(),"=-")
\h'\n[lss]u'print num," Tokens: ";
\h'\n[lss]u'for a=1 to num
\h'\n[lss]u'if (t$(a)="") then
\h'\n[lss]u'print "(EMPTY)";
\h'\n[lss]u'else
\h'\n[lss]u'print t$(a);
\h'\n[lss]u'endif
\h'\n[lss]u'if (a<num) print ",";
\h'\n[lss]u'next a
\h'\n[lss]u'print
\h'\n[lss]u'loop
\h'\n[lss]u'This program prints the following output:
\h'\n[lss]u'Please enter a line: a
\h'\n[lss]u'1 Tokens: a
\h'\n[lss]u'Please enter a line:
\h'\n[lss]u'0 Tokens:
\h'\n[lss]u'Please enter a line: ab
\h'\n[lss]u'1 Tokens: ab
\h'\n[lss]u'Please enter a line: a=b
\h'\n[lss]u'2 Tokens: a,b
\h'\n[lss]u'Please enter a line: a-
\h'\n[lss]u'2 Tokens: a,(EMPTY)
\h'\n[lss]u'Please enter a line: a-=
\h'\n[lss]u'3 Tokens: a,(EMPTY),(EMPTY)
\h'\n[lss]u'Please enter a line: =a-
\h'\n[lss]u'3 Tokens: (EMPTY),a,(EMPTY)
\h'\n[lss]u'Please enter a line: a=-b
\h'\n[lss]u'3 Tokens: a,(EMPTY),b
\h'\n[lss]u'Please enter a line: a--b-
\h'\n[lss]u'4 Tokens: a,(EMPTY),b,(EMPTY)
\h'\n[lss]u'Please enter a line: -a==b-c==
\h'\n[lss]u'7 Tokens: (EMPTY),a,(EMPTY),b,c,(EMPTY),(EMPTY)
\h'\n[lss]u'See also
\h'\n[lss]u'token
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sqr() ? compute the square of its argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a=sqr(b)
\h'\n[lss]u'Description
\h'\n[lss]u'The sqr-function computes the square of its numerical argument (i.e. it
\h'\n[lss]u'multiplies its argument with itself).
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'print a,sqr(a),a**2
\h'\n[lss]u'next a
\h'\n[lss]u'As you may see from the output, sqr can be written as **2 (or ^2) too.
\h'\n[lss]u'See also
\h'\n[lss]u'sqrt, **, ^
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sqrt() ? compute the square root of its argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'to be written
\h'\n[lss]u'Description
\h'\n[lss]u'The sqrt-function computes the square root of its numerical argument.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 5
\h'\n[lss]u'print a,sqrt(a),a**(1/2)
\h'\n[lss]u'next a
\h'\n[lss]u'As you may see from the output, sqrt can be written as **(1/2) (or ^(1/2)) too.
\h'\n[lss]u'See also
\h'\n[lss]u'sqr, **, ^
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'static ? preserves the value of a variable between calls to a subroutine
\h'\n[lss]u'Synopsis
\h'\n[lss]u'sub foo()
\h'\n[lss]u'static a
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'The static keyword can be used within subroutines to mark variables as static.
\h'\n[lss]u'This has two effects: First, the variable is local to the subroutine, i.e. its
\h'\n[lss]u'value is not know outside the subroutine (this is the effect of the local
\h'\n[lss]u'keyword). Second, the static-keyword arranges things, so that the variable
\h'\n[lss]u'keeps its value between invocations of the subroutine (this is different from
\h'\n[lss]u'the local-keyword).
\h'\n[lss]u'Example
\h'\n[lss]u'foo()
\h'\n[lss]u'foo()
\h'\n[lss]u'foo()
\h'\n[lss]u'sub foo()
\h'\n[lss]u'static a
\h'\n[lss]u'local b
\h'\n[lss]u'a=a+1
\h'\n[lss]u'b=b+1
\h'\n[lss]u'print a,b
\h'\n[lss]u'end sub
\h'\n[lss]u'This program shows the difference between static and local variables within a
\h'\n[lss]u'subroutine; it produces this output:
\h'\n[lss]u'1 1
\h'\n[lss]u'2 1
\h'\n[lss]u'3 1
\h'\n[lss]u'The output shows, that the static variable a keeps its value between subroutine
\h'\n[lss]u'calls, whereas b is initialized with the value 0 at every call to the
\h'\n[lss]u'subroutine foo.
\h'\n[lss]u'See also
\h'\n[lss]u'sub, local
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'step ? specifies the increment step in a for-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'for a=1 to 10 step 3
\h'\n[lss]u'?
\h'\n[lss]u'next a
\h'\n[lss]u'Description
\h'\n[lss]u'Specify, by which amount the loop-variable of a for-loop will be incremented at
\h'\n[lss]u'each step.
\h'\n[lss]u'The step (as well as the lower and upper bound) are computed anew in each step;
\h'\n[lss]u'this is not common, but possible, as the example below demonstrates.
\h'\n[lss]u'Example
\h'\n[lss]u'for x=1 to 1000 step y
\h'\n[lss]u'y=x+y
\h'\n[lss]u'print x," ",y," ";
\h'\n[lss]u'next x
\h'\n[lss]u'print
\h'\n[lss]u'This program computes the fibonacci numbers between 1 and 1000.
\h'\n[lss]u'See also
\h'\n[lss]u'for
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'str$() ? convert a number into a string
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=str$(a)
\h'\n[lss]u'b$=str$(x,"##.###")
\h'\n[lss]u'b$=str$(x,"###,###.##")
\h'\n[lss]u'b$=str$(x,"###,###.##","_.")
\h'\n[lss]u'Description
\h'\n[lss]u'The str$-function accepts a numeric argument and returns it as a string. This
\h'\n[lss]u'conversion between number and string can be controlled with the optional third
\h'\n[lss]u'argument (the format argument). See the following table of examples to learn
\h'\n[lss]u'about valid values of this argument. Note, that those examples fall in one of
\h'\n[lss]u'two categories: C-style and basic-style; the first 4 examples in the table
\h'\n[lss]u'below are C-style, the rest of the examples are basic-style. For more
\h'\n[lss]u'information on the C-style formats, you may refer to your favorite
\h'\n[lss]u'documentation on the C programming language. The basic-style formats are much
\h'\n[lss]u'simpler, they just depict the desired output, marking digits with '#'; groups
\h'\n[lss]u'of (usually three) digits may be separated with colons (','), the decimal dot
\h'\n[lss]u'must be marked by a literal dot ('.'). Moreover these characters (colons and
\h'\n[lss]u'dot) may be replaced by other characters to satisfy the needs of non-english
\h'\n[lss]u'(e.g. german) languages; see the examples below.
\h'\n[lss]u'Note, that for clarity, each space in the result has been replaced by the
\h'\n[lss]u'letter 'x', because it would be hard to figure out, how many spaces are
\h'\n[lss]u'produced exactly otherwise.
\h'\n[lss]u'Table 7.2. Examples for the format argument
\h'\n[lss]u'+-----------------------------------------------------------------------------+
\h'\n[lss]u'| Example | Result for | |
\h'\n[lss]u'| string | converting | Description |
\h'\n[lss]u'| | 1000*pi | |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |The '2' determines the minimum length of the |
\h'\n[lss]u'|%2.5f |3141.59265 |output; but if needed (as in the example) the |
\h'\n[lss]u'| | |output can be longer. The '5' is the number of |
\h'\n[lss]u'| | |digits after the decimal point. |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |Two spaces (which appear as 'x') are added to pad |
\h'\n[lss]u'|%12.5f |xx3141.59265|the output to the requested length of 12 |
\h'\n[lss]u'| | |characters. |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |The 'g' requests, that the precision ('5') |
\h'\n[lss]u'|%012.5g |0000003141.6|specifies the overall number of digits (before and|
\h'\n[lss]u'| | |after the decimal point). |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |The '-' requests the output to be left-centered |
\h'\n[lss]u'|%-12.5f |3141.59265xx|(therefore the filling space appears at the |
\h'\n[lss]u'| | |right). |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |Each '#' specifies a digit (either before or after|
\h'\n[lss]u'| | |the dot), the '.' specifies the position of the |
\h'\n[lss]u'|#####.## |x3141.59 |dot. As 1000*pi does not have enough digits, the 5|
\h'\n[lss]u'| | |requested digits before the dot are filled up with|
\h'\n[lss]u'| | |a space (which shows up as an 'x'). |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'|##,###.## |x3,141.59 |Nearly the same as above, but the colon from the |
\h'\n[lss]u'| | |format shows up within the result. |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'|##,###.## and| | |
\h'\n[lss]u'|an additional|x3.141,59 |Similar to the example above, but colon and dot |
\h'\n[lss]u'|argument of | |are replaced with dot and colon respectively. |
\h'\n[lss]u'|".," | | |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'|##,###.## and| |Similar to the example above, but colon and dot |
\h'\n[lss]u'|an additional|x3_141,59 |are replaced with underscore and colon |
\h'\n[lss]u'|argument of | |respectively. |
\h'\n[lss]u'|"_," | | |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |The format string does not contain a dot, and |
\h'\n[lss]u'|##### |x3142 |therefore the result does not have any fractional |
\h'\n[lss]u'| | |digits. |
\h'\n[lss]u'|-------------+------------+--------------------------------------------------|
\h'\n[lss]u'| | |As 1000*pi has 4 digits in front of the decimal |
\h'\n[lss]u'|##.### |##.### |dot and the format only specifies 2, yabasic does |
\h'\n[lss]u'| | |not know what to do; therefore it chooses just to |
\h'\n[lss]u'| | |reproduce the format string. |
\h'\n[lss]u'+-----------------------------------------------------------------------------+
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'input "Please enter a format string: " f$
\h'\n[lss]u'a$=str$(1000*pi,f$)
\h'\n[lss]u'for a=1 to len(a$)
\h'\n[lss]u'if (mid$(a$,a,1)=" ") mid$(a$,a,1)="x"
\h'\n[lss]u'next a
\h'\n[lss]u'print a$
\h'\n[lss]u'loop
\h'\n[lss]u'This is the program, that has been used to get the results shown in the table
\h'\n[lss]u'above.
\h'\n[lss]u'See also
\h'\n[lss]u'print, using
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'sub ? declare a user defined subroutine
\h'\n[lss]u'Synopsis
\h'\n[lss]u'foo(2,"hello")
\h'\n[lss]u'?
\h'\n[lss]u'sub foo(bar,baz$)
\h'\n[lss]u'?
\h'\n[lss]u'return qux
\h'\n[lss]u'?
\h'\n[lss]u'end sub
\h'\n[lss]u'Description
\h'\n[lss]u'The sub-keyword starts the definition of a user defined subroutine. With user
\h'\n[lss]u'defined subroutines you are able to somewhat extend yabasic with your own
\h'\n[lss]u'commands or functions. A subroutine accepts arguments (numbers or strings) and
\h'\n[lss]u'returns a number or a string (however, you are not required to assign the value
\h'\n[lss]u'returned to a variable).
\h'\n[lss]u'The name of the subroutine follows after the keyword sub. If the name (in the
\h'\n[lss]u'synopsis: foo) ends on a '$', the subroutine should return a string (with the
\h'\n[lss]u'return-statement), otherwise a number.
\h'\n[lss]u'After the name of the subroutine yabasic requires a pair of braces; within
\h'\n[lss]u'those braces you may specify a list of parameters, for which values can (but
\h'\n[lss]u'need not) be included when calling the subroutine. If you omit one of those
\h'\n[lss]u'parameters when calling such a subroutine, it assumes the value zero (for
\h'\n[lss]u'numeric parameters) or the empty string (for string-parameters). However from
\h'\n[lss]u'the special variable numparams you may find out, how many arguments have really
\h'\n[lss]u'been passed when calling the subroutine.
\h'\n[lss]u'Parameters of a subroutine are always local variables (see the keyword local
\h'\n[lss]u'for more explanation).
\h'\n[lss]u'From within the subroutine you may return any time with the keyword return;
\h'\n[lss]u'along with the return-keyword you may specify the return value. Note that more
\h'\n[lss]u'than one return is allowed within a single subroutine.
\h'\n[lss]u'Finally, the keyword end sub ends the subroutine definition. Note, that the
\h'\n[lss]u'definition of a subroutine need not appear within the program before the first
\h'\n[lss]u'call to this sub.
\h'\n[lss]u'Note
\h'\n[lss]u'As braces have two uses in yabasic (i.e. for supplying arguments to a
\h'\n[lss]u'subroutine as well as to list the indices of an array). yabasic can not tell
\h'\n[lss]u'apart an array from a subroutine with the same name. Therefore you cannot
\h'\n[lss]u'define a subroutine with the same name as an array !
\h'\n[lss]u'Example
\h'\n[lss]u'p=2
\h'\n[lss]u'do
\h'\n[lss]u'if (is_prime(p)) print p
\h'\n[lss]u'p=p+1
\h'\n[lss]u'loop
\h'\n[lss]u'sub is_prime(a)
\h'\n[lss]u'local b
\h'\n[lss]u'for b=2 to sqrt(a)
\h'\n[lss]u'if (frac(a/b)=0) return false
\h'\n[lss]u'next b
\h'\n[lss]u'return true
\h'\n[lss]u'end sub
\h'\n[lss]u'This example is not the recommended way to compute prime numbers. However it
\h'\n[lss]u'gives a nice demonstration of using a subroutine.
\h'\n[lss]u'See also
\h'\n[lss]u'local, static, peek
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'switch ? select one of many alternatives depending on a value
\h'\n[lss]u'Synopsis
\h'\n[lss]u'switch a
\h'\n[lss]u'case 1
\h'\n[lss]u'case 2
\h'\n[lss]u'?
\h'\n[lss]u'end switch
\h'\n[lss]u'?
\h'\n[lss]u'switch a$
\h'\n[lss]u'case "a"
\h'\n[lss]u'case "b"
\h'\n[lss]u'end switch
\h'\n[lss]u'Description
\h'\n[lss]u'The switch-statement selects one of many codepaths depending on a numerical or
\h'\n[lss]u'string expression. I.e. it takes an expression (either numeric or string) and
\h'\n[lss]u'compares it with a series of values, each wrapped within a case-clause. If the
\h'\n[lss]u'expression equals the value given in a case-clause, the subsequent statements
\h'\n[lss]u'are executed.
\h'\n[lss]u'The default-clause allows one to specify commands, which should be executed, if
\h'\n[lss]u'none of case-clauses matches.
\h'\n[lss]u'Note, that many case-clauses might be clustered (e.g. case "a":case "b":case
\h'\n[lss]u'"c"). Or put another way: You need a break-statement at the end of a
\h'\n[lss]u'case-branch, if you do not want to run into the next case.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a single digit: " n
\h'\n[lss]u'switch n
\h'\n[lss]u'case 0:print "zero":break
\h'\n[lss]u'case 1:print "one":break
\h'\n[lss]u'case 2:print "two":break
\h'\n[lss]u'case 3:print "three":break
\h'\n[lss]u'case 4:print "four":break
\h'\n[lss]u'case 5:case 6: case 7:case 8:case 9
\h'\n[lss]u'print "Much !":break
\h'\n[lss]u'default:print "Hey ! That was more than a single digit !"
\h'\n[lss]u'end switch
\h'\n[lss]u'This example translates a single digit into a string; note, how the cases 5 to
\h'\n[lss]u'7 are clustered.
\h'\n[lss]u'See also
\h'\n[lss]u'switch, case, break
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'system() ? hand a statement over to your operating system and return its
\h'\n[lss]u'exitcode
\h'\n[lss]u'Synopsis
\h'\n[lss]u'ret=system("foo")
\h'\n[lss]u'system("bar")
\h'\n[lss]u'Description
\h'\n[lss]u'The system-command accepts a single string argument, which specifies a command
\h'\n[lss]u'to be executed. The function will return the exitcode of the command; its
\h'\n[lss]u'output (if any) will be lost.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Please enter the name of the file, that should be deleted."
\h'\n[lss]u'input f$
\h'\n[lss]u'if (system("rm "+f$+" >/dev/null 2>&1")) then
\h'\n[lss]u'print "Error !"
\h'\n[lss]u'else
\h'\n[lss]u'print "okay."
\h'\n[lss]u'endif
\h'\n[lss]u'This program is Unix-specific: It uses the Unix-command rm to remove a file.
\h'\n[lss]u'See also
\h'\n[lss]u'system$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'system$() ? hand a statement over to your operating system and return its
\h'\n[lss]u'output
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print system$("dir")
\h'\n[lss]u'Description
\h'\n[lss]u'The system$-command accepts a single string argument, specifying a command,
\h'\n[lss]u'that can be found and executed by your operating system. It returns the output
\h'\n[lss]u'of this command as one big string.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter the name of a directory: " d$
\h'\n[lss]u'print
\h'\n[lss]u'print "This is the contents of the '"+d$+"':"
\h'\n[lss]u'print system$("dir "+d$)
\h'\n[lss]u'This example lists the contents of a directory, employing the dir-command
\h'\n[lss]u'(which is about the only program, that is known under Unix as well as Windows).
\h'\n[lss]u'See also
\h'\n[lss]u'system, chomp
\h'\n[lss]u'T
\h'\n[lss]u'tan() ? return the tangent of its argument
\h'\n[lss]u'tell ? get the current position within an open file
\h'\n[lss]u'text ? write text into your graphic-window
\h'\n[lss]u'then ? tell the long from the short form of the if-statement
\h'\n[lss]u'time$ ? return a string containing the current time
\h'\n[lss]u'to ? this keyword appears as part of other statements
\h'\n[lss]u'token() ? split a string into multiple strings
\h'\n[lss]u'triangle ? draw a triangle
\h'\n[lss]u'trim$() ? remove leading and trailing spaces from its argument
\h'\n[lss]u'true ? a constant with the value of 1
\h'\n[lss]u'Name
\h'\n[lss]u'tan() ? return the tangent of its argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'foo=tan(bar)
\h'\n[lss]u'Description
\h'\n[lss]u'The tan-function computes the tangent of its arguments (which should be
\h'\n[lss]u'specified in radians).
\h'\n[lss]u'Example
\h'\n[lss]u'for a=0 to 45
\h'\n[lss]u'print tan(a*pi/180)
\h'\n[lss]u'next a
\h'\n[lss]u'This example simply prints the tangent of all angles between 0 and 45 degrees.
\h'\n[lss]u'See also
\h'\n[lss]u'atan, sin
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'tell ? get the current position within an open file
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open #1,"foo"
\h'\n[lss]u'?
\h'\n[lss]u'position=tell(#1)
\h'\n[lss]u'Description
\h'\n[lss]u'The tell-function requires the number of an open file as an argument. It
\h'\n[lss]u'returns the position (counted in bytes, starting from the beginning of the
\h'\n[lss]u'file) where the next read will start.
\h'\n[lss]u'Example
\h'\n[lss]u'open #1,"foo","w"
\h'\n[lss]u'print #1 "Hello World !"
\h'\n[lss]u'close #1
\h'\n[lss]u'open #1,"foo"
\h'\n[lss]u'seek #1,0,"end"
\h'\n[lss]u'print tell(#1)
\h'\n[lss]u'close 1
\h'\n[lss]u'This example (mis)uses tell to get the size of the file. The seek positions the
\h'\n[lss]u'file pointer at the end of the file, therefore the call to tell returns the
\h'\n[lss]u'total length of the file.
\h'\n[lss]u'See also
\h'\n[lss]u'tell, open
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'text ? write text into your graphic-window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'text x,y,"foo"
\h'\n[lss]u'text x,y,"foo","lb"
\h'\n[lss]u'text x,y,"foo","cc","font"
\h'\n[lss]u'text x,y,"foo","font","rt"
\h'\n[lss]u'Description
\h'\n[lss]u'The text-commands displays a text-string (the third argument) at the given
\h'\n[lss]u'position (the first two arguments) within an already opened window. The font to
\h'\n[lss]u'be used can be optionally specified as either the fourth or fifth argument
\h'\n[lss]u'("font" in the example above). A font specified this way will also be used for
\h'\n[lss]u'any subsequent text-commands, as long as they do not specify a font themselves.
\h'\n[lss]u'The fourth or fifth optional argument ("lb" in the example above) can be used
\h'\n[lss]u'to specify the alignment of the text with respect to the specified position.
\h'\n[lss]u'This argument is always two characters long: The first character specifies the
\h'\n[lss]u'horizontal alignment and can be either l, r or c, which stand for left, right
\h'\n[lss]u'or center. The second character specifies the vertical alignment and can be one
\h'\n[lss]u'of t, b or c, which stand for top, bottom or center respectively. If you omit
\h'\n[lss]u'this alignment argument, the default "lb" applies; however this default may be
\h'\n[lss]u'changed with poke "textalign","xx"
\h'\n[lss]u'Example
\h'\n[lss]u'open window 500,200
\h'\n[lss]u'clear screen
\h'\n[lss]u'data "lt","lc","lb","ct","cc","cb","rt","rc","rb"
\h'\n[lss]u'for a=1 to 9
\h'\n[lss]u'read align$
\h'\n[lss]u'print "Alignment: ",align$
\h'\n[lss]u'line 50*a-15,100,50*a+15,100
\h'\n[lss]u'line 50*a,85,50*a,115
\h'\n[lss]u'text 50*a,100,"Test",align$
\h'\n[lss]u'inkey$
\h'\n[lss]u'next a
\h'\n[lss]u'This program draws nine crosses and writes the same text at each; however it
\h'\n[lss]u'goes through all possible nine alignment strings, showing their effect.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, peek, poke
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'then ? tell the long from the short form of the if-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'if (a<b) then
\h'\n[lss]u'?
\h'\n[lss]u'endif
\h'\n[lss]u'Description
\h'\n[lss]u'The keyword then is part of the if-statement; please see there for further
\h'\n[lss]u'explanations. However, not every if-statement requires the keyword then: If the
\h'\n[lss]u'keyword then is present, the if-clause may extend over more than one line, and
\h'\n[lss]u'the keyword endif is required to end it. If the keyword then is not present,
\h'\n[lss]u'the if-statement extends up to the end of the line, and any endif would be an
\h'\n[lss]u'error.
\h'\n[lss]u'Example
\h'\n[lss]u'if (1<2) then
\h'\n[lss]u'print "Hello ";
\h'\n[lss]u'endif
\h'\n[lss]u'if (2<3) print "world"
\h'\n[lss]u'if (2<1)
\h'\n[lss]u'print "!"
\h'\n[lss]u'This example prints Hello world. Note, that no exclamation mark (!) is printed,
\h'\n[lss]u'which might come as a surprise and may be changed in future versions of yabasic
\h'\n[lss]u'.
\h'\n[lss]u'See also
\h'\n[lss]u'if
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'time$ ? return a string containing the current time
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print time$
\h'\n[lss]u'print time$()
\h'\n[lss]u'Description
\h'\n[lss]u'The time$ function returns the current time in four fields separated by hyphens
\h'\n[lss]u''-'. The fields are:
\h'\n[lss]u'* The current hour in the range from 0 to 23, padded with zeroes (e.g. 00 or
\h'\n[lss]u'04) to a length of two characters.
\h'\n[lss]u'* The number of minutes, padded with zeroes.
\h'\n[lss]u'* The number of seconds, padded with zeroes.
\h'\n[lss]u'* The number of seconds, that have elapsed since the program has been
\h'\n[lss]u'started. This value increases as long as your program runs and is therefore
\h'\n[lss]u'unbound and not padded with zeroes.
\h'\n[lss]u'At the time of writing this documentation, time$ returns 22-58-53-0. Note, that
\h'\n[lss]u'the first three of the four fields returned by time$ have a fixed width;
\h'\n[lss]u'therefore it is easy to extract some fields with the usual string-functions
\h'\n[lss]u'mid$ (and others).
\h'\n[lss]u'Example
\h'\n[lss]u'print "Hello it is ",time$
\h'\n[lss]u'print "An empty for-loop with ten million iterations takes ";
\h'\n[lss]u'for a=1 to 10000000:next a
\h'\n[lss]u'print "Now it is ",time$
\h'\n[lss]u'print peek("secondsrunning")," seconds have passed."
\h'\n[lss]u'This program benchmarks the for-loop; however, it does not use the fourth field
\h'\n[lss]u'of the string returned by time$, because that string wraps around every 60
\h'\n[lss]u'seconds; rather the peek "secondsrunning" is queried.
\h'\n[lss]u'See also
\h'\n[lss]u'date
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'to ? this keyword appears as part of other statements
\h'\n[lss]u'Synopsis
\h'\n[lss]u'for a=1 to 100 step 2
\h'\n[lss]u'?
\h'\n[lss]u'next a
\h'\n[lss]u'line x,y to a,b
\h'\n[lss]u'Description
\h'\n[lss]u'The to-keyword serves two purposes (which are not related at all):
\h'\n[lss]u'* within for-statements, to specify the upper bound of the loop.
\h'\n[lss]u'* Within any graphical command (e.g. line), that requires two points (i.e.
\h'\n[lss]u'four numbers) as arguments, a comma ',' might be replaced with the keyword
\h'\n[lss]u'to. I.e. instead of 100,100,200,200 you may write 100,100 to 200,200 in
\h'\n[lss]u'such commands.
\h'\n[lss]u'Example
\h'\n[lss]u'Please see the command listed under "See also" for examples.
\h'\n[lss]u'See also
\h'\n[lss]u'for, line, rectangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'token() ? split a string into multiple strings
\h'\n[lss]u'Synopsis
\h'\n[lss]u'dim w$(10)
\h'\n[lss]u'?
\h'\n[lss]u'num=token(a$,w$())
\h'\n[lss]u'num=token(a$,w$(),s$)
\h'\n[lss]u'Description
\h'\n[lss]u'The token-function accepts a string (containing the text to be split), a
\h'\n[lss]u'reference to a string-array (which will receive the resulting strings, i.e. the
\h'\n[lss]u'tokens) and an optional string (with a set of characters, at which to split,
\h'\n[lss]u'i.e. the delimiters).
\h'\n[lss]u'The token-function regards its first argument as a list of tokens separated by
\h'\n[lss]u'delimiters and it will store the list of tokens within the array-reference that
\h'\n[lss]u'has been supplied. Note, that the array, which is passed as a reference (w$()
\h'\n[lss]u'in the synopsis), will be resized accordingly, so that you don't have to figure
\h'\n[lss]u'out the number of tokens in advance. The element at position zero (i.e. w$(0))
\h'\n[lss]u'will not be used.
\h'\n[lss]u'Normally (i.e. if you omit the third, the delimiter-argument) the function will
\h'\n[lss]u'regard space or tab as delimiters for tokens; however by supplying a third
\h'\n[lss]u'argument, you may split at any single of the characters within this string.
\h'\n[lss]u'E.g. if you supply ":;" as the third argument, then colon (:) or semicolon (;)
\h'\n[lss]u'will delimit tokens.
\h'\n[lss]u'Note, that token will never produce empty tokens, even if two or more
\h'\n[lss]u'separators follow in sequence. Refer to the closely related split-function, if
\h'\n[lss]u'you do not like this behaviour. In some way, the token-function focuses on the
\h'\n[lss]u'tokens and not on the separators (other than the split-function, which focuses
\h'\n[lss]u'on the separators).
\h'\n[lss]u'The second argument is a reference on a string-array, where the tokens will be
\h'\n[lss]u'stored; this array will be expanded (or shrunk) as necessary to have room for
\h'\n[lss]u'all tokens.
\h'\n[lss]u'The first argument finally contains the text, that will be split into tokens.
\h'\n[lss]u'The token-function returns the number of tokens, that have been found.
\h'\n[lss]u'Please see the examples below for some hints on the exact behaviour of the
\h'\n[lss]u'token-function and how it differs from the split-function:
\h'\n[lss]u'Example
\h'\n[lss]u'print "This program will help you to understand, how the"
\h'\n[lss]u'print "token()-function exactly works and how it behaves"
\h'\n[lss]u'print "in certain special cases."
\h'\n[lss]u'print
\h'\n[lss]u'print "Please enter a line containing tokens separated"
\h'\n[lss]u'print "by either '=' or '-'"
\h'\n[lss]u'dim t$(10)
\h'\n[lss]u'do
\h'\n[lss]u'print
\h'\n[lss]u'input "Please enter a line: " l$
\h'\n[lss]u'num=token(l$,t$(),"=-")
\h'\n[lss]u'print num," Tokens: ";
\h'\n[lss]u'for a=1 to num
\h'\n[lss]u'if (t$(a)="") then
\h'\n[lss]u'print "(EMPTY)";
\h'\n[lss]u'else
\h'\n[lss]u'print t$(a);
\h'\n[lss]u'endif
\h'\n[lss]u'if (a<num) print ",";
\h'\n[lss]u'next a
\h'\n[lss]u'print
\h'\n[lss]u'loop
\h'\n[lss]u'This program prints the following output:
\h'\n[lss]u'Please enter a line: a
\h'\n[lss]u'1 Tokens: a
\h'\n[lss]u'Please enter a line:
\h'\n[lss]u'0 Tokens:
\h'\n[lss]u'Please enter a line: ab
\h'\n[lss]u'1 Tokens: ab
\h'\n[lss]u'Please enter a line: a=b
\h'\n[lss]u'2 Tokens: a,b
\h'\n[lss]u'Please enter a line: a-
\h'\n[lss]u'1 Tokens: a
\h'\n[lss]u'Please enter a line: a-=
\h'\n[lss]u'1 Tokens: a
\h'\n[lss]u'Please enter a line: =a-
\h'\n[lss]u'1 Tokens: a
\h'\n[lss]u'Please enter a line: a=-b
\h'\n[lss]u'2 Tokens: a,b
\h'\n[lss]u'Please enter a line: a--b-
\h'\n[lss]u'2 Tokens: a,b
\h'\n[lss]u'Please enter a line: -a==b-c==
\h'\n[lss]u'3 Tokens: a,b,c
\h'\n[lss]u'See also
\h'\n[lss]u'split
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'triangle ? draw a triangle
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window 100,100
\h'\n[lss]u'triangle 100,100,50,50,100,50
\h'\n[lss]u'fill triangle 50,100,100,50,200,200
\h'\n[lss]u'clear fill triangle 20,20,10,10,200,200
\h'\n[lss]u'Description
\h'\n[lss]u'The triangle-command draws a triangle; it requires 6 parameters: The x- and
\h'\n[lss]u'y-coordinates of the three points making up the triangle. With the optional
\h'\n[lss]u'keywords clear and fill (which may appear both and in any sequence) the
\h'\n[lss]u'triangle can be cleared and filled respectively.
\h'\n[lss]u'Example
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'do
\h'\n[lss]u'phi=phi+0.2
\h'\n[lss]u'i=i+2
\h'\n[lss]u'color mod(i,255),mod(85+2*i,255),mod(170+3*i,255)
\h'\n[lss]u'dx=100*sin(phi):dy=20*cos(phi)
\h'\n[lss]u'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)
\h'\n[lss]u'sleep 0.1
\h'\n[lss]u'loop
\h'\n[lss]u'This example draws a colored triangles until you get exhausted.
\h'\n[lss]u'See also
\h'\n[lss]u'open window, open printer, line, circle, rectangle
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'trim$() ? remove leading and trailing spaces from its argument
\h'\n[lss]u'Synopsis
\h'\n[lss]u'a$=trim$(b$)
\h'\n[lss]u'Description
\h'\n[lss]u'The trim$-function removes all whitespace from the left and from the right end
\h'\n[lss]u'of a string and returns the result. Calling trim$ is equivalent to calling
\h'\n[lss]u'rtrim$(ltrim$()).
\h'\n[lss]u'Example
\h'\n[lss]u'do
\h'\n[lss]u'input "Continue ? Please answer yes or no: " a$
\h'\n[lss]u'a$=lower$(trim$(a$))
\h'\n[lss]u'if (len(a$)>0 and a$=left$("no",len(a$)) exit
\h'\n[lss]u'loop
\h'\n[lss]u'This example asks for an answer (yes or no) and removes spaces with trim$ to
\h'\n[lss]u'make the comparison with the string "no" more bulletproof.
\h'\n[lss]u'See also
\h'\n[lss]u'ltrim$, rtrim$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'true ? a constant with the value of 1
\h'\n[lss]u'Synopsis
\h'\n[lss]u'okay=true
\h'\n[lss]u'Description
\h'\n[lss]u'The constant true can be assigned to variables which will later appear in
\h'\n[lss]u'conditions (e.g. an if-statement.
\h'\n[lss]u'true may also be written as TRUE or even TrUe.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a string of all upper letters: " a$
\h'\n[lss]u'if (is_upper(a$)) print "Okay"
\h'\n[lss]u'sub is_upper(a$)
\h'\n[lss]u'if (a$=upper$(a$)) return true
\h'\n[lss]u'return false
\h'\n[lss]u'end sub
\h'\n[lss]u'See also
\h'\n[lss]u'false
\h'\n[lss]u'U
\h'\n[lss]u'until ? end a repeat-loop
\h'\n[lss]u'upper$() ? convert a string to upper case
\h'\n[lss]u'using ? Specify the format for printing a number
\h'\n[lss]u'Name
\h'\n[lss]u'until ? end a repeat-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'repeat
\h'\n[lss]u'?
\h'\n[lss]u'until (?)
\h'\n[lss]u'Description
\h'\n[lss]u'The until-keyword ends a loop, which has been introduced by the repeat-keyword.
\h'\n[lss]u'until requires a condition in braces (or an expression, see here for details)
\h'\n[lss]u'as an argument; the loop will continue until this condition evaluates to true.
\h'\n[lss]u'Example
\h'\n[lss]u'c=1
\h'\n[lss]u's=1
\h'\n[lss]u'repeat
\h'\n[lss]u'l=c
\h'\n[lss]u's=-(s+sig(s))
\h'\n[lss]u'c=c+1/s
\h'\n[lss]u'print c
\h'\n[lss]u'until(abs(l-c)<0.000001)
\h'\n[lss]u'This program calculates the sequence 1/1-1/2+1/3-1/4+1/5-1/6+1/7-1/8+ ? ;
\h'\n[lss]u'please let me know, if you know against which value this converges.
\h'\n[lss]u'See also
\h'\n[lss]u'repeat
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'upper$() ? convert a string to upper case
\h'\n[lss]u'Synopsis
\h'\n[lss]u'u$=upper$(a$)
\h'\n[lss]u'Description
\h'\n[lss]u'The upper$-function accepts a single string argument and converts it to all
\h'\n[lss]u'upper case.
\h'\n[lss]u'Example
\h'\n[lss]u'line input "Please enter a sentence without the letter 'e': " l$
\h'\n[lss]u'p=instr(upper$(l$),"E")
\h'\n[lss]u'if (p) then
\h'\n[lss]u'l$=lower$(l$)
\h'\n[lss]u'mid$(l$,p,1)="E"
\h'\n[lss]u'print "Hey, you are wrong, see here!"
\h'\n[lss]u'print l$
\h'\n[lss]u'else
\h'\n[lss]u'print "Thanks."
\h'\n[lss]u'endif
\h'\n[lss]u'This program asks for a sentence and marks the first (if any) occurrence of the
\h'\n[lss]u'letter 'e' by converting it to upper case (in contrast to the rest of the
\h'\n[lss]u'sentence, which is converted to lower case).
\h'\n[lss]u'See also
\h'\n[lss]u'lower$
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'using ? Specify the format for printing a number
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print a using "##.###"
\h'\n[lss]u'print a using("##.###",",.")
\h'\n[lss]u'Description
\h'\n[lss]u'The using-keyword may appear as part of the print-statement and specifies the
\h'\n[lss]u'format (e.g. the number of digits before and after the decimal dot), which
\h'\n[lss]u'should be used to print the number.
\h'\n[lss]u'The possible values for the format argument ("##.###" in the synopsis above)
\h'\n[lss]u'are described within the entry for the str$-function; especially the second
\h'\n[lss]u'line in the synopsis (print a using("##.###",",.")) will become clear after
\h'\n[lss]u'referring to str$. In fact the using clause is closely related to the
\h'\n[lss]u'str$-function; the former can always be rewritten using the latter; i.e. print
\h'\n[lss]u'foo using bar$ is always equivalent to print str$(foo,bar$). Therefore you
\h'\n[lss]u'should check out str$ to learn more.
\h'\n[lss]u'Example
\h'\n[lss]u'for a=1 to 10
\h'\n[lss]u'print sqrt(ran(10000*a)) using "#########.#####"
\h'\n[lss]u'next a
\h'\n[lss]u'This example prints a column of square roots of random number, nicely aligned
\h'\n[lss]u'at the decimal dot.
\h'\n[lss]u'See also
\h'\n[lss]u'print, str$
\h'\n[lss]u'V
\h'\n[lss]u'val() ? converts a string to a number
\h'\n[lss]u'Name
\h'\n[lss]u'val() ? converts a string to a number
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=val(x$)
\h'\n[lss]u'Description
\h'\n[lss]u'The val-function checks, if the start of its string argument forms a floating
\h'\n[lss]u'point number and then returns this number. The string therefore has to start
\h'\n[lss]u'with digits (only whitespace in front is allowed), otherwise the val-function
\h'\n[lss]u'returns zero.
\h'\n[lss]u'Example
\h'\n[lss]u'input "Please enter a length, either in inches (in) or centimeters (cm) " l$
\h'\n[lss]u'if (right$(l$,2)="in") then
\h'\n[lss]u'l=val(l$)*2.51
\h'\n[lss]u'else
\h'\n[lss]u'l=val(l$)
\h'\n[lss]u'print "You have entered ",l,"cm."
\h'\n[lss]u'This example queries for a length and checks, if it has been specified in
\h'\n[lss]u'inches or centimeters. The length is then converted to centimeters.
\h'\n[lss]u'See also
\h'\n[lss]u'str$
\h'\n[lss]u'W
\h'\n[lss]u'wait ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'wend ? end a while-loop
\h'\n[lss]u'while ? start a while-loop
\h'\n[lss]u'window origin ? move the origin of a window
\h'\n[lss]u'Name
\h'\n[lss]u'wait ? pause, sleep, wait for the specified number of seconds
\h'\n[lss]u'Synopsis
\h'\n[lss]u'wait 4
\h'\n[lss]u'Description
\h'\n[lss]u'The wait-command has many different names: You may write pause, sleep or wait
\h'\n[lss]u'interchangeably; whatever you write, yabasic will always do exactly the same.
\h'\n[lss]u'Therefore you should refer to the entry for the pause-function for further
\h'\n[lss]u'information.
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'wend ? end a while-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'while(a<b)
\h'\n[lss]u'?
\h'\n[lss]u'wend
\h'\n[lss]u'Description
\h'\n[lss]u'The wend-keyword marks the end of a while-loop. Please see the while-keyword
\h'\n[lss]u'for more details.
\h'\n[lss]u'wend can be written as end while or even end-while.
\h'\n[lss]u'Example
\h'\n[lss]u'line input "Please enter a sentence: " a$
\h'\n[lss]u'p=instr(a$,"e")
\h'\n[lss]u'while(p)
\h'\n[lss]u'mid$(a$,p,1)="E"
\h'\n[lss]u'p=instr(a$,"e")
\h'\n[lss]u'wend
\h'\n[lss]u'print a$
\h'\n[lss]u'This example reads a sentence and converts every occurrence of the letter e
\h'\n[lss]u'into uppercase (E).
\h'\n[lss]u'See also
\h'\n[lss]u'while (which is just the following entry).
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'while ? start a while-loop
\h'\n[lss]u'Synopsis
\h'\n[lss]u'while(?)
\h'\n[lss]u'?
\h'\n[lss]u'wend
\h'\n[lss]u'Description
\h'\n[lss]u'The while-keyword starts a while-loop, i.e. a loop that is executed as long as
\h'\n[lss]u'the condition (which is specified in braces after the keyword while) evaluates
\h'\n[lss]u'to true.
\h'\n[lss]u'Note, that the body of such a while-loop will not be executed at all, if the
\h'\n[lss]u'condition following the while-keyword is not true initially.
\h'\n[lss]u'If you want to leave the loop prematurely, you may use the break-statement.
\h'\n[lss]u'Example
\h'\n[lss]u'open #1,"foo"
\h'\n[lss]u'while(!eof(1))
\h'\n[lss]u'line input #1 a$
\h'\n[lss]u'print a$
\h'\n[lss]u'wend
\h'\n[lss]u'This program reads the file foo and prints it line by line.
\h'\n[lss]u'See also
\h'\n[lss]u'until, break, wend, do
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'origin ? move the origin of a window
\h'\n[lss]u'Synopsis
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'origin "cc"
\h'\n[lss]u'Description
\h'\n[lss]u'The origin-command applies to graphic windows and moves the origin of the
\h'\n[lss]u'coordinate system to one of nine point within the window. The normal position
\h'\n[lss]u'of the origin is in the upper left corner of the window; however in some cases
\h'\n[lss]u'this is inconvenient and moving the origin may save you from subtracting a
\h'\n[lss]u'constant offset from all of your coordinates.
\h'\n[lss]u'However, you may not move the origin to an arbitrary position; in horizontal
\h'\n[lss]u'position there are only three positions: left, center and right, which are
\h'\n[lss]u'decoded by the letters l, c and r. In vertical position the allowed positions
\h'\n[lss]u'are top, center and bottom; encoded by the letters t, c and b. Taking the
\h'\n[lss]u'letters together, you arrive at a string, which might be passed as an argument
\h'\n[lss]u'to the command; e.g. "cc" or "rt".
\h'\n[lss]u'Example
\h'\n[lss]u'100,100
\h'\n[lss]u'open window 200,200
\h'\n[lss]u'window origin "cc"
\h'\n[lss]u'circle 0,0,60
\h'\n[lss]u'This example draws a circle, centered at the center of the window.
\h'\n[lss]u'See also
\h'\n[lss]u'open window
\h'\n[lss]u'X
\h'\n[lss]u'xor() ? compute the exclusive or
\h'\n[lss]u'Name
\h'\n[lss]u'xor() ? compute the exclusive or
\h'\n[lss]u'Synopsis
\h'\n[lss]u'x=xor(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'The xor computes the bitwise exclusive or of its two numeric arguments. To
\h'\n[lss]u'understand the result, both arguments should be viewed as binary numbers (i.e.
\h'\n[lss]u'a series of 0 and 1); a bit of the result will then be 1, if exactly one
\h'\n[lss]u'argument has a 1 and the other has a 0 at this position in their binary
\h'\n[lss]u'representation.
\h'\n[lss]u'Note, that both arguments are silently converted to integer values and that
\h'\n[lss]u'negative numbers have their own binary representation and may lead to
\h'\n[lss]u'unexpected results when passed to and.
\h'\n[lss]u'Example
\h'\n[lss]u'print xor(7,4)
\h'\n[lss]u'This will print 3. This result is obvious, if you note, that the binary
\h'\n[lss]u'representation of 7 and 4 are 111 and 100 respectively; this will yield 011 in
\h'\n[lss]u'binary representation or 2 as decimal.
\h'\n[lss]u'The eor-function is the same as the xor function; both are synonymous; however
\h'\n[lss]u'they have each their own description, so you may check out the entry of eor for
\h'\n[lss]u'a slightly different view.
\h'\n[lss]u'See also
\h'\n[lss]u'and, or, eor, not
\h'\n[lss]u'Special characters
\h'\n[lss]u'# ? either a comment or a marker for a file-number
\h'\n[lss]u'// ? starts a comment
\h'\n[lss]u'@ ? synonymous to at
\h'\n[lss]u': ? separate commands from each other
\h'\n[lss]u'; ? suppress the implicit newline after a print-statement
\h'\n[lss]u'** or ^ ? raise its first argument to the power of its second
\h'\n[lss]u'Name
\h'\n[lss]u'# ? either a comment or a marker for a file-number
\h'\n[lss]u'Synopsis
\h'\n[lss]u'# This is a comment, but the line below not !
\h'\n[lss]u'open #1,"foo"
\h'\n[lss]u'Description
\h'\n[lss]u'The hash ('#') has two totally unrelated uses:
\h'\n[lss]u'* A hash might appear in commands related with file-io. yabasic uses simple
\h'\n[lss]u'numbers to refer to open files (within input, print, peek or eof). In those
\h'\n[lss]u'commands the hash may precede the number, which species the file. Please
\h'\n[lss]u'see those commands for further information and examples; the rest of this
\h'\n[lss]u'entry is about the second use (as a comment).
\h'\n[lss]u'* As the very first character within a line, a hash introduces comments
\h'\n[lss]u'(similar to rem).
\h'\n[lss]u''#' as a comment is common in most scripting languages and has a special use
\h'\n[lss]u'under Unix: If the very first line of any Unix-program begins with the
\h'\n[lss]u'character sequence '#!' ("she-bang", no spaces allowed), the rest of the line
\h'\n[lss]u'is taken as the program that should be used to execute the script. I.e. if your
\h'\n[lss]u'yabasic-program starts with '#!/usr/local/bin/yabasic', the program /usr/local/
\h'\n[lss]u'bin/yabasic will be invoked to execute the rest of the program. As a remark for
\h'\n[lss]u'windows-users: This mechanism ensures, that yabasic will be invoked to execute
\h'\n[lss]u'your program; the ending of the file (e.g. .yab) will be ignored by Unix.
\h'\n[lss]u'Example
\h'\n[lss]u'# This line is a valid comment
\h'\n[lss]u'print "Hello " : # But this is a syntax error, because
\h'\n[lss]u'print "World!" : # the hash is not the first character !
\h'\n[lss]u'Note, that this example will produce a syntax error and is not a valid program
\h'\n[lss]u'!
\h'\n[lss]u'See also
\h'\n[lss]u'input, print, peek or eof, //, rem
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'// ? starts a comment
\h'\n[lss]u'Synopsis
\h'\n[lss]u'// This is a comment !
\h'\n[lss]u'Description
\h'\n[lss]u'The double-slash ('//') is (besides REM and '#') the third way to start a
\h'\n[lss]u'comment. '//' is the latest and greatest in the field of commenting and allows
\h'\n[lss]u'yabasic to catch up with such cool languages like C++ and Java.
\h'\n[lss]u'Example
\h'\n[lss]u'// Another comment.
\h'\n[lss]u'print "Hello world !" // Another comment
\h'\n[lss]u'Unlike the example given for '#' this example is syntactically correct and will
\h'\n[lss]u'not produce an error.
\h'\n[lss]u'See also
\h'\n[lss]u'#, rem
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'@ ? synonymous to at
\h'\n[lss]u'Synopsis
\h'\n[lss]u'clear screen
\h'\n[lss]u'?
\h'\n[lss]u'print @(a,b)
\h'\n[lss]u'Description
\h'\n[lss]u'As '@' is simply a synonym for at, please see at for further information.
\h'\n[lss]u'See also
\h'\n[lss]u'at
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u': ? separate commands from each other
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print "Hello ":print "World"
\h'\n[lss]u'Description
\h'\n[lss]u'The colon (':') separates multiple commands on a single line.
\h'\n[lss]u'The colon and the newline-character have mostly the same effect, only that the
\h'\n[lss]u'latter, well, starts a new line too. The only other difference is their effect
\h'\n[lss]u'within the (so-called) short if, which is an if-statement without the keyword
\h'\n[lss]u'then. Please see the entry for if for more details.
\h'\n[lss]u'Example
\h'\n[lss]u'if (a<10) print "Hello ":print "World !"
\h'\n[lss]u'This example demonstrates the difference between colon and newline as described
\h'\n[lss]u'above.
\h'\n[lss]u'See also
\h'\n[lss]u'if
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'; ? suppress the implicit newline after a print-statement
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print "foo",bar;
\h'\n[lss]u'Description
\h'\n[lss]u'The semicolon (';') may only appear at the last position within a print
\h'\n[lss]u'-statement. It suppresses the implicit newline, which yabasic normally adds
\h'\n[lss]u'after each print-statement.
\h'\n[lss]u'Put another way: Normally the output of each print-statement appears on a line
\h'\n[lss]u'by itself. If you rather want the output of many print-statements to appear on
\h'\n[lss]u'a single line, you should end the print-statement with a semicolon.
\h'\n[lss]u'Example
\h'\n[lss]u'print "Hello ";:print "World !"
\h'\n[lss]u'This example prints Hello World ! in a single line.
\h'\n[lss]u'See also
\h'\n[lss]u'print
\h'\n[lss]u'-------------------------------------------------------------------------------
\h'\n[lss]u'Name
\h'\n[lss]u'** or ^ ? raise its first argument to the power of its second
\h'\n[lss]u'Synopsis
\h'\n[lss]u'print 2**b
\h'\n[lss]u'print 3^4
\h'\n[lss]u'Description
\h'\n[lss]u'** (or ^, which is an exact synonym), is the arithmetic operator of
\h'\n[lss]u'exponentiation; it requires one number to its left and a second one to its
\h'\n[lss]u'right; ** then raises the first argument to the power of the second and returns
\h'\n[lss]u'the result. The result will only be computed if it yields a real number (as
\h'\n[lss]u'opposed to a complex number); this means, that the power can not be computed,
\h'\n[lss]u'if the first argument is negative and the second one is fractional. On the
\h'\n[lss]u'other hand, the second argument can be fractional, if the first one ist
\h'\n[lss]u'positive; this means, that ** may be used to compute arbitrary roots: e.g.
\h'\n[lss]u'x**0.5 computes the square root of x.
\h'\n[lss]u'Example
\h'\n[lss]u'print 2**0.5
\h'\n[lss]u'See also
\h'\n[lss]u'sqrt
\h'\n[lss]u'Reserved Words
\h'\n[lss]u'Here is a list of all reserved words in yabasic. Please make sure, that you do
\h'\n[lss]u'not try to use one of them as the name of a variable or subroutine. Or, the
\h'\n[lss]u'other way around: If you get some mysterious error from yabasic and you just
\h'\n[lss]u'can't figure out why, then you might be using one of the reserved words below,
\h'\n[lss]u'without knowing.
\h'\n[lss]u'Anyway, here is the list:
\h'\n[lss]u'ABS ACOS AND ARRAYDIM ARRAYDIMENSION
\h'\n[lss]u'ARRAYSIZE AS ASC ASIN AT
\h'\n[lss]u'ATAN BEEP BELL BIN$ BIND
\h'\n[lss]u'BITBLIT BITBLIT$ BITBLT BITBLT$ BOX
\h'\n[lss]u'BREAK CASE CHR$ CIRCLE CLEAR
\h'\n[lss]u'CLOSE COLOR COLOUR COMPILE CONTINUE
\h'\n[lss]u'COS CURVE DATA DATE$ DEC
\h'\n[lss]u'DEFAULT DIM DO DOT ELSE
\h'\n[lss]u'ELSEIF ELSIF END ENDIF EOF
\h'\n[lss]u'EOR ERROR EXECUTE EXECUTE$ EXIT
\h'\n[lss]u'EXP EXPORT FI FILL FILLED
\h'\n[lss]u'FOR FRAC GETBIT$ GETSCREEN$ GLOB
\h'\n[lss]u'GOSUB GOTO HEX$ IF INKEY$
\h'\n[lss]u'INPUT INSTR INT INTERRUPT LABEL
\h'\n[lss]u'LEFT$ LEN LET LINE LOCAL
\h'\n[lss]u'LOG LOOP LOWER$ LTRIM$ MAX
\h'\n[lss]u'MID$ MIN MOD MOUSEB MOUSEBUTTON
\h'\n[lss]u'MOUSEMOD MOUSEMODIFIER MOUSEX MOUSEY NEW
\h'\n[lss]u'NEXT NOT NUMPARAM ON OPEN
\h'\n[lss]u'OR ORIGIN PAUSE PEEK PEEK$
\h'\n[lss]u'POKE PRINT PRINTER PUTBIT PUTSCREEN
\h'\n[lss]u'RAN READ READING RECT RECTANGLE
\h'\n[lss]u'REDIM REPEAT RESTORE RETURN REVERSE
\h'\n[lss]u'RIGHT$ RINSTR RTRIM$ SCREEN SEEK
\h'\n[lss]u'SIG SIN SLEEP SPLIT SPLIT$
\h'\n[lss]u'SQR SQRT STATIC STEP STR$
\h'\n[lss]u'SUB SUBROUTINE SWITCH SYSTEM SYSTEM$
\h'\n[lss]u'TAN TELL TEXT THEN TIME$
\h'\n[lss]u'TO TOKEN TOKEN$ TRIANGLE TRIM$
\h'\n[lss]u'UNTIL UPPER$ USING VAL WAIT
\h'\n[lss]u'WEND WHILE WINDOW WRITING XOR
\h'\n[lss]u'Please see here for explanations on how to use these words in yabasic.
\h'\n[lss]u'Chapter 8. Some general concepts and terms
\h'\n[lss]u'Logical shortcuts
\h'\n[lss]u'Conditions and expressions
\h'\n[lss]u'References on arrays
\h'\n[lss]u'Specifying Filenames under Windows
\h'\n[lss]u'Escape-sequences
\h'\n[lss]u'Creating a standalone program from your yabasic-program
\h'\n[lss]u'This chapter presents some general concepts and terms, which deserve a
\h'\n[lss]u'description on their own, but are not associated with a single command or
\h'\n[lss]u'function in yabasic. Most of these topics do not lend themselves to be read
\h'\n[lss]u'alone, rather they might be read (or skimmed) as background material if an
\h'\n[lss]u'entry from the alphabetical list of commands refers to them.
\h'\n[lss]u'Logical shortcuts
\h'\n[lss]u'Logical shortcuts are no special language construct and there is no keyword for
\h'\n[lss]u'them; they are just a way to evaluate logical expressions. Logical expressions
\h'\n[lss]u'(i.e. a series of conditions or comparisons joined by and or or) are only
\h'\n[lss]u'evaluated until the final result of the expression can be determined. An
\h'\n[lss]u'example:
\h'\n[lss]u'if (a<>0 and b/a>2) print "b is at least twice as big as a"
\h'\n[lss]u'The logical expression a<>0 and b/a>2 consists of two comparisons, both of
\h'\n[lss]u'which must be true, if the print statement should be executed. Now, if the
\h'\n[lss]u'first comparison (a<>0) is false, the whole logical expression can never be
\h'\n[lss]u'true and the second comparison (b/a>2) need not be evaluated.
\h'\n[lss]u'This is exactly, how yabasic behaves: The evaluation of a composed logical
\h'\n[lss]u'expressions is terminated immediately, as soon as the final result can be
\h'\n[lss]u'deduced from the already evaluated parts.
\h'\n[lss]u'In practice, this has the following consequences:
\h'\n[lss]u'* If two or more comparisons are joined with and and one comparison results
\h'\n[lss]u'in false, the logical expression is evaluated no further and the overall
\h'\n[lss]u'result is false.
\h'\n[lss]u'* If two or more comparisons are joined with or and one comparison results in
\h'\n[lss]u'true, the logical expression is evaluated no further and the result is
\h'\n[lss]u'true.
\h'\n[lss]u'?Nice, but whats this good for ??, I hear you say. Well, just have another look
\h'\n[lss]u'at the example, especially the second comparison (b/a>2); dividing b by a is
\h'\n[lss]u'potentially hazardous: If a equals zero, the expression will cause an error and
\h'\n[lss]u'your program will terminate. To avoid this, the first part of the comparison (a
\h'\n[lss]u'<>0) checks, if the second one can be evaluated without risk. This pre-checking
\h'\n[lss]u'is the most common usage and primary motivation for logical shortcuts (and the
\h'\n[lss]u'reason why most programming languages implement them).
\h'\n[lss]u'Conditions and expressions
\h'\n[lss]u'Well, bottomline there is no difference or distinction between conditions and
\h'\n[lss]u'expressions, at least as yabasic is concerned. So you may assign the result of
\h'\n[lss]u'comparisons to variables or use an arithmetic expression or a simple variable
\h'\n[lss]u'within a condition (e.g. within an if-statement). So the constructs shown in
\h'\n[lss]u'the example below are all totally valid:
\h'\n[lss]u'input "Please enter a number between 1 and 10: " a
\h'\n[lss]u'rem Assigning the result of a comparison to a variable
\h'\n[lss]u'okay=a>=1 and a<=10
\h'\n[lss]u'rem Use a variable within an if-statement
\h'\n[lss]u'if (not okay) error "Wrong, wrong !"
\h'\n[lss]u'So conditions and expressions are really the same thing (at least as long as
\h'\n[lss]u'yabasic is concerned). Therefore the terms conditions and expression can really
\h'\n[lss]u'be used interchangeably, at least in theory. In reality the term condition is
\h'\n[lss]u'used in connection with if or while whereas the term expression tends to be
\h'\n[lss]u'used more often within arithmetic context.
\h'\n[lss]u'References on arrays
\h'\n[lss]u'References on arrays are the only way to refer to an array as a whole and to
\h'\n[lss]u'pass it to subroutines or functions like arraydim or arraysize. Whereas (for
\h'\n[lss]u'example) a(2) designates the second element of the array a, a() (with empty
\h'\n[lss]u'braces) refers to the array a itself. a() is called an array reference.
\h'\n[lss]u'If you pass an array reference to one of your own subroutines, you need to be
\h'\n[lss]u'aware, that the subroutine will be able to modify the array you have passed in.
\h'\n[lss]u'So passing an array reference does not create a copy of the array; this has
\h'\n[lss]u'some interesting consequences:
\h'\n[lss]u'* Speed and space: Creating a copy of an array would be a time (and resource)
\h'\n[lss]u'consuming operation; passing just a reference is cheap and fast.
\h'\n[lss]u'* Returning many values: A subroutine, that wants to give back more than one
\h'\n[lss]u'value, may require an array reference among its arguments and then store
\h'\n[lss]u'its many return values within this array. This is the only way to return
\h'\n[lss]u'more than one value from a subroutine.
\h'\n[lss]u'Specifying Filenames under Windows
\h'\n[lss]u'As you probably know, windows uses the character '\' to separate the
\h'\n[lss]u'directories within a pathname; an example would be C:\yabasic\yabasic.exe (the
\h'\n[lss]u'usual location of the yabasic executable). However, the very same character '\'
\h'\n[lss]u'is used to construct escape sequences, not only in yabasic but in most other
\h'\n[lss]u'programming languages.
\h'\n[lss]u'Therefore the string "C:\t.dat" does not specify the file t.dat within the
\h'\n[lss]u'directory C:; this is because the sequence '\t' is translated into the
\h'\n[lss]u'tab-character. To specify this filename, you need to use the string "C:\\t.dat"
\h'\n[lss]u'(note the double slash '\\').
\h'\n[lss]u'Escape-sequences
\h'\n[lss]u'Escape-sequences are the preferred way of specifying 'special' characters. They
\h'\n[lss]u'are introduced by the '\'-character and followed by one of a few regular
\h'\n[lss]u'letters, e.g. '\n' or '\r' (see the table below).
\h'\n[lss]u'Escape-sequences may occur within any string at any position; they are replaced
\h'\n[lss]u'at parsetime (opposed to runtime), i.e. as soon as yabasic discovers the
\h'\n[lss]u'string, with their corresponding special character. As a consequence of this
\h'\n[lss]u'len("\a") returns 1, because yabasic replaces "\a" with the matching special
\h'\n[lss]u'character just before the program executes.
\h'\n[lss]u'Table 8.1. Escape sequences
\h'\n[lss]u'+--------------------------------------------+
\h'\n[lss]u'|Escape Sequence| Matching special character |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\n |newline |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\t |tabulator |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\v |vertical tabulator |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\b |backspace |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\r |carriage return |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\f |formfeed |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\a |alert (i.e. a beeping sound)|
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\\ |backslash |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\' |single quote |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\" |double quote |
\h'\n[lss]u'|---------------+----------------------------|
\h'\n[lss]u'|\xHEX |chr$(HEX) (see below) |
\h'\n[lss]u'+--------------------------------------------+
\h'\n[lss]u'Note, that an escape sequences of the form \xHEX allows one to encode arbitrary
\h'\n[lss]u'characters as long as you know their position (as a hex-number) within the
\h'\n[lss]u'ascii-charset: For example \x012 is transformed into the character chr$(18) (or
\h'\n[lss]u'chr$(dec("12",16)). Note that \x requires a hexa-decimal number (and the
\h'\n[lss]u'hexa-decimal string "12" corresponds to the decimal number 18).
\h'\n[lss]u'Creating a standalone program from your yabasic-program
\h'\n[lss]u'Creating a standalone-program from the command line
\h'\n[lss]u'Creating a standalone-program from within your program
\h'\n[lss]u'Downsides of creating a standalone program
\h'\n[lss]u'See also
\h'\n[lss]u'Note
\h'\n[lss]u'The bind-feature, which is described below, is at an experimental stage right
\h'\n[lss]u'now. It works (at least for me !) under Windows and Linux, but I cannot even
\h'\n[lss]u'promise it for other variants of Unix. However, if it does not work for your
\h'\n[lss]u'Unix, I will at least try to make it work, if you give me sufficient
\h'\n[lss]u'information of your system.
\h'\n[lss]u'Sometimes you may want to give one of your yabasic-programs to other people.
\h'\n[lss]u'However, what if those other people do not have yabasic installed ? In that
\h'\n[lss]u'case you may create a standalone-program from your yabasic-program, i.e. an
\h'\n[lss]u'executable, that may be executed on its own, standalone, even (and especially
\h'\n[lss]u'!) on computers, that do not have yabasic installed. Having created a
\h'\n[lss]u'standalone program, you may pass it around like any other program (e.g. one
\h'\n[lss]u'written in C) and you can be sure that your program will execute right away.
\h'\n[lss]u'Such a standalone-program is simply created by copying the full yabasic
\h'\n[lss]u'-interpreter and your yabasic-program (plus all the libraries it does import)
\h'\n[lss]u'together into a single, new program, whose name might be chosen at will (under
\h'\n[lss]u'windows of course it should have the ending .exe). If you decide to create a
\h'\n[lss]u'standalone-program, there are three bits in yabasic, that you may use:
\h'\n[lss]u'* The bind-command, which does the actual job of creating the standalone
\h'\n[lss]u'program from the yabasic-interpreter and your program.
\h'\n[lss]u'* The command-line Option --bind (see options), which does the same from the
\h'\n[lss]u'command-line.
\h'\n[lss]u'* The special peek("isbound"), which may be used to check, if the yabasic
\h'\n[lss]u'-program containing this peek is bound to the interpreter as part of a
\h'\n[lss]u'standalone program.
\h'\n[lss]u'With these bits you know enough to create a standalone-program. Actually there
\h'\n[lss]u'are two ways to do this: on the command line and from within your program.
\h'\n[lss]u'Creating a standalone-program from the command line
\h'\n[lss]u'Let's say you have the following very simple program within the file foo.yab:
\h'\n[lss]u'print "Hello World !"
\h'\n[lss]u'Normally you would start this yabasic-program by typing yabasic foo.yab and as
\h'\n[lss]u'a result the string Hello World ! would appear on your screen. However, to
\h'\n[lss]u'create a standalone-program from foo.yab you would type:
\h'\n[lss]u'yabasic -bind foo.exe foo.yab
\h'\n[lss]u'This command does not execute your program foo.yab but rather create a
\h'\n[lss]u'standalone-program foo.exe. Note: under Unix you would probably name the
\h'\n[lss]u'standalone program foo or such, omitting the windows-specific ending .exe.
\h'\n[lss]u'Yabasic will confirm by printing something like: ---Info: Successfully bound
\h'\n[lss]u''yabasic' and 'foo.yab' into 'foo.exe'.
\h'\n[lss]u'After that you will find a program foo.exe (which must be made executable with
\h'\n[lss]u'the chmod-command under Unix first). Now, executing this program foo.exe (or
\h'\n[lss]u'foo under Unix) will produce the output Hello World !.
\h'\n[lss]u'This newly created program foo.exe might be passed around to anyone, even if he
\h'\n[lss]u'does not have yabasic installed.
\h'\n[lss]u'Creating a standalone-program from within your program
\h'\n[lss]u'It is possible to write a yabasic-program, that binds itself to the yabasic
\h'\n[lss]u'-interpreter. Here is an example:
\h'\n[lss]u'if (!peek("isbound")) then
\h'\n[lss]u'bind "foo"
\h'\n[lss]u'print "Successfully created the standalone executable 'foo' !"
\h'\n[lss]u'exit
\h'\n[lss]u'endif
\h'\n[lss]u'print "Hello World !"
\h'\n[lss]u'If you run this program (which may be saved in the file foo.yab) via yabasic
\h'\n[lss]u'foo.yab, the peek("isbound") in the first line will check, if the program is
\h'\n[lss]u'already part of a standalone-program. If not (i.e. if the yabasic-interpreter
\h'\n[lss]u'and the yabasic-program are separate files) the bind-command will create a
\h'\n[lss]u'standalone program foo containing both. As a result you would see the output
\h'\n[lss]u'Successfully created the standalone executable 'foo' !. Note: Under Windows you
\h'\n[lss]u'would probably choose the filename foo.exe.
\h'\n[lss]u'Now, if you run this standalone executable foo (or foo.exe), the very same
\h'\n[lss]u'yabasic-program that is shown above will be executed again. However, this time
\h'\n[lss]u'the peek("isbound") will return TRUE and therefore the condition of the
\h'\n[lss]u'if-statement is false and the three lines after then are not executed. Rather
\h'\n[lss]u'the last print-statement will run, and you will see the output Hello World !.
\h'\n[lss]u'That way a yabasic-program may turn itself into a standalone-program.
\h'\n[lss]u'Downsides of creating a standalone program
\h'\n[lss]u'Now, before you go out and turn all your yabasic-programs into standalone
\h'\n[lss]u'programs, please take a second to consider the downsides of doing so:
\h'\n[lss]u'* The new standalone program will be at least as big as the interpreter
\h'\n[lss]u'itself, so you need to pass a few hundred kilobytes around, just to save
\h'\n[lss]u'people from having to install yabasic themselves.
\h'\n[lss]u'* There is no easy way to extract your yabasic-program from within the
\h'\n[lss]u'standalone program: If you ever want to change it, you need to have it
\h'\n[lss]u'around separately.
\h'\n[lss]u'* If a new version of yabasic becomes available, again you need to recreate
\h'\n[lss]u'all of your standalone programs to take advantage of bugfixes and
\h'\n[lss]u'improvements.
\h'\n[lss]u'So, being able to create a standalone program is certainly a good thing, but
\h'\n[lss]u'certainly not a silver bullet.
\h'\n[lss]u'See also
\h'\n[lss]u'The bind-command, the peek-function and the command line options.
\h'\n[lss]u'Chapter 9. A few example programs
\h'\n[lss]u'A very simple program
\h'\n[lss]u'The demo of yabasic
\h'\n[lss]u'A very simple program
\h'\n[lss]u'The program below is a very simple program:
\h'\n[lss]u'repeat
\h'\n[lss]u'input "Please enter the first number, to add " a
\h'\n[lss]u'input "Please enter the second number, to add " b
\h'\n[lss]u'print a+b
\h'\n[lss]u'until(a=0 and b=0)
\h'\n[lss]u'This program requests two numbers, which it than adds. The process is repeated
\h'\n[lss]u'until you enter zero (or nothing) twice.
\h'\n[lss]u'The demo of yabasic
\h'\n[lss]u'The listing below is the demo of yabasic. Note, that parts of this demo have
\h'\n[lss]u'been written before some of the more advanced features (e.g subroutines) of
\h'\n[lss]u'yabasic have been implemented. So please do not take this as a particular good
\h'\n[lss]u'example of yabasic-code.
\h'\n[lss]u'//
\h'\n[lss]u'// This program demos yabasic
\h'\n[lss]u'//
\h'\n[lss]u'// Check, if screen is large enough
\h'\n[lss]u'clear screen
\h'\n[lss]u'sw=peek("screenwidth"):sh=peek("screenheight")
\h'\n[lss]u'if (sw<78 or sh<24) then
\h'\n[lss]u'print
\h'\n[lss]u'print " Sorry, but your screen is to small to run this demo !"
\h'\n[lss]u'print
\h'\n[lss]u'end
\h'\n[lss]u'endif
\h'\n[lss]u'sw=78:sh=24
\h'\n[lss]u'// Initialize everything
\h'\n[lss]u'restore mmdata
\h'\n[lss]u'read mmnum:dim mmtext$(mmnum)
\h'\n[lss]u'for a=1 to mmnum:read mmtext$(a):next a
\h'\n[lss]u'// Main loop selection of demo
\h'\n[lss]u'ysel=1
\h'\n[lss]u'label mainloop
\h'\n[lss]u'clear screen
\h'\n[lss]u'print colour("cyan","magenta") at(7,2) "################################"
\h'\n[lss]u'print colour("cyan","magenta") at(7,3) "################################"
\h'\n[lss]u'print colour("cyan","magenta") at(7,4) "################################"
\h'\n[lss]u'print colour("yellow","blue") at(8,3) " This is the demo for yabasic "
\h'\n[lss]u'yoff=7
\h'\n[lss]u'for a=1 to mmnum
\h'\n[lss]u'if (a=mmnum) then ydisp=1:else ydisp=0:fi
\h'\n[lss]u'if (a=ysel) then
\h'\n[lss]u'print colour("blue","green") at(5,yoff+ydisp+a) mmtext$(a);
\h'\n[lss]u'else
\h'\n[lss]u'print at(5,yoff+ydisp+a) mmtext$(a);
\h'\n[lss]u'endif
\h'\n[lss]u'next a
\h'\n[lss]u'print at(3,sh-3) "Move selection with CURSOR KEYS (or u and d),"
\h'\n[lss]u'print at(3,sh-2) "Press RETURN or SPACE to choose, ESC to quit."
\h'\n[lss]u'do // loop for keys pressed
\h'\n[lss]u'rev=1
\h'\n[lss]u'do // loop for blinking
\h'\n[lss]u'k$=inkey$(0.4)
\h'\n[lss]u'if (k$="") then
\h'\n[lss]u'if (ysel=mmnum) then
\h'\n[lss]u'if (rev=1) then
\h'\n[lss]u'print colour("blue","green") at(5,yoff+mmnum+1) mmtext$(mmnum);
\h'\n[lss]u'rev=0
\h'\n[lss]u'else
\h'\n[lss]u'print colour("yellow","red") at(5,yoff+mmnum+1) mmtext$(mmnum);
\h'\n[lss]u'rev=1
\h'\n[lss]u'endif
\h'\n[lss]u'endif
\h'\n[lss]u'else // key has been pressed, leave loop
\h'\n[lss]u'break
\h'\n[lss]u'endif
\h'\n[lss]u'loop // loop for blinking
\h'\n[lss]u'yalt=ysel
\h'\n[lss]u'if (k$="up" or k$="u") then
\h'\n[lss]u'if (ysel=1) then ysel=mmnum else ysel=ysel-1 fi
\h'\n[lss]u'redraw():heal():continue
\h'\n[lss]u'fi
\h'\n[lss]u'if (k$="down" or k$="d") then
\h'\n[lss]u'if (ysel=mmnum) then ysel=1 else ysel=ysel+1 fi
\h'\n[lss]u'redraw():heal():continue
\h'\n[lss]u'fi
\h'\n[lss]u'if (k$=" " or k$="enter" or k$="right") then
\h'\n[lss]u'on ysel gosub overview,bitmap,tetraeder,endit
\h'\n[lss]u'goto mainloop
\h'\n[lss]u'fi
\h'\n[lss]u'if (k$="esc") then
\h'\n[lss]u'endit()
\h'\n[lss]u'fi
\h'\n[lss]u'beep
\h'\n[lss]u'print at(3,sh-5) "Invalid key: ",k$," "
\h'\n[lss]u'loop // loop for keys pressed
\h'\n[lss]u'// redraw line
\h'\n[lss]u'sub redraw()
\h'\n[lss]u'if (yalt=mmnum) then ydisp=1:else ydisp=0:fi
\h'\n[lss]u'print at(5,yoff+yalt+ydisp) mmtext$(yalt);
\h'\n[lss]u'if (ysel=mmnum) then ydisp=1:else ydisp=0:fi
\h'\n[lss]u'print colour("blue","green") at(5,yoff+ysel+ydisp) mmtext$(ysel);
\h'\n[lss]u'return
\h'\n[lss]u'end sub
\h'\n[lss]u'// erase a line
\h'\n[lss]u'sub heal()
\h'\n[lss]u'print at(3,sh-5) " "
\h'\n[lss]u'return
\h'\n[lss]u'end sub
\h'\n[lss]u'// Go here to exit
\h'\n[lss]u'label endit
\h'\n[lss]u'print at(3,sh-8) "Hope you liked it ...\n ";
\h'\n[lss]u'exit
\h'\n[lss]u'return
\h'\n[lss]u'// Present a short overview
\h'\n[lss]u'label overview
\h'\n[lss]u'clear screen
\h'\n[lss]u'print
\h'\n[lss]u'print " Yabasic is a quite traditional basic: It comes with"
\h'\n[lss]u'print " print, input, for-next-loops, goto, gosub, while and"
\h'\n[lss]u'print " repeat. It has user defined procedures and libraries,"
\h'\n[lss]u'print " however, it is not object oriented.\n"
\h'\n[lss]u'print " Yabasic makes it easy to open a window, draw lines"
\h'\n[lss]u'print " and print the resulting picture.\n"
\h'\n[lss]u'print " Yabasic programs are interpreted and run under Unix"
\h'\n[lss]u'print " and Windows. The Yabasic interpreter (around 200K)"
\h'\n[lss]u'print " and any Yabasic program can be glued together to"
\h'\n[lss]u'print " form a standalone executable.\n"
\h'\n[lss]u'print " Yabasic is free software, i.e. subject to the"
\h'\n[lss]u'print " MIT License.\n"
\h'\n[lss]u'print "\n\n\n While you read this, I am calculating prime numbers,\n"
\h'\n[lss]u'print " Press any key to return to main menu ..."
\h'\n[lss]u'can=1
\h'\n[lss]u'print at(6,17) "This is a prime number: "
\h'\n[lss]u'label nextcan
\h'\n[lss]u'can=can+2
\h'\n[lss]u'for i=2 to sqrt(can):if (frac(can/i)=0) then goto notprime:fi:next i
\h'\n[lss]u'print at(32,17) can;
\h'\n[lss]u'label notprime
\h'\n[lss]u'if (lower$(inkey$(0))<>"") then
\h'\n[lss]u'print at(10,sh) "Wrapping around once ...";
\h'\n[lss]u'for x=1 to sw
\h'\n[lss]u'a$=getscreen$(0,0,1,sh-2)
\h'\n[lss]u'b$=getscreen$(1,0,sw-1,sh-2)
\h'\n[lss]u'putscreen b$,0,0
\h'\n[lss]u'putscreen a$,sw-1,0
\h'\n[lss]u'next x
\h'\n[lss]u'sleep 2
\h'\n[lss]u'return
\h'\n[lss]u'fi
\h'\n[lss]u'goto nextcan
\h'\n[lss]u'// Show some animated bitmaps
\h'\n[lss]u'label bitmap
\h'\n[lss]u'clear screen
\h'\n[lss]u'print
\h'\n[lss]u'print "Yabasic offers some commands for drawing simple graphics."
\h'\n[lss]u'print reverse at(5,12) " Press any key to return to main menu ... "
\h'\n[lss]u'n=20
\h'\n[lss]u'open window 400,400
\h'\n[lss]u'for b=20 to 0 step -1
\h'\n[lss]u'color 255-b*12,0,b*12
\h'\n[lss]u'fill circle 200,200,b
\h'\n[lss]u'next b
\h'\n[lss]u'c$=getbit$(179,179,221,221)
\h'\n[lss]u'for a=1 to 2000
\h'\n[lss]u'color ran(255),ran(255),ran(255)
\h'\n[lss]u'x=ran(500)-100:y=ran(500)-100
\h'\n[lss]u'fill rectangle ran(500)-100,ran(500)-100,ran(500)-100,ran(500)-100
\h'\n[lss]u'next a
\h'\n[lss]u'x=200:y=200:phi=ran(2*pi):dx=2*sin(phi):dy=2*cos(phi)
\h'\n[lss]u'o$=""
\h'\n[lss]u'count=0
\h'\n[lss]u'label pong
\h'\n[lss]u'count=count+1
\h'\n[lss]u'if (o$<>"") putbit o$,xo-2,yo-2
\h'\n[lss]u'if (count>1000) then
\h'\n[lss]u'phi=ran(2*pi):dx=2*sin(phi):dy=2*cos(phi)
\h'\n[lss]u'sleep 2
\h'\n[lss]u'count=0
\h'\n[lss]u'endif
\h'\n[lss]u'xo=x:yo=y
\h'\n[lss]u'x=x+dx:y=y+dy
\h'\n[lss]u'o$=getbit$(x-2,y-2,x+46,y+46)
\h'\n[lss]u'putbit c$,x,y,"t"
\h'\n[lss]u'if (x<0 or x>360) dx=-dx
\h'\n[lss]u'if (y<0 or y>360) dy=-dy
\h'\n[lss]u'if (inkey$(0)<>"") then
\h'\n[lss]u'close window
\h'\n[lss]u'return
\h'\n[lss]u'endif
\h'\n[lss]u'goto pong
\h'\n[lss]u'return
\h'\n[lss]u'label tetraeder
\h'\n[lss]u'open window 400,400
\h'\n[lss]u'clear window
\h'\n[lss]u'clear screen
\h'\n[lss]u'print reverse at(5,12) " Press any key to return to main menu ... "
\h'\n[lss]u'dim opoints(4,3)
\h'\n[lss]u'restore points
\h'\n[lss]u'for n=1 to 4:for p=1 to 3:read opoints(n,p):next p:next n
\h'\n[lss]u'dim triangles(4,3)
\h'\n[lss]u'restore triangles
\h'\n[lss]u'for n=1 to 4:for p=1 to 3:read triangles(n,p):next p:next n
\h'\n[lss]u'phi=0:dphi=0.1:psi=0:dpsi=0.05
\h'\n[lss]u'dim points(4,3)
\h'\n[lss]u'r=60:g=20
\h'\n[lss]u'dr=0.5:dg=1.2:db=3
\h'\n[lss]u'label main
\h'\n[lss]u'phi=phi+dphi
\h'\n[lss]u'psi=psi+dpsi
\h'\n[lss]u'for n=1 to 4
\h'\n[lss]u'points(n,1)=opoints(n,1)*cos(phi)-opoints(n,2)*sin(phi)
\h'\n[lss]u'points(n,2)=opoints(n,2)*cos(phi)+opoints(n,1)*sin(phi)
\h'\n[lss]u'p2= points(n,2)*cos(psi)-opoints(n,3)*sin(psi)
\h'\n[lss]u'points(n,3)=opoints(n,3)*cos(psi)+ points(n,2)*sin(psi)
\h'\n[lss]u'points(n,2)=p2
\h'\n[lss]u'next n
\h'\n[lss]u'r=r+dr:if (r<0 or r>60) dr=-dr
\h'\n[lss]u'g=g+dg:if (g<0 or g>60) dg=-dg
\h'\n[lss]u'b=b+db:if (b<0 or b>60) db=-db
\h'\n[lss]u'dm=dm+0.01
\h'\n[lss]u'm=120-80*sin(dm)
\h'\n[lss]u'for n=1 to 4
\h'\n[lss]u'p1=triangles(n,1)
\h'\n[lss]u'p2=triangles(n,2)
\h'\n[lss]u'p3=triangles(n,3)
\h'\n[lss]u'n1=points(p1,1)+points(p2,1)+points(p3,1)
\h'\n[lss]u'n2=points(p1,2)+points(p2,2)+points(p3,2)
\h'\n[lss]u'n3=points(p1,3)+points(p2,3)+points(p3,3)
\h'\n[lss]u'if (n3>0) then
\h'\n[lss]u'sp=n1*0.5-n2*0.7-n3*0.6
\h'\n[lss]u'color 60+r+30*sp,60+g+30*sp,60+b+30*sp
\h'\n[lss]u'fill triangle 200+m*points(p1,1),200+m*points(p1,2),200+m*points(p2,1),200+m*points(p2,2),200+m*points(p3,1),200+m*points(p3,2)
\h'\n[lss]u'endif
\h'\n[lss]u'next n
\h'\n[lss]u'if (inkey$(0.1)<>"") close window:return
\h'\n[lss]u'clear window
\h'\n[lss]u'goto main
\h'\n[lss]u'label points
\h'\n[lss]u'data -1,-1,+1, +1,-1,-1, +1,+1,+1, -1,+1,-1
\h'\n[lss]u'label triangles
\h'\n[lss]u'data 1,2,4, 2,3,4, 1,3,4, 1,2,3
\h'\n[lss]u'// Data section ...
\h'\n[lss]u'label mmdata
\h'\n[lss]u'// Data for main menu: Number and text of entries in main menu
\h'\n[lss]u'data 4
\h'\n[lss]u'data " Yabasic in a nutshell "
\h'\n[lss]u'data " Some graphics "
\h'\n[lss]u'data " A rotating Tetraeder "
\h'\n[lss]u'data " Exit this demo "
\h'\n[lss]u'Chapter 10. The Copyright of yabasic
\h'\n[lss]u'yabasic may be copied under the terms of the MIT License, which is distributed
\h'\n[lss]u'with yabasic in the file LICENSE.
\h'\n[lss]u'The MIT License grants extensive rights as long as you keep the copyright
\h'\n[lss]u'notice present in most files untouched. Here is a list of things that are
\h'\n[lss]u'possible under the terms of the MIT License:
\h'\n[lss]u'* Put yabasic on your own homepage or CD and even charge for the service of
\h'\n[lss]u'distributing yabasic.
\h'\n[lss]u'* Write your own yabasic-programs, pack your program and yabasic into a
\h'\n[lss]u'package and sell the whole thing.
\h'\n[lss]u'* Modify yabasic and add or remove features, sell the modified version
\h'\n[lss]u'without adding the sources.
AUTHOR
Marc 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 on yabasic.
BUGS
Still some.
yabasic(1)