Shellapi

Print the passed text with the specified color without impacting the current terminal setting (resets to normal) The background color name of the palette shall be specified without the "bg_" prefix

arg1

text to print

arg2

text foreground color

arg3

text background color

_setColored <arg1> <arg2> <arg3>

Updates the passed text by adding the specified fore and background colors The background color name of the palette shall be specified without the "bg_" prefix

arg1

text to print

arg2

text foreground color

arg3

text background color

_load <arg1> <arg2>

Loads another script file by sourcing it (if not loaded yet before). Prior to sourcing, the global var __SHELL_SOURCE_NAME__ is set to hold the basename of the sourced script. __SHELL_SOURCE_NAME__ is restored to previous value after the sourcing.

arg1

name of the script without extension

arg2

parent dir path of the script, relatively to this.

Returns 1 on error (invalid args), 0 otherwise.

_isLoadDepCached

Tells whether the cache indicates that the dependency was already loaded

_loadVDep

Loads a possible dependency bound with a given distro version

_loadDep

Standard/generic end-user wrapper for dealing with package dependencies.

_loaded <arg1>

Function to be called by any script API to check whether it has been already sourced or not. When not loaded yet, it defines a global variable which existence means script file had been sourced yet before.

Typical use:

if _loaded "${BASH_SOURCE[0]}"  ; then
 return 0
fi

arg1

path to the source file of the calling script

Returns 0 if already loaded, 1 otherwise.

_usage <arg1>

Standard/generic end-user wrapper for handling usage errors by doing the following:

display of a script usage. The calling script-specific usage is displayed by invoking a callback function formatted <appname>__usage where <appname> is given by first parameter
display any error specified by second parameter on standard error
exit process with code - 1

Optionally displays an error message if second argument is specified

arg1

optional error message to be displayed

_susage <arg1>

Short usage function. Standard/generic end-user wrapper for handling usage errors by doing the following:

display of a script usage. The calling script-specific usage is displayed by invoking a callback function formatted <appname>__susage where <appname> is given by first parameter
display any error specified by second parameter on standard error
exit process with code - 1

Optionally displays an error message if second argument is specified

arg1

optional error message to be displayed

_invokeCallback <arg1>

Invokes safely an application callback, displaying a warning if the callback does not exist.

arg1

callback function name

_help <arg1>

Standard/generic end-user wrapper for handling help doc by doing the following:

display of a script app help. The calling script-specific help is displayed by invoking a callback function formatted <appname>__help where <appname> is __SHELL_CURRENT_APPNAME__ If any argument is specified, the call back is <appname>__fullhelp
exit process with code 0

Optionally displays an error message if second argument is specified

arg1

any string

_optionsN

This does the same as _options() except that it accepts the additional parameters OPTION_LIST_ARGS_TYPE so that the argument description can reflect the argument types defined. _options() is kept for compatibility.

_options

Displays script options according to the description list of all options as stored in global variable <APPNAME>__OPTION_LIST_DESC to be passed on as first argument and <APPNAME>__OPTION_LIST_ARGS to be passed on as second argument

_soptions

Displays a short synopsis of the options according to the description list of all options as stored in global variable <APPNAME>__OPTION_LIST_DESC.

_parseArgs

Standard/generic end-user wrapper for parsing argument. It handles the -h/--help argument invoking a callback function formatted <appname>__help where <appname> is __SHELL_CURRENT_APPNAME__, ending calling _quit

It handles the --man argument invoking a callback function formatted <appname>__man where <appname> is __SHELL_CURRENT_APPNAME__ ending calling _quit

_parseFromArgToVars

not documented

_parseArgsProcessDashLessArg <arg1> <arg2> <arg3> <arg4>

Internal callback which performs either of the following depending on the 3rd argument value:

processes option values by evaluating <APPNAME>__OPTION_LIST_VALS[<option>], in which case the option value is given by 2nd argument.
otherwise, processes argument values which are not options (not starting with a dash).

When the 3rd argument is empty, it means the 2nd arg (arg value) is not an option value and the user callback of the same name is called passing on the argument count so far and the argument value (<Appname>___parseArgsProcessDashLessArg).

The amount of dashless arguments processed is tracked by a counter passed on by ref.

arg1 &

List giving the actions to perform for options with values. Passed by ref since it’s a map, but is not aimed to be modified

arg2

argument value (which can be an option value)

arg3

previous argument (reference).

arg4 &

arg counter name (reference)

Returns incremented counter

_quit

App shell quitting.

Ensures a fault-less quitting of the shell (return value 0).

User may override default behavior by defining a callback function of the form "<appname>__quit"

In absence of user callback, it calls __quit

__quit

Straight application quitting and bypassing any user-defined quit function.

It deactivates the trap for EXIT SIGHUP SIGINT SIGTERM SIGQUIT SIGABRT and calls _exit function.

_exit <arg1> <arg2>

Exits the shell bailing out with an error message if exit code is not 0. At the end, it calls the _cleanup callback.

arg1

exit code

arg2

error message to be displayed

_main

Standard/generic end-user wrapper for invoking main script function Invokes a callback function formatted <appname>__quit where <appname> is __SHELL_CURRENT_APPNAME__

_cleanup <arg1>

Standard/generic end-user wrapper for cleaning up upon signal arising

It invokes a callback function formatted <appname>_cleanup, passing on the exit code. Eventually, it calls system exit with the initial caught exit code

arg1

any string

_initShellApi

Initializes this shell API framework.

Following global variables are set:

__SHELL_CURRENT_APPNAME__: it is the argument passed while sourcing this core shell api. It gives the logical name of the application script
__SHELL_SRC_NAME__: Source file name of the first application script which sources this core shell api.

_setJobId

not documented

_initLogVars

Initializes only the variables related to the message, warning, errors log files, in particular with regard to the log file names and the number of messages:

__LOG_FILE__
__LOG_WARN_FILE__
__LOG_ERR_FILE__
__NB_LOG__
__NB_WARNING_LOG__
__NB_ERR_LOG__

_initLogs

Initializes the log file: message, warning, errors.

_getConfigDir <arg1>

Returns the path to the existing configuration directory for the currently registered application (__SHELL_CURRENT_APPNAME__), which is defined as <user home dir>/.config/<app name>/.

arg1

reference to the variable where to store the configuration folder path

Returns 0 when a valid configuration folder exists (and was possibly created by this function), otherwise:

1 when failing to create config dir,
2 when invalid config dir

_getRecentListFilePath

not documented

_readRecentList

Reads the recent list for the application. The configuration file is expected to be <user home dir>/.config/<app name>/recentlist.yml.

The values of the configuration are stored in a map named : <appname in uppercase>__RECENT. The keys are the genuine YAML keys .

Example applied for Sumo: for config line " my parameter : my value", there will be value defined as follows <APPNAME>__VARS["my parameter"]="my value"

Returns 0 on success, 2 when invalid config dir

__getRecentListFilePath

not documented

_saveRecentList

not documented

_lockedFileGetAbsPath

not documented

_lockedFileRead

not documented

_lockedFileWrite

not documented

_getLogDir <arg1>

Returns the log folder path, ensuring parent dirs are created

arg1 &

the reference of the variable where to store the path

_getLogPath <arg1>

Returns the user’s log file path, ensuring parent dirs are created If any parameter is specified, the log file is truncated and the __LOG_NB__ is reset to 0

arg1 &

the reference of the variable where to store the path

_getLogWarnPath <arg1>

Returns the user’s warning log file path, ensuring parent dirs are created If any parameter is specified, the log file is truncated and the __LOG_NB_WARN__ is reset to 0

arg1 &

the reference of the variable where to store the path

_getLogErrPath <arg1>

Returns the user’s error log file path, ensuring parent dirs are created. If any parameter is specified, the log file is truncated and the __LOG_NB_ERR__ is reset to 0

arg1 &

the reference of the variable where to store the path

_getConfigFilePath

Returns the user’s local configuration file path. Note this file is not created by this function and may not exist.

_readConfig

Reads the configuration for the application. The configuration file is expected to be <user home dir>/.config/<app name>/<appname in lowercase>.yml. When this file does not exist, the function <appname>__getDefaultConfigFile is called if the function exists, in order to get the appname’s own default config file path.

The values of the configuration are stored in a map named : <appname in uppercase>__VARS. The keys are the YAML keys in upper case where spaces are replaced with "_"

Example applied for Sumo: for config line " my parameter : my value", there will be value defined as follows <APPNAME>__VARS["MY_PARAMETER"]="my value"

Returns 0 on success, 2 when invalid config dir 3 when invalid config file or failed to read it 4 Sumo-default config does not exist or User-specific config does not exist

_appendConfig

not documented

_getDependenciesCacheFile

not documented

_readDependenciesCache

not documented

_writeDependenciesCache

not documented

_resetDependenciesCache

not documented

_foreachLine <arg1> <arg2> <arg3>

Iterates through the lines

arg1

String containing lines

arg2

either a function or a code block. In case a

arg3

argument passed on to the called function code block is passed then the iteration variable is the name of the array extended with 'Item'

_foreach <arg1> <arg2> <arg3>

Iterates through an array and executes the action passed as second argument

arg1

ref to var containing the array

arg2

either a function or a code block. In case a

arg3

argument passed on to the called function code block is passed then the iteration variable is the name of the array extended with 'Item'

_foreach2 <arg1> <arg2> <arg3> <arg4>

Same as _foreach, but iterates over 2 arrays which have both the same size

arg1

ref to var containing the array

arg2

ref to var containing the second array

arg3

either a function or a code block. In case a

arg4

argument passed on to the called function

_foreach3 <arg1> <arg2> <arg3> <arg4> <arg5>

Same as _foreach, but iterates over 3 arrays which have both the same size

arg1

ref to var containing the array

arg2

ref to var containing the second array

arg3

ref to var containing the 3rd array

arg4

either a function or a code block. In case a

arg5

argument passed on to the called function

_debugging

Tells whether the debug mode is active.

_debug

Activate or deactivate debug mode. Debug mode is detected as active if variable __LOG_DEBUG__ is defined. It can be activated by this function with the following argument value:

no argument (null string)
true
0 Any other value unsets the variabmle

_log_dbg

Displays the passed argument string on the standard error output if __LOG_DEBUG__ var. exists. The default behavior can be overriden by a user-defined function of the form <appname>___log_dbg where <appname> the argument passed while sourcing this core shell api. By default, the line is prefixed with [debug].

_log_err

Displays the passed argument string on the standard error output and inserts it in the error log file. The default behavior can be overriden by a user-defined function of the form <appname>___log_err where <appname> the argument passed while sourcing this core shell api. By default, the line is prefixed with [error].

_log_warn

Displays the passed argument string as a warning on the standard error output and inserts it in the warning log file. The default behavior can be overriden by a user-defined function of the form <appname>___log_warn where <appname> the argument passed while sourcing this core shell api. By default, the line is prefixed with [warning].

_log_high

Same as _log(), except it is reserved for messages of higher importance by displaying 'info' with blue background to catch attention

_log

Displays the passed arguments on the standard output and writes it in the log file if log files were initialized (see initLogs). The default behavior can be overriden by a user-defined function of the form <appname>___log where <appname> the argument passed while sourcing this core shell api.

_log_if

Same as _log(), but the first argument is boolean telling whether to actually log the passed message. This is useful in application where there’s a switch driven by a configuration parameter

_log_ifnot

Same as _log(), but the first argument is boolean giving a condition that shall not be met for the loggin

_logf

Same as _log(), but only writes the log file and no message is displayed on terminal.

_log_array <arg1>

Displays the passed shell array string on the standard output in the following format: <array key>:<array value for that key> The _log function is used for the display.

arg1

name of the array. The array shall be passed by reference, not with all of its values.

_log_n

Same as _log, except there is no new line displayed.

_log_status

not documented

_log_status_end

not documented

_log_vars_exit

not documented

_log_vars

not documented

_log_title

Same as _log, except that the message is preceeded and followed by an empty line. The default behavior can be overriden by a user-defined function of the form <appname>___log_title where <appname> the argument passed while sourcing this core shell api.

_makeDir

Creates each component of the specified dir path (mkdir -p) if the dir path does not exit. Redirects errors in the error log files.

_test <arg1> <arg2> <arg3>

Executes a test

arg1

test description

arg2

expected result, i.e. 0 (success) or 1 (fail)

arg3

command line to execute

Returns 0 on success, 1 otherwise

_testCase

Executes the case which ID is specified as argument. When batch execution all tests, the ID will be an increasing number starting from 0. But a random ID can be passed for executing a specific test run via _test. It is up to the _testCase user implementation to handle that ID (which can be a random string). Typically, there would be a case enumeration where the numeric ID and the alternative clear text ID is defined like 0|<my test name>)
Returns 0 on success, 1 otherwise

_testAll

Executes all tests by invoking testCase passing as argument an increment ID starting from 0
Returns 0 on success, 1 otherwise

Term__setTextMode

not documented

Term__resetColorData

not documented

Term__resetColor

not documented

Term__setColorOn

not documented

Term__setBgColorOn

not documented

Term__setColor

Sets either the foreground or the background color To change the background color, 'true' must be passed as second argument.
Returns this sets Term__text_fgcolor and Term__text_bgcolor, and sets Term__text_color from these latter values

Term__buildPalette

Feed the mal _pal which maps readable colors to the terminal escaped char Readable colors are of the form: [bg_]<color name>[_<text_mode>] If the text mode is not specified , it refers to the default normal text color If 'bg_' is specified, then the color refers to the background color. Otherwise, it is foreground color

Term__showPalette

not documented

Term__testColors

not documented

trapDirExits

Exits if the passed folder does not exist

trapFileExits

Exits if the passed file does not exist

Env__fn_exists

Tells whether the function exists and is defined.

Env__distro

Returns the name and version of the system distribution. Name and version are separated separated by ' '

Env__distroname

Returns the name only of the system distribution

Env__distrover <arg1>

Returns the version only of the system distribution

arg1

the maximum number of version numbers requested. If not specified, original extracted version is returned.

Env__arch

Returns the name of the machine architecture. By default, replaces x86_64 by amd64

Str__swap

If called with a single value, this value is assigned to the variable and saves the initial value of the variable in an internal buffer.

Afterwards, if the function is called without value, it restores the last saved value for the given variable and forgets about it. Recalling the function does not affect anymore the variable. If called without value and not saved value is available, it has no effect.

If called with 2 values, variable is assigned alternatively between the 2 values by successive calls by checking the currently saved value.

Str__randomWord

not documented

Str__diff <arg1> <arg2>

Makes a diff between 2 string using the diff systemtool

arg1

string

arg2

string

Str__getDiffLines <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

Performs a 'brutal' line-by-line diff of 2 multiline strings and returns an array containing the lines differences. This function is primarly designed to extract differences between two blocks which are expected to be the same with only few differences.

arg1

string 1

arg2

string 2

arg3

ref of var used to store the line numbers as an array

arg4

ref of var used to store the lines of input string 1 that differ at the line numbers stored in above array

arg5

ref of var used to store the lines of input string 2 that differ at the line numbers stored in above array

arg6

optional bool telling whether to ignore leading and trailing whitespaces for each compared line (false by default)

Str__isEmpty <arg1>

Tests a string for emptiness

arg1

string to test for emptiness

Str__spaces <arg1>

Returns a series of spaces which length is given by first parameter.

arg1

number of spaces

Str__padded <arg1>

Prints the passed string and appends the number of space padding till to reach the specified fix size. There’s no new line added.

arg1

number of spaces

Str__indent <arg1> <arg2> <arg3>

Indents a paragraph by inserting spaces at the start of each line.

arg1

number of spaces to add

arg2

ref to the var used as input and modified with the indended content.

arg3

optional Start line from which to indent

Str__prefix <arg1> <arg2> <arg3>

Prefixes each line of a paragraph with the passed prefix string

arg1

prefix

arg2

ref to the var used as input and modified with the prefixed content.

arg3

optional Start line from which to prefix

Str__seq <arg1> <arg2>

Returns a sequence of the same size of length given by first parameter

arg1

the char to repeat

arg2

number of chars

Str__len <arg1>

Prints the length of the passed string

arg1

string

Str__upcaseFirst <arg1>

Upcase the first letter of the passed argument string

arg1 &

string

Returns 0 on success, 1 if wrong arguments

Str__lower <arg1>

Returns the argument string in lowercase

arg1

string

Returns lowercase string

Str__toLower <arg1>

Lowercase the passed string by reference. This version should be used instead of lower() when possible since its definition prevents it to be called from a subshell

arg1

string, which is lowercased

Str__upper <arg1>

Returns the argument string in uppercase

arg1

string

Returns lowercase string

Str__toUpper <arg1>

Uppercase the passed string by reference. This version should be used instead of upper() when possible since its definition prevents it to be called from a subshell

arg1

string, which is uppercased

Str__startsWith <arg1> <arg2>

Tells whether the passed string starts with another.

arg1

string

arg2

expected start substring

Returns 0: yes, 1:no

Str__endsWith

not documented

Str__grepAndGetField <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

Retrieves the field values of all lines containing a certain substring according to the passed separator and index

arg1

string

arg2

substring to search for

arg3

field separator

arg4

field index

arg5 &

ref to var storing the array of found fields

arg6

optional bool telling with not to interpret \ as an escape char

Str__grep <arg1> <arg2> <arg3>

A simple grep to capture all lines containing a substring

arg1

string

arg2

substring to search for

arg3 &

ref to var storing the lines that matched

Str__getField <arg1> <arg2> <arg3> <arg4> <arg5>

Retrieves the field value in the passed string according to the passed separator and field index.

arg1

string providing the formatted string fields

arg2

field separator

arg3

field index

arg4

ref to the variable that will be assigned the field value

arg5

optional bool telling with not to interpret \ as an escape char

Str__contains <arg1> <arg2>

Tells whether the passed string contains a substring.

arg1

string

arg2

substring to search for

Returns 0: yes, 1:no

Str__nbCommonEndString <arg1> <arg2> <arg3>

Return the string tail in commmon between both given input string, regardless of char case and heading or trailing whitespaces.

arg1

string 1

arg2

string 2

arg3

tail in commmon between both given input string, in lower case

Str__squeeze <arg1> <arg2> <arg3>

Squeezes multiple consecutive whitespaces to a single one

arg1

string to squeeze

arg2 &

result string

arg3

Optional, char to squeeze, by default whitespaces ()

Returns the number of removed chars

Str__escape <arg1> <arg2> <arg3> <arg4>

Replaces all the occurrences of the first string parameters trimming leading and trailing occurrences and replacing the rest with the value of the third parameter.

arg1

string to be processed

arg2

string to escape

arg3

replacement string

arg4 &

resulting string

Returns 0

Str__escapeChar <arg1> <arg2>

Escapes all the occurrences of the pass char inserting a backslash

arg1 &

input string to be escaped

arg2

string to escape

Returns 0

Str__escapeXML <arg1>

Escapes special XML chars to make them usable as a value in an element. inserting a backslash

arg1 &

input string to be escaped

Returns 0

Str__trim <arg1> <arg2> <arg3> <arg4>

Trims the passed string of the specified char on both of its ends

IMPORTANT UPDATE:

in#$c is not efficient for big string, because it scans from the end till the beginning till to find a starting 'c' till to find the in="${in#$c}" in="${in%$c}" in%$c is either for the same reasons.

arg1

string to be trimmed

arg2 &

variable

arg3

char to be removed, is by default

arg4

The number of char to remove, by default all.

Returns number of trimmed char in all

Str__trimOnce <arg1> <arg2> <arg3> <arg4>

Same as Str__trim but attempts to remove only 1 occurrence with a very simple implementation. Written for the sake of performance, since the regular variant reveals to be much slower.

arg1

string to be trimmed

arg2 &

variable

arg3

char to be removed, is by default

arg4

The number of char to remove, by default all.

Returns number of trimmed char in all

Str__trimStart <arg1> <arg2> <arg3> <arg4>

Trims the passed string of the specified starting char

arg1

string to be trimmed

arg2 &

variable

arg3

char to be removed at the start of the string. Optional, is by default

arg4

The number of char to remove, by default all.

Returns number of trimmed char in all

Str__skip

not documented

Str__skipWs

not documented

Str__trimEnd <arg1> <arg2> <arg3> <arg4>

Trims the passed string of the specified ending char

arg1

string to be trimmed

arg2 &

variable

arg3

char to be removed at the end of the string. Optional, is by default

arg4

The number of char to remove, by default all.

Returns number of trimmed char in all

Str__last <arg1> <arg2>

Gets the last char of the passed string and stores it in the second arg passed by reference

arg1

string

arg2

last char

@return: char

Str__head <arg1> <arg2> <arg3>

Prints the first chars till to match the first occurrence of the passed separator, or the last occurrence if any third argument is specified.

arg1

string

arg2

separator

arg3

recurse flag

Returns the heading substring

example

$(head "www.example.com" .) -> "www"

example

$(head "www.example.com" . last) -> "www.example"

Str__toHead <arg1> <arg2> <arg3>

Same as Str__head, except that it stores the results in the passed variable

arg1

var ref for input/output string

arg2

separator

arg3

recurse flag

Returns the heading substring

example

$(head "www.example.com" .) -> "www"

example

$(head "www.example.com" . last) -> "www.example"

Str__tail <arg1> <arg2> <arg3>

Returns the last chars till to match the first occurrence of the passed separator, or the last occurrence if any third argument is specified, when scanning the string reversely.

arg1

string

arg2

separator

arg3

recurse flag

Returns the tail

example

$(tail "www.example.com" .) -> "com"

example

$(tail "www.example.com" . last) -> "example.com"

Str__toTail <arg1> <arg2> <arg3>

Same as Str__tail, except that the results in not echoed on stdout but replaces the value of input variable itself passed as reference

arg1

string reference which will hold the tail as result

arg2

separator

arg3

recurse flag

Str__eraseCommonTail

not documented

Str__split <arg1> <arg2> <arg3> <arg4> <arg5>

Split the passed string in two parts according to the passed separator. The first occurrence of the separator from the left is considered.

arg1

input string reference which will hold the input string to split

arg2 &

resulting left part. If no separator found, the left part equals the input string

arg3

separator

arg4 &

resulting right part. If no separator found, the right is an empty string

arg5

Optional (0 dflt): "1" or "0": indicates which string shall be empty in case no separator is found (0:left, 1:right part shall be empty): <0 erroneous arguments.

Returns 0 if the string could be split into 2 parts, false (1) otherwise (namely no separator found)

Str__replace <arg1> <arg2> <arg3>

Replaces all occurences of a certain string with another. Modifies the input string

arg1

string

arg2

substring to replace

arg3

replacement substring

Returns updated input string

Str__replaceOne <arg1> <arg2> <arg3>

Replaces only 1 occurence of a certain string with another. Modifies the input string

arg1

string

arg2

substring to replace

arg3

replacement substring

Returns updated input string

Str__substringCount <arg1> <arg2>

Counts the number of occurences of a certain substring

arg1

string

arg2

substring to count occurrences of @print count

Returns 0

Str__lineCount <arg1> <arg2>

Returns the number of lines of the specified string

arg1 &

reference to the input string

arg2

ref to the var that will store the result

Str__linesToArray <arg1> <arg2>

Retrieves the lines contained in a string and stores them into the passed array

arg1 &

reference to the input string

arg2

ref to the array var that will store the result

Str__shrinkToRight <arg1> <arg2> <arg3>

If the passed string size exceeds a maximum size (maxlen) , it is truncated at right and truncated part is replaced with a replacement string

arg1 &

reference to the input string to be truncated

arg2

maximum output string length

arg3

replacement for the shrinked data

Str__shrinkToMid <arg1> <arg2> <arg3>

Shrinks the passed string to a string of a maximum size (maxlen) given in second argument. The string is shrinked that both ends of the string is limited to maxlen/2, the remaining being replaced with the specified replacement string.

arg1 &

reference to the input string to be truncated

arg2

maximum output string length

arg3

replacement for the shrinked data

Str__fitToLineWidth <arg1> <arg2>

Rearranges a multiline text so that each line does not exceed the specified width as argument, by splitting the line as many times as necessary. During the process, the original linefeeds are preserved.

arg1 &

reference to the input string to be rearranged

arg2

maximum line width

Str__justify <arg1> <arg2>

Rearranges a multiline text so that each line is forced to have the specified width by duplicating spaces as much as necessary.

arg1 &

reference to the input string to be rearranged

arg2

target line width

Str__toCharArray <arg1> <arg2>

Converts a string to a char array, storing in the passed variable all chars as an array.

arg1

input string

arg2

ref to the variable storing the chars. The variable will be an array.

Str__toAsciiDocId

Str__isWord

Indicates whether the passed argument is a word, than means a random sequence of chars from a to z (lowercase or uppercase) -, _ or .

Str__highlight <arg1> <arg2> <arg3> <arg4> <arg5>

Highlight substrings in input string matching any of the passed keywords

arg1

input string

arg2

var ref to keywords to hightlight

arg3

bool ignore case?

arg4

highlight color

arg5 &

string with hightlighted items

Int__isInt

not documented

Int__Int

not documented

Int__Int_r

not documented

Int__percentage

not documented

Int__calc

not documented

Int__calc_r

not documented

Int__withinRange

not documented

Int__series

not documented

Int__min <arg1> <arg2> <arg3>

Returns the minimum of the two passed integers

arg1

first int

arg2

second int

arg3

ref to var for storing maximum values

Int__max <arg1> <arg2> <arg3>

Returns the maximum of the two passed integers

arg1

first int

arg2

second int

arg3

ref to var for storing maximum values

Int__readVersion <arg1> <arg2> <arg3>

Retrieves version numbers from a string of the form 'x[[.y].z]' If a component is not define, there’s an empty string

arg1 &

returned major version

arg2 &

returned minor version

arg3 &

returned update version

Int__getIntTrail

not documented

Float__compare

not documented

Float__calc

not documented

Math__byteSize2ReadableSize

not documented

Math__kbyteSize2ReadableSize

not documented

Math__size2ReadableSize <arg1>

arg1

scale: 0 size given is in byte, 1 size given is in kb, 2 size given is MB

Math__convertSizeToMiB <arg1> <arg2>

arg1

size value

arg2

size value

Args__checkCount <arg1> <arg2> <arg3> <arg4>

This function can be conveniently used to check the number of arguments passed to a called function

arg1

function name. This name shall be set by the calling function using ${FUNCNAME[0]}

arg2

required number of arguments

arg3

actual passed number of arguments

arg4

extra message in case of mismatch

Returns 0 when the args counts are matching, 1 otherwise. It is up to the calling function to determine whether it can go on its execution or interrupt

Args__checkMinCount <arg1> <arg2> <arg3> <arg4>

This function can be conveniently used to check the minimum required number of arguments passed to a called function

arg1

function name. This name shall be set by the calling function using ${FUNCNAME[0]}

arg2

required of minimum number of arguments

arg3

actual passed number of arguments

arg4

extra message in case of mismatch

Returns 0 when the args counts are matching, 1 otherwise. It is up to the calling function to determine whether it can go on its execution or interrupt

Array__print <arg1> <arg2>

Prints the values

arg1

Array to print

arg2

Array items separator

Array__concat <arg1> <arg2>

Concatenates 2 arrays

arg1

Array to which will be appended the items of the second array

arg2

Array that will be appended to the first passed array ref

Array__getSortedArray <arg1> <arg2>

Sorts an array of spaceless values. Note this does not work if an value contains any space, because this output array is rebuilt from a sorted string

arg1

ref to input array

arg2

ref to new sorted output array

Returns 0 when found, 1 when not

Array__contains <arg1> <arg2>

Tells whether an array contains a string equal to the passed value

arg1

name of the array variable

arg2

value string to search for in the array

Returns 0 when found, 1 when not

Array__contains_by_string <arg1> <arg2>

Same as Array__contains, except that the array is past in the form of a string where items are separated with a space. The function reconstructs a builtin array from the string.

arg1

string where array values are separated with a space

arg2

value string to search for in the array

Returns 0 when found, 1 when not

Array__fromString <arg1> <arg2> <arg3> <arg4> <arg5>

Creates an array from a string, in which fields are separated by the specified separator. Spaces are trimmed from each field

Update: this replaces Array__fromStringOLD, because it is possible to detect chars escaped with \, whereby the separator can be contained itself in a value. It is also more efficient.

arg1

string providing the formatted array

arg2

separator

arg3

ref to the variable that will be assigned the created array

arg4

optional bool telling with not to interpret \ as an escape char

arg5

optional bool whether trim fields (true by dflt). When not required, this can improve performance

Array__fromStringOLD <arg1> <arg2> <arg3>

Creates an array from a string, in which fields are separated by the specified separator. Spaces are trimmed from each field

arg1

string providing the formatted array

arg2

separator

arg3

ref to the variable that will be assigned the created array

Array__toString <arg1> <arg2> <arg3>

Converts an array to a string , separating items by the supplied separator

arg1

ref to input array

arg2

separator

arg3

ref to var that will contain output string

Array__toTextTable <arg1> <arg2> <arg3> <arg4>

Converts a table of records to a terminal output sheet where the data of each line is displayed in a column on equal size, which is set to the data field of maximum size

A record is a lines containing data fields which are separated by the specified separator as arg 2. When no separator is specified, ';' is assumed, i.e. CSV records format is assumed

Option third parameter enables to pass an alternate table of records to use explicitly for the computing of the column width. A typical use is when the input string containing escape chars for terminal colors, whereby the length of the internal string won’t match that on the display. Typically, the 3rd argument would be the copy of the 1st argument, but without the terminal escape chars.

arg1

input string

arg2

separator

arg3

alternate table of records to use explicitly for the computing of the column width

arg4

optional bool telling whether not to interpret \ as an escape char. This can be useful when values contains terminal color escale sequences

Input__getForcedInput

not documented

Input__pushForcedInput

Push on the stack a forced input, i.e. a predefined answer for any Input__ function

Input__testYesForcedInput

not documented

Input__testForcedInput

not documented

Input__popForcedInput

Removes a forced input from the head of the stack.

this function shall not be called from a subshell (using $(..)), since this creates a subshell process, whereby the original Input____forced_input is not modifed.

Input__clearForcedInput

not documented

Input__pressToContinue

not documented

Input__timeoutKeystroke

not documented

Input__password <arg1>

Prompts for a password

arg1

reference to the variable where password will be saved.

Input__confirm_high

Performs the exact same as Input__confirm, but prefixes the question sentence with 'Question' on yellow background.

Input__confirm <arg1> <arg2> <arg3>

Prompts for a confirmation among the following : y,Y,n,yes,YES,no,NO Default prompt 'y/n' is automatically appended to the question by default.

arg1

question sentence

arg2

optional default answer if nothing entered.

arg3

optional alternative prompt

Returns 0 upon positive confirmation, 1 otherwise Question is asked until a valid answer is given.

Input__memsize <arg1> <arg2> <arg3> <arg4>

Prompts for a memory size among the following : xG, xM, xK respectively x Gibibytes (GiB), x Mebibytes (MiB), x kibibytes (KiB) Default prompt 'int followed by G/M/K or a to abort' is automatically appended to the question by default. Question is asked until a valid answer is given except if param 4 is specified

arg1

question sentence

arg2

result size is stored in this parameter

arg3

unit of the returned memsize

arg4

bool telling whether to abort an invalid memory size input

Returns 0 upon positive entry,

Input__dirpath <arg1> <arg2> <arg3> <arg4>

Prompts for a file system path. Question is asked until a valid answer is given.

arg1

question sentence

arg2

default proposed path

arg3

flag telling to create folder if does not exist. 0: do create but confirm, 1: do create but no confirm, do not create otherwise

arg4

path is stored in this parameter

Returns 0 upon positive entry,

Input__sentence

not documented

Input__Word <arg1> <arg2> <arg3> <arg4>

Prompts for a word, i.e. a sequence of alphanumeric letter plus other chars like _,- and . Question is asked until a valid answer is given.

arg1

question sentence

arg2

default value

arg3

word is stored in this parameter

arg4

option Accepted input pattern

Returns 0 upon positive entry,

Input__cursorSelect

not documented

Input__cursorSelect_manageIgnoreIndex <arg1> <arg2> <arg3>

This function is intended to be called after an update of the current index, to determine whether the new index is pointing to an index to be ignored. Depending on the previous navigation action (up or downwards the list), the current index is corrected to avoid an ignore index and shifted resp. one step up or down in the list. NOTE: It does not not yet handle the case of successive ignored lines, for which it may have to be called recursively

arg1

last user navigation action (key sequence).

arg2

updated index

arg3

map of ignored index

Input__cursorSelec…eIndexOnCurrentPage <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

This function is intended to be called before a page jump to determine whether there’s an ignore ahead when jumping forward (down) or one before current index when jumping backward (up). If so

arg1

current page index

arg2

current index in current page (relative index)

arg3

page jump direction : true if up, false if down

arg4

Number of items that can be displayed on one terminal page

arg5

The map of 'ignore index'

arg6

Found ignore index on the way to the page jump

File__basename <arg1> <arg2>

Returns the base file name (with its extension) of the passed file name

arg1

filename

arg2 &

returned file basename

File__dirname <arg1> <arg2>

Returns the dirname of the passed file path. The path is assumed to be an absolute path without . or .. components.

arg1

filepath

arg2 &

returned file basename

File__corename <arg1> <arg2>

Returns the core file name (without its extension) of the passed file name

arg1

filename

arg2 &

returned file corename

File__ext

Returns the file extension of the passed file name

File__noext

Returns the file path with extension

File__realpath <arg1> <arg2> <arg3> <arg4>

Returns the realpath of a file

arg1

filename

arg2 &

ref of var used to store returned absolute path

arg3

bool telling whether to resolve links (true by default)

arg4

bool telling whether to check existence (false by default)

File__cwd

not documented

File__dirExists

not documented

File__exists

not documented

File__fileExists

not documented

File__linkExists

not documented

File__getSize <arg1> <arg2>

Return the size of the passed file or directory in bytes

arg1

file path

arg2

ref to variable where to store size

File__dirSHA256 <arg1> <arg2> <arg3> <arg4>

Computes a signature for a directory based on the ls -gRA command ensuring a consistent and deterministic ls content on any machine regardless of:

Time zone
System language
Entry sorting , using time-based sorting with --sort=time
owner and group

arg1

directory for which to compute the SHA256 fingerprint

arg2 &

ref to variable that will be assigned the fingerprint value

arg3

optional list of --ignore options for file patterns to be excluded from the computing Examples: --ignore=".mp4" --ignore=".jpg" --ignore=".nfs*" --ignore=".swp*"

arg4 &

optional the source data from which the fingerprint was computed

File__lsSignature <arg1>

Returns a universal, consistent and deterministic 'ls' signature for the specified file or folder across any system, regardless of :

Time zone
System language
owner and group

The format is the following: <UTC timestamp> <size in bytes> <permissions/file mode bits> <number of hardlinks> <quoted path>

arg1

valid file or dir path

Returns echoes the signature and standard output

File__createSubdirs <arg1>

Creates in the current working directory subdirectories which names are given as array to this function

arg1

array of dirs to create

File__createTempDir <arg1>

Creates a temporary folder in default system /tmp folder and inserts it in the global map for subsequent cleanup

arg1 &

the name of the temporary dir

File__deleteTempDir <arg1>

Deletes the temporary folder passed as argument. If it was created with File__createTempDir, it also clears the matching entry in the global map. This function adds a level of safety by checking that the argument really starts with /tmp

arg1

temporary directory

File__deleteAllTempDirs <arg1>

Deletes all temporary folders created with File__createTempDir

arg1

temporary directory

File__createTempFile <arg1> <arg2>

Creates a temporary file in default system /tmp folder and inserts it in the global map for subsequent cleanup

arg1 &

the name of the temporary dir

arg2

optional the extension of the temp file

File__deleteTempFile <arg1>

Deletes the temporary file passed as argument. If it was created with File__createTempFile, it also clears the matching entry in the global map. This function adds a level of safety by checking that the argument really starts with /tmp

arg1

temporary directory

File__deleteAllTempFiles <arg1>

Deletes all temporary files created with File__createTempFile

arg1

temporary directory

File__deleteAllTempItems <arg1>

Deletes all temporary files created with File__createTempFile

arg1

temporary directory

File__copyDirs <arg1> <arg2> <arg3>

Performs a mirror copy of folders contained within the passed source folder path to the specified target folder. The operation uses the function File__mirrorCopy.

arg1

parent folder

arg2

destination folder

arg3

optional a space-separated list of exclude patterns for folders to be excluded and not copied.

File__mirrorCopy <arg1> <arg2> <arg3>

Performs a mirror of a file/folder The operation is based on the rsync command, whose output on standard output is filtered. This function is useful when it is itself used from another script.

arg1

source file/folder

arg2

destination file/folder

arg3

optional file containing the list of files/folders to exclude (one name per line)

Returns 0 only upon success

File__readYAMLLikeFile <arg1> <arg2>

THIS FUNCTION IS DOOMED TO BE DEPRECATED. SEE shell-api-yaml.sh, YAML__setFile <file> true

Reads a YAML-like file consisting of a list of pairs 'property name : propery value' on each like. This is not a YAML parser, it is just a basic reader for simple configuration without having to depend on other tools.

arg1

path to the file to read the properties from

arg2

reference to the output map where to store the properties,

whereby keys are the prop names and values the prop values The map must be declare wit "declare A" Returns 0 on success, 1 when not existing or not a regular file, 2 when invalid syntax. On error 2, the prop map may already contain the values which could be read till that point.

File__readYAMLLikeLine

not documented

File__writeJobProgressFile

not documented

File__setProgressFileTotalSteps

not documented

File___writeJobProgressFile

not documented

File__createFromZTemplate <arg1> <arg2> <arg3>

Creates a new file from a "Z" template, i.e. a template text file which contains keywords of the form '%<keyword id>%' which are replaced by associated values pass as parameters to this function

arg1

source template file

arg2 &

file

arg3

a map declare with 'declare -A' given the value to use for each keyword id (without % chars)

File__list <arg1> <arg2>

Lists the files of the passed folder path and stores their basename in the passed array var ref

arg1

folder path

arg2

ref to var where to store filenames as an array

File__foreach <arg1> <arg2>

Iterates through the files contained in the passed directory and and executes the action passed as second argument

arg1

folder path

arg2

either a function or a code block. In case a code block is passed then the iteration variable is the 'fileItem'

File__append <arg1> <arg2>

Appends some content to a file. Uses the printf function. Third parameter tells whether to add a new line (true by default).

arg1

ref to var containing the file path

arg2

var containing the data to write

Date__readYMD <arg1> <arg2> <arg3> <arg4>

Given a string of the form yy-mm-dd hh:mm:ss, extract the year, month and day items and stores it into the passed var refs.

arg1

Input date time string of the form "yy-mm-dd hh:mm:ss"

arg2

extracted output year

arg3

extracted output month

arg4

extracted output day

Date__readYMD2

not documented

Date__isLessOrEqualThan <arg1> <arg2> <arg3> <arg4>

Given a date string of the form yy-mm-dd hh:mm:ss, tells this date is earlier than the supplied YMD date components.

arg1

Input date time string of the form "yy-mm-dd hh:mm:ss"

arg2

extracted output year

arg3

extracted output month

arg4

extracted output day

Returns 0 if less, 1 otherwise

Date__timestamp

not documented

Date__startTimer

not documented

Date__elapsedSecondsTimer

not documented

Date__elapsedMinutesTimer

not documented

Date__getTimezone <arg1>

Returns the active timezone. First attempts to read it from TZ env variables. When not attempts to read it using timedatectl

arg1

ref to var where to store timezone

User__getFullUserName

not documented

Term__countdown <arg1>

Implements a simple countdown

arg1

1: number of seconds till timeout

Term__resize <arg1> <arg2>

Resizes the terminal the number of lines and columns as specified in the arguments. Basically, this is a wrapper for the 'resize' commmand, which standard output is masked.

arg1

number of lines

arg2

number of columns

Returns the return value of the bash 'resize' command

Term__rows

not documented

Term__cols

not documented

Term__resizeMinimum <arg1> <arg2>

Ensures that the terminal has at a minimum the size as specified in the arguments. If the current terminal is large enough, its size is not modified.

arg1

number of minimum rows

arg2

number of minimum columns

Returns the return value of the bash 'resize' command

Term__updateLine <arg1>

Prints a string on standard output by overwriting last printed line. A carriage return is done and line till the end is cleared prior to printing value

arg1

string print on the standard output

Term__updateProgressBar <arg1> <arg2> <arg3>

This enables to show and update a text-based progress bar on the terminal. The bar is of the form, e.g. : |===== | 25% The bar is displayed the first time that the function is called according to a maximum step value and a number of incrementation achieved steps.

The masking of the cursor is activated when this function is called. It is up to the calling script to restore the terminal settings (e.g. by using Term__reset) when the progress bar is not used anymore.

arg1

unique identifying name of the bar. This will be used to define global env. var.

used for the purpose of managing the bar.

arg2

max steps

arg3

number of achieved steps at the call of this function. This is an incremental value.

E.g. assuming a max step of 100, calling 4 times this function with 25 achieved steps results in a 100% completion. Returns 0 when 100% is reached, 1 otherwise.

Term__clear

not documented

Term__maskCursor

Make the cursor invisible and disable echoing.

Term__restoreCursor

Reverse operation of cursor masking, it ensures the cursor is visible and key echoing is enabled.

Term__eatReturns

not documented

Term__enterPrivateBufferMode

Enter the private buffer mode, whereby the existing scrollback can be saved and restored afterwards when either Term__exitPrivateBufferMode or Term__reset is called.

Term__exitPrivateBufferMode

Exits the private buffer mode.

Term__reset

Resets the terminal by enforcing cursor visibility and echoing and exiting of private buffer mode.

Term__cursorMoveLeft <arg1>

Moves the cursor to the left for the amount of specified chars

arg1

number of char pos

Term__moveTo

not documented

Term__moveCursorUp

not documented

Term__moveCursorDown

not documented

Term__eraseLinesUp

not documented

Term__eraseLines <arg1> <arg2>

Erase the amount of terminal lines as specified by first argument starting from the current line. The cursor pos is reset to the line start of the current line before call of this function.

arg1

number of lines to erase

arg2

optional : 'true' for rewinding, 'false' for not rewinding

Term__eraseCurrentLine

Erase the current terminal line and pushes back the cursor to the line start.

Term__eraseCurrent…umpCursorToNextLine

Erase the current terminal line and pushes back the cursor to the line start.

Term__printBanner <arg1> <arg2> <arg3> <arg4> <arg5> <arg6> <arg7>

Prints banner frame which fits with the content of the message.

There are various parameters to control aspect of the frame.

Special lines are interpreted:

<hr> prints a separation line

arg1

message to display

arg2

char for the horizontal frame borders

arg3

char for the left frame border

arg4

char for the right frame border

arg5

separator char for fields

arg6

number of blank lines at top and bottom of the frame

arg7

top and bottom h border visibility : 1=no top, 2=no bottom, 3=none

@example:

With text=" <hr>

Backup of AppData (Application Data) of distant Windows system

Please check system is running and reachable over network ! "

Term__printBanner "\$text" "|" " " "-" 1

results in:

________________________________________________________________
|
| disk
|----------------------------------------------------------------
|
| Backup of AppData (Application Data) of distant Windows system
|
| Please check system is running and reachable over network !
|________________________________________________________________

Term__resolveMaxColumnsWidth <arg1> <arg2>

Provided a table which rows are given as lines and cells are given as space-separated values in each rows, this function computes the maximum number of chars that occupies each column. To operation, this function relies on function Term__printTableRow, whereby the second and third parameters are used specifically for that purpose.

arg1

the number of columns of the table

arg2

the table itself

Returns an array giving the maximum number of chars occupied by each column. E.g "10 6 20" for a 3-column table

example

here an example of parameters: /dev/sda 447,1G disk /dev/sda1 100M part vfat /dev/sda2 16M  part

Term___printTableRow

This function is called internally by Term__printTableRow. See related documentation.

Term__printTableRow <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

Provided a table which rows are given as lines and cells are given as space-separated values in each rows, this function displays the table with fixed size columns given by second parameter as a list of char length for each column. By using Term__resolveMaxColumnsWidth prior to this function, one can compute the exact width of each column to match the largest string value which can be found in that column.

The actual function which is achieving the display is Term___printTableRow (with 3 underscores). This wrapper function is in charge of setting the line formatting (e.g. color) according to the line header which is ended by '§§'.

arg1

the table itself

arg2

list of char length for each column. E.g. "10 6 8" for a 3-column table.

arg3

char used for the left vertical border

arg4

char used for the right vertical border

arg5

char used as cell separator

arg6

optional, a number of extra end-padding for the cells

example

here an example of table: table: /dev/sda 447,1G disk /dev/sda1 100M part vfat /dev/sda2 16M  part

test__perf

Examples of usage:

test__perf 5000  'var=$(dirname ${BASH_SOURCE[0]})'
#test__perf 5000  'var=${BASH_SOURCE[0]%/*}'

#test__perf 5000  'GENAPP__VARS["MYDIR"]="$(readlink -f "${Genapp__sourcedirname}")"'
test__perf 5000  'read Genapp__sourcedirname< <(readlink -f "${Genapp__sourcedirname}")'

Test__assertFilesShouldNotExist <arg1>

Checks that the list of passed regular file paths are not valid (do NOT exist). Exits the current shell script (_exit -1 is called) when at least one file exists.

arg1

list of regular file paths

Test__assertFilesShouldExist <arg1>

Checks that the list of passed regular file paths are valid (exist). Otherwise, exits the current shell script (_exit -1 is called) when at least one file does not exist.

arg1

list of regular file paths

Test__assertDirsShouldExist <arg1>

Checks that the list of passed directory paths are valid (exist). Otherwise, exits the current shell script (_exit -1 is called) when at least one folder does not exist.

arg1

list of directory paths

Test__assertFileLastLine <arg1> <arg2>

Checks whether the last line of the passed file corresponds exactly to the string passed as second argument. Thus, char case is relevant. Exits the current shell script (_exit -1 is called) when the file does not exist or line was not found.

arg1

File path

arg2

Expected last line

Test__assertFileLine <arg1> <arg2> <arg3>

Checks whether the line of the specified line number of the passed file corresponds exactly to the string passed as third argument. Thus, char case is relevant. Exits the current shell script (_exit -1 is called) when the file does not exist or line was not found.

arg1

File path

arg2

Line number (from 1)

arg3

Expected line of the specified line number

Test__assertFileContent <arg1> <arg2>

Checks whether the content of the passed file matches exactly the string passed as second argument. Thus, char case is relevant. Exits the current shell script (_exit -1 is called) when the file does not exist or the content does mismatch

arg1

File path

arg2

String giving the expected file content

Test__assertFileContentPattern <arg1> <arg2>

Checks whether the content of the passed file matches the specified string pattern as second argument. Pattern is like those passed to the bash’s [[ ]] test operator. Exits the current shell script (_exit -1 is called) when the file does not exist or the content does not match the pattern

arg1

File path

arg2

String giving the pattern of the expected file content

Test__assertFileContainsLine <arg1> <arg2>

Checks whether the passed file contains a line corresponding exactly to the string passed as second argument, thus char case is relevant. Exits the current shell script (_exit -1 is called) when the file does not exist or line was not found.

arg1

File path

arg2

Line to search for

Test__assertSameFiles <arg1> <arg2> <arg3>

Test whether 2 files have exactly the same content. 'diff' tool is used for the test. On failure, exits the current shell script (_exit -1 is called)

arg1

a message to display after base message '<1st file basename> is the same '…

arg2

1st file path

arg3

2nd file path

Test__assertChangeDir <arg1>

Changes the current working directory to the passed one. On failure, exits the current shell script (_exit -1 is called)

arg1

new current working directory path

Test__assertChangeToNewDir <arg1>

Same as Test__assertChangeDir, except that it creates the directory when it does not exist. On failure to cd or create the folder, exits the current shell script (_exit -1 is called)

arg1

new current working directory path, created if necessary

Test__assertCleanupDir <arg1>

Removes the passed directory and all its content recursively. Exits the current shell script (_exit -1 is called) if the folder does not exist or the removal failed.

arg1

Path of working directory to remove

Test__assertCmdExit <arg1> <arg2>

This checks the exit code of the passed command execution against the passed reference value Exits the current shell script (_exit -1 is called) upon mismatch

arg1

expected exit code

arg2

command to execute

Test__assertCmdNotExit <arg1> <arg2>

This checks the exit code of the passed command execution is different of the passed reference value Exits the current shell script (_exit -1 is called) when the exit code does match

arg1

expected exit code

arg2

command to execute

Test__assertCmd <arg1> <arg2>

This checks the first output line resulting from passed command execution. Exits the current shell script (_exit -1 is called) when there’s a mismatch.

arg1

command to execute

arg2

expected output string

Test__assertCmdOutput <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

This checks that the output of command matches that of a reference file content. 3rd parameter tells whether to ignore whitespaces at the beginning and end of each content lines to compare Optionally, start and end line numbers can be specified. Optionally, an additional space-separated line numbers to be ignored can be specified.

arg1

reference file which content gives the expected output

arg2

command to execute

arg3

bool tells whether to ignore whitespaces at the beginning and end of each content lines

arg4

optional start line from which to check content

arg5

optional end line (included) no till which to check content

arg6

optional space-separated line no-s to be ignored

Test__assertCmdOutput_handleLineDiffs

not documented

Test__assertSymlinkPath <arg1> <arg2>

Tests whether a symbolic link points to the specified absolute path On failure, exits the current shell script (_exit -1 is called)

arg1

symbolic link path

arg2

absolute path (not another link)

Test__assertTwoCommandsSameOutput

This checks the output of one command is the same of another command Exits the current shell script (_exit -1 is called) when there’s a mismatch.

Networking functions index

File: shell-api-net.sh

Function

Documentation

Net__checkOpenPort <arg1> <arg2>

Tests whether a given port is open on a given host on the network using nmap

arg1

service name, the relevant port number will be resolved from the name. Recognized values:

nfs, ssh, ftp

arg2

service host

Net__isHTTP <arg1>

Tells whether the passed argument looks like an HTTM URL, i.e. of the basic form [http[s]://]xxx(.yyy)+

Safe characters: Alphanumeric [0-9a-zA-Z], special characters $-_.+!*'(), No Reserved characters which are not allowed: / ? : @ = &

arg1

URL

Returns 0 when valid URL, false (1) when not, <0 on arg error

Net__decodeHTTP <arg1> <arg2>

Extracts only the host address from the HTTP URL

arg1

HTTP URL

arg2

reference to var for storing extracting hostname

Net__isURL <arg1>

Tells whether the passed argument looks like an URL, i.e. of the basic form xxxxx://yyyyy

arg1

URL

Returns 0 when valid URL, false (1) when not

Net__isIP <arg1>

Tells whether the passed argument looks like an IP4 address, i.e. of the basic form <number>.<number>.<number>.<number>

arg1

Returns 0 when valid IP, false (1) when not, <0 on arg error

Net__isUNC <arg1>

Tells whether the passed argument looks like a UNC path (universal naming convention) of the basic form //server/sharename[/path]

arg1

URL

Returns 0 when valid UNC, false (1) when not, <0 on arg error

Net__decodeUNC <arg1>

Extracts hostname/ip, share from passed UNC

Example of valid netlogin: //192.168.0.40/MyShareName

arg1

UNC

Net__isLogin <arg1>

Tells whether the passed argument looks like a login path of the basic form userlogin@host

arg1

Netlogin

Net__decodeLogin <arg1>

Extracts hostname/ip and user from passed netlogin <user>@<host>[:path]

examples of valid netlogin:

albert@192.168.0.40
mikky@truesite.org:some/path

arg1

Netlogin

Net__isFTPURL <arg1>

Tells whether the passed argument looks like a FTP URL, i.e. of the basic form ftp://[user@]host

arg1

URL

Net__decodeFTPURL

not documented

Net__isNFSURL <arg1>

Tells whether the passed argument looks like an NFS URL, i.e. of the basic form nfs://host:share

arg1

URL

Net__isNFS <arg1>

Tells whether the passed argument looks like a regular NFS device, i.e. of the basic form host:share

arg1

URL

Net__decodeNFSURL

not documented

Net__isSSHURL <arg1>

Tells whether the passed argument looks like a SSH URL, i.e. of the basic form ssh://[user@]host[:port][/path]

arg1

URL

Net__decodeSSHURL

not documented

Net__isSMBURL <arg1>

Tells whether the passed argument looks like a SMB URL, i.e. of the basic form smb://yyyyy

arg1

URL

Net__decodeSMBURL <arg1>

Extracts hostname/ip, user and share (shared folder name) from the passed URL. Expected URL format is the following: smb://<hostname or IP>[/<user>[:password][/<share>]]

Examples of valid URL:

smb://192.168.0.40/MyDataShare
smb://192.168.0.40/

arg1

SAMBA URL

Net__getHostIP

not documented

Net__getLocalHostIP

not documented

Net__getLocalHostname

not documented

Net__getHostname <arg1> <arg2>

Retrieves the hostname from the passed IP. This function executes 2 subshells , one for nsloopkup, another for awk.

arg1

IP address

arg2 &

hostname resulting hostname, which is param 1 if it was actually not a valid IP address

Net__IP2Name <arg1> <arg2>

Converts an IP to the matching hostname

arg1

IP address

arg2 &

hostname resulting hostname, which is param 1 if it was actually not a valid IP address

Net__resolve

not documented

Net__getDeviceName

Retrieves the name of the network device

Net__getDeviceMAC <arg1> <arg2>

Retrieves the MAC address bound with the network device passwed as argument

arg1

network device name

arg2 &

MAC addres

Net__getMAC <arg1>

Retrieves the MAC address bound with the device used for default routing

arg1 &

MAC addres

Net__MAC

Same as Net__getMAC, except that it echoes the MAC instead of assigning a variable passed as argument

Net__download <arg1>

Download a file from a given URL using wget

arg1

URL

Returns 0 on success, 2 if site is not reachable, 1 if site is reachable but download failed somehow.

Net__isCloudDevice

Tells whether the passed argument string is a valid known cloud service driver (not an URL). e.g. google-drive-ocamlfuse

Net__getCloudURLFromDevice

not documented

Net__isNetworkURL

not documented

System devices and low-level file system index

File: shell-api-dev.sh

Function

Documentation

Dev_getPartUUID

not documented

Dev_getPartNames

not documented

Dev_getPartNamesReduced

not documented

Dev__initPartTypes

not documented

Dev__initfstype2PartUUIDTable

not documented

Dev__isBlockDevice

not documented

Dev__isRegularFile

not documented

Dev__getFileType

not documented

Dev__getBlockDeviceParent <arg1>

Retrieves and prints on stdout the block device size

arg1

device path

Returns 0

Dev__blockDeviceSize <arg1>

Retrieves and prints on stdout the block device size

arg1

device path

Returns 0

Dev__getBlockDeviceLabel <arg1> <arg2>

Retrieves the block device label

arg1

device path

arg2 &

ref to var where to store label.

Returns return value of lsblk command executed

Dev__findMount <arg1> <arg2> <arg3>

Retrieves the source and mount point from an argument which is either the source or the mount point. This function relies on 'mount' command which prevents it from blocking in case of broken connections.

arg1

mountpoint

arg2 &

source found

arg3 &

mount point found

Dev__findMountSource <arg1> <arg2>

Retrieves the source of a mounted folder. If a network connection is broken, the findmnt command may block. As alternative, use findMount above.

arg1

mountpoint

arg2 &

variable holding the found source

Dev__findMountPoint <arg1> <arg2>

Retrieves the mounted folder from a source device

arg1

device path

arg2 &

variable

Dev__findMountPointOptions <arg1> <arg2>

Retrieves the options from a source device

arg1

device path

arg2 &

variable

Dev__getDeviceInfo <arg1> <arg2>

Retrieves a device specific info with udevadm tool

arg1

block device

arg2

the type of data requested

Returns 0 if the requested data was found, 1 otherwise and the output data is set to "-"

Dev__isBootable <arg1>

Tells whether the device bound with the passed block device path is bootable. For that purpose, the output of 'parted' is analysed for search for the first partition id '1:' and the 'boot' keyward Requires root priviledges.

arg1

block device path

Returns 0 when device is bootable, false (1) when not, <0 on usage error.

Dev__getBootType <arg1>

This function uses gdisk to determine the type of the boot record of the device (if any) among GPT, MDR, APM and BSD, and request 'parted' to determine whether the device is actually bootable

arg1

system device path

Dev__wipeDisk <arg1>

Erases any trace of a file system on the specified block device using wipefs

arg1 &

block device path

Dev__resetDiskDevice <arg1>

Erases any trace of a file systems on the specified block device by zeroing the first 1M of the device. ATTENTION: this operation is destructive, use with care! ATTENITION: this may not work with GPT because there may be backup sectors, use wipefs -a --force

arg1 &

block device path

Dev__getDeviceFSType

not documented

Dev__createRawDiskImage <arg1> <arg2> <arg3>

Generic low-level wrapper for creating a basic raw disk image filled with 0. This operation is time-consuming and may only be useful when handling disks in regular files.

arg1 &

disk image file path or block device path

arg2 &

disk size in bytes

arg3

block size (e.g. 512 or 1024)

Returns the value of 'dd' commands

Dev__createSinglePartition <arg1> <arg2> <arg3>

Generic low-level wrapper for creating a partition given a file system type. The type of partitition is deduced from the file system type, but not file system is created. Take care, this function can have destructive effect.

arg1

disk image file path or block device path

arg2

expected file system to be host to deduce the partition type to create

arg3

boolean telling whether root priviledges are required (0=true, false otherwise)

Dev__createSinglePartitionDirect <arg1> <arg2> <arg3>

Generic low-level wrapper for creating directly a basic partition by script without having to specify a file system type in advance like Dev__createSinglePartition() function. Take care, this function can have destructive effect.

arg1

disk image file path or block device path

arg2

expected file system to be host to deduce the partition type to create

arg3

boolean telling whether root priviledges are required (0=true, false otherwise)

Dev__getDeviceMapper <arg1> <arg2> <arg3>

Returns the device mapper name for a block device. If none exists, the original input block device path is returned.

This function may be systematically called whatever the source is, which may result in message like "Device sdb1 not found Command failed." on stderr This is however harmless and shall be hidden, otherwise this misleads the log reader in thinking there’s an error.

arg1

Block device path

arg2

Prefix to add to the found device mapper

arg3

Ref to variable where to store device mapper name

Dev__getLVMPartitionDevices <arg1>

arg1

the top LVM group device for which to get the underlying system devices mapping actual partitions

Dev__getPartitionDevices <arg1> <arg2>

Get the devices which are mapping partitions for the specified system device, which is assumed to be a top disk device.

Uses sfdisk, partprobe,

arg1

the disk device for which to get the underlying system devices mapping partitions

arg2 &

a list of space-separated device paths

Dev__deactivateAllVolumeGroupsForDisk <arg1> <arg2>

Provided a disk block device, this function deactivates all volume groups inside that disk. It is assumed that partitions inside the volume group(s) have been unmounted.

This uses 'vgchange -a n' command. Other commands, see 'Dev__getPartitionDevices'

arg1

the disk device for which to get the underlying system devices mapping partitions

arg2 &

a list of space-separated device paths

Returns 0 if at least the partition of the devices could be resolved and VG could be deactivate, 1 otheriwse.

Dev__loop_open <arg1> <arg2> <arg3>

Allocates a loop device for the file specified as first argument.

arg1

disk file name

arg2

disk type

arg3 &

loop block device

Returns 0 only on sucess

Vera__findMountPointFromVolume <arg1> <arg2>

Retrieves the mounted folder for a Vera volume (file name) given as first argument.

arg1

absolute path of Vera encrypted file

arg2 &

variable where the mount point will be stored

Vera__findMountPointFromSlot <arg1> <arg2>

Retrieves the mounted folder for a Vera slot number given as first argument.

arg1

Slot number

arg2 &

variable where the mount point will be stored

Vera__findLabelFromMountPoint <arg1> <arg2>

Retrieves the slot number from a VERA mountpoint.

arg1

Mount point path

arg2 &

variable where the slot number will be stored

Vera_getEscapedList

This routine enables to get the vera list where all spaces within simple quites are espaced with '§§' chars, so that it can be safely processed by awk. It also redirects the standard error to /dev/null.

Adb__getVersion

not documented

Adb__getSDKVersion

not documented

Adb__getDeviceName

not documented

Adb__listDevices

not documented

Multimedia file manipulation functions index

File: shell-api-multimedia.sh

Function

Documentation

Image__getDimension <arg1> <arg2>

Enables the get the actual dimension of an image as returned by exiftool

arg1

Image file path

arg2

A reference to the variable where to store the dimension in the form of a string "<width> <height>"

Image__isPortrait

not documented

Image__chopFromRatio <arg1> <arg2> <arg3> <arg4> <arg5> <arg6> <arg7> <arg8> <arg9> <arg10>

Truncate passed image so that the ratio height/width for portrait images or ratio width/height for landscape images matches ratio. By the default, the target image file is not overwritten if it already exists , except if fifth argument is specified <image ratio threshold>

arg1

source image file

arg2

width and height separated by a space

arg3

target base image file name. The target image will have the same extension of source image. Source and target can be the same

arg4

target image height/width ratio

arg5

boolean allowing to chop the largest edge if image ratio is greater than the target ratio

arg6

boolean allowing to chop the shortest edge if image ratio is below the target ratio

arg7

boolean optional telling whether the target image file shall be overwritten if it exists. Other values means 'no'

arg8

Gives the image format of the chopped image variante for printable devices. That image is not resized, its name is the source image name

prefixed with "pdf_" and the ".png" extension. When no extension is specified, it is not generated.

arg9

Optional target image size if chopped image has to be resized. Chopped image file name and extension is as specified by 3rd argument.

arg10

Optional target image size for mobile devices. Chopped image file name and extension for mobiles devices is the same as the normal chopped image

except that it is prefixed with "mobile_" When no specified, the image for mobile is not generated

Image__autoOrient

not documented

Image__normalizeOrientation <arg1> <arg2> <arg3>

arg1

image file with extension

arg2

target image file with extension

arg3

boolean (0/1) telling whether to overwrite existing (false by default)

Returns 0 if a change was done , 1 otherwise.

SVG_text

not documented

Image__ico <arg1>

Generates .ico from another image format in the specified target directory. The target icon will have the same as the original image and stored in the same folder.

arg1

source image file

Image__generateFromPDF <arg1> <arg2> <arg3> <arg4> <arg5> <arg6>

Generates files of the form <PDF filebasename>-<image PPI>-<page>.jpg

arg1

pdffile path

arg2

output directory

arg3 &

list of files generated

arg4

output image format

arg5

output image PPI resolution

arg6

other options

pfgtocairo: resolution: -r, -rx , -ry (default is 150 PPI) -transp for transparent background with PNG

Image__generatePDFFromImageFiles

not documented

Image__watermark

not documented

Packaging functions index

File: shell-api-packing.sh

Function

Documentation

Pkg__install <arg1> <arg2> <arg3> <arg4> <arg5> <arg6> <arg7>

Installs the named packages according to the specified method. The URL can contain the following placeholders which will be replaced with actual values:

%%name%%: package name as specified by 1st argument
%%version%%: version as specified by 2nd argument
%%arch%%: machine archicture as return by 'uname -m'. amd64 is returned for x86_64
%%distroname%%: linux distribution name as returned by 'lsb_release -is'
%%distrover%%: distribution version

arg1

package name

arg2

package version.

arg3

installation method (apt, gem, snap, dpkg, http folder,…)

arg4

if necessary, URL or filename

arg5

options

arg6

an executable condition to fulfill for performing the installation

arg7

an executable post installation condition, which result has to be returned by this function.

example

Pkg__install vera https://launchpad.net/veracrypt/trunk/1.26.14/+download/

DPKG__isInstalled <arg1>

Checks whether a debian package passed as argument is installed.

arg1

debian package name This function takes into consideration different possible variant names of the package depending on the linux distribution and its version.

DPKG__exists <arg1>

Checks whether the passed package name even exists for installation.

arg1

apt/dpgk package name

APT__isInstalled <arg1>

Checks whether a system APT package passed as argument is installed.

arg1

apt package name

APT__install <arg1> <arg2>

Installs the list of APT packages given as argument.

arg1

list of space-separated package names in a string.

arg2

additional install options

APT__distant_install <arg1> <arg2>

Installs the list of APT packages given as argument.

arg1

list of space-separated package names in a string.

arg2

additional install options

OPAM__isInstalled <arg1>

Tells whether the passed OPAM package is installed.

arg1

package name

Returns 0 if installed, another value otherwise.

OPAM__install <arg1>

Installs the list of snap packages given as argument.

arg1

array of snap package names

SNAP__isInstalled <arg1>

Tells whether the passed SNAP package is installed.

arg1

package name

SNAP__install <arg1>

Installs the list of snap packages given as argument.

arg1

array of snap package names

GEM__isInstalled <arg1>

Tells whether the passed GEM package is installed.

arg1

package name

GEM__install <arg1>

Installs the list of GEM packages given as argument.

arg1

array of package names

YAML file handling functions index

File: shell-api-yaml.sh

Function

Documentation

YAML__setFile <arg1> <arg2>

Sets the currently processed YAML file passed as 1st argument (sets variable YAML__FILE) OR reads the YAML file all at once and stores the values in the global map YAML_DATA.

The function YAML__read*, YAML__write*, YAML__keys* will access the file using yq each time.

The function YAML__readAll, YAML__get*, YAML__getKeys*, YAML__writeAll, YAML__isUndefined, YAML__normalize, YAML__dumpAll will use the values stored in the global data map.

arg1

YAML file

arg2

OPTIONAL(false) bool telling whether to read all YAML file content and make it accessible via the global YAML_DATA map

Returns 0 on success, any other value otherwise

YAML__closeFile

not documented

YAML__getKeys <arg1> <arg2>

Retrieves the keys defined below a given data path.

arg1

field path of form '.this.is.my.data.path'

arg2 &

the array of keys

Returns 0 on success, any other value on error

YAML__checkExists <arg1>

Checks whether the field path exists in the global YAML_DATA map holding all data

arg1

field path of form '.this.is.my.data.path'

Returns 0 on success, any other value on error

YAML__get <arg1> <arg2> <arg3>

Gets a YAML field from the global YAML_DATA map holding all data

arg1

field path of form '.this.is.my.data.path'

arg2 &

ref to variable where to store the data.

arg3

OPTIONAL(false) tells whether field is optional. When so and field value

is empty, then the input var is unchanged.

YAML__isntVoid <arg1>

Tells whether the passed value is not a 'void' YAML value, ie. it is neither 'null' nor ''.

arg1

value to test

YAML__unescape

not documented

YAML__escape

not documented

YAML__get_bool

not documented

YAML__get_int

not documented

YAML__isUndefined <arg1>

Tells whether the value of the passed YAML field is either empty or 'null'. It reads the value using YAML__get using the passed key and check whether it is empty or 'null'

arg1

YAML key name

Returns Returns 0 when the passed YAML field value is either empty or 'null'

YAML__getFilename <arg1>

Get the currently processed YAML file as set with YAML__setFile.

arg1

YAML file

Returns the return value of the yq command , i.e. 0 only on success.

YAML__eval <arg1>

Evaluates the rule passed as 1s argument from the currently set YAML file

arg1

YAML filter rule

Returns the return value of the yq command , i.e. 0 only on success.

YAML__read <arg1> <arg2>

Reads an YAML field using YAML__eval and stores the values in the passed named variable.

arg1

1 in data path

arg2

2 out variable where read values will be stored

Returns the return value of the yq command , i.e. 0 only on success.

YAML__read_from_stdin

not documented

YAML__read_optional <arg1> <arg2>

Same as YAML__read() except that when the field path does not exist, the output variable remains unchanged and not error is raised.

arg1

1 in field path

arg2

2 out variable where read values will be stored

Returns 0 if field exists and value was read, 1 otherwise

YAML__read_bool

not documented

YAML__assignBool

not documented

YAML__read_int

not documented

YAML__write <arg1> <arg2>

Writes in-place an YAML field

arg1

1 in data path

arg2

2 in value to assign

Returns the return value of the yq command , i.e. 0 only on success.

YAML__writeArray <arg1> <arg2>

Writes in-place an YAML array

arg1

1 in data path

arg2

2 in a space-separated values

Returns the return value of the yq command , i.e. 0 only on success.

YAML__exists <arg1>

Tells whether the YAML filter rule , resp. YAML field, is not 'null' in the currently set YAML file

arg1

YAML filter rule

Returns 0 when so, 1 otherwise

YAML__keys <arg1>

If YAML__exists is successfully, returns the keys of the matching YAML field.

arg1

YAML filter rule

Returns If rule result is not null, returns status of 'yq', 1 otherwise

YAML__nbKeys_from_stdin

not documented

YAML__nbKeys

not documented

YAML__keys_from_stdin

not documented

YAML__writeAll

not documented

YAML__normalize

not documented

YAML__readAll <arg1> <arg2>

arg1

file yo read

arg2

a map declared with "declare -A" to store the (key,value) pairs

YAML__readAll_getStoreValue

not documented

YAML__trimQuotes

not documented

YAML__readAll_storeRawValue

not documented

YAML__readAll_storeValue

not documented

YAML__readAll_decodeQuote

not documented

YAML__readAll_decodeArrayValue

not documented

YAML__dumpAll

not documented

YAML__getKeysFromStore

This function returns the keys from the YAML data store. It only works if there’s one level of root nodes, otherwise it would return all nodes. This can be solve by checking the dots, but considering the node names might themselves contain dots.

XML transformation functions index

File: shell-api-xslt.sh

Function

Documentation

XSLT__modifyXML

not documented

XSLT__transformToText

not documented

Framework self-test functions index

File: shell-api-selftest.sh

Function

Documentation

testPerfTrim

not documented

testGrepAndGetField

not documented

testGetField

not documented

testPerfGrepApi

not documented

testGrepApi

not documented

testTimer

not documented

testYamlPerfReadAll

not documented

testYamlOneFile

not documented

testManyYamlTests

not documented

testCommonEndString

not documented

testAdbAPI

not documented

testPkgInstallAlternative

not documented

testDistroEnv

not documented

testInputDirPath

not documented

testLogStatus

not documented

Test__printResult <arg1> <arg2>

Use this function to display the test result

arg1

boolean result (eg. value of $?). 0=success, otherwise failure

arg2

[2…n] list of additional infos in case of failure, typically a message of type "got <value>, whilst expected <other value>" of the basic form xxxxx://yyyyy

Returns mirrors first parameter

Test_File

not documented

Test__File_in_out

not documented

Test_URL

not documented

Test__ProgressBar

not documented

Test__Str_squeeze_testOneString

not documented

Test__Str_escape_testOneString

not documented

Test__Str_trim_testOneString

not documented

Test__Str_eraseCommonTail

not documented

Test__Str

not documented

Test__Input__dirpath_checkOutput

not documented

Test__Input__dirpath

not documented

Test__Input__dirpath_forcedinput

not documented

Shellapi

Global API index

Core framework functions index

Global scope

Args - Shell function argument handling

Array - Arrays

Date - Date, time and timers

Env - Shell and Linux Environment

File - File and directories

Float - Floating numbers

Input - User input functions

Int - Integer numbers

Math - Math functions

Str - Strings handling

Term - Terminal settings

Test

test

User - System user-related settings

System devices and low-level file system index

Adb - ADB-related functions

Dev - System devices and low-level file system settings

Vera - VERA-related functions

Multimedia file manipulation functions index

Image - Image manipulation functions

SVG - SVG manipulation functions

Networking functions index

Net - Networking functions

Packaging functions index

APT - APT package handling functions

DPKG - dpkg package handling functions

GEM - GEM package handling functions

OPAM - OPAM package handling functions

Pkg - High-level package handling functions

SNAP - SNAP package handling functions

Framework self-test functions index

Test

System functions index

CPU - CPU information functions

Desktop - Desktop settings

gnome - GNOME settings

Screen - Screen settings

Sys - System process control functions

XML transformation functions index

XSLT - XML Transformations

YAML file handling functions index

YAML - YAML file handling functions

API documentation

Core framework functions index

Networking functions index

System devices and low-level file system index

Multimedia file manipulation functions index

Packaging functions index

YAML file handling functions index

XML transformation functions index

Framework self-test functions index