BASIS  r3148
basis Namespace Reference

Namespaces

namespace  argparse
namespace  diff3
namespace  os
namespace  util
namespace  utilities
namespace  which

Classes

class  CmdLine
 Manages command line definition and parsing of arguments. More...
class  ExistingDirectoryConstraint
 Constrain argument values to paths of existing directories. More...
class  ExistingFileConstraint
 Constrain argument values to paths of existing files. More...
class  MultiArg
 An argument that allows multiple values of type T to be specified. More...
class  NegativeValueConstraint
 Constrain argument values to negative values. More...
class  NonZeroValueConstraint
 Constrain argument values to non-zero values. More...
class  PositiveValueConstraint
 Constrain argument values to positive values. More...
class  Subprocess
 Platform-independent interface to create and control a subprocess. More...
class  ValueArg
 An argument that allows multiple values of type T to be specified. More...
class  ZeroOrNegativeValueConstraint
 Constrain argument values to zero or negative values. More...
class  ZeroOrPositiveValueConstraint
 Constrain argument values to zero or positive values. More...

Typedefs

typedef TCLAP::Arg Arg
 Base type of command-line arguments.
typedef TCLAP::ArgException ArgException
 Exception thrown by command-line parsing library.
typedef TCLAP::ArgParseException ArgParseException
 Exception thrown on command-line argument parsing error.
typedef
TCLAP::SpecificationException 
CmdLineException
 Exception thrown when command-line specification is wrong.
typedef
TCLAP::CmdLineParseException 
CmdLineParseException
 Exception thrown on command-line parsing error.
typedef basis::ValueArg< double > DoubleArg
 Floating-point argument (double precision).
typedef TCLAP::ExitException ExitException
 Exception thrown by command-line parsing library to indicate that program should exit with the given exit code.
typedef basis::ValueArg< float > FloatArg
 Floating-point argument.
typedef basis::ValueArg< int > Int32Arg
 Signed 32-bit integer argument.
typedef basis::ValueArg< long > Int64Arg
 Signed 64-bit integer argument.
typedef basis::ValueArg< int > IntArg
 Alias for Int32Arg.
typedef basis::MultiArg< double > MultiDoubleArg
 Floating-point argument (double precision, multiple occurrences allowed).
typedef basis::MultiArg< float > MultiFloatArg
 Floating-point argument (multiple occurrences allowed).
typedef basis::MultiArg< int > MultiInt32Arg
 Signed 32-bit integer argument (multiple occurrences allowed).
typedef basis::MultiArg< long > MultiInt64Arg
 Signed 64-bit integer argument (multiple occurrences allowed).
typedef basis::MultiArg< int > MultiIntArg
 Alias for MultiInt32Arg.
typedef basis::MultiArg
< std::string > 
MultiStringArg
 String argument (multiple occurrences allowed).
typedef TCLAP::MultiSwitchArg MultiSwitchArg
 Counts occurrences of option switch.
typedef basis::MultiArg
< unsigned int > 
MultiUInt32Arg
 Unsigned 32-bit integer argument (multiple occurrences allowed).
typedef basis::MultiArg
< unsigned long > 
MultiUInt64Arg
 Unsigned 64-bit integer argument (multiple occurrences allowed).
typedef basis::MultiArg
< unsigned int > 
MultiUIntArg
 Alias for MultiUInt32Arg.
typedef
TCLAP::UnlabeledValueArg
< std::string > 
PositionalArg
 Positional argument.
typedef
TCLAP::UnlabeledMultiArg
< std::string > 
PositionalArgs
 Positional arguments.
typedef basis::ValueArg
< std::string > 
StringArg
 String argument.
typedef
TCLAP::ValuesConstraint
< std::string > 
StringValuesConstraint
 Constrains string arguments to allow only predefined values.
typedef TCLAP::SwitchArg SwitchArg
 Switch to enable/disable option.
typedef basis::ValueArg
< unsigned int > 
UInt32Arg
 Unsigned 32-bit integer argument.
typedef basis::ValueArg
< unsigned long > 
UInt64Arg
 Unsigned 64-bit integer argument.
typedef basis::ValueArg
< unsigned int > 
UIntArg
 Alias for UInt32Arg.

Functions

std::string bindir ()
 Get absolute path of directory containing runtime executables.
std::string datadir ()
 Get absolute path of directory containing auxiliary data.
int execute (const std::string &cmd, bool quiet=false, std::ostream *out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false)
 Execute command as subprocess.
int execute (std::vector< std::string > args, bool quiet=false, std::ostream *out=NULL, bool allow_fail=false, int verbose=0, bool simulate=false)
 Execute command as subprocess.
def execute
 Execute command as subprocess.
std::string exedir (const std::string &name=std::string())
 Get directory of executable file.
def exedir
 Get directory of executable file.
std::string exename (const std::string &name=std::string())
 Get name of executable file.
def exename
 Get name of executable file.
std::string exepath (const std::string &name=std::string())
 Get absolute path of executable file.
def exepath
 Get absolute path of executable file.
int get_terminal_columns ()
 Get maximum number of columns of terminal window.
int get_terminal_lines ()
 Get maximum number of lines of terminal window.
void get_terminal_size (int &lines, int &columns)
 Get size of terminal window.
bool istarget (const std::string &name)
 Determine whether a given build target is known.
def istarget
 Determine whether a given build target is known.
std::string libdir ()
 Get absolute path of directory containing libraries.
std::string libexecdir ()
 Get absolute path of directory containing auxiliary executables.
void print_contact (const char *contact=NULL)
 Print contact information.
def print_contact
 Print contact information.
void print_version (const char *name, const char *version=NULL, const char *project=NULL, const char *copyright=NULL, const char *license=NULL)
 Print version information including copyright and license notices.
def print_version
 Print version information including copyright and license notices.
std::ostream & print_wrapped (std::ostream &os, const std::string &text, int width, int indent, int offset)
 Print text, wrapped at a fixed maximum number of columns.
std::string targetuid (const std::string &name)
 Get UID of build target.
def targetuid
 Get UID of build target.

Variables

list __all__ = []
dictionary _EXECUTABLE_TARGETS
tuple _path = os.getenv('BASIS_PYTHONPATH')
string _TARGET_UID_PREFIX = 'basis'
tuple _TARGETS_BASE = os.path.dirname(os.path.realpath(__file__))
tuple basis = imp.load_module('basis', _file, _filepath, _desc)
const char * CONTACT = "SBIA Group <sbia-software at uphs.upenn.edu>"
 Default contact to use for help output of executables.
const char * COPYRIGHT = "2011, 2012, 2013 University of Pennsylvania"
 Default copyright of executables.
const char * LICENSE = "See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file."
 Default license of executables.
const char * PROJECT = "BASIS"
 The project name.
 qsplit = utilities.qsplit
 Split quoted string of arguments.
const char * RELEASE = "r3148"
 Complete version information as output by --version option.
 SubprocessError = utilities.SubprocessError
 Exception thrown when command execution failed.
 tostring = utilities.tostring
 Convert array of arguments to quoted string.
tuple utilities = imp.load_module('basis.utilities', _file, _filepath, _desc)
const char * VERSION = "0.0.0"
 The version string given as "<major>.<minor>.<patch>".
const unsigned int VERSION_MAJOR = 0
 The major version number.
const unsigned int VERSION_MINOR = 0
 The minor version number.
const unsigned int VERSION_PATCH = 0
 The patch number.

Typedef Documentation

typedef TCLAP::ArgException basis::ArgException

Exception thrown by command-line parsing library.

Definition at line 58 of file except.h.

typedef TCLAP::ArgParseException basis::ArgParseException

Exception thrown on command-line argument parsing error.

Definition at line 65 of file except.h.

typedef TCLAP::SpecificationException basis::CmdLineException

Exception thrown when command-line specification is wrong.

Definition at line 71 of file except.h.

typedef TCLAP::CmdLineParseException basis::CmdLineParseException

Exception thrown on command-line parsing error.

Definition at line 68 of file except.h.

typedef TCLAP::ExitException basis::ExitException

Exception thrown by command-line parsing library to indicate that program should exit with the given exit code.

Definition at line 62 of file except.h.


Function Documentation

string basis::bindir ( )

Get absolute path of directory containing runtime executables.

Returns:
Absolute path of directory containing runtime executables.

Definition at line 199 of file basis.cxx.

string basis::datadir ( )

Get absolute path of directory containing auxiliary data.

Returns:
Absolute path of directory containing auxiliary data.

Definition at line 229 of file basis.cxx.

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

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.
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 293 of file basis.cxx.

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

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,out]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.
[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.
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 301 of file basis.cxx.

string basis::exedir ( const std::string &  name = std::string())

Get directory of executable file.

Parameters:
[in]nameName of command or NULL.
Returns:
Absolute path of 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 283 of file basis.cxx.

string basis::exename ( const std::string &  name = std::string())

Get name of executable file.

Note:
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.
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 277 of file basis.cxx.

string basis::exepath ( const std::string &  name = std::string())

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.
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 271 of file basis.cxx.

bool basis::istarget ( const std::string &  name)

Determine whether a given build target is known.

Parameters:
[in]nameName of build target.
Returns:
Whether the named target is a known executable target.

Definition at line 265 of file basis.cxx.

string basis::libdir ( )

Get absolute path of directory containing libraries.

Returns:
Absolute path of directory containing libraries.

Definition at line 219 of file basis.cxx.

string basis::libexecdir ( )

Get absolute path of directory containing auxiliary executables.

Returns:
Absolute path of directory containing auxiliary executables.

Definition at line 209 of file basis.cxx.

void basis::print_contact ( const char *  contact = NULL)

Print contact information.

Parameters:
[in]contactName of contact. If NULL, CONTACT is used.

Definition at line 243 of file basis.cxx.

void basis::print_version ( const char *  name,
const char *  version = NULL,
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. Defaults to RELEASE.
[in]projectName of project this executable belongs to. If NULL, defaults to PROJECT. If 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, COPYRIGHT is used. If an empty string, no copyright notice is printed.
[in]licenseInformation regarding licensing. If NULL, LICENSE is used. If an empty string, no license information is printed.

Definition at line 249 of file basis.cxx.

string basis::targetuid ( const std::string &  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.

Parameters:
[in]nameName of build target.
Returns:
UID of named build target.

Definition at line 259 of file basis.cxx.


Variable Documentation

list basis::__all__ = []

Definition at line 11 of file __init__.py.

tuple basis::_path = os.getenv('BASIS_PYTHONPATH')

Definition at line 41 of file basis.py.

tuple basis::basis = imp.load_module('basis', _file, _filepath, _desc)

Definition at line 58 of file basis.py.

tuple basis::utilities = imp.load_module('basis.utilities', _file, _filepath, _desc)

Definition at line 64 of file basis.py.