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.91 of yabasic

However, it 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.

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.

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

Under Windows yabasic will mostly be invoked by double-clicking on an appropriate icon; this way you do not have a chance to specify any of the command line options below. However, advanced users may change the librarypath in the registry, which has the same effect as specifying it as an option on the command line.

See the chapter on options for a complete list of all options, either on Unix or Windows.

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.

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

yabasic accepts a number of options on the command line.

See chapter on options for a complete list of all options, either on Unix or Windows.

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.

In addition to the usual decimal notation (e.g. 1234), yabasic also supports numeric literals with base 2 or 16; examples are 0b10011 (the number 19, written with base 2) or 0x34AF (the number 13487, written with base 16) respectively. Please note that these numbers (apart from the way you write them into your program) are no different from “ordinary” numbers and can be used in any place, where a normal number with base 10 would fit. E.g. you may compute the sine sin(0b110); so the base 2 (or 16) is just a different way of representation.

See bin$, hex$ or dec for related functions.

See also adding code during execution.

Logical shortcuts are no special language construct and there is no keyword for them; they are just a way to evaluate logical expressions. Logical expressions (i.e. a series of conditions or comparisons joined by and or or) are only evaluated until the final result of the expression can be determined. An example:

if (a<>0 and b/a>2) print "b is at least twice as big as a"

The logical expression a<>0 and b/a>2 consists of two comparisons, both of which must be true, if the print statement should be executed. Now, if the first comparison (a<>0) is false, the whole logical expression can never be true and the second comparison (b/a>2) need not be evaluated.

This is exactly, how yabasic behaves: The evaluation of a composed logical expressions is terminated immediately, as soon as the final result can be deduced from the already evaluated parts.

In practice, this has the following consequences:

“Nice, but whats this good for ?”, I hear you say. Well, just have another look at the example, especially the second comparison (b/a>2); dividing b by a is potentially hazardous: If a equals zero, the expression will cause an error and your program will terminate. To avoid this, the first part of the comparison (a<>0) checks, if the second one can be evaluated without risk. This pre-checking is the most common usage and primary motivation for logical shortcuts (and the reason why most programming languages implement them).

Well, bottomline there is no difference or distinction between conditions and expressions, at least as yabasic is concerned. So you may assign the result of comparisons to variables or use an arithmetic expression or a simple variable within a condition (e.g. within an if-statement). So the constructs shown in the example below are all totally valid:

input "Please enter a number between 1 and 10: " a

rem   Assigning the result of a comparison to a variable
okay=a>=1 and a<=10

rem   Use a variable within an if-statement
if (not okay) error "Wrong, wrong !"

So conditions and expressions are really the same thing (at least as long as yabasic is concerned). Therefore the terms conditions and expression can really be used interchangeably, at least in theory. In reality the term condition is used in connection with if or while whereas the term expression tends to be used more often within arithmetic context.

Yabasic, of course, allows to compare strings with strings and numbers with numbers; <, <=, > and >= compare their left-hand side to their right-hand side as usual; nothing new here and examples can be found throughout this manual.

More interesting, the equality-operator (for numbers as well as for strings) can be written in two different ways: either as = (traditional) or as == (more modern). The second form has the advantage of beeing visually distinct from the assignment-operator, which is the single =. One may argue therefore, that using == results in code, that is easier to understand and read; This manual however sticks to tradition and mostly uses the single = for equality-check.

Finally, inequality can be checked with <> or !=; both operators behave identically and so it is only a matter of taste, which one to use.

References on arrays are the only way to refer to an array as a whole and to pass it to subroutines or functions like arraydim or arraysize.

While (for example) a(2) designates the second element of the array a, a() (with empty braces) refers to the array a itself. a() is called an array reference. A nice example is the bultin function split, that accepts an array-reference and modifies the content of this array.

You may also pass to and use array reference within your own subroutines; these subroutines will then be able to modify the array you have passed in often this is intended.

Passing an array reference does not create a copy of the array; this has some interesting consequences:

dim words$(4)
for i=1 to 4
  read words$(i)
next i

print_words(words$())
upcase_words(words$())
print_words(words$())

sub print_words(w$())
  local i
  for i=1 to arraysize(w$(),1)
    print w$(i)," ";
  next i
  print    
end sub

sub upcase_words(w$())
  local i
  for i=1 to arraysize(w$(),1)
    w$(i) = upper$(w$(i))
  next i
end sub

data "case","does","not","matter"
            

	      
case does not matter
CASE DOES NOT MATTER		
	      
	    

As you probably know, windows uses the character '\' to separate the directories within a pathname; an example would be C:\programs\yabasic\yabasic.exe (a possible location of the yabasic executable). However, the very same character '\' is used to construct escape sequences, not only in yabasic but in most other programming languages.

Therefore e.g. the string "C:\t.dat" does not specify the file t.dat within the directory C:; this is because the sequence '\t' is translated into the tab-character (and thus giving a rather unusal filename containing a tab). To specify this filename, you need to use the string "C:\\t.dat" (note the double slash '\\').

Escape-sequences are the preferred way of specifying 'special' characters. They are introduced by the '\'-character and followed by one of a few regular letters, e.g. '\n' or '\r' (see the table below).

Escape-sequences may occur within any string at any position; they are replaced at parsetime (opposed to runtime), i.e. as soon as yabasic discovers the string, with their corresponding special character. As a consequence of this len("\a") returns 1, because yabasic replaces "\a" with the matching special character just before the program executes.

Note, that an escape sequences of the form \xHEX allows one to encode arbitrary characters as long as you know their position (as a hex-number) within the ascii-charset: For example \x012 is transformed into the character chr$(18) (or chr$(dec("12",16)). Note that \x requires a hexa-decimal number (and the hexadecimal string "12" corresponds to the decimal number 18).

Sometimes you may want to give one of your yabasic-programs to other people. However, what if those other people do not have yabasic installed ? In that case you may create a standalone-program from your yabasic-program, i.e. an executable, that may be executed on its own, standalone, even (and especially !) on computers, that do not have yabasic installed. Having created a standalone program, you may pass it around like any other program (e.g. one written in C) and you can be sure that your program will execute right away.

Such a standalone-program is simply created by copying the full yabasic-interpreter and your yabasic-program (plus all the libraries that it may import) together into a single, new program, whose name might be chosen at will (under windows of course it should have the ending .exe). If you decide to create a standalone-program, there are three facilities in yabasic, that you may use:

With these bits you know enough to create a standalone-program. Actually there are two ways to do this: on the command line and from within your program.

print "Hello World !"

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

print "Hello World !"

Yabasic allows to employ functionality from an external library; i.e. from a library, which is not written in yabasic, but rather in C; such a library is called a foreign library, as opposed to a library written in yabasic itself. Calling out to a foreign library can be useful, if such a library provides functionality, that can not be replicated in yabasic itself and for which a commandline-interface (which could be used via system) does not exist or is too cumbersome or slow. Examples would be libraries libVLC or libcurl which offer the functionality of vlc or curl to other programs, especially programs written in yabasic.

The foreign function interface of yabasic relies on the great libffi-library, a library making it easy to call other libraries dynamicaaly and the established standard for this task.

if peek$("os")="windows" then
  lib$ = "msvcrt.dll"
else
  lib$ = "libm.so.6"
endif

print "cos(2): ",foreign_function_call(lib$,"double","cos","double",2)

if peek$("os")="windows" then
  lib$ = "msvcrt.dll"
else
  lib$ = "libm.so.6"
endif

print foreign_function_call$(lib$,"string","strstr","string","foobar","string","ob","options","copy_string_result")

message_box("Hello World !","Message from yabasic")

sub message_box(message$, title$)
  msgptr$ = foreign_buffer_alloc$(len(message$)+1)
  foreign_buffer_set msgptr$, 0, message$
  titleptr$ = foreign_buffer_alloc$(len(title$)+1)
  foreign_buffer_set titleptr$, 0, title$
  hwnd$ = foreign_function_call$("user32.dll", "buffer", "GetActiveWindow")
  ret = foreign_function_call("user32.dll", "int32", "MessageBoxA", "buffer", hwnd$, "buffer", msgptr$, "buffer", titleptr$, "uint32", 0)
  foreign_buffer_free msgptr$
  foreign_buffer_free titleptr$
  return ret
end sub

struct tm {
    int tm_sec;    /* Seconds (0-60) */
    int tm_min;    /* Minutes (0-59) */
    int tm_hour;   /* Hours (0-23) */
    int tm_mday;   /* Day of the month (1-31) */
    int tm_mon;    /* Month (0-11) */
    int tm_year;   /* Year - 1900 */
    int tm_wday;   /* Day of the week (0-6, Sunday = 0) */
    int tm_yday;   /* Day in the year (0-365, 1 Jan = 0) */
    int tm_isdst;  /* Daylight saving time */
};
    

# First: Determine the correct library depending on OS
#
if peek$("os")="windows" then
  lib$ = "msvcrt.dll"
else
  lib$ = "libm.so.6"
endif

# Second: Get the unix-time
#
# time() has a pointer argument to store the result (in addition to returning it)
# we pass NULL, so only the return value is relevant
#
null$ = foreign_buffer_alloc$(-1)
now = foreign_function_call(lib$,"int","time","buffer",null$)
print "Seconds since the epoch: ",now

# Third: Convert the unix-time to a segmented time
#
# localtime() does not accept the time-value as an argument, but rather requires a pointer
# to the time-value, so we construct a buffer for one int and put in our value
now$ = foreign_buffer_alloc$(foreign_function_size("int"))
foreign_buffer_set now$,0,"int",now
# Dump the buffer for educational purpose
print "Dump of buffer:          ",foreign_buffer_dump$(now$)
# localtime() returns a structure with the componentes (year, day, sec, etc.) as elements
local$ = foreign_function_call$(lib$,"buffer","localtime","buffer",now$)

# Fourth: Get the current year from the resulting buffer
#
# assuming, that year is the sixth element of the structure
# so offset is 5
offset = 5 * foreign_function_size("int")
year = foreign_buffer_get(local$,offset,"int")
print "Current year:            ", year + 1900


# Fifth: manipulate the segmented time
#
# set year to something else
foreign_buffer_set local$,offset,"int",year-50


# Sixth: convert time-structure from localtime into ascii
#
print "50 years back:           ", foreign_function_call$(lib$,"string","asctime","buffer",local$)

Seconds since the epoch: 1559014899
Dump of buffer:          F3ADEC5C
Current year:            2019
50 years back:           Tue May 28 05:41:39 1969

typedef struct {
  CURLversion age;          /* see description below */
  const char *version;      /* human readable string */
  unsigned int version_num; /* numeric representation */
  const char *host;         /* human readable string */
  int features;             /* bitmask, see below */
  char *ssl_version;        /* human readable string */
  long ssl_version_num;     /* not used, always zero */
  const char *libz_version; /* human readable string */
  const char * const *protocols; /* protocols */

  ...                       /* more lines omitted */
  
} curl_version_info_data;
    

# Get structure with version info
info$ = frnfn_call$("libcurl.so.4","buffer","curl_version_info","int",1)
# dump it for reference
print frnbf_dump$(info$,32)
# assume, that the pointer to version string is at offset 8
sinfo$ = frnbf_get_buffer$(info$,8)
# print readable version
print frnbf_get$(sinfo$,0,10)