Elements 6.3.1
A C++ base framework for the Euclid Software.
Loading...
Searching...
No Matches
ElementsKernel: The Kernel Module of the Elements Framework

Core CMake, C++ and Python utilities. More...

Collaboration diagram for ElementsKernel: The Kernel Module of the Elements Framework:

Namespaces

namespace  Elements
 
namespace  Elements::System
 
namespace  boost
 
namespace  boost::program_options
 

Classes

class  BoostTestAdapter
 
class  GoogleMockSetupFixture
 
class  Elements::Environment
 Python dictionary-like Environment interface. More...
 
class  Elements::Environment::Variable
 proxy class to overload the assignment More...
 
class  Elements::Exception
 Elements base exception class. More...
 
class  Elements::Logging
 Logging API of the Elements framework. More...
 
class  Elements::Program
 Abstract class for all Elements programs. More...
 
class  Elements::ProgramManager
 Class for managing all Elements programs. More...
 

Macros

#define __attribute__(x)
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_AUXILIARY_IMPL_
 
#define NON_REDUNDANT_MOVE(x)   std::move(x)
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_CONFIGURATION_IMPL_
 
#define ELEMENTS_DEPRECATED   __attribute__((__deprecated__))
 
#define ELEMENTS_DEPRECATED_MSG(msg)   __attribute__((__deprecated__(msg)))
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_EXCEPTION_IMPL_
 
#define ELEMENTS_API
 Dummy definitions for the backward compatibility mode.
 
#define ELEMENTS_IMPORT
 
#define ELEMENTS_EXPORT
 
#define ELEMENTS_LOCAL
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_FUNCPTRCAST_IMPL_
 
#define LIKELY(x)   x
 
#define UNLIKELY(x)   x
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_LOGGING_IMPL_
 
#define ELEMENTS_DEFAULT_LOGLEVEL   DEBUG
 
#define CREATE_MANAGER_WITH_ARGS(MANAGER, ELEMENTS_PROGRAM, ...)
 
#define CREATE_MANAGER(ELEMENTS_PROGRAM_NAME, MANAGER)   CREATE_MANAGER_WITH_ARGS(MANAGER, ELEMENTS_PROGRAM_NAME, )
 
#define MAIN_FOR_WITH_ARGS(ELEMENTS_PROGRAM, ...)
 
#define MAIN_FOR(ELEMENTS_PROGRAM_NAME)   MAIN_FOR_WITH_ARGS(ELEMENTS_PROGRAM_NAME, )
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_MODULE_IMPL_
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_NUMBER_IMPL_
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_PATH_IMPL_
 Macro to prevent the direct inclusion of the implementation file.
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_PATHSEARCH_IMPL_
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_PROGRAM_MANAGER_IMPL_
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_PROJECT_IMPL_
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_REAL_IMPL_
 
#define MAIN(ELEMENTS_PROGRAM)
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_STORAGE_IMPL_
 
#define _xstr(s)   str(s)
 
#define _str(s)   #s
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_THIS_MODULE_IMPL_
 
#define ELEMENTS_UNUSED   __attribute__((unused))
 
#define ELEMENTSKERNEL_ELEMENTSKERNEL_VERSION_IMPL_
 

Enumerations

enum class  Elements::ExitCode : int {
  Elements::ExitCode::OK = 0 , Elements::ExitCode::NOT_OK = 1 , Elements::ExitCode::USAGE = 64 , Elements::ExitCode::DATAERR = 65 ,
  Elements::ExitCode::NOINPUT = 66 , Elements::ExitCode::NOUSER = 67 , Elements::ExitCode::NOHOST = 68 , Elements::ExitCode::UNAVAILABLE = 69 ,
  Elements::ExitCode::SOFTWARE = 70 , Elements::ExitCode::OSERR = 71 , Elements::ExitCode::OSFILE = 72 , Elements::ExitCode::CANTCREAT = 73 ,
  Elements::ExitCode::IOERR = 74 , Elements::ExitCode::TEMPFAIL = 75 , Elements::ExitCode::PROTOCOL = 76 , Elements::ExitCode::NOPERM = 77 ,
  Elements::ExitCode::CONFIG = 78
}
 Strongly typed exit numbers. More...
 

Functions

ELEMENTS_API std::string Elements::Kernel::getAuxiliaryVariableName ()
 retrieve the variable name used for the auxiliary file lookup
 
ELEMENTS_API std::string Elements::Kernel::Auxiliary::getVariableName ()
 alias for the getAuxiliaryVariableName function
 
template<typename T >
ELEMENTS_API Path::Item Elements::Kernel::Auxiliary::getPath (const T &file_name, bool raise_exception=true)
 alias for the getAuxiliaryPath function
 
ELEMENTS_API std::vector< Path::ItemElements::Kernel::Auxiliary::getLocations (bool exist_only=false)
 alias for the getAuxiliaryLocations function
 
ELEMENTS_API std::string Elements::Kernel::getConfigurationVariableName ()
 retrieve the variable name used for the configuration file lookup
 
ELEMENTS_API std::string Elements::Kernel::Configuration::getVariableName ()
 alias for the getAuxiliaryVariableName function
 
template<typename T >
ELEMENTS_API Path::Item Elements::Kernel::Configuration::getPath (const T &file_name, bool raise_exception=true)
 alias for the getAuxiliaryPath function
 
ELEMENTS_API std::vector< Path::ItemElements::Kernel::Configuration::getLocations (bool exist_only=false)
 alias for the getConfigurationLocations function
 
static void Elements::Environment::checkOutOfRange (const std::string &)
 check that the variable is in the environment
 
template<typename DESTPTR , typename SRC >
constexpr DESTPTR Elements::System::FuncPtrCast (SRC *const src_p) noexcept
 Cast from void * to function pointer.
 
template<typename TargetType , typename SourceType >
ELEMENTS_API TargetType Elements::numberCast (const SourceType &s)
 this function is a number cast. It behaves exactly as a static_cast except when casting from a floating point number to an integral one. This one is doing the correct rounding.
 
ELEMENTS_API std::vector< ItemElements::Kernel::Path::getLocationsFromEnv (const std::string &path_variable, bool exist_only=false)
 function to get the locations from an environment variable
 
ELEMENTS_API std::vector< ItemElements::Kernel::Path::getLocations (const Type &path_type, bool exist_only=false)
 function to get the locations for the specific type
 
template<typename T , typename U >
ELEMENTS_API Item Elements::Kernel::Path::getPathFromLocations (const T &file_name, const std::vector< U > &locations)
 retrieve path from a file name and a set of location to look into
 
template<typename T , typename U >
ELEMENTS_API std::vector< ItemElements::Kernel::Path::getAllPathFromLocations (const T &file_name, const std::vector< U > &locations)
 retrieve all the paths from a file name and a set of location to look into
 
template<typename T >
ELEMENTS_API Item Elements::Kernel::Path::getPathFromEnvVariable (const T &file_name, const std::string &path_variable)
 retrieve path from a file name and an environment variable to look into
 
template<typename T >
ELEMENTS_API std::string Elements::Kernel::Path::joinPath (const std::vector< T > &path_list)
 collate a vector of path into a string using PATH_SEP
 
template<typename... Args>
ELEMENTS_API auto Elements::Kernel::Path::join (Args &&... args) -> decltype(joinPath(std::forward< Args >(args)...))
 alias for the joinPath function
 
ELEMENTS_API std::vector< ItemElements::Kernel::Path::splitPath (const std::string &path_string)
 split a string into a vector of path using PATH_SEP
 
template<typename... Args>
ELEMENTS_API auto Elements::Kernel::Path::split (Args &&... args) -> decltype(splitPath(std::forward< Args >(args)...))
 alias for the splitPath function
 
template<typename T , typename U >
ELEMENTS_API std::vector< ItemElements::Kernel::Path::multiPathAppend (const std::vector< T > &initial_locations, const std::vector< U > &suffixes)
 path join each suffix to each initial locations
 
template<typename T >
ELEMENTS_API std::vector< ItemElements::Kernel::Path::removeDuplicates (const std::vector< T > &path_list)
 remove duplicated paths keeping the order
 
template<typename T >
ELEMENTS_API std::vector< T > Elements::Kernel::pathSearch (const std::string &searched_name, T directory, SearchType search_type)
 Searches for a file or a directory in a directory. The search can be recursive (SearchType.Recursive) and in that case more than one results can be return.
 
static const ModuleInfoElements::System::getThisModuleInfo ()
 function to retrieve the current module
 
constexpr std::uint_least64_t CALC_PROJECT_VERSION (const std::uint_least64_t maj, const std::uint_least64_t min, const std::uint_least64_t pat)
 Mangle major, minor and patch version number into a single integer.
 
ELEMENTS_API std::string Elements::getVersionFromSvnKeywords (const std::string &svnUrl, const std::string &svnId)
 Function returning a version string extracted from SVN keywords.
 
ELEMENTS_API std::string Elements::getVersionString (unsigned short major, unsigned short minor, unsigned short patch=0)
 Function converting the version numbers into a string.
 

Variables

ELEMENTS_API const std::string Elements::Kernel::Path::PATH_SEP {":"}
 Separator of path entries. Usually ":" on Unix.
 
ELEMENTS_API const std::map< Type, const std::stringElements::Kernel::Path::VARIABLE
 map containing the name of the path variable for each type
 
ELEMENTS_API const std::map< Type, const std::vector< std::string > > Elements::Kernel::Path::SUFFIXES
 map containing the default project installation suffixes for each variable
 
ELEMENTS_API const std::map< Type, const std::vector< std::string > > Elements::Kernel::Path::DEFAULT_LOCATIONS
 map containing the default external locations for each variable
 
ELEMENTS_API const std::map< Type, const bool > Elements::Kernel::Path::HAS_SUBLEVELS
 map containing the sub-level property of the path components
 

Detailed Description

Core CMake, C++ and Python utilities.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3.0 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3.0 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3.0 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Macro Definition Documentation

◆ __attribute__

#define __attribute__ ( x)

Definition at line 32 of file Attribute.h.

◆ _str

#define _str ( s)    #s

Macro to convert a preprocessor constant into a string.

Definition at line 40 of file Stringify.h.

◆ _xstr

#define _xstr ( s)    str(s)

helper macro

Definition at line 34 of file Stringify.h.

◆ CREATE_MANAGER

#define CREATE_MANAGER ( ELEMENTS_PROGRAM_NAME,
MANAGER )   CREATE_MANAGER_WITH_ARGS(MANAGER, ELEMENTS_PROGRAM_NAME, )

Macro that declares a program manager with all the needed arguments. It is typically called from the MAIN_FOR(ELEMENTS_PROGRAM_NAME, MANAGER) macro.

Parameters
ELEMENTS_PROGRAM_NAMEname of the main program class, derived from the class Elements::Program class.
MANAGERname of the manager variable to be created.

Definition at line 77 of file Main.h.

◆ CREATE_MANAGER_WITH_ARGS

#define CREATE_MANAGER_WITH_ARGS ( MANAGER,
ELEMENTS_PROGRAM,
... )
Value:
Elements::Module::name(), Elements::Project::searchDirectories(), log4cpp::Priority::ELEMENTS_DEFAULT_LOGLEVEL \
}
Class for managing all Elements programs.
static std::string versionString()
static std::vector< std::string > searchDirectories()
static std::string vcsVersion()
static std::string versionString()

Macro that declares a program manager with custom constructor arguments. It is typically called from the MAIN_FOR(ELEMENTS_PROGRAM_NAME, MANAGER) macro.

Parameters
ELEMENTS_PROGRAMcall of the main program constructor, derived from the class Elements::Program class.
MANAGERname of the manager variable to be created.

Definition at line 53 of file Main.h.

◆ ELEMENTS_API

#define ELEMENTS_API

Dummy definitions for the backward compatibility mode.

Definition at line 74 of file Export.h.

◆ ELEMENTS_DEFAULT_LOGLEVEL

#define ELEMENTS_DEFAULT_LOGLEVEL   DEBUG

Definition at line 41 of file Main.h.

◆ ELEMENTS_DEPRECATED

#define ELEMENTS_DEPRECATED   __attribute__((__deprecated__))

This macro create a warning message for a deprecated function or class

Definition at line 35 of file Deprecated.h.

◆ ELEMENTS_DEPRECATED_MSG

#define ELEMENTS_DEPRECATED_MSG ( msg)    __attribute__((__deprecated__(msg)))

This macro create a warning message for a deprecated function or class This version takes a msg as argument. This message will be displayed together with the deprecation warning.

Definition at line 44 of file Deprecated.h.

◆ ELEMENTS_EXPORT

#define ELEMENTS_EXPORT

Definition at line 76 of file Export.h.

◆ ELEMENTS_IMPORT

#define ELEMENTS_IMPORT

Definition at line 75 of file Export.h.

◆ ELEMENTS_LOCAL

#define ELEMENTS_LOCAL

Definition at line 77 of file Export.h.

◆ ELEMENTS_UNUSED

#define ELEMENTS_UNUSED   __attribute__((unused))

This macro is there to

  • allows to pass the argument name, even if it is not used. it will silence the compiler warning about this
  • It's a bit better that the ugly gcc form. Until the nice [[]] will be the mainstream syntax.
  • we can also hide compiler specific attribute here

Definition at line 39 of file Unused.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_AUXILIARY_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_AUXILIARY_IMPL_

Definition at line 104 of file Auxiliary.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_CONFIGURATION_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_CONFIGURATION_IMPL_

Definition at line 100 of file Configuration.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_EXCEPTION_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_EXCEPTION_IMPL_

Definition at line 159 of file Exception.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_FUNCPTRCAST_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_FUNCPTRCAST_IMPL_

Definition at line 55 of file FuncPtrCast.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_LOGGING_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_LOGGING_IMPL_

Definition at line 299 of file Logging.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_MODULE_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_MODULE_IMPL_

Definition at line 59 of file Module.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_NUMBER_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_NUMBER_IMPL_

Definition at line 49 of file Number.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_PATH_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_PATH_IMPL_

Macro to prevent the direct inclusion of the implementation file.

Definition at line 284 of file Path.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_PATHSEARCH_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_PATHSEARCH_IMPL_

Definition at line 90 of file PathSearch.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_PROGRAM_MANAGER_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_PROGRAM_MANAGER_IMPL_

Definition at line 288 of file ProgramManager.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_PROJECT_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_PROJECT_IMPL_

Definition at line 72 of file Project.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_REAL_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_REAL_IMPL_

Definition at line 394 of file Real.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_STORAGE_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_STORAGE_IMPL_

Definition at line 80 of file Storage.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_THIS_MODULE_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_THIS_MODULE_IMPL_

Definition at line 53 of file ThisModule.h.

◆ ELEMENTSKERNEL_ELEMENTSKERNEL_VERSION_IMPL_

#define ELEMENTSKERNEL_ELEMENTSKERNEL_VERSION_IMPL_

Definition at line 84 of file Version.h.

◆ LIKELY

#define LIKELY ( x)    x

Macro for compiler branch optimisation. To be used when is x condition is more likely to happen that the other one

Definition at line 41 of file Likely.h.

◆ MAIN

#define MAIN ( ELEMENTS_PROGRAM)
Value:
ELEMENTS_API int main(int argc, char* argv[]) { \
auto program = ELEMENTS_PROGRAM(); \
Elements::ExitCode exit_code = program.run(argc, argv); \
return static_cast<Elements::ExitCodeType>(exit_code); \
}
ExitCode
Strongly typed exit numbers.
Definition Exit.h:97
#define ELEMENTS_API
Dummy definitions for the backward compatibility mode.
Definition Export.h:74
std::underlying_type< ExitCode >::type ExitCodeType
Underlying type of the ExitCode class.
Definition Exit.h:122

Macro which must be used to create a main in classes that derived from Elements::SimpleProgram, i.e., these derived classes must end with the following line:

MAIN(ELEMENTS_PROGRAM)
#define MAIN(ELEMENTS_PROGRAM)

.

Parameters
ELEMENTS_PROGRAMname of the main program class, derived from the class Elements::SimpleProgram class.

Definition at line 83 of file SimpleProgram.h.

◆ MAIN_FOR

#define MAIN_FOR ( ELEMENTS_PROGRAM_NAME)    MAIN_FOR_WITH_ARGS(ELEMENTS_PROGRAM_NAME, )

Macro which must be used to create a main in classes that derived from Elements::Program, i.e., these derived classes must end with the following line:

MAIN_FOR(ELEMENTS_PROGRAM_NAME)
#define MAIN_FOR(ELEMENTS_PROGRAM_NAME)
Definition Main.h:123

The macro is equipped with a set_terminate placed just before the main function definition:

static void onTerminate() noexcept
This is the set_terminate handler that is used in the MAIN_FOR macro.
#define ELEMENTS_UNUSED
Definition Unused.h:39
T set_terminate(T... args)

That handler will do a smooth catching of any exception raised in the run part of the program and call std::abort().

Parameters
ELEMENTS_PROGRAM_NAMEname of the main program class, derived from the class Elements::Program class.

Definition at line 123 of file Main.h.

◆ MAIN_FOR_WITH_ARGS

#define MAIN_FOR_WITH_ARGS ( ELEMENTS_PROGRAM,
... )
Value:
ELEMENTS_API int main(int argc, char* argv[]) { \
CREATE_MANAGER_WITH_ARGS(manager, ELEMENTS_PROGRAM, __VA_ARGS__); \
Elements::ExitCode exit_code = manager.run(argc, argv); \
return static_cast<Elements::ExitCodeType>(exit_code); \
}

Macro which must be used to create a main in classes that derived from Elements::Program, i.e., these derived classes must end with the following line:

MAIN_FOR_WITH_ARGS(ELEMENTS_PROGRAM, ...)
#define MAIN_FOR_WITH_ARGS(ELEMENTS_PROGRAM,...)
Definition Main.h:97

. The macro is equipped with a set_terminate placed just before the main function definition:

That handler will do a smooth catching of any exception raised in the run part of the program and call std::abort(). This version allows the passing of the Elements::Program constructor arguments

Parameters
ELEMENTS_PROGRAMname of the main program class, derived from the class Elements::Program class.

Definition at line 97 of file Main.h.

◆ NON_REDUNDANT_MOVE

#define NON_REDUNDANT_MOVE ( x)    std::move(x)

Definition at line 38 of file Compat.h.

Referenced by Elements::getLogLayout().

◆ UNLIKELY

#define UNLIKELY ( x)    x

Macro for compiler branch optimisation. To be used when is x condition is less likely to happen that the other one

Definition at line 42 of file Likely.h.

Enumeration Type Documentation

◆ ExitCode

enum class Elements::ExitCode : int
strong

Strongly typed exit numbers.

This has to be used with the MAIN_FOR macro There is no clear universal specification for exit codes. Every system has more or less its convention. Please have a look at http://en.wikipedia.org/wiki/Exit_status. These exit codes do exist for this very documentation. They allow a minimal communication with the batch framework. This gives a clear answer to the caller without the need of parsing the output of the executable. Notes:

  • by default (without any implementation), the uncaught signal produces an exit code of 128+signal value. Please have a look at "man 7 signal". For example the good old SIGSEGV (11) would trigger a system generated exit code of 139 = 128 + 11
  • we can use the exit code range [1,63] to define our own specific codes. Which should be less general that the ones below and reflect the behaviour of our own code.
    • OK : Everything is fine
    • NOT_OK : Something went wrong. This should be the default value for any unspecified failure.
  • the numbers used below are extracted from the header file /usr/include/sysexits.h
    • USAGE : The command was used incorrectly, e.g., with the wrong number of arguments, a bad flag, a bad syntax in a parameter, or whatever.
    • DATAERR : The input data was incorrect in some way. This should only be used for user's data & not system files.
    • NOINPUT : An input file (not a system file) did not exist or was not readable. This could also include errors like "No message" to a mailer (if it cared to catch it).
    • NOUSER : The user specified did not exist. This might be used for mail addresses or remote logins.
    • NOHOST : The host specified did not exist. This is used in mail addresses or network requests.
    • UNAVAILABLE : A service is unavailable. This can occur if a support program or file does not exist. This can also be used as a catchall message when something you wanted to do doesn't work, but you don't know why.
    • SOFTWARE : An internal software error has been detected. This should be limited to non-operating system related errors as possible.
    • OSERR : An operating system error has been detected. This is intended to be used for such things as "cannot fork", "cannot create pipe", or the like. It includes things like getuid returning a user that does not exist in the passwd file.
    • OSFILE : Some system file (e.g., /etc/passwd, /etc/utmp, etc.) does not exist, cannot be opened, or has some sort of error (e.g., syntax error).
    • CANTCREAT : A (user specified) output file cannot be created.
    • IOERR : An error occurred while doing I/O on some file.
    • TEMPFAIL : temporary failure, indicating something that is not really an error. In sendmail, this means that a mailer (e.g.) could not create a connection, and the request should be reattempted later.
    • PROTOCOL : the remote system returned something that was "not possible" during a protocol exchange.
    • NOPERM : You did not have sufficient permission to perform the operation. This is not intended for file system problems, which should use NOINPUT or CANTCREAT, but rather for higher level permissions.
Enumerator
OK 

Everything is OK.

NOT_OK 

Generic unknown failure.

USAGE 

command line usage error

DATAERR 

data format error

NOINPUT 

cannot open input

NOUSER 

addressee unknown

NOHOST 

host name unknown

UNAVAILABLE 

service unavailable

SOFTWARE 

internal software error

OSERR 

system error (e.g., can't fork)

OSFILE 

critical OS file missing

CANTCREAT 

can't create (user) output file

IOERR 

input/output error

TEMPFAIL 

temp failure; user is invited to retry

PROTOCOL 

remote error in protocol

NOPERM 

permission denied

CONFIG 

configuration error

Definition at line 97 of file Exit.h.

Function Documentation

◆ CALC_PROJECT_VERSION()

std::uint_least64_t CALC_PROJECT_VERSION ( const std::uint_least64_t maj,
const std::uint_least64_t min,
const std::uint_least64_t pat )
constexpr

Mangle major, minor and patch version number into a single integer.

◆ checkOutOfRange()

void Elements::Environment::checkOutOfRange ( const std::string & index)
staticprivate

check that the variable is in the environment

Definition at line 286 of file Environment.cpp.

References Elements::Environment::hasKey(), and std::stringstream::str().

Referenced by Elements::Environment::unSet().

Here is the call graph for this function:

◆ FuncPtrCast()

template<typename DESTPTR , typename SRC >
DESTPTR Elements::System::FuncPtrCast ( SRC *const src_p)
constexprnoexcept

Cast from void * to function pointer.

Small helper function that performs the cast from void * to function pointer in a standards compliant way. For more information on this type of 'type punning, see https://github.com/CppCon/CppCon2017/blob/master/Presentations/Type%20Punning%20In%20C%2B%2B17%20-%20Avoiding%20Pun-defined%20Behavior/Type%20Punning%20In%20C%2B%2B17%20-%20Avoiding%20Pun-defined%20Behavior%20-%20Scott%20Schurr%20-%20CppCon%202017.pdf and https://www.youtube.com/watch?v=sCjZuvtJd-k

Parameters
src_ppointer address to convert
Template Parameters
SRCsource pointer type
DESTPTRdestination pointer type
Returns
destination pointer

Referenced by Elements::System::getProcedureByName(), Elements::System::getThisExecutableInfo(), Elements::System::moduleHandle(), and Elements::System::ModuleInfo::ModuleInfo().

◆ getAllPathFromLocations()

template<typename T , typename U >
ELEMENTS_API std::vector< Item > Elements::Kernel::Path::getAllPathFromLocations ( const T & file_name,
const std::vector< U > & locations )

retrieve all the paths from a file name and a set of location to look into

Parameters
file_namefile name to look for. Can be of the form "Some.txt" or "Place/Some.txt"
locationsvector of locations to look into
Template Parameters
Ttype of the file name. Can be anything that can be converted to a boost filesystem path. In principle either std::string or path.
Utype of the location. Can be anything that can be converted to a boost filesystem path. In principle either std::string or path.
Returns
all the found paths

◆ getAuxiliaryVariableName()

string Elements::Kernel::getAuxiliaryVariableName ( )

retrieve the variable name used for the auxiliary file lookup

Returns
the standard variable name: ELEMENTS_AUX_PATH

Definition at line 41 of file Auxiliary.cpp.

Referenced by Elements::Kernel::Auxiliary::getVariableName().

◆ getConfigurationVariableName()

string Elements::Kernel::getConfigurationVariableName ( )

retrieve the variable name used for the configuration file lookup

Returns
the standard variable name: ELEMENTS_CONF_PATH

Definition at line 41 of file Configuration.cpp.

Referenced by Elements::Kernel::Configuration::getVariableName().

◆ getLocations() [1/3]

std::vector< Path::Item > Elements::Kernel::Auxiliary::getLocations ( bool exist_only = false)

alias for the getAuxiliaryLocations function

Returns
same as getAuxiliaryLocations

Definition at line 80 of file Auxiliary.cpp.

References Elements::Kernel::getAuxiliaryLocations(), and Elements::Kernel::Auxiliary::getLocations().

Referenced by Elements::Kernel::Auxiliary::getLocations(), and Elements::Kernel::Auxiliary::getPath().

Here is the call graph for this function:

◆ getLocations() [2/3]

std::vector< Path::Item > Elements::Kernel::Configuration::getLocations ( bool exist_only = false)

alias for the getConfigurationLocations function

Returns
same as getConfigurationLocations

Definition at line 76 of file Configuration.cpp.

References Elements::Kernel::getConfigurationLocations().

Here is the call graph for this function:

◆ getLocations() [3/3]

vector< Item > Elements::Kernel::Path::getLocations ( const Type & path_type,
bool exist_only = false )

function to get the locations for the specific type

This function return the raw locations for the given type. It doesn't add the internal locations which are not in the variable (like /usr/lib for the library type)

Parameters
path_typetype of the path
exist_onlyif true returns only existing locations. by default it is set to false.
Returns
return a list of boost filesystem paths

Definition at line 100 of file Path.cpp.

References Elements::Kernel::Path::getLocationsFromEnv(), and Elements::Kernel::Path::VARIABLE.

Here is the call graph for this function:

◆ getLocationsFromEnv()

vector< Item > Elements::Kernel::Path::getLocationsFromEnv ( const std::string & path_variable,
bool exist_only = false )

function to get the locations from an environment variable

This function return the raw locations pointed by the environment variable. It doesn't add the internal locations which are not in the variable (like /usr/lib for the LD_LIBRARY_PATH environment variable)

Parameters
path_variablename of the environment variable
exist_onlyif true returns only existing locations. by default it is set to false.
Returns
return a list of boost filesystem paths

Definition at line 82 of file Path.cpp.

References std::vector< T >::begin(), std::vector< T >::end(), std::vector< T >::erase(), std::remove_if(), and Elements::Kernel::Path::split().

Referenced by Elements::Kernel::Path::getLocations().

Here is the call graph for this function:

◆ getPath() [1/2]

template<typename T >
ELEMENTS_API Path::Item Elements::Kernel::Auxiliary::getPath ( const T & file_name,
bool raise_exception = true )

alias for the getAuxiliaryPath function

Parameters
file_namefile name of the auxiliary file to be found.
raise_exceptionenable the raising of an exception if the file is not found
Returns
same as getAuxiliaryPath

References Elements::Kernel::Auxiliary::getPath().

Referenced by Elements::Kernel::Auxiliary::getPath(), Elements::Kernel::Auxiliary::getPath(), and Elements::Kernel::Auxiliary::getPath().

Here is the call graph for this function:

◆ getPath() [2/2]

template<typename T >
ELEMENTS_API Path::Item Elements::Kernel::Configuration::getPath ( const T & file_name,
bool raise_exception = true )

alias for the getAuxiliaryPath function

Parameters
file_namefile name of the configuration file to be found.
raise_exceptionenable the raising of an exception if the file is not found
Returns
same as getAuxiliaryPath

◆ getPathFromEnvVariable()

template<typename T >
ELEMENTS_API Item Elements::Kernel::Path::getPathFromEnvVariable ( const T & file_name,
const std::string & path_variable )

retrieve path from a file name and an environment variable to look into

Parameters
file_namefile name to look for. Can be of the form "Some.txt" or "Place/Some.txt"
path_variablename of the environment variable
Template Parameters
Ttype of the file name. Can be anything that can be converted to a boost filesystem path. In principle either std::string or path.
Returns
first match of the file stem

◆ getPathFromLocations()

template<typename T , typename U >
ELEMENTS_API Item Elements::Kernel::Path::getPathFromLocations ( const T & file_name,
const std::vector< U > & locations )

retrieve path from a file name and a set of location to look into

Parameters
file_namefile name to look for. Can be of the form "Some.txt" or "Place/Some.txt"
locationsvector of locations to look into
Template Parameters
Ttype of the file name. Can be anything that can be converted to a boost filesystem path. In principle either std::string or path.
Utype of the location. Can be anything that can be converted to a boost filesystem path. In principle either std::string or path.
Returns
first match of the file stem

◆ getThisModuleInfo()

static const ModuleInfo & Elements::System::getThisModuleInfo ( )
static

function to retrieve the current module

It has to be included in the target source and compiled within the module to be identified.

◆ getVariableName() [1/2]

string Elements::Kernel::Auxiliary::getVariableName ( )

alias for the getAuxiliaryVariableName function

Returns
same as getAuxiliaryVariableName

Definition at line 72 of file Auxiliary.cpp.

References Elements::Kernel::getAuxiliaryVariableName(), and Elements::Kernel::Auxiliary::getVariableName().

Referenced by Elements::Kernel::Auxiliary::getVariableName().

Here is the call graph for this function:

◆ getVariableName() [2/2]

string Elements::Kernel::Configuration::getVariableName ( )

alias for the getAuxiliaryVariableName function

Returns
same as getAuxiliaryVariableName

Definition at line 68 of file Configuration.cpp.

References Elements::Kernel::getConfigurationVariableName().

Here is the call graph for this function:

◆ getVersionFromSvnKeywords()

string Elements::getVersionFromSvnKeywords ( const std::string & svnUrl,
const std::string & svnId )

Function returning a version string extracted from SVN keywords.

ElementsExample/src/program/Program.cpp shows how to use this method to implement a getVersion in a program

Parameters
svnUrlThis is a string that can be filled with the HeadURL svn keywords. Writing #define SVN_URL "SVN $HeadURL$ in a file. @param svnId This is a string that can be filled with the Id svn keywords. Writing \#define SVN_ID "SVN $Id$ in a file.

the svn keywords will be expanded upon the next commit if the svn client is instructed to do this with svn propset svn:keywords 'Id Revision HeadURL' Program.cpp

Returns
Todo
remove the any reference to SVN for the next major release

Definition at line 35 of file Version.cpp.

◆ getVersionString()

string Elements::getVersionString ( unsigned short major,
unsigned short minor,
unsigned short patch = 0 )

Function converting the version numbers into a string.

This function return either 2 numbers separated with a "." if the patch number is zero. Or 3 numbers separated with a "." if the patch is not zero.

Parameters
majorMajor version number
minorMinor version number
patchPatch version number
Returns
The formatted string with the version numbers
Todo
use the unsigned uint16_t instead of short for the next major release

Definition at line 68 of file Version.cpp.

References std::to_string().

Here is the call graph for this function:

◆ join()

template<typename... Args>
ELEMENTS_API auto Elements::Kernel::Path::join ( Args &&... args) -> decltype(joinPath(std::forward< Args >(args)...))

alias for the joinPath function

Parameters
argsForward arguments
Returns
same as joinPath

◆ joinPath()

template<typename T >
ELEMENTS_API std::string Elements::Kernel::Path::joinPath ( const std::vector< T > & path_list)

collate a vector of path into a string using PATH_SEP

Parameters
path_listlist of path to be joined.
Returns
collated string

Referenced by Elements::Kernel::Path::getPathFromEnvVariable< string >().

◆ multiPathAppend()

template<typename T , typename U >
ELEMENTS_API std::vector< Item > Elements::Kernel::Path::multiPathAppend ( const std::vector< T > & initial_locations,
const std::vector< U > & suffixes )

path join each suffix to each initial locations

Parameters
initial_locationslist of initial locations.
suffixeslist of suffixes
Returns
full list of each joined item

Referenced by Elements::Kernel::Path::getPathFromEnvVariable< string >().

◆ numberCast()

template<typename TargetType , typename SourceType >
ELEMENTS_API TargetType Elements::numberCast ( const SourceType & s)

this function is a number cast. It behaves exactly as a static_cast except when casting from a floating point number to an integral one. This one is doing the correct rounding.

Parameters
snumber to cast
Returns
casted number

◆ pathSearch()

template<typename T >
ELEMENTS_API std::vector< T > Elements::Kernel::pathSearch ( const std::string & searched_name,
T directory,
SearchType search_type )

Searches for a file or a directory in a directory. The search can be recursive (SearchType.Recursive) and in that case more than one results can be return.

Parameters
searched_nameName of the searched file or directory
Template Parameters
Tinput type string or Boost path of the directory in which the search is carried out
Parameters
directoryThe directory where the search is performed.
search_typeTwo options: SearchType.Local search in directory only SearchType.Recursive search in sub-directories too
Returns
A vector of paths of the files found or empty string, if nothing is found

◆ removeDuplicates()

template<typename T >
ELEMENTS_API std::vector< Item > Elements::Kernel::Path::removeDuplicates ( const std::vector< T > & path_list)

remove duplicated paths keeping the order

Parameters
path_listlist of path to uniquify.
Returns
deduplicated list of path

Referenced by Elements::Kernel::Path::getPathFromEnvVariable< string >().

◆ split()

template<typename... Args>
ELEMENTS_API auto Elements::Kernel::Path::split ( Args &&... args) -> decltype(splitPath(std::forward< Args >(args)...))

alias for the splitPath function

Parameters
argsForward arguments
Returns
same as splitPath

Referenced by Elements::Kernel::Path::getLocationsFromEnv().

◆ splitPath()

vector< Item > Elements::Kernel::Path::splitPath ( const std::string & path_string)

split a string into a vector of path using PATH_SEP

Parameters
path_stringstring containing a list of path separated by PATH_SEP
Returns
vector of path

Definition at line 104 of file Path.cpp.

References std::vector< T >::begin(), std::vector< T >::cbegin(), std::vector< T >::cend(), Elements::Kernel::Path::PATH_SEP, std::vector< T >::size(), and std::transform().

Here is the call graph for this function:

Variable Documentation

◆ DEFAULT_LOCATIONS

const map< Type, const vector< string > > Elements::Kernel::Path::DEFAULT_LOCATIONS
Initial value:
{
{Type::executable, {}},
{Type::library, {"/usr/lib64", "/usr/lib"}},
{Type::python, {}},
{Type::configuration, {"/usr/share/conf"}},
{Type::auxiliary, {"/usr/share/auxdir", "/usr/share/aux"}}
}

map containing the default external locations for each variable

Definition at line 64 of file Path.cpp.

◆ HAS_SUBLEVELS

const std::map< Type, const bool > Elements::Kernel::Path::HAS_SUBLEVELS
Initial value:
{
{Type::executable, false},
{Type::library, false},
{Type::python, true},
{Type::configuration, true},
{Type::auxiliary, true}
}

map containing the sub-level property of the path components

Definition at line 72 of file Path.cpp.

◆ PATH_SEP

const string Elements::Kernel::Path::PATH_SEP {":"}

Separator of path entries. Usually ":" on Unix.

Definition at line 44 of file Path.cpp.

Referenced by Elements::Kernel::Path::splitPath().

◆ SUFFIXES

const map< Type, const vector< string > > Elements::Kernel::Path::SUFFIXES
Initial value:
{
{Type::executable, {"scripts", "bin"}},
{Type::library, {"lib"}},
{Type::python, {"python"}},
{Type::configuration, {"conf", "share/conf"}},
{Type::auxiliary, {"auxdir", "aux", "share/auxdir", "share/aux"}}
}

map containing the default project installation suffixes for each variable

Definition at line 56 of file Path.cpp.

◆ VARIABLE

const map< Type, const string > Elements::Kernel::Path::VARIABLE
Initial value:
{
{Type::executable, "PATH"},
{Type::library, System::SHLIB_VAR_NAME},
{Type::python, "PYTHONPATH"},
{Type::configuration, "ELEMENTS_CONF_PATH"},
{Type::auxiliary, "ELEMENTS_AUX_PATH"}
}

map containing the name of the path variable for each type

Definition at line 48 of file Path.cpp.

Referenced by Elements::Kernel::Path::getLocations().