Auxiliary implementations for use in BASH scripts. More...

Collaboration diagram for BASH Utilities:

Files
file	basis.sh
	Main module of BASIS BASH Utilities.
Functions
function	basis_array_to_quoted_string (in var, in elements)
	Build quoted string from array.
function	basis_split (in var, in str)
	Split (quoted) string.
function	execute_process (in options, in cmd, in args)
	Execute command as subprocess.
function	get_executable_directory (in dir, in target)
	Get directory of executable file.
function	get_executable_name (in name, in target)
	Get name of executable file.
function	get_executable_path (in path, in target)
	Get absolute path of executable file.
function	get_target_uid (in uid, in target)
	Get UID of build target.
function	is_known_target (in target)
	Determine whether a given target is known.
function	match (in value, in pattern)
	This function implements a more portable way to do pattern matching.
function	print_contact (in contact)
	Print contact information.
function	print_version (in name, in copyright)
	Print version information.
function	upvar (in var, in values)
	Assign variable one scope above the caller.
function	upvars ()
	Assign variables one scope above the caller.
Variables
	BASIS_BASH___DIR__
	Absolute path of directory of current BASH file.
	BASIS_BASH___FILE__
	Absolute path of current BASH file.
	BASIS_BASH_FUNCTION_realpath
	Definition of realpath() function.
	BASIS_BASH_UTILITIES
	Include BASIS utilities for BASH.
	PROJECT_NAMESPACE_BASH
	CMake variable of BASH namespace of project.

Detailed Description

Auxiliary implementations for use in BASH scripts.

Function Documentation

function basis_array_to_quoted_string	(	in	var,
		in	elements
	)

Build quoted string from array.

Example:

 basis_array_to_quoted_string 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 basis_split	(	in	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'"
 basis_split 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 execute_process	(	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_process ls /not/existing
 # to prevent this, provide the --allow_fail option
 execute_process --allow_fail ls /not/existing
 # to make it explicit where the command-line to execute starts, use --
 execute_process --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_process ls / &> /dev/null

Or to store the command output in a variable including error messages use it as follows:

 output=`execute_process ls / 2>&1`

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:

--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.
--verbose, -v	Print command-line to stdout before execution.
--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 get_executable_directory	(	in	dir,
		in	target
	)

Get directory of executable file.

Parameters:

[out]	dir	Absolute directory of executable file.
[in]	target	Name/UID of build target. If no argument is given, the directory where the file of the calling executable is located is returned.

Returns:: Nothing.

Return values:

0	On success.
1	On failure.

function get_executable_name	(	in	name,
		in	target
	)

Get name of executable file.

Parameters:

[out]	name	Name of the executable or an empty string if unknown.
[in]	target	Name/UID of build target. If no argument is given, the name of the calling executable is returned instead.

Returns:: Nothing.

Return values:

0	On success.
1	On failure.

function get_executable_path	(	in	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 get_target_uid	(	in	uid,
		in	target
	)

Get UID of build target.

Parameters:

[out]	uid	UID of build target.
[in]	target	Name/UID of build target.

Returns:: Nothing.

Return values:

0	On success.
1	On failure.

function is_known_target ( in target )

Determine whether a given target is known.

Parameters:

[in] target Name/UID of build target.

Returns:: Whether the given build target is known by this module.

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 print_contact ( in contact )

Print contact information.

Parameters:

[in] contact Contact name. Defaults to official software contact. Generally, it is not advised to use a contact different from the official one.

Returns:: Nothing.

function print_version	(	in	name,
		in	copyright
	)

Print version information.

Parameters:

[in]	name	Name of program. Give a constant expression here, not the name of the executable as extracted from the first command-line argument or similar! By default, however, the executable name is extracted from the first command-line argument. This is not recommended.
[in]	copyright	Copyright and license notice. Defaults to official SBIA software license.

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}

Todo:: Under some circumstances, the 'local "$1" &&' part of the upvar() usage example has to be skipped. It is not yet clear what the correct solution/usage really is...

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.

See also:: upvars(); http://fvue.nl/wiki/Bash:_Passing_variables_by_reference

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.

See also:: http://fvue.nl/wiki/Bash:_Passing_variables_by_reference

Variable Documentation

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 110 of file UtilitiesTools.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 97 of file UtilitiesTools.cmake.

BASIS_BASH_FUNCTION_realpath

Definition of realpath() function.

Example:

 #! /usr/bin/env bash
 @BASIS_BASH_FUNCTION_realpath@
 exec_dir=$(realpath $0)

See also:: http://stackoverflow.com/questions/7665/how-to-resolve-symbolic-links-in-a-shell-script

Definition at line 125 of file UtilitiesTools.cmake.

BASIS_BASH_UTILITIES

Include BASIS utilities for BASH.

Example:

 #! /usr/bin/env bash
 @BASIS_BASH_UTILITIES@
 get_executable_directory exec_dir
 get_executable_name      exec_name

 echo "The executable ${exec_name} is located in ${exec_dir}."

Definition at line 178 of file UtilitiesTools.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.

The BASH module namespace of a BASIS project is made up of its name in upper case only to distinguish it from the actual variable or function name as well as the namespace of the project it belongs to.

Example:

 # The project's namespace is SBIA_BASIS and the name of the
 # module in this example is mymodule.sh. This gives the fully-qualified module
 # namespace SBIA_BASIS_MYMODULE. Note that private identifiers
 # are further
 # prefixed with an underscore '_'.

 # return if already loaded
 [ "${_SBIA_BASIS_MYMODULE_INCLUDED:-0}" -eq 1 ] && return 0
 _SBIA_BASIS_MYMODULE_INCLUDED=1

 # define private global variable
 _SBIA_BASIS_MYMODULE_verbose=0

 # define public function
 #
 # Note: To not complicate the use of the module, the name must not necessarily
 #       include the fully-qualified namespace identifier, but the name should
 #       chosen carefully to avoid name conflicts with other modules.
 MYMODULE_string()
 {
     # ...
 }

Definition at line 266 of file ProjectSettings.cmake.

Files

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation