This section explains the syntax and usage of some special shell commands.

Built-in commands

This section explains the built-in commands.

Command echo

The echo command writes its parameters to stdout exactly as provided. If the -n option is used as the first parameter, no newline is printed at the end of the output.

Examples:

Command	Output
`echo "Hello World!"`	`Hello World!\n`
`echo -n "Hello World!"`	`Hello World!`

Command getenv

The getenv command retrieves the value of an environment variable. If the variable does not exist, it returns an empty string "".

Requires one argument: a valid environment variable name (like those in Bash).

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_GETENV_PARAM_NUMBER`	Wrong number of parameters provided
`bs::shell_status::SHELL_CMD_ERROR_GETENV_VARIABLE_NAME_INVALID`	Provided variable name is invalid

Example: getenv USER

Command setenv

The setenv command sets the value of an environment variable or creates it if it does not exist. Requires two arguments: a valid environment variable name (like those in Bash) and a value.

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_SETENV_PARAM_NUMBER`	Wrong number of parameters provided
`bs::shell_status::SHELL_CMD_ERROR_SETENV_VARIABLE_NAME_INVALID`	Provided variable name is invalid

Example:

setenv SHELL "BashSpark"

Command getvar

The getvar command retrieves the value of a local variable. If the variable does not exist, it returns an empty string "".

Requires one argument: a valid variable name (like those in Bash).

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_GETVAR_PARAM_NUMBER`	Wrong number of parameters provided
`bs::shell_status::SHELL_CMD_ERROR_GETVAR_VARIABLE_NAME_INVALID`	Provided variable name is invalid

Example:

getvar variable

Command setvar

The setvar command sets the value of a local variable or creates it if it does not exist. Requires two arguments: a valid variable name (like those in Bash) and a value.

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_SETVAR_PARAM_NUMBER`	Wrong number of parameters provided
`bs::shell_status::SHELL_CMD_ERROR_SETVAR_VARIABLE_NAME_INVALID`	Provided variable name is invalid

Example: setvar variable "value"

Command seq

The seq command creates a sequence of integers. The sequence can be growing or shrinking.

Takes 3 integer parameters: start, step, end.

The step parameter is optional and defaults to 1 or -1 depending on the sequence direction.
The sequence must extend over a closed set of values (logic error if violated).
Integer parameters are limited to 18 digits (64-bit signed integers).

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_SEQ_PARAM_NUMBER`	Wrong number of parameters
`bs::shell_status::SHELL_CMD_ERROR_SEQ_INVALID_INT_FORMAT`	Parameter is not a valid integer
`bs::shell_status::SHELL_CMD_ERROR_SEQ_INT_OUT_OF_BOUNDS`	Parameter exceeds 64-bit integer limits
`bs::shell_status::SHELL_CMD_ERROR_SEQ_ITERATION_LOGIC`	Step and range do not allow a valid sequence

Examples:

Command	Output
`seq 1 5`	`1 2 3 4 5`
`seq 1 2 5`	`1 3 5`
`seq 5 -2 1`	`5 3 1`
`seq 5 1`	`5 4 3 2 1`
`echo -n $(seq 1 5)`	`1 2 3 4 5`

Command math

The math command performs simple integer arithmetic. It takes mathematical expressions as parameters, broken down into independent tokens.

Supports:

Operators: +, -, *, /, ^, **, ×, ÷
Integer numbers within the range of 64-bit signed integers
Parentheses: ( ) (including nested parentheses)
Negative powers partially: { x != 0 } ^ { y < 0 } = 0
Functions:
- factorial(x)
- sum(variable; start; end; step; expression) — sums expression over the sequence of variable, e.g., count = sum(x;1;1;100;1)
- product(variable; start; end; step; expression) — multiplies expression over the sequence of variable, e.g., factorial = product(x;1;1;100;x)
- Note: a variable inside sum/product hides the same variable from the outside scope
- Variable names must be valid shell variable names

Possible errors:

Error Code	Meaning
`bs::shell_status::SHELL_CMD_ERROR_MATH_NOT_AN_INTEGER`	Value is not an integer
`bs::shell_status::SHELL_CMD_ERROR_MATH_OVERFLOW`	Integer overflow
`bs::shell_status::SHELL_CMD_ERROR_MATH_UNDERFLOW`	Integer underflow
`bs::shell_status::SHELL_CMD_ERROR_MATH_DIV_BY_ZERO`	Division by zero
`bs::shell_status::SHELL_CMD_ERROR_MATH_POW_0_EXP_0`	0^0 power is undefined
`bs::shell_status::SHELL_CMD_ERROR_MATH_FACTORIAL_NEGATIVE`	Factorial of negative number
`bs::shell_status::SHELL_CMD_ERROR_MATH_MALFORMED_EXPRESSION`	Expression is malformed
`bs::shell_status::SHELL_CMD_ERROR_MATH_MAX_DEPTH_REACHED`	Maximum recursion depth reached (512)
`bs::shell_status::SHELL_CMD_ERROR_MATH_INVALID_VARIABLE_NAME`	Invalid variable name in function
`bs::shell_status::SHELL_CMD_ERROR_MATH_SEQ_ITERATION_LOGIC`	Sequence logic error in sequence function

Examples:

Command	Output
`math + 1`	`1`
`math - 1`	`-1`
`math +1`	`1`
`math -1`	`-1`
`math 3 + 4`	`7`
`math 3 * 4`	`12`
`math 12 / 4`	`3`
`math 12 % 5`	`2`
`math 2 ^ 3`	`8`
`math 2 ** 3`	`8`
`math 2 ** - 3`	`0`
`math 2 + 2 * 2 + 2 ^ 2 + 2 * 2 + 2`	`16`
`math 42 ^ 0 + 1 ^ 42 + 0 ^ 42`	`2`
`math $ 2 + 2 $ * $ 2 + 2 $ ^ $ 2 + 2 $ * $ 2 + 2 $`	`4096`
`math $(echo "( 2 + 2 ) * ( 2 + 2 ) ^ ( 2 + 2 ) * ( 2 + 2 )")`	`4096`
`math $ \( 2 + 2 $ * $ 2 + 2 $ \) ^ $ \( 1 + 2 $ * $ 1 + 2 $ \)`	`68719476736`
`math factorial $ 5 $`	`120`
`math product $ x , 1 , 1 , 5 , x $`	`120`
`math sum $ x , 1 , 1 , 5 , x $`	`15`
`echo $( math sign $ - 42 $ ) $( math sign $ 0 $ ) $( math sign $ + 42 $ )`	`-1 0 1`
`math abs $ - 42 $`	`42`
`math abs $ + 42 $`	`42`
`setvar i $(math i + 1)`	``

Command test

The test command performs simple tests. It takes test expressions as parameters, broken down into independent tokens.

Capabilities:

Operators or: -o, ||
Operators and: -a, &&
Comparison operators: ==, -eq, >, -gt, <, -lt, >=, -ge, <=, -le Note that comparison operators will apply numeric comparison if both arguments are numbers or <=> on std::string if they aren't.
Operator =~: use a =~ b, checks if a matches b. Uses C++ regex, not bash regex.
Parentheses: ( ) (and nested parentheses).

Possible status codes outputs:

Status	Description
`bs::shell_status::SHELL_SUCCESS`	Test passed
`bs::shell_status::SHELL_CMD_TEST_FALSE`	Test failed
`bs::shell_status::SHELL_CMD_ERROR_TEST_UNCLOSED_PARENTHESIS`	Opened parenthesis not closed
`bs::shell_status::SHELL_CMD_ERROR_TEST_MALFORMED_EXPRESSION`	Malformed expression
`bs::shell_status::SHELL_CMD_ERROR_TEST_MALFORMED_REGEX`	Malformed regex

Examples:

Command	Meaning	Result
`test -z ""`	Is the string empty?	true
`test -n "d"`	Is the string non-empty?	true
`test 7 -eq 0007`	Numeric equality (leading zeros allowed)	true
`test 7 != 42`	Numeric inequality	true
`test abc != 42`	String inequality	true
`test 7 -gt 6`	Numeric greater-than	true
`test b > a`	Lexicographic greater-than	true
`test 6 -le 7`	Numeric ≤ comparison	true
`test 'hello' =~ '^h.*o$'`	Regex match	true
`test 'abc' =~ '^[0-9]+$'`	Regex check: digits only?	false
`test 'test@example.com' =~ '^[^@]+@[^@]+\\\\.[^@]+$'`	Email-like pattern	true

Command fcall

The fcall command calls functions. The first parameter is the function name. The other parameters are the function parameters.

Example:

function echon {
    echo -n $@
}
 
fcall echon Hello World!

Output: Hello World!

Script examples

This section displays some simple example scripts. Allows to better grasp the shell syntax.

Hello world

echo -n 'Hello, World!'"

Output: Hello, World!\n

While loop

setvar count 1
while [ $count <= 5 ];
do
    echo \"Count: $count\"; setvar count $(math $count + 1);
done

Output:

Count: 1
Count: 2
Count: 3
Count: 4
Count: 5

Until loop

setvar count 1
until [ $count > 5 ];
do
    echo \"Count: $count\"; setvar count $(math $count + 1);
done

Output:

Count: 1
Count: 2
Count: 3
Count: 4
Count: 5

Loop for

for i in $(seq 1 5);
do
    echo -n $i;
done

Output: 12345

Function

function greet {
    echo \"Ave $1\"
}
 
fcall greet Cesar

Output: Ave Cesar\n

Count function arguments

function count_args {
    echo -n $#
}
 
fcall count_args $(seq 1 5)

Output: 5

Function with if-else block

function oddeven {
    if [ $(math $1 % 2) == 0 ];
    then
        echo \"$1 is even\"
    else
        echo \"$1 is odd\"
    fi
}
 
fcall oddeven

Output:

42 is even

11 is odd

Function that displays it's arguments

function show_args {
    if [ $# > 1 ];
    then
        for i in $(seq 1 $#);
        do
            echo \"arg $i: \\u201C${!i}\\u201D\";
        done
    else
        echo 'No arguments';
    fi
}
 
fcall show_args
fcall show_args $(seq 1 5)

Output:

No arguments
arg 1: “1”
arg 2: “2”
arg 3: “3”
arg 4: “4”
arg 5: “5”