Commit bfd6ee03 authored by John Spikowski's avatar John Spikowski

AIR Script BASIC User Guide Conversion

parent 39b28c35
Script Basic User Guide
* [Introduction](
* [Using ScriptBasic](
* [Running from command line](
* [Running CGI programs](
* [Writing CGI programs](
* [Installation Instructions](
* [Installation under Windows](
* [Installation under Windows from source](
* [Installation under Linux](
* [Installation under other Unices](
* [Configuration](
* [Configuration file location under Windows NT](
* [Configuration file location under UNIX](
* [Overriding the default configuration file](
* [Trouble shooting installation](
* [Code caching](
* [How cache file name is calculated](
* [Cache handling shortages](
* [Cache security](
* [Compiling BASIC programs](
* [Binary format of the BASIC code](
* [Compiling BASIC program to EXE](
* [BASIC to EXE compilation technical details](
* [Compiling BASIC programs to C](
* [Compilation under Windows NT](
* [Compilation under UNIX](
* [Compiling ScriptBasic with modules](
* [General Language Format](
* [Hello World](
* [Strings](
* [Numbers](
* [Variables](
* [Constants](
* [Forcing Variable Declaration](
* [Arrays](
* [Creating arrays](
* [Array index limits](
* [Deleting an array](
* [Associative Arrays](
* [Notes for using associative arrays](
* [Using Array Mixed Mode](
* [Expressions](
* [Operators](
* [Power operator (^)](
* [Multiplication operator (\*)](
* [Division operator (/)](
* [Integer division operator (\)](
* [Modulus operator (%)](
* [Addition and subtraction operators (+, -)](
* [Bit-wise and logical NOT (NOT)](
* [Equality operator (=)](
* [Not equal operator (<>)](
* [Compare operators (<, <=, >, >=)](
* [Logical operators (and, or, xor)](
* [Concatenation operator (&)](
* [ByVal operator](
* [LIKE operator](
* [Extension operators](
* [Planned, Future Operators](
* [Assignments (LET)](
* [Operator Assignments](
* [Comments](
* [Including Files](
* [Internal preprocessors](
* [Using external preprocessor](
* [#! /usr/bin/scriba](
* [@goto start](
* [#!/@goto](
* [Interacting with the user](
* [Print](
* [Input](
* [Handling command line arguments](
* [Name spaces](
* [File Handling](
* [Opening and creating files](
* [Text and binary files](
* [Switching between binary and text mode](
* [Getting a free file number](
* [Positioning in a file](
* [Reading and writing files](
* [Getting and setting the current working directory](
* [Locking a file](
* [Locking file range](
* [Truncating a file](
* [Deleting a file or directory](
* [Creating a directory](
* [Setting file parameters](
* [Listing files](
* [Open directory](
* [Function NextFile](
* [Function EOD](
* [Reset directory](
* [Close directory](
* [Networking](
* [Opening a Socket](
* [Getting the host name](
* [String handling commands](
* [Split and splita](
* [Unpack](
* [Conditional Execution](
* [The statement GOTO](
* [Loop constructs](
* [Functions and Subroutines](
* [Declaration of subroutines and function](
* [Calling functions and subroutines](
* [Returning a value](
* [Local and global variables](
* [More on local and global variables](
* [Parameters passed by value and by reference](
* [ByVal command](
* [Calling functions indirectly](
* [Reference Variables](
* [Pattern matching](
* [The operator LIKE](
* [The function JOKER](
* [Escaping wild cards](
* [Ambiguous matching](
* [Advanced matching](
* [Handling run-time errors](
* [On error goto](
* [Resume](
* [Levels of error handling](
* [Error codes](
* [Setting options](
* [Other miscellaneous commands](
* [Sleep](
* [Using External modules](
* [Command reference](
* [ABS](
* [ACOS](
* [ACTAN](
* [ADDRESS( myFunc() )](
* [ASC(string)](
* [ASIN](
* [ATAN](
* [ATN](
* [BIN](
* [BINMODE * [ # fn ] | input | output](
* [CALL subroutine](
* [CHDIR directory](
* [CHOMP()](
* [CHR(code)](
* [CINT](
* [CLOSE * [ # ] fn](
* [CLOSE DIRECTORY * [#] dn](
* [COMMAND()](
* [COMMANDF Details](
* [Concatenate operator &](
* [CONF(](
* [COS](
* [COTAN](
* [COTAN2](
* [CRYPT(string,salt)](
* [CURDIR()](
* [CVD](
* [CVI](
* [CVL](
* [CVS](
* [DAY](
* [DECLARE COMMAND function ALIAS cfun LIB library](
* [DECLARE SUB function ALIAS cfun LIB library](
* [DECLARE SUB Details](
* [DELETE file/directory_name](
* [DELTREE file/directory_name](
* [DO](
* [DO UNTIL condition](
* [DO WHILE condition](
* [END](
* [ENVIRON()](
* [ENVIRON Details](
* [EOD(dn)](
* [EOF(n)](
* [ERROR() or ERROR n](
* [ERROR$() or ERROR$(n)](
* [EVEN](
* [EXECUTE()](
* [EXECUTE Details](
* [EXECUTE Details](
* [EXECUTE Details](
* [EXP](
* [FALSE](
* [FILEACCESSTIME(file_name)](
* [FILECOPY filename,filename](
* [FILECREATETIME(file_name)](
* [FILEEXISTS(file_name)](
* [FILELEN(file_name)](
* [FILEMODIFYTIME(file_name)](
* [FIX](
* [LOCK # fn, mode](
* [FOR var=exp_start TO exp_stop * [ STEP exp_step ]](
* [FORK()](
* [FORMAT()](
* [FORMATDATE Details](
* [FILEOWNER(FileName)](
* [FRAC](
* [FUNCTION fun()](
* [FUNCTION Details](
* [GCD](
* [GOSUB label](
* [GOTO label](
* [HCOS](
* [HCTAN](
* [HEX(n)](
* [HOUR](
* [HSIN](
* [HTAN](
* [ICALL n,v1,v2, ... ,vn](
* [ICALL Details](
* [IF condition THEN](
* [IMAX](
* [IMIN](
* [INPUT(n,fn)](
* [INSTR(base_string,search_string * [ ,position ] )](
* [INSTRREV(base_string,search_string * [ ,position ] )](
* [INT](
* [ISDIRECTORY(file_name)](
* [ISFILE(file_name)](
* [JOIN(joiner,str1,str2,...)](
* [JOIN Details](
* [JOKER(n)](
* [JOKER Details](
* [KILL(pid)](
* [LCASE()](
* [LCM](
* [LEFT(string,len)](
* [LEFT Details](
* [LEN()](
* [v = expression](
* [v &= expression](
* [v /= expression](
* [v \= expression](
* [v -= expression](
* [v += expression](
* [v *= expression](
* [string LIKE pattern](
* [LIKE Details](
* [LOC()](
* [LOCK # fn, mode](
* [LOCK REGION # fn FROM start TO end FOR mode](
* [LOF()](
* [LOG](
* [LOG10](
* [LTRIM()](
* [MAX](
* [MID(string,start * [ ,len ])](
* [MID Details](
* [MIN](
* [MKD](
* [MKDIR directory_name](
* [MKI](
* [MKL](
* [MKS](
* [MONTH](
* [NAME filename,filename](
* [NEXTFILE(dn)](
* [NOW](
* [OCT(n)](
* [ODD](
* [ON ERROR GOTO * [ label | NULL ]](
* [ON ERROR RESUME * [ label | next ]](
* [OPEN file_name FOR mode AS * [ # ] i * [ LEN=record_length ]](
* [OPEN DIRECTORY dir_name PATTERN pattern OPTION option AS dn](
* [OPTION symbol value](
* [OPTION(](
* [pack(](
* [PAUSE](
* [PI](
* [POP](
* [POW](
* [PRINT * [ # fn , ] print_list](
* [ref v1 = v2](
* [REPLACE(base_string,search_string,replace_string * [,number_of_replaces] * [,position])](
* [RESET](
* [RESET DIRECTORY * [#] dn](
* [RESUME * [ label | next ]](
* [REWIND * [ # ]fn](
* [RIGHT(string,len)](
* [RIGHT Details](
* [RND](
* [ROUND](
* [RTRIM()](
* [SEC](
* [SEEK fn,position](
* [SET FILE filename parameter=value](
* [SET WILD ](
* [SIN](
* [SLEEP(n)](
* [SPACE(n)](
* [SPLIT string BY string TO var_1,var_2,var_3,...,var_n](
* [SPLITA string BY string TO array](
* [SPLITAQ string BY string QUOTE string TO array](
* [SQR](
* [STOP](
* [STR(n)](
* [STR Details](
* [STRING(n,code)](
* [STRREVERSE(string)](
* [SUB fun()](
* [swap a,b](
* [SYSTEM(executable_program)](
* [TAN](
* [TAN2](
* [TEXTMODE * [ # fn] | input | output](
* [TRIM()](
* [TRUE](
* [TRUNCATE fn,new_length](
* [TYPE](
* [UCASE()](
* [UNDEF variable](
* [UNDEF Details](
* [UNPACK string BY format TO v1,v2,...,vn](
* [VAL](
* [WAITPID(PID,ExitCode)](
* [WHILE condition](
* [YEAR](
# Introduction
\[\<\<\<\] [\[\>\>\>\]](
ScriptBasic is a BASIC language interpreter with several features that
makes it unique. First of all ScriptBasic itself is **free** and is
supported by the **GNU LGPL licence**. Note that the GNU LGPL
[licence]( applies only to
ScriptBasic itself, while the modules interfacing 3rd party software may
apply different licenses. For example the module interface code for the
module T\<bdb\> is under LGPL, but the library it uses, namely the
Berkeley DB is NOT LGPL\!
ScriptBasic runs on **Windows NT, Windows95, Linux, Tru64 UNIX** and
probably on many other platforms. ScriptBasic the ideal tool to write
small scripts that gurus write in Perl. However you need not be a guru
to powerfully program in ScriptBasic.
This is not the only situation to consider ScriptBasic. ScriptBasic can
be a valuable tool for experts as well as a language interpreter ready
to be built into their application. Read the list of ScriptBasic
features and decide how you can use it.
- **IT IS BASIC.** No question, this is the MOST important feature of
ScriptBasic. There are a lot of people who can program BASIC and
only BASIC. There are many people, who can not really program. Those
who do not really know what programming is, and still: they write
their five-liners in BASIC to solve their simple problems. They
never write Perl, Tcl, Java or C. Therefore it is BASIC.
- **SCRIPTING** language. There are no data types in the language. You
can store real numbers, integer numbers and strings in any variable.
You can mix them and conversion is done automatically. Therefore the
language is very simple and easy to use.
- **PORTABLE** Available in C source and can be compiled on UNIXes as
well as on Windows NT.
- **4E LANGUAGE**, which means easy to extend, easy to embed.
ScriptBasic was developed to provide clean and clear interfaces
around it, and inside it. It is easy to embed the language to an
application and use it as a macro language just like TCL. It is also
easy to implement new built-in function and new commands. You can
develop dynamically loaded libraries that ScriptBasic may load at
run time. The language source is clean, well documented and
development guides are available.
- **COMPILED CODE** ScriptBasic creates intermediate compiled code,
which is interpreted afterwards. This can protect intellectual
property for the BASIC programmer and faster code loading.
- Syntax analysis is done at first and only syntactically perfect
programs start to run.
- The compiled code is put into a continuous memory space and
compiled code can be saved and loaded again to run without
recompilation. This is vital for CGI scripts and is not
available for most scripting programming languages.
- Compiled code is binary, not readable. Therefore you can develop
and distribute programs and getting some help to protect your
intellectual property. You need not give the source code.
- **MULTI THREAD** aware. Although the current implementation is not
multi thread, all the code was designed to be thread safe. You can
embed the code into systems that run multiple interpreters in the
same process. On the other hand the interpreter can run the same
code in multiple threads and was designed to be capable handling
call-back functions, and multithread programs in the future.
This documentation is the User's Guide for the so-called STANDARD
variation of the interpreter. This code runs on the command line,
accepts command line arguments and runs a single program in a single
process. Other variations exist, which are based on the same code but
exhibit different interfaces to the system. Some features for those
variations may be different, but most language features probably remain
the same. The variation Eszter SB Application Engine is shipped with the
ScriptBasic package and is embedding the interpreter into a
multi-thread, single process web server. Other embedded variations are
available from independent developers.
This document describes how to use the interpreter and the programming
\[\<\<\<\] [\[\>\>\>\]](
# Print
[\[\<\<\<\]]( [\[\>\>\>\]](
The print statement can either print to a file or to the standard
output, which is usually the terminal window. If no file number is
specified after the keyword the statement print prints to the screen. It
takes a list of expressions, formats them and prints the values to the
print "haho!"
print "hahaho!"
print "kukac\n"
print "oooh"
print "The number is ",number
The list of expression is one or more expressions separated by commas.
Old implementations of the BASIC language used `;` for that and inserted
a space between the printed item. These old BASIC languages used the
comma as list separator to put the next printed item on the next tab
position. There is nothing like that in ScriptBasic. The comma simply
separates the list elements, which are printed adjacent. Comma does not
insert space between them and does not position on tab. `;` as list
separator is not allowed.
In case you want to position something in tab position you can
print "hello\ttab"
use the `\t` escaped character.
[\[\<\<\<\]]( [\[\>\>\>\]](
# Input
[\[\<\<\<\]]( [\[\>\>\>\]](
ScriptBasic has the usual input statement, however a slightly different
from other BASIC implementations. Input statement in other basic
languages reads the keyboard and puts a string, real or integer number
into the variable depending on the type of the variable. In ScriptBasic
there is no type of the variables, any variable can hold any type of
value. Thus the input statement can not know if the input is to be read
as integer, real or character string as typed.
Because of this ScriptBasic reads the characters as typed into the
variable on the input statement as string. Because this is the usual
behavior of the BASIC languages for the command `line input` ScriptBasic
also names this statement `LINE INPUT`.
This command reads a whole line from the file specified after the \#
sign or from the standard input if no file number was specified. The
string read is put into the variables listed on the command. Each
variable gets a line including the line terminating new line character.
print "Give me a line:"
line input a
print "This is a=",a,"This was a\n"
To remove the new line from the end of the read string you can use the
function `chomp`.
[\[\<\<\<\]]( [\[\>\>\>\]](
# Handling command line arguments
[\[\<\<\<\]]( [\[\>\>\>\]](
Though the command line is parsed by the interpreter up to the name of
the executable basic program name and all other command line options and
arguments are passed to the basic program to handle. To access this part
of the command line the basic program should use the function
`command()`. This function does not need any argument and returns a
string containing the command line arguments.
In the variation STANDARD the command line returned by the function
`command()` contains the parameters separated by a single space. Even if
the real command line contains multiple spaces or tabs between the
parameters it is converted to a list of parameters separated by single
' This program demonstrates the command function
' start the program using the command line:
' scriba commandline.bas a b c d e f
print "The command line was:\n",command(),"\n"
will print
The command line was:
a b c d e f
[\[\<\<\<\]]( [\[\>\>\>\]](
# Interacting with the user
[\[\<\<\<\]]( [\[\>\>\>\]](
Although this topic is detailed elsewhere we present a short
introduction here, because of its importance. Interacting with the user
is the most important action a program takes. There are many ways to do
it, but the most frequently used is printing to the screen and reading
from the keyboard and interpreting command line arguments. To do this
ScriptBasic has the command print and the command line input.
[\[\<\<\<\]]( [\[\>\>\>\]](
# Name spaces
[\[\<\<\<\]]( [\[\>\>\>\]](