Files
file	utilities.sh
	Main module of project-independent BASIS utilities.

Functions
function	abspath (in path)
	Get absolute path given a relative path. More...

function	execute (in options, in cmd, in args)
	Execute command as subprocess. More...

function	exedir (out dir, in name)
	Get directory of executable file. More...

function	exename (out file, in name)
	Get name of executable file. More...

function	exepath (out path, in target)
	Get absolute path of executable file. More...

function	import (in options, in module)
	Import Bash module. More...

function	istarget (in target)
	Determine whether a given build target is known. More...

function	match (in value, in pattern)
	This function implements a more portable way to do pattern matching. More...

function	normpath (in path)
	Clean path, i.e., remove occurences of "./", duplicate slashes,... More...

function	print_contact (in contact)
	Print contact information. More...

function	print_version (in options, in name, in version)
	Print version information including copyright and license notices. More...

function	qsplit (out var, in str)
	Split (quoted) string. More...

function	realpath (in path)
	Get canonical file path. More...

function	targetuid (out uid, in name)
	Get UID of build target. More...

function	tostring (out var, in elements)
	Build quoted string from array. More...

function	upvar (in var, in values)
	Assign variable one scope above the caller. More...

function	upvars ()
	Assign variables one scope above the caller. More...

Variables
cmake	BASIS_BASH___DIR__
	Absolute path to directory of current BASH file. More...

cmake	BASIS_BASH___FILE__
	Absolute path of current BASH file. More...

cmake	PROJECT_NAMESPACE_BASH
	CMake variable of BASH namespace of project. More...

Detailed Description

Function Documentation

§ abspath()

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.

§ execute()

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:

output=`execute 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:

-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.

§ exedir()

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.

§ exename()

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.

§ exepath()

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.

§ import()

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. A .sh file name extension of the modules is appended to the module name when looking for a matching Bash module file. It must not be included in the module name to avoid confusion with the dot used as path / submodule separator. The module name "utils.sh" thus translates to the file path "utils/sh.sh"!

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 (excl. .sh file name extension).

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.

§ istarget()

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.

§ match()

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.

§ normpath()

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.

§ print_contact()

function print_contact ( in contact )

Print contact information.

Parameters

[in] contact Name of contact. Defaults to ${CONTACT}.

Returns: Nothing.

§ print_version()

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.

§ qsplit()

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.

§ realpath()

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.

§ targetuid()

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.

§ tostring()

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.

§ upvar()

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.

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

§ upvars()

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

Returns: Nothing.

Variable Documentation

§ BASIS_BASH_DIR

cmake BASIS_BASH___DIR__

Absolute path to directory of current BASH file.

Note: Does not resolve symbolic links.

Example:

readonly __MYMODULE_dir=@BASIS_BASH___DIR__@

Definition at line 308 of file UtilitiesTools.cmake.

§ BASIS_BASH_FILE

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

§ PROJECT_NAMESPACE_BASH

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 139 of file ProjectSettings.cmake.

Files

Functions

Variables

Detailed Description

Function Documentation

§ abspath()

§ execute()

§ exedir()

§ exename()

§ exepath()

§ import()

§ istarget()

§ match()

§ normpath()

§ print_contact()

§ print_version()

§ qsplit()

§ realpath()

§ targetuid()

§ tostring()

§ upvar()

§ upvars()

Variable Documentation

§ BASIS_BASH___DIR__

§ BASIS_BASH___FILE__

§ PROJECT_NAMESPACE_BASH

§ BASIS_BASH_DIR

§ BASIS_BASH_FILE