Auxiliary implementations for use in Bash scripts. More...
Files | |
file | basis.sh |
BASIS utilities of BASIS package. | |
file | utilities.sh |
Main module of project-independent BASIS utilities. | |
Functions | |
function | abspath (in path) |
Get absolute path given a relative path. | |
function | execute (in options, in cmd, in args) |
Execute command as subprocess. | |
function | exedir (out dir, in name) |
Get directory of executable file. | |
function | exename (out file, in name) |
Get name of executable file. | |
function | exepath (out path, in target) |
Get absolute path of executable file. | |
function | import (in options, in module) |
Import Bash module. | |
function | istarget (in target) |
Determine whether a given build target is known. | |
function | match (in value, in pattern) |
This function implements a more portable way to do pattern matching. | |
function | normpath (in path) |
Clean path, i.e., remove occurences of "./", duplicate slashes,... | |
function | print_contact (in contact) |
Print contact information. | |
function | print_version (in options, in name, in version) |
Print version information including copyright and license notices. | |
function | qsplit (out var, in str) |
Split (quoted) string. | |
function | realpath (in path) |
Get canonical file path. | |
function | targetuid (out uid, in name) |
Get UID of build target. | |
function | tostring (out var, in elements) |
Build quoted string from array. | |
function | upvar (in var, in values) |
Assign variable one scope above the caller. | |
function | upvars () |
Assign variables one scope above the caller. | |
Variables | |
cmake | BASIS_BASH___DIR__ |
Absolute path of directory of current BASH file. | |
cmake | BASIS_BASH___FILE__ |
Absolute path of current BASH file. | |
string | PROJECT = "BASIS" |
Project name. | |
cmake | PROJECT_NAMESPACE_BASH |
CMake variable of BASH namespace of project. | |
string | RELEASE = "r3148" |
Project release. | |
string | VERSION = "0.0.0" |
Project version. | |
int | VERSION_MAJOR = 0 |
Major project version. | |
int | VERSION_MINOR = 0 |
Minor project version. | |
int | VERSION_PATCH = 0 |
Project patch number. |
Detailed Description
Auxiliary implementations for use in Bash scripts.
Function Documentation
function abspath | ( | in | path | ) |
Get absolute path given a relative path.
This function converts a relative path to an absolute path. If the given path is already absolute, this path is passed through unchanged.
- Parameters:
-
[in] path Absolute or relative path.
- Returns:
- Absolute path.
function execute | ( | in | options, |
in | cmd, | ||
in | args | ||
) |
Execute command as subprocess.
This function is used to execute a subprocess within a Bash script.
Example:
# the next command will exit the current shell if it fails execute ls /not/existing # to prevent this, provide the --allow_fail option execute --allow_fail ls /not/existing # to make it explicit where the command-line to execute starts, use -- execute --allow_fail -- ls /not/existing
Note that the output of the command is not redirected by this function. In order to execute the command quietly, use this function as follows:
execute ls / &> /dev/null
Or to store the command output in a variable including error messages use it as follows:
Note that in this case, the option --allow_fail has no effect as the calling shell will never be terminated. Only the subshell in which the command is executed will be terminated. Checking the exit code $? is in this case required.
- Parameters:
-
[in] options Function options as documented below. [in] cmd Executable of command to run or corresponding build target name. This is assumed to be the first non-option argument or the argument that follows the special '--' argument. [in] args All remaining arguments are passed as arguments to the given command.
- Options:
-f, --allow_fail Allows the command to fail. By default, if the command returns a non-zero exit code, the exit() function is called to terminate the current shell. -v, --verbose [int] Print command-line to stdout before execution. Optionally, as it is sometimes more convenient to pass in the value of another variable which controls the verbosity of the parent process itself, a verbosity value can be specified following the option flag. If this verbosity less or equal to zero, the command-line of the subprocess is not printed to stdout, otherwise it is. -s, --simulate If this option is given, the command is not actually executed, but the command-line printed to stdout only.
- Returns:
- Exit code of subprocess.
function exedir | ( | out | dir, |
in | name | ||
) |
Get directory of executable file.
- Parameters:
-
[out] dir Directory of executable file or an empty string if not found. If name
is not given, the directory of this executable is returned.[in] name Name of command or an empty string.
- Returns:
- Whether or not the command was found.
- Return values:
-
0 On success. 1 On failure.
function exename | ( | out | file, |
in | name | ||
) |
Get name of executable file.
- Parameters:
-
[out] file Name of executable file or an empty string if not found. If name
is not given, the name of this executable is returned.[in] name Name of command or an empty string.
- Returns:
- Whether or not the command was found.
- Return values:
-
0 On success. 1 On failure.
function exepath | ( | out | path, |
in | target | ||
) |
Get absolute path of executable file.
This function determines the absolute file path of an executable. If no arguments are given, the absolute path of this executable is returned. If the given argument is a known build target name, the absolute path of the executable built by this target is returned. Otherwise, the named command is searched in the system PATH and it's absolute path returned if found. If the given argument is neither the name of a known build target nor an executable found on the PATH, an empty string is returned and the return value is 1.
- Parameters:
-
[out] path Absolute path of executable file. [in] target Name/UID of build target. If no argument is given, the file path of the calling executable is returned.
- Returns:
- Nothing.
- Return values:
-
0 On success. 1 On failure.
function import | ( | in | options, |
in | module | ||
) |
Import Bash module.
This function can be used to import, i.e., source, a named module, where the module is searched for in the directories specified by the BASHPATH
(environment) variable. Modules can be prepended by the names of the subdirectories they are located in relative to a directory listed in the BASHPATH
, where dots (.) can be used instead of slashes to separate the parts of the relative module path. Moreover, the .sh
extension of the modules is appended to the module name if not specified.
Example:
import sbia.basis.core import -o optional.module if [ $? -eq 0 ]; then echo "Module optional.module imported successfully" else echo "Module optional.module not found" fi
- Note:
- The directories listed in the
BASHPATH
must be absolute paths starting with a forward slash (/).
- Parameters:
-
[in] options Option flags. The only possible option is -o. If this option is given before the module name, the function returns with return value 1 on error. Otherwise, it calls the exit function with this exit code. It can therefore be used for optional modules, which do not necessarily need to be imported. [in] module Name of the module to import.
- Returns:
- Only on success or if the -o option is given. Otherwise it calls the exit function if an error occurs.
- Return values:
-
0 if the module was loaded successfully. 1 on error if -o option is given.
function istarget | ( | in | target | ) |
Determine whether a given build target is known.
- Parameters:
-
[in] target Name of build target.
- Returns:
- Whether the named target is a known executable target.
function match | ( | in | value, |
in | pattern | ||
) |
This function implements a more portable way to do pattern matching.
Unfortunately, there are significant differences in the way patterns have to be matched when using different shells. This function considers which shell is used (at the moment only BASH), and uses the appropriate syntax for the pattern matching.
- Parameters:
-
[in] value The string to match against pattern. [in] pattern The pattern to match.
- Returns:
- Whether the given string matches the given pattern.
- Return values:
-
0 On match. 1 Otherwise.
function normpath | ( | in | path | ) |
Clean path, i.e., remove occurences of "./", duplicate slashes,...
This function removes single periods (.) enclosed by slashes or backslashes, duplicate slashes (/) or backslashes (\), and further tries to reduce the number of parent directory references.
For example, "../bla//.//.\bla\\\\\bla/../.." is convert to "../bla".
- Parameters:
-
[in] path Path.
- Returns:
- Cleaned path.
function print_contact | ( | in | contact | ) |
Print contact information.
- Parameters:
-
[in] contact Name of contact. Defaults to ${CONTACT}
.
- Returns:
- Nothing.
function print_version | ( | in | options, |
in | name, | ||
in | version | ||
) |
Print version information including copyright and license notices.
Example:
print_version 'foo' '1.0' print_version 'foo' -v '1.0' print_version -v 1.0 -p BarStool 'foo' print_version 'foo' -v '1.2' -c '2012 University of Pennsylvania' \ -l 'Apache License, Version 2.0'
- Parameters:
-
[in] options Function options as documented below. [in] name Name of executable. Should not be set programmatically to the first argument of the main script, but a string literal instead. [in] version Version of executable. Defaults to ${RELEASE}
if defined, otherwise this argument is required.
- Options:
-v, --version <version> Version of executable. Can be either given as option or second positional argument after the name
.-p, --project <name> Name of project this executable belongs to. Defaults to ${PROJECT}
if defined. If 'none', no project information is printed.-c --copyright <copyright> The copyright notice. Defaults to ${COPYRIGHT}
. If 'none', no copyright notice is printed.-l --license <license> Information regarding licensing. Defaults to ${LICENSE}
. If 'none', no license information is printed.
- Returns:
- Nothing.
function qsplit | ( | out | var, |
in | str | ||
) |
Split (quoted) string.
This function can be used to split a (quoted) string into its elements.
Example:
str="'this' 'isn\'t' a \"simple example of \\\"a quoted\\\"\" 'string'" qsplit array "${str}" echo ${#array[@]} # 5 echo "${array[3]}" # simple example of "a quoted"
- Parameters:
-
[out] var Result variable for array. [in] str Quoted string.
- Returns:
- Nothing.
function realpath | ( | in | path | ) |
Get canonical file path.
This function resolves symbolic links and returns a cleaned path.
- Parameters:
-
[in] path Path.
- Returns:
- Canonical file path without duplicate slashes, ".", "..", and symbolic links.
function targetuid | ( | out | uid, |
in | name | ||
) |
Get UID of build target.
The UID of a build target is its name prepended by a namespace identifier which should be unique for each project.
This function further initializes the dictionary storing the information about the executable targets upon the first invocation. Reason to do it here is that every access to the dictionaries first calls this function to get the UID of a build target. Moreover, also this function needs to have the already initialized dictionaries to ensure that an already valid target identifier is not modified. As Bash does not provide hash tables, dictionary data structures, the imitation of these is necessary which, however, results in many eval() calls with noticeable impact on running time. Therefore, to decrease the time required to source the BASIS utilities, the required dictionary structure is initialized only upon first use.
- Parameters:
-
[out] uid UID of named build target. [in] name Name of build target.
- Returns:
- Nothing.
- Return values:
-
0 On success. 1 On failure.
function tostring | ( | out | var, |
in | elements | ||
) |
Build quoted string from array.
Example:
tostring str 'this' "isn't" a 'simple example of "a quoted"' 'string' echo "${str}"
- Parameters:
-
[out] var Name of result variable for quoted string. [in] elements All remaining arguments are considered to be the elements of the array to convert.
- Returns:
- Nothing.
function upvar | ( | in | var, |
in | values | ||
) |
Assign variable one scope above the caller.
This function can be used inside functions to return values by assigning them to a variable in the scope of the caller.
- Note:
- For assigning multiple variables, use upvars(). Do NOT use multiple upvar() calls, since one upvar() call might reassign a variable to be used by another upvar() call.
Example:
foo () { local "$1" && upvar $1 "Hello, World!" } foo greeting echo ${greeting}
- Parameters:
-
[in] var Variable name to assign value to [in] values Value(s) to assign. If multiple values, an array is assigned, otherwise a single value is assigned.
- Returns:
- Nothing.
- Return values:
-
0 On success. 1 On failure.
function upvars | ( | ) |
Assign variables one scope above the caller.
- Synopsis
- local varname [varname ...] && upvars [-v varname value] | [-aN varname [value ...]] ...
- Options:
- -aN Assign next N values to varname as array
- -v Assign single value to varname#
- Return values:
-
0 On success. 1 On failure.
- Returns:
- Nothing.
Variable Documentation
cmake BASIS_BASH___DIR__ |
Absolute path of directory of current BASH file.
- Note:
- Does not resolve symbolic links.
Example:
readonly __MYMODULE_dir=@BASIS_BASH___DIR__@
Definition at line 141 of file UtilitiesTools.cmake.
cmake BASIS_BASH___FILE__ |
Absolute path of current BASH file.
- Note:
- Does not resolve symbolic links.
Example:
readonly __MYMODULE=@BASIS_BASH___FILE__@
Definition at line 128 of file UtilitiesTools.cmake.
cmake PROJECT_NAMESPACE_BASH |
CMake variable of BASH namespace of project.
In BASH, there exists no such concept of a namespace or package. However, variable and function names defined in a module which is supposed to be sourced by other BASH scripts should use a unique prefix for variable and function names.
Definition at line 127 of file ProjectSettings.cmake.
string RELEASE = "r3148" |
string VERSION = "0.0.0" |
int VERSION_MAJOR = 0 |
int VERSION_MINOR = 0 |
int VERSION_PATCH = 0 |