15 KiB
Table of Contents
- sdk::Alias
- sdk::Array
- sdk::Echo
- sdk::Eval
- sdk::ForIn
- sdk::Function
- sdk::GoTo
- sdk::If
- sdk::Release
- sdk::Set
- sdk::Unalias
- sdk::env::Get
- sdk::env::PrintCurrentDirectory
- sdk::env::Set
- sdk::env::SetCurrentDirectory
- sdk::fs::Print
- sdk::fs::Read
- sdk::fs::Write
- sdk::process::Execute
- sdk::process::Exit
- sdk:🧵:Sleep
sdk::Alias
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
None
Examples
This example creates a new my_echo alias that will print the prefix before the requested arguments.
alias my_echo echo [ECHO]
# This will print "[ECHO] hello world "
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
# commands
elseif command
# 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 a command with arguments and invokes it.
If the result of the command is one of the following:
- No output
- false (case insensitive)
- 0
- no (case insensitive)
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
- else/end_if - no parameters
Return Value
None
Examples
Simple example of an if statement that evaluates to 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::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 a simple text value:
var = set hello
Return an expanded value:
var = set "home: ${HOME}"
Aliases:
set
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::Get
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::Set
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::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 an error.
Parameters
The new current directory.
Return Value
The new current directory.
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::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.
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.
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::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
Example of exit with code '0'
code = exit
Example of exit with error code '1'
code = exit 1
Aliases:
exit
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
Example of 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.