Yabasic

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

This document applies to version 2.760 of yabasic

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

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

About yabasic

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

yabasic puts emphasis on giving results quickly and easily; therefore simple commands are provided to open a graphic window, print the graphics or control the console screen and get keyboard or mouse information. The example below opens a window, draws a circle and prints the graphic:

open window 100,100
open printer
circle 50,50,40
text 10,50,"Press any key to get a printout"
clear screen
inkey$
close printer
close window

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

Chapter 2. The yabasic-program under Windows

Starting yabasic
Options
The context Menu

Starting yabasic

Once, yabasic has been set up correctly, there are three ways to start it:

Rightclick on your desktop: The desktop menu appears with a submenu named new. From this submenu choose yabasic. This will create a new icon on your desktop. If you rightclick on this icon, its context menu will appear; choose Execute to execute the program.
As a variant of the way described above, you may simply create a file with the ending .yab (e.g. with your favorite editor). Everything else then works as described above.
From the start-menu: Choose yabasic from your start-menu. A console-window will open and you will be asked to type in your program. Once you are finished, you need to type return twice, and yabasic will parse and execute your program.
Note
This is not the preferred way of starting yabasic ! Simply because the program, that you have typed, can not be saved and will be lost inevitably ! There is no such thing as a save-command and therefore no way to conserve the program, that you have typed. This mode is only intended for quick hacks, and short programs.

Options

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

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

-help or -?: Prints a short help message, which itself describes two further help-options.
-version: Prints the version of yabasic.
-geometry +X-POSITION+Y-POSITION: Sets the position of the graphic window, that is opened by open window (the size of this window, of course, is specified within the open window-command). An example would be -geometry +20+10, which would place the graphic window 10 pixels below the upper border and 20 pixels right of the left border of the screen. This value cannot be changed, once yabasic has been started.
-font NAME-OF-FONT: Name of the font, which will be used for graphic-text; can be any of decorative, dontcare, modern, roman, script, swiss. You may append a fontsize (measured in pixels) to any of those fontnames; for example -font swiss30 chooses a swiss-type font with a size of 30 pixels.
-bind NAME-OF-STANDALONE-PROGRAM: Create a standalone program (whose name is specified by NAME-OF-STANDALONE-PROGRAM) from the yabasic-program, that is specified on the commandline. See the section about creating a standalone-program for details.
-execute A-PROGRAM-AS-A-SINGLE-STRING: With this option you may specify some yabasic-code to be executed rigth away.This is useful for very short programs, which you do not want to save within a file. If this option is given, yabasic will not read any code from a file. Let's say, you have forgotten some of the square numbers between 1 and 10; in this case the command yabasic -e 'for a=1 to 10:print a*a:next a' will give you the answer immediately.
-infolevel INFOLEVEL: Change the infolevel of yabasic, where INFOLEVEL can be one of debug, note, warning, error and fatal (the default is warning). This option changes the amount of debugging-information yabasic produces. However, normally only the author of yabasic (me !) would want to change this.
-doc NAME-OF-A-PROGRAM: Print the embedded documentation of the named program. The embedded documentation of a program consists of all the comments within the program, which start with the special keyword doc. This documentation can also be seen by choosing the corresponding entry from the context-menu of any yabasic-program.
-librarypath DIRECTORY-WITH-LIBRARIES: Change the directory, wherein libraries will be searched and imported (with the import-command). See also this entry for more information about the way, libraries are searched.

The context Menu

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

Execute: This will invoke yabasic to execute your program. The same happens, if you doubleclick on the icon.
Edit: notepad will be invoked, allowing you to edit your program.
View docu: This will present the embedded documentation of your program. Embedded documentation is created with the special comment doc.

Chapter 3. The yabasic-program under Unix

Starting yabasic
Options
Setting defaults

Starting yabasic

If your system administrator (vulgo root) has installed yabasic correctly, there are three ways to start it:

You may use your favorite editor (emacs, vi ?) to put your program into a file (e.g. foo). Make sure that the very first line starts with the characters '#!' followed by the full pathname of yabasic (e.g. '#!/usr/local/bin/yabasic'). This she-bang-line ensures, that your Unix will invoke yabasic to execute your program (see also the entry for the hash-character). Moreover, you will need to change the permissions of your yabasic-program foo, e.g. chmod u+x foo. After that you may invoke yabasic to invoke your program by simply typing foo (without even mentioning yabasic). However, if your PATH-variable does not contain a single dot ('.') you will have to type the full pathname of your program: e.g. /home/ihm/foo (or at least ./foo).
Save your program into a file (e.g. foo) and type yabasic foo. This assumes, that the directory, where yabasic resides, is contained within your PATH-variable.
Finally your may simply type yabasic (maybe it will be necessary to include its full pathname). This will make yabasic come up and you will be asked to type in your program. Once you are finished, you need to type return twice, and yabasic will parse and execute your program.
Note
This is not the preferred way of starting yabasic ! Simply because the program, that you have typed, can not be saved and will be lost inevitably ! There is no such thing as a save-command and therefore no way to conserve the program, that you have typed. This mode is only intended for quick hacks, and short programs, i.e. for using yabasic as some sort of fancy desktop calculator.

Options

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

-help or -?

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

-version

Prints the version of yabasic.

-fg FOREGROUND-COLOR or -foreground FOREGROUND-COLOR

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

-bg BACKGROUND-COLOR or -background BACKGROUND-COLOR

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

-geometry +X-POSITION+Y-POSITION

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

-display BACKGROUND-COLOR

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

-font NAME-OF-FONT

Name of the font, which will be used for text within the graphics window.

-execute A-PROGRAM-AS-A-SINGLE-STRING

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

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

prints the square numbers from 1 to 10.

-bind NAME-OF-STANDALONE-PROGRAM

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

-infolevel INFOLEVEL

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

-doc NAME-OF-A-PROGRAM

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

-librarypath DIRECTORY-WITH-LIBRARIES

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

Setting defaults

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

Here is a sample section, which may appear within this file:

yabasic*foreground: blue
yabasic*background: gold
yabasic*geometry: +10+10
yabasic*font: 9x15

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

Chapter 4. Some features of yabasic, explained by topic

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

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

`print`, `input` and others

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

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

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

Control statements: loops, `if` and `switch`

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

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

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

Drawing and painting

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

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

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

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

Reading from and writing to files

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

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

Subroutines and Libraries

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

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

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

String processing

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

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

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

Arithmetic

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

Data and such

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

Other interesting commands.

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

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

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

Number processing and conversion

abs(): returns the absolute value of its numeric argument
acos(): returns the arcus cosine of its numeric argument
and(): the bitwise arithmetic and
asin(): returns the arcus sine of its numeric argument
atan(): returns the arctangent of its numeric argument
bin$(): converts a number into a sequence of binary digits
cos(): return the cosine of its single argument
dec(): convert a base 2 or base 16 number into decimal form
eor(): compute the bitwise exclusive or of its two arguments
euler: another name for the constant 2.71828182864
exp(): compute the exponential function of its single argument
frac(): return the fractional part of its numeric argument
int(): return the integer part of its single numeric argument
log(): compute the natural logarithm
max(): return the larger of its two arguments
min(): return the smaller of its two arguments
mod(): compute the remainder of a division
or(): arithmetic or, used for bit-operations
pi: a constant with the value 3.14159
ran(): return a random number
sig(): return the sign of its argument
sin(): return the sine of its single argument
sqr(): compute the square of its argument
sqrt(): compute the square root of its argument
tan(): return the tangent of its argument
xor(): compute the exclusive or
** or ^: raise its first argument to the power of its second

Conditions and control structures

and: logical and, used in conditions
break: breaks out of a switch statement or a loop
case: mark the different cases within a switch-statement
continue: start the next iteration of a for-, do-, repeat- or while-loop
default: mark the default-branch within a switch-statement
do: start a (conditionless) do-loop
else: mark an alternative within an if-statement
elsif: starts an alternate condition within an if-statement
end: terminate your program
endif: ends an if-statement
false: a constant with the value of 0
fi: another name for endif
for: starts a for-loop
gosub: continue execution at another point within your program (and return later)
goto: continue execution at another point within your program (and never come back)
if: evaluate a condition and execute statements or not, depending on the result
label: mark a specific location within your program for goto, gosub or restore
loop: marks the end of an infinite loop
next: mark the end of a for loop
not: negate an expression; can be written as !
on gosub: jump to one of multiple gosub-targets
on goto: jump to one of many goto-targets
on interrupt: change reaction on keyboard interrupts
logical or: logical or, used in conditions
pause: pause, sleep, wait for the specified number of seconds
repeat: start a repeat-loop
return: return from a subroutine or a gosub
sleep: pause, sleep, wait for the specified number of seconds
switch: select one of many alternatives depending on a value
then: tell the long from the short form of the if-statement
true: a constant with the value of 1
until: end a repeat-loop
wait: pause, sleep, wait for the specified number of seconds
wend: end a while-loop
while: start a while-loop
:: separate commands from each other

Data keeping and processing

arraydim(): returns the dimension of the array, which is passed as an array reference
arraysize(): returns the size of a dimension of an array
data: introduces a list of data-items
dim: create an array prior to its first use
read: read data from data-statements
redim: create an array prior to its first use. A synonym for dim
restore: reposition the data-pointer

String processing

asc(): accepts a string and returns the position of its first character within the ascii charset
chr$(): accepts a number and returns the character at this position within the ascii charset
glob(): check if a string matches a simple pattern
hex$(): convert a number into hexadecimal
instr(): searches its second argument within the first; returns its position if found
left$(): return (or change) left end of a string
len(): return the length of a string
lower$(): convert a string to lower case
ltrim$(): trim spaces at the left end of a string
mid$(): return (or change) characters from within a string
right$(): return (or change) the right end of a string
split(): split a string into many strings
str$(): convert a number into a string
token(): split a string into multiple strings
trim$(): remove leading and trailing spaces from its argument
upper$(): convert a string to upper case
val(): converts a string to a number

File operations and printing

at(): can be used in the print-command to place the output at a specified position
beep: ring the bell within your computer; a synonym for bell
bell: ring the bell within your computer (just as beep)
clear screen: erases the text window
close: close a file, which has been opened before
close printer: stops printing of graphics
print color: print with color
print colour: see print color
eof: check, if an open file contains data
getscreen$(): returns a string representing a rectangular section of the text terminal
inkey$: wait, until a key is pressed
input: read input from the user (or from a file) and assign it to a variable
line input: read in a whole line of text and assign it to a variable
open: open a file
open printer: open printer for printing graphics
print: Write to terminal or file
putscreen: draw a rectangle of characters into the text terminal
reverse: print reverse (background and foreground colors exchanged)
screen: as clear screen clears the text window
seek(): change the position within an open file
tell: get the current position within an open file
using: Specify the format for printing a number
#: either a comment or a marker for a file-number
@: synonymous to at
;: suppress the implicit newline after a print-statement

Subroutines and libraries

end sub: ends a subroutine definition
export: mark a function as globally visible
import: import a library
local: mark a variable as local to a subroutine
numparams: return the number of parameters, that have been passed to a subroutine
return: return from a subroutine or a gosub
static: preserves the value of a variable between calls to a subroutine
step: specifies the increment step in a for-loop
sub: declare a user defined subroutine

Other commands

bind(): Binds a yabasic-program and the yabasic-interpreter together into a standalone program.
compile: compile a string with yabasic-code on the fly
date$: returns a string with various components of the current date
doc: special comment, which might be retrieved by the program itself
docu$: special array, containing the contents of all docu-statement within the program
error: raise an error and terminate your program
execute$(): execute a user defined subroutine, which must return a string
execute(): execute a user defined subroutine, which must return a number
exit: terminate your program
pause: pause, sleep, wait for the specified number of seconds
peek: retrieve various internal informations
peek$: retrieve various internal string-informations
poke: change selected internals of yabasic
rem: start a comment
sleep: pause, sleep, wait for the specified number of seconds
system$(): hand a statement over to your operating system and return its output
system(): hand a statement over to your operating system and return its exitcode
time$: return a string containing the current time
to: this keyword appears as part of other statements
wait: pause, sleep, wait for the specified number of seconds
//: starts a comment
:: separate commands from each other

Graphics and printing

backcolor: specify the colour for subsequent drawing of the background
box: draw a rectangle. A synonym for rectangle
circle: draws a circle in the graphic-window
clear: Erase circles, rectangles or triangless
clear window: clear the graphic window and begin a new page, if printing is under way
close curve: close a curve, that has been drawn by the line-command
close window: close the graphics-window
colour: specify the colour for subsequent drawing
dot: draw a dot in the graphic-window
fill: draw a filled circles, rectangles or triangles
getbit$(): return a string representing the bit pattern of a rectangle within the graphic window
line: draw a line
mouseb: extract the state of the mousebuttons from a string returned by inkey$
mousemod: return the state of the modifier keys during a mouseclick
mousex: return the x-position of a mouseclick
mousey: return the y-position of a mouseclick
new curve: start a new curve, that will be drawn with the line-command
open window: open a graphic window
putbit: draw a rectangle of pixels into the graphic window
rectangle: draw a rectangle
triangle: draw a triangle
text: write text into your graphic-window
window origin: move the origin of a window

Chapter 6. All commands and functions of yabasic grouped alphabetically

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

A

abs() - returns the absolute value of its numeric argument
acos() - returns the arcus cosine of its numeric argument
and - logical and, used in conditions
and() - the bitwise arithmetic and
arraydim() - returns the dimension of the array, which is passed as an array reference
arraysize() - returns the size of a dimension of an array
asc() - accepts a string and returns the position of its first character within the ascii charset
asin() - returns the arcus sine of its numeric argument
at() - can be used in the print-command to place the output at a specified position
atan() - returns the arctangent of its numeric argument

Name

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

Synopsis

y=abs(x)

Description

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

Example

print abs(-2),abs(2)

This example will print 2 2

Name

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

Synopsis

x=acos(angle)

Description

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

Example

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

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

Name

and — logical and, used in conditions

Synopsis

if (a and b) …
while (a and b) …

Description

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

Note, that logical shortcuts may take place.

Example

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

Name

and() — the bitwise arithmetic and

Synopsis

x=and(a,b)

Description

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

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

Example

print and(6,3)

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

Name

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

Synopsis

a=arraydim(b())

Description

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

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

Example

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

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

Name

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

Synopsis

x=arraysize(a(),b)

Description

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

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

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

Example


rem
rem  This program adds two matrices elementwise.
rem

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

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

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

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

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

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

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

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

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

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

 end sub

Name

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

Synopsis

a=asc(char$)

Description

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

Example

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

Name

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

Synopsis

angle=asin(x)

Description

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

Example

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

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

Name

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

Synopsis

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

Description

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

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

Example

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

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

Name

atan() — returns the arctangent of its numeric argument

Synopsis

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

Description

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

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

Example

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

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

Name

color — change color for background of graphic window

Synopsis

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

Description

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

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

Example

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

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

Name

backcolour — see backcolor

Synopsis

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

Name

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

Synopsis

beep

Description

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

Example

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