25 KiB
Table of Contents
- sdk::Alias (alias)
- sdk::Array (array)
- sdk::Echo (echo)
- sdk::Eval (eval)
- sdk::ForIn (for)
- sdk::Function (function, fn)
- sdk::GoTo (goto)
- sdk::If (if)
- sdk::Not (not)
- sdk::Release (release)
- sdk::Set (set)
- sdk::ShowCommandDocumentation (man)
- sdk::Unalias (unalias)
- sdk::env::GetVar (get_env)
- sdk::env::PrintCurrentDirectory (pwd)
- sdk::env::SetCurrentDirectory (cd, set_current_dir)
- sdk::env::SetVar (set_env)
- sdk::env::UnsetVar (unset_env)
- sdk::fs::CopyPath (cp)
- sdk::fs::CreateDirectory (mkdir)
- sdk::fs::CreateEmptyFile (touch)
- sdk::fs::DeleteEmptyDirectory (rmdir)
- sdk::fs::DeletePath (rm)
- sdk::fs::GetCanonicalPath (canonicalize)
- sdk::fs::GetFileName (basename)
- sdk::fs::GetParentDirectory (dirname)
- sdk::fs::MovePath (mv)
- sdk::fs::Print (cat)
- sdk::fs::Read (readfile)
- sdk::fs::Write (writefile)
- sdk::math::Calc (calc)
- sdk::process::Execute (exec)
- sdk::process::Exit (exit)
- sdk::test::Assert (assert)
- sdk::test::AssertEquals (assert_eq)
- sdk::test::AssertFail (assert_fail)
- sdk:🧵:Sleep (sleep)
sdk::Alias
var = alias command arguments
This command enables to define new commands with default arguments.
The new alias can be invoked with additional arguments that will be appended to the default set.
Parameters
Any number of arguments which will be added to the already defined arguments set during the aliasing.
Return Value
true if the alias was created, else false.
Examples
# This example creates a new **my_echo** alias that will print the prefix before the requested arguments.
created = alias my_echo echo [ECHO]
# This will print "[ECHO] hello world "
created = my_echo hello world
Aliases:
alias
sdk::Array
handle = array value1 value2 value3 ...
Creates an array from the input arguments and returns a handle to that array.
This handle can be passed to other commands which support arrays using handles.
Once the array is no longer used, it should be released using the release command.
Parameters
Any number of arguments which will construct the array.
Return Value
A handle to the array.
Examples
handle = array ${var} "hello world" 5 ${another_var}
# once done we should release the handle
release ${handle}
Aliases:
array
sdk::Echo
echo [arg]*
The echo command will printout all provided arguments.
After all input is done, an end of line will be printed as well.
Parameters
Any number of arguments may be provided and will be printed.
Return Value
The amount of arguments printed.
Examples
# Print multiple arguments:
echo hello world
# Print multiple spaces between words
echo "hello world"
Aliases:
echo
sdk::Eval
eval command arguments
The eval command enables to run dynamically created commands.
The command and arguments passed can be variables in the form of ${name}.
Parameters
Any number of arguments which will construct a line to evaluate and execute.
Return Value
The result of the evaluated line.
Examples
command = set echo
eval ${command} hello world
Aliases:
eval
sdk::ForIn
args = array a b c
for arg in args
# commands
end_for
release args
The for/in command enables to iterate over an array (see array command).
The first argument will contain the current iteration value from the array.
Once all values have been read, it will exit the loop.
Parameters
- for
- The variable name which will hold the current iteration value
- The string "in"
- The handle to the array of values to iterate
- end_for - no parameters
Return Value
None
Examples
# Simple example iteration over the list of letters:
args = array a b c
for arg in args
echo current arg is: ${arg}
end_for
release args
# Example nested loops:
range = array 1 2 3
for i in range
for j in range
echo i: ${i} j: ${j}
end_for
end_for
Aliases:
for
sdk::Function
function my_function
# function content
return output
end_function
This command provides the function language feature as a set of commands:
- function - Defines a function start block
- end_function - Defines the end of the function block
- return - Allows to exist a function at any point and return an output
- function name - Dynamically created commands based on the function name which are used to invoke the function code.
When a function command is detected, it will search for the end_function command that comes after.
That entire block is considered the function code block (functions cannot be nested in outer functions)
In order to invoke the function, simply call the function name with any amount of paramters.
Those parameters will be set as $1, $2, ... and so on.
Since variables are global, it will overwrite any older values stored in those variables.
To exist a function and return a value, simply use the return command with the value you want to return.
The variable that was used when the function was originally called, will now store that value.
The return command can be used to exist early without any value.
In case the code reached the end_function call, the function will exist but will return not value.
Parameters
- function - The function name used later on to invoke the function
- end_function - no parameters
- return - optional single paramter to return as an output of the function call
- function name - Any number of arguments which will automatically be set as global variables: $1, $2, ... as so on.
Return Value
The function invocation returns the output provided by the return command.
Examples
# Simple example of a function definition which echo 'hello world' and exists.
# function start
function hello_world
echo hello world
end_function
# function invocation
hello_world
# Example of calling a function and returning a value
function get_hello_world
return "hello world"
end_function
# function invocation
text = get_hello_world
# this will print "hello world"
echo ${text}
# Example of passing arguments
function print_input
# $1 is set with the value 'hello'
# $2 is set with the value 'world'
echo ${1} ${2}
end_function
print_input hello world
# Functions can call other functions
function get_one
return 1
end_function
function get_number
number = get_one
return ${number}
end_function
output = get_number
# this will print 1
echo ${output}
Aliases:
function, fn
sdk::GoTo
goto :label
The goto command enables you to jump to any position in the script, if that position has a label value.
Parameters
A single valid label value.
Return Value
None
Examples
goto :good
echo bad
:good echo good
Aliases:
goto
sdk::If
if command|value
# commands
elseif command|value
# commands
else
# commands
end_if
This command provides the if/elseif/else condition language feature as a set of commands:
- if - Defines an if condition
- elseif - Defines optional secondary condition blocks
- else - Optinoal fallback block
- end_if - Defines the end of the entire if/else block
if and elseif commands accept either:
- A command with optional arguments and invokes it
- A single value which doesn't match any known command
If the value or the result of the command is one of the following:
- No output
- false (case insensitive)
- 0
- no (case insensitive)
- Empty value
It is considered falsy.
In case of falsy value, it will skip to the next elseif/else block.
If a truthy (non falsy) output is found, it will invoke the commands of that code block and ignore all other elseif/else blocks.
if blocks can be nested in other if blocks (see examples).
Parameters
- if/elseif - A command and its arguments to invoke and evaluate its output, if a single value is provided an no such command exists, it is evaluated as a value.
- else/end_if - no parameters
Return Value
None
Examples
# Simple example of an if statement that evaluates the argument value as true and echos "in if"
if true
echo in if
end_if
# Example of using **not** command to reverse the output value
if not false
echo in if
end_if
# Example of an if statement that evaluates the command as true and echos "in if"
if set true
echo in if
end_if
# Example of if condition returning a falsy result and navigation goes to the else block which echos "in else"
if set false
echo should not be here
else
echo in else
end_if
# Example of if condition returning a falsy result and navigation goes to the elseif block has a truthy condition
if set false
echo should not be here
elseif set true
echo in else if
else
echo should not be here
end_if
# Nested if example:
if set false
echo should not be here
elseif set true
echo in else if but not done yet
if set true
echo nested if
end_if
else
echo should not be here
end_if
Aliases:
if
sdk::Not
output = not command|value
Enables to switch falsy to true and truthy to false.
The not commands accept either:
- A command with optional arguments and invokes it
- A single value which doesn't match any known command
If the value or the result of the command is one of the following:
- No output
- false (case insensitive)
- 0
- no (case insensitive)
- Empty value
It will return true, otherwise it will return false.
Parameters
A command and its arguments to invoke and evaluate its output, if a single value is provided an no such command exists, it is evaluated as a value.
Return Value
The switched value of the input.
Examples
# Simple example of converting true/false values
is_false = not true
echo is false: ${is_false}
is_true = not false
echo is true: ${is_true}
# Example of converting command output value
is_false = not set true
echo is false: ${is_false}
is_true = not set false
echo is true: ${is_true}
Aliases:
not
sdk::Release
release handle
Releases an internal handle stored in the runtime memory.
Certain commands (such as array) will create a handle and the variable will only hold a reference to that handle.
In order to release those handles once they are no longer needed, the release command should be used.
Parameters
The handle name.
Return Value
- true - If a handle was found and removed
- false - If no handle was found
Examples
release ${array_handle}
Aliases:
release
sdk::Set
var = set arg
The set command will simply return the provided argument and set it to the output variable.
Parameters
Only the first argument will be returned.
Return Value
The first command argument.
Examples
# Return simple 'hello' text value
var = set hello
# Return expanded value: 'home: ....'
var = set "home: ${HOME}"
Aliases:
set
sdk::ShowCommandDocumentation
var = man command
Prints and returns the help documentation of the provided command.
Parameters
The command name.
Return Value
The help documentation or if not found, none.
Examples
man set
Aliases:
man
sdk::Unalias
unalias name
Removes previously defined alias and return true/false based if an alias was actually removed.
Parameters
The alias name to remove.
Return Value
A true/false value in case an alias with the provided name existed.
Examples
alias my_echo echo [ECHO]
# This will print "[ECHO] hello world "
my_echo hello world
unalias my_echo
# This will error
echo The script will now error as my_echo is no longer defined
my_echo hello world
Aliases:
unalias
sdk::env::GetVar
var = get_env key
Returns the environment variable value for the provided key.
Parameters
First argument is the environment variable key.
Return Value
The environment variable value.
Examples
home = get_env HOME
Aliases:
get_env
sdk::env::PrintCurrentDirectory
var = pwd
Prints and also returns the current directory.
Parameters
None
Return Value
The current directory path.
Examples
# Print the current directory:
pwd
# Print and also store the current directory:
directory = pwd
Aliases:
pwd
sdk::env::SetCurrentDirectory
cd path
Sets the current directory based on the input path.
If no path is provided, it will default to the user home directory.
If the path does not exist, it will return none.
Parameters
The new current directory.
Return Value
The new current directory or none in case of any error such as target directory not found.
Examples
# Move to user home directory and store the path in the home variable
home = cd
# Move to the requested directory
cd ./scripts
Aliases:
cd, set_current_dir
sdk::env::SetVar
set_env key value
Sets the environment variable defined by the provided key to the provided value.
Parameters
Two arguments are required:
- key - The name of the environment variable to set
- value - The new environment variable value
Return Value
None
Examples
set_env HOME /usr/me
Aliases:
set_env
sdk::env::UnsetVar
unset_env key
Removes the environment variable defined by the provided key.
Parameters
The name of the environment variable to remove
Return Value
None
Examples
unset_env HOME
Aliases:
unset_env
sdk::fs::CopyPath
var = cp source target
This command copies the requested file or directory to the target location.
If the source directory is not empty, its entire contents will be copied as well.
Parameters
- The source path to copy
- The target path
Return Value
true if the path was copied.
Examples
# copy a single file
copied = cp ./file1.txt ./file2.txt
# copy a directory
copied = cp ./source ./target
Aliases:
cp
sdk::fs::CreateDirectory
var = mkdir directory
This command will create the requested directory (and needed parent directories) and return true/false if it was successful.
Parameters
The directory name to create.
Return Value
The operation success value - true if directory exists, else false.
Examples
exists = mkdir ./dir/subdir
Aliases:
mkdir
sdk::fs::CreateEmptyFile
var = touch file
This command will create an empty file and return true/false if the file exists.
If file exits, it will not be modified.
Parameters
The file path.
Return Value
If the file exists after the command, it will return true.
In case of any error, it will return false.
Examples
exists = touch ./dir/file.txt
Aliases:
touch
sdk::fs::DeleteEmptyDirectory
var = rmdir path
This command delete the requested empty directory and returns true if successful.
If the path leads to a file or a directory which is not empty, this command will fail.
Parameters
A single parameter holding the directory path.
Return Value
true if the directory was deleted.
Examples
deleted = rmdir ./mydir
Aliases:
rmdir
sdk::fs::DeletePath
var = rm [-r] path
This command delete the requested file, empty directory or recursively deletes a directory and all its content (files and sub directories) if the -r flag is provided.
Parameters
- Optional flags (currently only -r is supported which indicates recursive deletion)
- The path to delete
Return Value
true if the path was deleted.
Examples
# delete a file or empty directory
deleted = rm ./target
# deletes a directory and all its content
deleted = rm -r ./target
Aliases:
rm
sdk::fs::GetCanonicalPath
var = canonicalize path
This command will return the c path for the provided input.
In case unable, it will return the original input.
Parameters
The file/directory path to canonicalize.
Return Value
The canonicalized path, or if unsuccessful, the original path.
Examples
path = canonicalize ./target
Aliases:
canonicalize
sdk::fs::GetFileName
var = basename path
This command will return the last path element of the provided path.
If unable, it will return none.
Parameters
The path to extract the last element from.
Return Value
The last path element or none if unsuccessful.
Examples
file = basename ./dir/file.txt
Aliases:
basename
sdk::fs::GetParentDirectory
var = dirname path
This command will return the parent path of the provided path.
If the parent path is empty, it will return none.
Parameters
The path to extract the parent path from.
Return Value
The parent path or none.
Examples
directory = dirname ./dir/file.txt
Aliases:
dirname
sdk::fs::MovePath
var = mv source target
This command moves the requested source path to the target path.
- If the source and target paths define a file, it will move the file as defined.
- If target path is a directory path, it will move the source file/directory into that target directory path.
All missing parent directories in the target path will be created as needed.
Parameters
- The source path to copy
- The target path
Return Value
true if the move was successful.
Examples
# move a single file
moved = mv ./file1.txt ./file2.txt
# move a single file into the target directory
moved = mv ./file1.txt ./somedir
# move entire directory into another directory
moved = mv ./source ./target/subdir
Aliases:
mv
sdk::fs::Print
var = cat file
The cat command will print out the requested file.
In addition it will also return the value to the output variable.
Parameters
A single parameter holding the file path.
Return Value
The file content or none if the file does not exist.
Examples
cat ./docs/sdk.md
Aliases:
cat
sdk::fs::Read
var = readfile file
The readfile command will read the requested file and return the value to the output variable.
Parameters
A single parameter holding the file path.
Return Value
The file content or none in case file does not exist.
Examples
text = readfile ./Cargo.toml
Aliases:
readfile
sdk::fs::Write
result = writefile file text
This command enables to write the provided text into the requested file.
It will return true/false value based if it was able to write the text to the file.
Parameters
- The target file
- The text content to write
Return Value
true/false based if it was able to write the text to the file.
Examples
out = writefile ./target/tests/writefile.txt "line 1\nline 2"
Aliases:
writefile
sdk::math::Calc
var = calc [operation]
The calc command accepts multiple arguments which make up a mathematical operation which will be calculated and its result will be returned.
Parameters
Any number of arguments which will construct a line to calculate.
Return Value
The result of the mathematical calculation.
Examples
# result is 36
result = calc 1 + 5 * 7
Aliases:
calc
sdk::process::Execute
exec command [args]*
output = exec command [args]*
stdout = set ${output.stdout}
stderr = set ${output.stderr}
exit_code = set ${output.code}
Executes the provided native command and arguments.
If no output variable is set, the command output will be flushed to the main out/err stream of the parent process.
If an output variable is set, it will be used as a base variable name from which the command stout, stderr and exit code information can be pulled from.
The actual output variable name will not be modified, instead new variables will be created using that variable name as a baseline:
- output.stdout - Will hold the stdout text content.
- output.stderr - Will hold the stderr text content.
- output.code - Will hold the process exit code.
Parameters
The command to execute and its arguments.
Return Value
Optionally a base name to access the process stout, stderr and exit code information.
Examples
# Example of running a command and flushing its output to the parent process.
exec echo hello world
# Example of running a command and storing its output.
output = exec echo hello world
stdout = set ${output.stdout}
stderr = set ${output.stderr}
exit_code = set ${output.code}
echo stdout: ${stdout}
echo stderr: ${stderr}
echo exit code: ${exit_code}
Aliases:
exec
sdk::process::Exit
code = exit [code]
Exits the script with the given code stored in the output variable.
Parameters
A positive number as exit code or none for 0.
Return Value
The exit code.
Examples
# exit with code '0'
code = exit
# exit with code '1'
code = exit 1
Aliases:
exit
sdk::test::Assert
assert value [error message]
Used to validate the input is truthy.
If the value is one of the following:
- No output
- false (case insensitive)
- 0
- no (case insensitive)
- Empty value
It is considered falsy and will exist with an error.
Parameters
- The value to evaluate
- Optional error message
Return Value
true if truthy.
Examples
# valid conditions
assert ok
assert true
assert yes
value = set "some text"
assert ${value}
# error conditions
assert
assert false
assert 0
assert false "This is my error message"
Aliases:
assert
sdk::test::AssertEquals
assert_eq value1 value2 [error message]
Used to validate the input is the same.
If they are not, the command will exist with an error.
Parameters
- Two values to evaluate if they are equal
- Optional error message
Return Value
true if truthy.
Examples
# valid conditions
assert_eq yes yes
assert_eq false false
value = set "some text"
assert_eq ${value} "some text"
# error conditions
assert_eq 1 2
assert_eq 1 2 "This is my error message"
Aliases:
assert_eq
sdk::test::AssertFail
assert_fail [error message]
This command will exist with an error.
If error message is provided, it will be used as part of the error output.
Parameters
Optional error message.
Return Value
None
Examples
assert_fail
assert_fail "This is my error message"
Aliases:
assert_fail
sdk:🧵:Sleep
sleep millies
Will cause the script execution to half for the given amount of milliseconds.
The command will also return the amount of milliseconds waited.
Parameters
A positive numeric value.
Return Value
The amount of milliseconds waited.
Examples
# will sleep for 10 milliseconds
time = sleep 10
echo Waited for ${time} milliseconds.
Aliases:
sleep
License
Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.