BaCon BASIC converter documentation

Introduction

BaCon is an acronym for BAsic CONverter. The BaCon BASIC converter is a tool to convert programs written in BASIC syntax to C. The resulting C program should be compilable with GCC or CC.

BaCon is intended to be a programming aid in creating small tools which can be compiled on different Unix-based platforms. It tries to revive the days of the good old BASIC.

The BaCon converter passes expressions and numeric assignments to the C compiler without verification or modification. This means that the assignment symbol '=', which is used in C programs, also must be used in BaCon programs. Another consequence is that the C comparison symbol '==' also must be used in BaCon (there is an alias for the comparison symbol which is 'EQ'). Because of this BaCon can be considered a lazy converter: it relies on the expression parser of the C compiler.

BaCon usage and parameters

To use BaCon, download the converter and make sure the program has executable rights. There is no difference between the Kornshell version or the BASH version. Only one of them is needed. Suppose the BASH version is downloaded, the converter can be used as follows:

bash ./bacon.bash myprog.bac

By default the converter will refer to '/bin/bash' by itself. It uses a so-called 'shebang' which allows the program to run standalone provided the executable rights are set correctly. This way there is no need to execute BaCon with an explicit use of BASH. So this is valid:

./bacon.bash myprog.bac

All BaCon programs should use the '.bac' extension. But it is not necessary to provide this extension for conversion. So BaCon also understands the following syntax:

./bacon.bash myprog

The BaCon Basic Converter can be started with the following parameters.

-c: determine which C compiler should create the binary. The default value is 'gcc'. Example: ./bacon -c cc prog. In this situation, the converted program will be compiled by a C compiler called 'cc'.
-i: the compilation will use an additional external C include file
-l: the compilation will link with an additional library
-m: increase the amount of temporary buffers used for string processing. The default is 32. This parameter in fact determines how many string manipulations can be performed at the same time in a single statement. Higher values may cause memory problems on different platforms.
-s: BaCon has a stack which can be manipulated with the statements PULL and PUSH. By default, the stack is able to store 8 values or strings. With this parameter the storage capacity can be adjusted.
-d: determine the directory where BaCon should store the generated C files. Default value is the current directory.
-n: do not compile the C code automatically after conversion.
-p: do not cleanup the generated C files. Default behavior is to delete all generated C files automatically.
-o: the compiler will optimize the binary for the current platform. For GCC it means that the compilerflag '-mtune=native' will be used during compilation. Note that the resulting binary may not run on other platforms with other types of processors.
-a: force 32-bit compilation.
-g: the compiler will add debug information into the resulting binary. This may come handy when debugging the binary with GDB or Valgrind.
-w: the compiler will emit all warnings it encounters during compilation.
-v: shows the current version of BaCon.
-h: shows an overview of all possible options on the prompt. Same as the '-?' parameter.

General syntax

BaCon consists of statements, functions and expressions. Each line should begin with a statement. Functions always return a value to a variable or statement (like PRINT) but also can be used standalone. Expressions are not converted but are passed unchanged to the C compiler (lazy conversion).

BaCon does not need line numbers. One statement per line is accepted. If there are more statements on the same line then these are ignored.

Statements are always written without using brackets. Only functions must use brackets to enclose their arguments.

Variables will be declared implicitly from the first moment a variable is used. If a variable name ends with the '$' symbol, a string variable is assumed. Otherwise it is regarded as numeric. By default, BaCon assumes long type with NUMBER variables. With the 'DECLARE' statement it is possible to define a variable to any C-type explicitly.

The three main types in BaCon are defined as STRING, NUMBER and FLOATING.

Subroutines may be defined using SUB/ENDSUB. These SUB routines do not return a value. With FUNCTON/ENDFUNCTION routines can be defined which do return a value. The return value must be explicitly stated with the statement RETURN.

Variables which are used and declared within a SUB or FUNCTION have a global scope, meaning that they are seen by the main program and other routines. With the LOCAL statement variables can be declared local to the FUNCTION or SUB.

Mathematics, variables

The standard operators for mathematics can be used, like '+' for addition, '-' for substraction, '/' for division and '*' for multiplication. For the binary and use the '&' symbol, and for the binary or use '|'. Binary shifts are possible with '>>' and '<<'. The C operators '+=', '-=' and the like are not valid in BaCon.

Variable names may be of any length but cannot start with a number or an underscore symbol.

Arrays

An array will never be declared implicitly by BaCon, so arrays must be declared explicitly. This can be done by using the keyword GLOBAL for arrays which should be globally visible, or LOCAL for local array variables.

Arrays must be declared in the C syntax, using square brackets for each dimension. For example, a local string array must be declared like this: 'LOCAL array$[5]'. Two-dimensional arrays are written like 'array[5][5]', three-dimensional arrays like 'array[5][5][5]' and so on.

As BaCon is a lazy converter, arrays are passed as they are to the C compiler. This means that also their behavior is similar to the behavior in C. For example, if an array is declared as 'array[5]', then it means that the array elements range from 0 to 4. Element 5 is not part of the array.

Arrays must be declared with fixed dimensions, meaning that it is not possible to determine the dimensions of an array using variables or functions, so during program runtime. The reason for this is that the C compiler needs to know the array dimensions during compile time.

In BaCon, numeric arrays can have all dimensions, but string arrays cannot have more than one dimension.

Strings by value or by reference

Strings can be stored by value or by reference. By value means that a copy of the original string is stored in a variable. This happens automatically when when a string variablename ends with the '$' symbol.

Sometimes it may be necessary to refer to a string by reference. In such a case, simply declare a variablename as STRING but omit the '$' at the end. Such a variable will point to the same memory location as the original string. The following examples should show the difference between by value and by reference.

When using stringvariables by value:

a$ = "I am here"
b$ = a$
a$ = "Hello world..."
PRINT a$, b$

This will print “Hello world...I am here”. The variables point to their own memory area so they contain different strings. Now consider the following code:

a$ = "Hello world..."
LOCAL b TYPE STRING
b = a$
a$ = "Goodbye..."
PRINT a$, b FORMAT "%s%s\n"

This will print “Goodbye...Goodbye...” because the variable 'b' points to the same memory area as 'a$'. (The optional FORMAT forces the variable 'b' to be printed as a string, otherwise BaCon assumes that the variable 'b' contains a value.)

Statements and functions

ABS

ABS(x)

Type: function

Returns the absolute value of x.

ADDRESS

ADDRESS(x)

Type: function

Returns the memory address of variable x. This function can be used when passing pointers to imported C functions (see IMPORT).

AND

x AND y

Type: operator

Performs a logical and between x and y. For the binary and, use the '&' symbol.

ARGUMENT$

ARGUMENT$

Type: variable

Reserved variable containing the arguments to the program. The arguments are separated by spaces.

ASC

ASC(char)

Type: function

Calculates the ASCII value of char (opposite of CHR$). Example:

PRINT ASC("x")

CALL

CALL <sub name> [TO <var>]

Type: statement

Calls a subroutine if the sub is defined at the end of the program. With the optional TO a function can be invoked which stores the result value in <var>. Example:

CALL fh2cel(72) TO celsius
PRINT celsius

CATCH

CATCH GOTO <label> | RESET

Type: statement

Sets the error function where the program should jump to if error checking is enabled with TRAP. For an example, see the RESUME statement. Using the RESET argument restores the BaCon default error messages.

CHANGEDIR

CHANGEDIR <directory>

Type: statement

Changes the current working directory. Example:

CHANGEDIR "/tmp/mydir"

CHOP$

CHOP$(x)

Type: function

Returns a string where on both sides <CR>, <NL>, <TAB> and <SPACE> have been removed.

CHR$

CHR$(x)

Type: function

Returns the character belonging to ASCII number x. This function does the opposite of ASC. The value for x must lay between 0 and 255.

CLEAR

CLEAR

Type: statement

Clears the terminal screen. To be used with ANSI compliant terminals.

CLOSE

CLOSE FILE|DIRECTORY|NETWORK|MEMORY <handle>

Type: statement

Close file, directory or network identified by handle. Example:

CLOSE FILE myfile

COLOR

Type: statement

Sets coloring for the output of characters in a terminal screen. For FG, the foreground color is set. With BG, the background color is set. This only works with ANSI compliant terminals. Example:

COLOR FG TO GREEN
PRINT "This is green!"
COLOR RESET

CONCAT$

CONCAT$(x$, y$, …)

Type: function

Returns the concatenation of x$, y$, ... The CONCAT function can accept an unlimited amount of arguments. Example:

PRINT CONCAT$("Help this is ", name$, "carrying a strange ", thing$)

CONST

CONST <var> = <value> | <expr>

Type: statement

Assigns a value a constant variable.

COPY

COPY <file> TO <newfile>

Type: statement

Copies a file to a new file. Example:

COPY "file.txt" TO "/tmp/new.txt"

COS

COS(x)

Type: function

Returns the calculated COSINUS of x.

DATA

DATA <x, y, z....>

Type: statement

Defines float, integer or string data. In a DATA statement there can only be one type of data. The data can be read with the READ statement. If one more data is read than available, then in case of numeric data a '0' will retrieved, and in case of string data an empty string. Example:

DATA 1, 2, 3, 4, 5, 6
DATA 0.5, 0.7,0.11, 0.15
DATA "one", "two", "three", "four"

DAY

DAY(x)

Type: function

Returns the day of the month (1-31) where x is amount of seconds since January 1, 1970.

DEC

DEC(x)

Type: function

Calculates the decimal value of x, where x should be passed as a string. Example:

PRINT DEC("AB1E")

DECLARE

DECLARE <var>[,var2,var3,...] TYPE <c-type>

Type: statement

Explicitely declares a variable to a C-type. This is always a global declaration. Use LOCAL for local declarations. This function is available for compatibility reasons. It does the same thing as the GLOBAL statement.

DEF FN

DEF FN <label> [(args)] = <value> | <expr>

Type: statement

Assigns a value or expression to a label. Example:

DEF FN func(x) = 3 * x
PRINT func(12)

DELETE

DELETE <FILE|DIRECTORY> <name>

Type: statement

Deletes a file or directory. If an error occurs then this can be retrieved with the CATCH statement. Example:

DELETE FILE "/tmp/data.txt"

END

END [value]

Type: statement

Exits a program. Optionally, a value can be provided which the program can return to the shell.

ENDFILE

ENDFILE(filehandle)

Type: function

Function to check if EOF on a file opened with <handle> is reached. If the end of a file is reached, the value '1' is returned, else this function returns '0'. For an example, see the OPEN statement.

EQ

x EQ y

Type: operator

Verifies if x is equal to y. This is an alias for the C construct '=='. Example:

IF q EQ 5 THEN
PRINT "q equals 5"
END IF

EQUAL

EQUAL(x$, y$)

Type: function

Returns 1 if x$ and y$ are equal, or 0 if x$ and y$ are not equal. This is the only way in BaCon to compare two strings.

ERR$

ERR$(x)

Type: function

Returns the runtime error as a human readable string, identified by x. Example:

PRINT ERR$(ERROR)

ERROR

ERROR

Type: variable

This is a reserved variable, which contains the last error number.

EVEN

EVEN(x)

Type: function

Returns 1 if x is even, else returns 0.

FALSE

FALSE

Type: variable

Represents and returns the value of '0'.

FILELEN

FILELEN(filename)

Type: function

Returns the size of a file identified by <filename>. If an error occurs this function returns '0'. The ERR$ statement can be used to check for an error. Example:

length = FILELEN("/etc/passwd")

FILETYPE

FILETYPE(filename)

Type: function

Returns the type of a file identified by <filename>. If an error occurs this function returns '0'. The ERR$ statement can be used find out which error. The following values may be returned:

Value	Meaning
1	Regular file
2	Directory
3	Character device
4	Block device
5	Named pipe (FIFO)
6	Symbolic link
7	Socket

FILL$

FILL$(x, y)

Type: function

Returns an x amount of ASCII character y. The value for y must lay between 0 and 255. Example printing 10 times the character '@':

PRINT FILL$(10, 64)

FLOOR

FLOOR(x)

Type: function

Returns the rounded down value of x.

FOR

FOR var = x TO y [STEP z]
<body>
[BREAK]
NEXT [var]

Type: statement

With FOR/NEXT a body of statements can be repeated a fixed amount of times. The variable will be increased with 1 unless a STEP is specified. Example:

FOR x = 1 TO 10 STEP 0.5
PRINT x
NEXT

FREE

FREE x

Type: statement

Releases claimed memory (see also MEMORY).

FUNCTION

FUNCTION <name> ()|(STRING s, NUMBER i, FLOATING f)
<body>
RETURN <x>
ENDFUNCTION | END FUNCTION

Type: statement

Defines a function. The variables within a function are visible globally, unless declared with the LOCAL statement. A FUNCTION always returns a value, this should explicitly be specified with the RETURN statement. Instead of the Bacon types STRING, NUMBER and FLOATING for the incoming arguments, also regular C-types can be used. Example:

FUNCTION fh2cel (NUMBER fahrenheit)
    LOCAL celsius
    celsius = fahrenheit*9/5 + 32
    RETURN celsius
END FUNCTION

GETBYTE

GETBYTE <memory> FROM <filehandle> [SIZE x]

Type: statement

Retrieves binary data into a memory area from a file identified by handle, with optional size of x bytes (default size = 1 byte). This command is useful in case binary data must be fetched. Example:

OPEN prog$ FOR READING AS myfile
txt = MEMORY(100)
GETBYTE txt FROM myfile SIZE 100
CLOSE FILE myfile

GETENVIRON$

GETENVIRON$(var$)

Type: function

Returns the value of the environment variable 'var$'. If the environment variable does not exist, this function returns an empty string.

GETFILE

GETFILE <var> FROM <dirhandle>

Type: statement

Reads a file from an opened directory. Subsequent reads return the files in the directory. If there are no more files then an empty string is returned. Refer to the OPEN statement for an example on usage.

GETKEY

GETKEY

Type: function

Returns a key from the keyboard without waiting for <RETURN>-key. Example:

PRINT "Press <escape> to exit now..."
key = GETKEY
IF key EQ 27 THEN
END
END IF

GETLINE

GETLINE <var> FROM <handle>

Type: statement

Reads a line of data from a memory area identified by <handle> into a variable. The memory area can be opened in streaming mode using the the OPEN statement. A line of text is read until the next newline character. Example:

GETLINE txt$ FROM mymemory

See also PUTLINE to store lines of text into memory areas.

GLOBAL

GLOBAL <var>[,var2,var3,...] TYPE <c-type>

Type: statement

Defines a global variable <var> with C type <type>. In most cases BaCon tries to declare variables implicitly, so in most cases there is no need to use this statement. Variables declared with the GLOBAL keyword are visible in each part of the program. See also the LOCAL keyword for local declarations. Example:

GLOBAL x TYPE float

GOTO

GOTO <label>

Type: statement

Jumps to a label defined elsewhere in the program. See also the LABEL statement.

GOTOXY

GOTOXY x, y

Type: statement

Puts cursor to position x,y where 0,0 is the upper left of the terminal screen. An ANSI compliant terminals is required. The arguments must be numbers (so not variables). Example:

GOTOXY 10, 10

HEX$

HEX$(x)

Type: function

Calculates the hexadecimal value of x. Returns a string with the result.

HOUR

HOUR(x)

Type: function

Returns the hour (0-23) where x is the amount of seconds since January 1, 1970.

IF

IF <expression> THEN
    <body>
[ELIF]
    <body>
[ELSE]
    [body]
ENDIF | END IF

Type: statement

Execute <body> if <expression> is true. If <expression> is not true then run the optional ELSE body. Multiple IF's can be written with ELIF. The IF construction should end with ENDIF or END IF. Example:

a = 0
IF a > 10 THEN
PRINT "a is bigger than 10"
ELSE
PRINT "a is smaller than 10"
END IF

IMPORT

IMPORT <function[(type arg1, type arg2, ...)]> FROM <library> TYPE <type>

Type: statement

Import a function from a C library defining the type of returnvalue. Optionally, the type of arguments can be specified. Example:

IMPORT "ioctl" FROM "libc.so" TYPE int
IMPORT "gdk_draw_line(long, long, int, int, int, int)" FROM "libgdk-x11-2.0.so" TYPE void

INCLUDE

INCLUDE <filename>

Type: statement

Adds a external BaCon file to current program. Nested includes are not supported. Example:

INCLUDE "beep.bac"

INPUT

INPUT [text[, ... ,]<variable[$]>

Type: statement

Gets input from the user. If the variable ends with a '$' then the input is considered to be a string. Otherwise it will be treated as numeric. Example:

INPUT a$
PRINT "You entered the following: ", a$

The input statement also can print text. The input variable always must be present at the end of the line. Example:

INPUT "What is your age? ", age
PRINT "You probably were born in ", YEAR(NOW) - age

INSTR

INSTR(haystack$, needle$ [,z])

Type: function

Returns the position where needle$ begins in haystack$, optionally starting at position z. If not found then this function returns the value '0'.

INSTRREV

INSTRREV(haystack$, needle$ [,z])

Type: function

Returns the position where needle$ begins in haystack$, but start searching from the end of haystack$, optionally at position z also counting from the end. If not found then this function returns the value '0'.

ISFALSE

ISFALSE(x)

Type: function

Verifies if x is equal to 0.

ISTRUE

ISTRUE(x)

Type: function

Verifies if x is not equal to 0.

LABEL

LABEL <label>

Type: statement

Defines a label. A label may not contain spaces.

LCASE$

LCASE$(x$)

Type: function

Converts x$ to lowercase characters and returns the result.

LEFT$

LEFT$(x$, y)

Type: function

Returns y characters from the left of x$.

LEN

LEN(x$)

Type: function

Returns the length of x$.

LET

LET <var> = <value> | <expr>

Type: statement

Assigns a value or result from an expression to a variable. The LET stament may be omitted. Example:

LET a = 10

LOCAL

LOCAL <var>[,var2,var3,...] TYPE <c-type>

Type: statement

This statement only has sense within functions, subroutines or records. It defines a local variable <var> with C type <type> which will not be visible for other functions, subroutines or records, nor for the main program. If the TYPE keyword is omitted then variables are assumed to be of 'long' type. If TYPE is omitted and the variablename ends with a '$' then the variable will be a string. Example:

LOCAL x, y TYPE int
LOCAL q$

MAKEDIR

MAKEDIR <directory>

Type: statement

Creates and empty directory. Errors can be retrieved with CATCH. Example:

MKDIR "/tmp/mydir"

MAXRANDOM

MAXRANDOM

Type: variable

Reserved variable which contains the maximum value RND can generate. The actual value may vary on different operating systems.

MEMORY

MEMORY(x)

Type: function

Claims memory of x byte size, returning the address where the memory block resides. Use FREE to release the memory again.

MEMREWIND

MEMREWIND <handle>

Type: statement

Returns to the beginning of a memory area opened with <handle>.

MID$

MID$(x$, y, [z])

Type: function

Returns z characters starting at position y in x$. The parameter 'z' is optional. When omitted, this function returns everything from position 'y' until the end of the string.

MINUTE

MINUTE(x)

Type: function

Returns the minute (0-59) where x is amount of seconds since January 1, 1970.

MOD

MOD(x, y)

Type: function

Returns the modulo of x divided by y.

MONTH

MONTH(x)

Type: function

Returns the month (1-12) in a year, where x is the amount of seconds since January 1, 1970.

MONTH$

MONTH$(x)

Type: function

Returns the month of the year as string in the system's locale ("January", "February", etc), where x is the amount of seconds since January 1, 1970.

NE

x NE y

Type: operator

Checks if x and y are not equal. This is an alias for the C construct '!='.

NL$

NL$

Type: variable

Represents the newline as a string.

NOT

NOT(x)

Type: function

Returns the negation of x.

NOW

NOW

Type: funtion

Returns the amount of seconds since January 1, 1970.

ODD

ODD(x)

Type: Function

Returns 1 if x is odd, else returns 0.

OPEN

Type: statement

When used with READING, WRITING, APPENDING or READWRITE, this statement opens a file assigning a handle to it. The READING keyword opens a file for read-only, the WRITING for writing, APPENDING to append data and READWRITE opens a file both for reading and writing. Example:

OPEN "data.txt" FOR READING AS myfile
WHILE NOT(ENDFILE(myfile)) DO
    READLN txt$ FROM myfile
    IF NOT(ENDFILE(myfile)) THEN
        PRINT txt$
    ENDIF
WEND
CLOSE FILE myfile

When used with DIRECTORY a directory is opened as a stream. Subsequent reads will return the files in the directory. Example:

OPEN "." FOR DIRECTORY AS mydir
REPEAT
GETFILE myfile$ FROM mydir
PRINT "File found: ", myfile$
UNTIL ISFALSE(LEN(myfile$))
CLOSE DIRECTORY mydir

When used with NETWORK a network address is opened as a stream.

OPEN "www.google.com:80" FOR NETWORK AS mynet
SEND "GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n") TO mynet
REPEAT
RECEIVE dat$ FROM mynet
total$ = CONCAT$(total$, dat$)
UNTIL ISFALSE(WAIT(mynet, 500))
PRINT total$
CLOSE NETWORK mynet

When used with SERVER the program starts as a server to accept incoming TCP connections.

OPEN "localhost:51000" FOR SERVER AS myserver
WHILE NOT(EQUAL(LEFT$(dat$, 4), "quit")) DO
RECEIVE dat$ FROM myserver
PRINT "Found: ", dat$
WEND
CLOSE SERVER myserver

When used with MEMORY a memory area can be used in streaming mode.

data = MEMORY(500)
OPEN data FOR MEMORY AS mem
PUTLINE "Hello cruel world" TO mem
MEMREWIND mem
GETLINE txt$ FROM mem
CLOSE MEMORY mem
PRINT txt$

OR

x OR y

Type: operator

Performs a logical or between x and y. For the binary or, use the '|' symbol.

OS$

OS$

Type: function

Function which returns the name and machine of the current Operating System.

PEEK

PEEK(x)

Type: function

Returns a 1-byte value stored at memory address x.

PI

Type: variable

Reserved variable containing the number for PI: 3.14159265.

POKE

POKE <x>, <y>

Type: statement

Stores a 1-byte value <y> at memory addres <x>. Use PEEK to retrieve a value from a memory address. Example:

mem = MEMORY(500)
POKE mem, 32

POW

POW(x, y)

Type: function

Raise x to the power of y.

PRINT

Type: statement

Prints a numeric value, text, variable or result from expression. A semicolon at the end of the line prevents printing a newline. Example:

PRINT "This line does ";
PRINT "end here: ";
PRINT linenr + 2

Multiple arguments maybe used but they must be separated with a comma or a '+'-sign. Examples:

PRINT "This is operating system: ", OS$
PRINT "This is month " + MONTH$(NOW) + " in the year " + STR$(YEAR(NOW))

The FORMAT argument is optional and can be used to specify different types in the PRINT argument. The syntax of FORMAT is similar to the printf argument in C. Example:

PRINT "My age is ", 40, " years which is ", 10 + 30 FORMAT "%s%d%s%d\n"

PULL

PULL x

Type: statement

Get value from the internal stack into variable <x>. The argument must be a variable.

PUSH

PUSH <x>|<expression>

Type: statement

Push a value <x> or expression to the internal stack. See also PULL.

PUTBYTE

PUTBYTE <memory> TO <filehandle> [SIZE x]

Type: statement

Store binary data from a memory area to a file identified by handle with optional size of x bytes (default size = 1 byte). This is the inverse of GETBYTE, refer to this command for an example.

PUTLINE

PUTLINE "text"|<var> TO <handle>

Type: statement

Write a line of data to a memory area identified by handle. The line will be terminated by a newline character. The memory area must be set in streaming mode first using OPEN. Example:

PUTLINE "hello world" TO mymemory

READ

READ <x[$]>

Type: statement

Reads a value from a DATA block into variable <x>. Example:

LOCAL dat[8]
FOR i = 0 TO 7
READ dat[i]
NEXT
DATA 10, 20, 30, 40, 50, 60, 70, 80

READLN

READLN <var> FROM <handle>

Type: statement

Reads a line of data from a file identified by handle into a variable. Example:

READLN txt$ FROM myfile

RECEIVE

RECEIVE <var> FROM <handle>

Type: statement

Reads data from a network location identified by handle into a variable. Subsequent reads return more data until the buffer is empty. Example:

OPEN "www.google.com:80" FOR NETWORK AS mynet
SEND "GET / HTTP/1.1\r\nHost: www.google.com\r\n\r\n" TO mynet
REPEAT
RECEIVE dat$ FROM mynet
total$ = CONCAT$(total$, dat$)
UNTIL ISFALSE(WAIT(mynet, 500))
CLOSE NETWORK mynet

RECORD

RECORD <var>
    LOCAL <member1> TYPE <type>
    LOCAL <member2> TYPE <type>
    ....
END RECORD

Type: statement

Defines a record <var> with members. The members should be defined using the LOCAL statement and can be accessed with the 'var.member' notation. Also refer to WITH for assigning values to multiple members at the same time. Example:

RECORD var
LOCAL x
LOCAL y
END RECORD
var.x = 10
var.y = 20
PRINT var.x + var.y

REGEX

REGEX (txt$, expr$)

Type: function

Applies a POSIX Extended Regular Expression expr$ to the string txt$. If the expression matches, the value '1' is returned. Else this function returns '0'. Examples:

' Does the string match alfanum character
PRINT REGEX("Hello world", "[[:alnum:]]")

' Does the string *not* match a number
PRINT REGEX("Hello world", "[^0-9]")

' Does the string contain an a, l or z
PRINT REGEX("Hello world", "a|l|z")

REM

REM [remark]

Type: statement

Adds a comment to your code. Any type of string may follow the REM statement. Instead of REM also the single quote symbol ' maybe used to insert comments in the code.

RENAME

RENAME <filename> TO <new filename>

Type: statement

Renames a file. If different paths are included the file is moved from one path to the other. Example:

RENAME "tmp.txt" TO "real.txt"

REPEAT

REPEAT
<body>
[BREAK]
UNTIL <expr>

Type: statement

The REPEAT/UNTIL construction repeats a body of statements. The difference with WHILE/WEND is that the body will be executed at least once. The optional BREAK statement can be used to break out the loop. Example:

REPEAT
C = GETKEY
UNTIL C EQ 27

REPLACE$

REPLACE$(haystack$, needle$, replacement$)

Type: function

Substitutes a substring <needle$> in <haystack$> with <replacement$> and returns the result. The replacement does not necessarily need to be of the same size as the substring. Example:

PRINT REPLACE$("Hello world", "l", "p")
PRINT REPLACE$("Some text", "me", "123")

RESIZE

RESIZE <x>, <y>

Type: statement

Resizes memory area starting at address <x> to an amount of <y> bytes.

RESTORE

RESTORE

Type: statement

Restores the internal DATA pointer(s) to the beginning of the first DATA statement.

RESUME

RESUME

Type: function

When an error is catched, this statement tries to continue after the statement where an error occurred. Example:

TRAP LOCAL
CATCH GOTO print_err
DELETE FILE "somefile.txt"
PRINT "Resumed..."
END
LABEL print_err
PRINT ERR$(ERROR)
RESUME

REVERSE$

REVERSE$(x$)

Type: function

Returns the reverse of x$.

REWIND

REWIND <handle>

Type: statement

Returns to the beginning of a file opened with <handle>.

RIGHT$

RIGHT$(x$, y)

Type: function

Returns y characters from the right of x$.

RND

RND(x)

Type: function

Returns a random number between 0 and the reserved variable MAXRANDOM. The generation of random numbers can be seeded with the statement SEED.

ROUND

ROUND(x)

Type: function

Rounds x to the nearest integer number. For compatibility reasons, also the keyword INT may be used instead.

SEARCH

SEARCH(handle, string)

Type: function

Searches for a <string> in file opened with <handle>. Returns the offset in the file where the first occurrence of <string> is located. Use SEEK to effectively put the filepointer at this position. If the string is not found, then the value '-1' is returned.

SECOND

SECOND(x)

Type: function

Returns the second (0-59) where x is the amount of seconds since January 1, 1970.

SEED

SEED x

Type: statement

Seeds the random number generator with some value. Example:

SEED NOW

SEEK

SEEK <handle> OFFSET <offset> [WHENCE START|CURRENT|END]

Type: statement

Puts the filepointer to new position at <offset>, optionally starting from <whence>.

SEND

SEND <var> TO <handle>

Type: statement

Sends data to a network location identified by handle. For an example, see the RECEIVE statement.

SIN

SIN(x)

Type: function

Returns the calculated SINUS of x

SLEEP

SLEEP <x>

Type: statement

Sleeps <x> milliseconds (sleep 1000 is 1 second).

SPC$

SPC$(x)

Type: function

Returns an x amount of spaces.

SPLIT

SPLIT <string> BY <sub> TO <array> SIZE <variable>

Type: statement

This statement can split a string into smaller pieces. The <sub> argument determines where the string is splitted. The results are stored in <array>, which may not be declared before. The total amount of elements created in this array is stored in <variable>. Example:

SPLIT "one two three" BY " " TO array$ SIZE dimension
FOR i = 0 TO dimension-1
PRINT array$[i]
NEXT

SQR

SQR(x)

Type: function

Calculates the square root from a number.

STR$

STR$(x)

Type: function

Convert numeric value x to a string (opposite of VAL). Example:

PRINT STR$(123)

SUB

SUB <name>[(STRING s, NUMBER i, FLOATING f)]
<body>
ENDSUB | END SUB

Type: statement

Defines a subprocedure. A subprocedure never returns a value (use FUNCTION instead).

Variables used in a sub are visible globally, unless declared with LOCAL. The incoming arguments are always local. Instead of the BaCon types STRING, NUMBER and FLOATING for the incoming arguments, also regular C-types also can be used. Example:

SUB add(NUMBER x, NUMBER y)
    LOCAL result
    PRINT "The sum of x and y is: ";
    result = x + y
    PRINT result
END SUB

SYSTEM

SYSTEM <command$>

Type: statement

Executes an operating system command. Example:

SYSTEM "ls -l"

TAB$

TAB$(x)

Type: function

Returns an x amount of tabs.

TAN

TAN(x)

Type: function

Returns the calculated tangens of x.

TELL

TELL(handle)

Type: function

Returns current position in file opened with <handle>.

TIMEVALUE

TIMEVALUE(a,b,c,d,e,f)

Type: function

Returns the amount of seconds since January 1 1970, from year (a), month (b), day (c), hour (d), minute (e), and seconds (f).

TRAP

TRAP <LOCAL|SYSTEM>

Type: statement

Sets the runtime error trapping. By default, trapping is performed by the operating system. This means that if an error occurs, a signal will be catched by the program and a generic error message is displayed on the prompt. The program will then exit gracefully. If trapping is put to LOCAL, BaCon tries to examine statements and functions where possible, and will display an error message based on the operating system internals, indicating which statement or function causes a problem. Optionally, when a CATCH is set, BaCon can jump to a LABEL instead, where a self-defined error function can be executed, and from where a RESUME is possible. Note that the CATCH statement does not work with functions.

The setting LOCAL decreases the performance of the program, because additional runtime checks are carried out when the program is executed.

TRUE

TRUE

Type: variable

Represents and returns the value of '1'.

UCASE$

UCASE$(x$)

Type: function

Converts x$ to uppercase characters and returns the result.

USEC

USEC
<body>
ENDUSEC | END USEC

Type: statement

Defines a body with C code. This code is passed unmodified to the C compiler. Example:

USEC
    char *str;
    str = strdup("Hello");
    printf("%s\n", str);
END USEC

VAL

VAL(x$)

Type: function

Returns the actual value of x$. This is the opposite of STR$. Example:

nr$ = "456"
q = VAL(nr$)

VERSION

VERSION

Type: variable

Reserved variable which contains the BaCon version number.

WAIT

WAIT(handle, milliseconds)

Type: function

Suspends the program for a maximum of <milliseconds> until data becomes available on <handle>.

This is especially useful in network programs where a RECEIVE will block if there is no data available. The WAIT function checks the handle and if there is data in the queue, it returns with value '1'. If there is no data then it waits for at most <milliseconds> before it returns. If there is no data available, WAIT returns '0'. Refer to the RECEIVE statement for an example.

WEEK

WEEK(x)

Type: function

Returns the week number (1-53) in a year, where x is the amount of seconds since January 1, 1970. Example:

PRINT WEEK(NOW)

WEEKDAY$

WEEKDAY$(x)

Type: function

Returns the day of the week as a string in the system's locale ("Monday", "Tuesday", etc), where x is the amount of seconds since January 1, 1970.

WHILE

WHILE <expr> DO
<body>
[BREAK]
WEND

Type: statement

The WHILE/WEND is used to repeat a body of statements and functions. The optional BREAK statement can be used to break out the loop. Example:

LET a = 5
WHILE a > 0 DO
PRINT a
a = a – 1
WEND

WITH

WITH <var>
    .<var> = <value>
    .<var> = <value>
    ....
END WITH

Type: statement

Assign values to individual members of a RECORD. For example:

WITH myrecord
    .name$ = "Peter"
    .age = 40
    .street = Westlands 1
    .city = The Hague
END WITH

WRITELN

WRITELN "text"|<var> TO <handle>

Type: statement

Write a line of data to a file identified by handle. Example:

WRITELN "hello world" TO myfile

YEAR

YEAR(x)

Type: function

Returns the year where x is amount of seconds since January 1, 1970. Example:

PRINT YEAR(NOW)

Runtime error codes

Code	Meaning
0	Success
1	Trying to access illegal memory
2	Error opening file
3	Could not open library
4	Symbol not found in library
5	Wrong hexvalue
6	Unable to claim memory
7	Unable to delete file
8	Could not open directory
9	Unable to rename file
10	NETWORK argument should contain colon with port number
11	Could not resolve hostname
12	Socket error
13	Unable to open address
14	Error reading from socket
15	Error sending to socket
16	Error checking socket
17	Unable to bind the specified socket address
18	Unable to listen to socket address
19	Cannot accept incoming connection
20	Unable to remove directory
21	Unable to create directory
22	Unable to change to directory
23	GETENVIRON argument does not exist as environment variable
24	Unable to stat file
25	Search contains illegal string
26	Cannot return OS name
27	Illegal regex expression

Created with OpenOffice 3.1.1.