Classes | Functions
basis::util Namespace Reference

Classes

class  IExecutableTargetInfo
 Provides information about executable build targets. More...
 
class  SubprocessError
 Exception type thrown by execute(). More...
 

Functions

int execute (const std::string &cmd, bool quiet=false, std::ostream *out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false, const IExecutableTargetInfo *targets=NULL)
 Execute command as subprocess. More...
 
int execute (std::vector< std::string > args, bool quiet=false, std::ostream *out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false, const IExecutableTargetInfo *targets=NULL)
 Execute command as subprocess. More...
 
std::string exedir (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
 Get directory of executable file. More...
 
std::string exename (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
 Get name of executable file. More...
 
std::string exepath (const std::string &name=std::string(), const IExecutableTargetInfo *targets=NULL)
 Get absolute path of executable file. More...
 
bool istarget (const std::string &name, const IExecutableTargetInfo *targets=NULL)
 Determine whether a given build target is known. More...
 
void print_contact (const char *contact)
 Print contact information. More...
 
void print_version (const char *name, const char *version, const char *project=NULL, const char *copyright=NULL, const char *license=NULL)
 Print version information including copyright and license notices. More...
 
std::vector< std::string > qsplit (const std::string &args)
 Split quoted string. More...
 
std::string targetuid (const std::string &name, const IExecutableTargetInfo *targets=NULL)
 Get UID of build target. More...
 
std::string tostring (const std::vector< std::string > &args)
 Convert array of arguments to quoted string. More...
 

Function Documentation

§ execute() [1/2]

int basis::util::execute ( const std::string &  cmd,
bool  quiet = false,
std::ostream *  out = NULL,
bool  allow_fail = false,
int  verbose = 0,
bool  simulate = false,
const IExecutableTargetInfo targets = NULL 
)

Execute command as subprocess.

This function is a replacement for system() on Unix and is furthermore less platform dependent. The first argument of the given command-line string is mapped to an absolute executable file using exepath() if the given first argument is a know build target name. Otherwise, the command-line is used unmodified.

Parameters
[in]cmdCommand-line given as double quoted string. Arguments containing whitespaces have to be quoted using double quotes. Use a backslash (\) to escape double quotes inside an argument as well as to escape a backslash itself (required if backslash at end of double quoted argument, e.g., "this argument \\").
[in]quietTurns off output of stdout of child process to stdout of parent process.
[out]outOutput stream where command output is written to.
[in]allow_failIf true, no exception is thrown if the exit code of the child process is non-zero. Otherwise, a SubprocessException object is thrown in that case.
[in]verboseVerbosity of output messages. Does not affect verbosity of executed command.
[in]simulateWhether to simulate command execution only.
[in]targetsStructure providing information about executable targets.
Returns
Exit code of command or -1 if subprocess creation failed.
Exceptions
SubprocessErrorIf subprocess creation failed or command returned a non-zero exit code while allow_fail is false.

Definition at line 138 of file utilities.cxx.

§ execute() [2/2]

int basis::util::execute ( std::vector< std::string >  args,
bool  quiet = false,
std::ostream *  out = NULL,
bool  allow_fail = false,
int  verbose = 0,
bool  simulate = false,
const IExecutableTargetInfo targets = NULL 
)

Execute command as subprocess.

This function is a replacement for system() on Unix and is furthermore less platform dependent. The first argument of the given command-line string is mapped to an absolute executable file using exepath() if the given first argument is a know build target name. Otherwise, the command-line is used unmodified.

Parameters
[in]argsCommand-line given as argument vector. The first argument has to be either a build target name or the name/path of the command to execute. Note that as a side effect, the first argument of the input vector is replaced by the absolute path of the actual executable file if applicable.
[in]quietTurns off output of stdout of child process to stdout of parent process.
[out]outOutput stream where command output is written to.
[in]allow_failIf true, no exception is thrown if the exit code of the child process is non-zero. Otherwise, a SubprocessException object is thrown in that case.
[in]verboseVerbosity of output messages. Does not affect verbosity of executed command.
[in]simulateWhether to simulate command execution only.
[in]targetsStructure providing information about executable targets.
Returns
Exit code of command or -1 if subprocess creation failed.
Exceptions
SubprocessErrorIf subprocess creation failed or command returned a non-zero exit code while allow_fail is false.

Definition at line 147 of file utilities.cxx.

§ exedir()

string basis::util::exedir ( const std::string &  name = std::string(),
const IExecutableTargetInfo targets = NULL 
)

Get directory of executable file.

Parameters
[in]nameName of command or NULL.
[in]targetsStructure providing information about executable targets.
Returns
Absolute path to directory containing executable or an empty string if not found. If name is NULL, the directory of this executable is returned.
See also
exepath()

Definition at line 115 of file utilities.cxx.

§ exename()

string basis::util::exename ( const std::string &  name = std::string(),
const IExecutableTargetInfo targets = NULL 
)

Get name of executable file.

The name of the executable may or may not include the file name extension depending on the executable type and operating system. Hence, this function is neither an equivalent to os::path::basename(exepath()) nor os::path::filename(exepath()). In particular, on Windows, the .exe and .com extension is not included in the returned executable name.

Parameters
[in]nameName of command or NULL.
[in]targetsStructure providing information about executable targets.
Returns
Name of executable file or an empty string if not found. If name is NULL, the name of this executable is returned.
See also
exepath()

Definition at line 102 of file utilities.cxx.

§ exepath()

string basis::util::exepath ( const std::string &  name = std::string(),
const IExecutableTargetInfo targets = NULL 
)

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 command names a known executable build target, the absolute path to the corresonding built (and installed) executable file is returned. Otherwise, the named command is searched in the system PATH and its absolute path returned if found. If the executable is not found, an empty string is returned.

Todo:
This function currently makes use of the which command implemented in Python and called as subprocess in order to search a command in the system PATH. This which command is part of BASIS and can also be used on Windows. However, a native C++ implementation would be desireable.
Parameters
[in]nameName of command or NULL.
[in]targetsStructure providing information about executable targets.
Returns
Absolute path of executable or an empty string if not found. If name is NULL, the path of this executable is returned.
See also
exename()
exedir()

Definition at line 64 of file utilities.cxx.

§ istarget()

bool basis::util::istarget ( const std::string &  name,
const IExecutableTargetInfo targets = NULL 
)

Determine whether a given build target is known.

Parameters
[in]nameName of build target.
[in]targetsStructure providing information about executable targets.
Returns
Whether the named target is a known executable target.

Definition at line 58 of file utilities.cxx.

§ print_contact()

void basis::util::print_contact ( const char *  contact)

Print contact information.

Parameters
[in]contactName of contact.

Definition at line 33 of file utilities.cxx.

§ print_version()

void basis::util::print_version ( const char *  name,
const char *  version,
const char *  project = NULL,
const char *  copyright = NULL,
const char *  license = NULL 
)

Print version information including copyright and license notices.

Parameters
[in]nameName of executable. Should not be set programmatically to the first argument of the main() function, but a string literal instead.
[in]versionVersion of executable, e.g., release of project this executable belongs to.
[in]projectName of project this executable belongs to. If NULL or an empty string, no project information is printed.
[in]copyrightThe copyright notice, excluding the common prefix "Copyright (c) " and suffix ". All rights reserved.". If NULL or an empty string, no copyright notice is printed.
[in]licenseInformation regarding licensing. If NULL or an empty string, no license information is printed.

Definition at line 39 of file utilities.cxx.

§ qsplit()

vector< string > basis::util::qsplit ( const std::string &  args)

Split quoted string.

Parameters
[in]argsQuoted string of arguments.
Returns
Array of arguments.
See also
tostring()

Definition at line 132 of file utilities.cxx.

§ targetuid()

string basis::util::targetuid ( const std::string &  name,
const IExecutableTargetInfo targets = NULL 
)

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.

Parameters
[in]nameName of build target.
[in]targetsStructure providing information about executable targets.
Returns
UID of named build target.

Definition at line 52 of file utilities.cxx.

§ tostring()

string basis::util::tostring ( const std::vector< std::string > &  args)

Convert array of arguments to quoted string.

Parameters
[in]argsArray of arguments.
Returns
Double quoted string, i.e., string where arguments are separated by a space character and surrounded by double quotes if necessary. Double quotes within an argument are escaped with a backslash.
See also
split()

Definition at line 126 of file utilities.cxx.