libbbb - rexscript commands

Home

Following list describes the commands that RexScript provides. Specific implementation may extend this set with custom commands.

Create Temporary File
Creates a temporary file
^\s*BEGIN\s+TEMP\s+(.+)\s*$
Syntax:
BEGIN TEMP name some text some other text END
Arguments:
name
the name of the file that will be created
The content between the markers is written to file exactly as it is.
Create Temporary Directories
Creates a list of temporary directories
^\s*BEGIN\s+DIRS\s*$
Syntax:
BEGIN DIRS some dir name some dir name/some other dir name END
Each line between markers is interpreted to be a directory name.
Set variable
Changes the value of a variable
^\s*SET\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
SET VarName Value SET VarName ${Value} SET ${VarHoldingVarName} text value
Arguments:
first
name of the variable to set/create may contain digits, letters, underscore and minus signs
second
value to assign
The name of the variable needs to be provided without the ${} markers, unless the name is stored in a variable, like in third example. There, we assume that ${VarHoldingVarName} contains a proper variable name, like VarName.
To asign the value of a variable to another use second form.
Set variable with block
Changes the value of a variable
^\s*SETB\s+([a-zA-Z0-9_-\:]+)\s*$
Syntax:
SETB VarName value at index 0 value at index 1 value at index 2 END
Arguments:
VarName
name of the variable to set/create may contain digits, letters, underscore and minus signs
The name of the variable needs to be provided without the ${} markers, unless the name is stored in a variable.
Each line in the input block will become one entry in the array containing variable's values.
Split text
Splits the text and assigns the result to a variable
^\s*SETX\s+([a-zA-Z0-9_-\:]+)\[(.+)\]\s+(.*)\s*$
Syntax:
SPLIT VarName $_REGEXPATTERN_$ text to split SPLIT VarName $_REGEXPATTERN_$ ${var_name}
Arguments:
VarName
name of the variable to set/create
REGEXPATTERN
a regular expression pattern describing the separator; $_ and _$ are markers (not part of the pattern).
text to split
anything after the _$ marker and the white spaces following it is the text to split
To escape _$ or $_ use regular expression convention (\$, \_).
Append to variable
Appends the value to a variable
^\s*APPEND\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
APPEND VarName Value APPEND VarName ${Value} APPEND ${VarHoldingVarName} text value
Arguments:
first
name of the variable to set/create may contain digits, letters, underscore and minus signs
second
value to append
The name of the variable needs to be provided without the ${} markers, unless the name is stored in a variable, like in third example. There, we assume that ${VarHoldingVarName} contains a proper variable name, like VarName.
To append the value of a variable to another use second form.
Read file
Reads the content of a file into a variable
^\s*READF\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
READF VarName path to file
Arguments:
VarName
name of the variable that recieves the file
path
path to the file to read; if relative, .it is computed with regards to the script file path
The function attempts to read the file and throws an error if it fails. It creates one entry in the array for each line in the file.
Write file
Writes content to a file
^\s*WRITEF\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
WRITEF VarName path to file
Arguments:
VarName
name of the variable to dump to file
path
path to the destination file; if relative, .it is computed with regards to the script file path
The function attempts to write the file and throws an error if it fails. It creates one line in file for each array entry.
If the file already exists old content is lost (no backup file is created).
Append to file
Appends content to a file
^\s*APPENDF\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
APPENDF VarName path to file
Arguments:
VarName
name of the variable to dump to file
path
path to the destination file; if relative, .it is computed with regards to the script file path
The function attempts to write the file and throws an error if it fails. It creates one line in file for each array entry.
New content is placed after old content. If the file does not exists, it is created.
Include
Includes another document
^\s*INCLUDE\s+(.+)\s*$
Syntax:
INCLUDE path and name of the file
Arguments:
path
should not be quoted; leading and trailing spaces are trimmed
The content of the other document is executed line by line, then the execution returns to next line following the one with INCLUDE directive.
The file to be included is searched relative to the directory of the file containing the directive
Compute
Interpret expression and assign result to variable
^\s*COMPUTE\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
COMPUTE VarName expression + other
Arguments:
VarName
name of the variable that will hold the result
Following opperations are defined:
- addition using +
- substraction using -
- multiplication using *
- integer division using \
- modulus with %
- real (floating point) division using /
- raising to a power with ^
- all kinds of parantesis: ()[]{}- logical equality using =
- logical and via &&, or via ||, not via !
For logic expressions zero is false and anything else is true. Strings that can't be converted to a number or logic symbol will generate an error
if then else
Conditional execution
^\s*IF\s+(.+)\s*$
Syntax:
if expression ... else if expression ... else ... end if
Arguments:
expression
mathematical expression
Conditional expressions may be nested. The condition is evaluated just as COMPUTE would do.
For each in list
Executes the block once for each item in list
^\s*FOR\s+([a-zA-Z0-9_-\:]+)\s+IN\s+([a-zA-Z0-9_-\:]+)\s*$
Syntax:
for VarIter in VarSrc ... continue ... break ... end for
Arguments:
VarSrc
Source variable; each element of its internal array is iterated; note that no ${} markers sould be used.
VarIter
Iterator variable; new value gets assigned to this variable; note that no ${} markers sould be used.
For a to b
Clasic for loop
^\s*FOR\s+([a-zA-Z0-9_-\:]+)\s*=\s*([^\s]+)\s+TO\s+([^\s]+)(?:(?:\s+STEP\s+([^\s]+))*)\s*$
Syntax:
for VarIter = Start to End step n ... continue ... break ... end for
Arguments:
VarIter
Iterator variable; new value gets assigned to this variable; note that no ${} markers sould be used.
Conditional expressions may be nested. The condition is evaluated just as COMPUTE would do.
While
Executes a loop while condition is true
^\s*WHILE\s+(.+)\s*$
Syntax:
while condition ... continue ... break ... end while
Arguments:
condition
mathematical expression that is evaluated just as COMPUTE would evaluate it.
To allow for expressions containing variables. this block is a little different in that the expression is evaluated again aon each loop, thus allowing changes in the inner loop to affect the expression. Usually (in for or if statements, for example) the variables are expanded then the line is interpreted.
Del
Delete a variable
^\s*DEL\s+([a-zA-Z0-9_-\:]+)\s*$
Syntax:
DEL VarName
Arguments:
VarName
name of the variable to remove
The variable is completly removed; any reference to it will trigger an error or generate empty content, depending on circumstances
GetEnv
Get the value of an environment variable
^\s*GETENV\s+([a-zA-Z0-9_-\:]+)\s+([a-zA-Z0-9_-\:]+)\s*$
Syntax:
GETENV VarName EnvVarName
Arguments:
VarName
name of the variable that recieves the value
EnvVarName
name of system variable to querry
Scaffold already reads all system variables at the beginning of the program and creates one variable for each. If that is not convenient for some reason then this function may be used to get a fresh value.
First argument recieves the value and second argument is the name of the environment variable. Note that, unlike the environment variables that are retrived at the beginning of the program the value is not splitted; VarName will have a single array entry with exact value.
Frequency
Changes the frequency of the internal clock
^\s*FREQUENCY\s+([0-9]+)\s*$
Syntax:
FREQUENCY miliseconds
Arguments:
miliseconds
an integer larger than 0
The program does not executs statements in a file one after the other in a loop; instead, it executes a line every few number of miliseconds.
SetEnv
Set the value of an environment variable
^\s*SETENV\s+([a-zA-Z0-9_-\:]+)\s+(.+)\s*$
Syntax:
SETENV EnvVarName Value
Arguments:
EnvVarName
name of the environment variable to use
Value
the string to set
Scaffold already reads all system variables at the beginning of the program and creates one variable for each. However, changing those variables will have no effect on the coresponding environment variables. To set an environment variable (to be seen in a child process, for example) one needs to use this method. For example, if one has updated PATH variable it should use SETENV PATH ${PATH.join(:)} to make that change visible to child processes.
Verbosity control
Changes the verbosity
^\s*LOG\s+(.+)\s+((ON)|(OFF))\s*$
Syntax:
LOG name LOG name ON LOG name OFF
Arguments:
name
one of the valid log targets (see below)
This statements allows control over the types of messages that are being presented to the user. The types are:
- DEBUG (only available for debug builds)
- COMMANDS - what commands are being executed
- FILES - opperations involving script files
Custom implementation may provide their own switches for logging.
Log multi-line text
Changes the verbosity
^\s*BEGIN\s+LOG\s*$
Syntax:
BEGIN LOG name ON name OFF END
Arguments:
name
one of the valid log targets (see below)
This statements allows control over the types of messages that are being presented to the user. The types are:
- DEBUG (only available for debug builds)
- COMMANDS - what commands are being executed
- FILES - opperations involving script files
Custom implementation may provide their own switches for logging.
Wait
Stops execution for specified number of miliseconds
^\s*WAIT\s+([0-9]+)\s*$
Syntax:
WAIT miliseconds
Arguments:
miliseconds
an integer larger than 0
During the wait events are processed.
Echo
Output single line text
^\s*ECHO\s+(.+)\s*$
Syntax:
ECHO text
Arguments:
text
the content to output
Leading and trailing spaces are removed, then the text is presented to the user through standard output.
Use BEGIN ECHO if these limitations do not suit you.
Echo multi-line text
Output multi-line text
^\s*BEGIN\s+ECHO\s*$
Syntax:
BEGIN ECHO some text some other text END
The content between the markers is send to standard output exactly as it is.


Depedencies:

Home