Class program

Synopsis

#include "breeze/process/program.hpp"

class program

Description

A singleton class to manage the overall status of the program and its termination.

Methods

programDeleted copy constructor (this class is a singleton).
declare_errorDeclares a program error.
exit_codeReturns: An integer to be passed to std::exit() or returned from main()
instanceReturns: A reference to the one and only instance of the class.
nameReturns: The program name set by set_name()
operator=Deleted copy assignment operator (this class is a singleton).
set_name overloadSets the program name from the arguments to main(), if argv[ 0 ] points to a non-empty name (i.e
set_name overloadSets the program name from the arguments to main(), if argv[ 0 ] points to a non-empty name; otherwise sets it from fallback.
set_name overloadSets the program name to name, with any leading path stripped.
set_terminate_handlerSets *user_function as the "terminate handler", i.e
terminateTriggers the termination of the program with the exit code which corresponds to the maximum value seen until now

Source

Lines 30-183 in breeze/process/program.hpp.

class program
{
public:
    //!     Deleted copy constructor (this class is a singleton).
    // -----------------------------------------------------------------------
                        program(    program const & ) = delete ;

    //!     Deleted copy assignment operator (this class is a singleton).
    // -----------------------------------------------------------------------
    program &           operator =( program const & ) = delete ;

private:
                        program() noexcept ;

public:
    //!     The gravity of an error.
    //
    //      NOTE: keep the enumeration in sync with the exit_codes[]
    //            array in the implementation file.
    // -----------------------------------------------------------------------
    enum gravity
    {
        comment = 0, // equivalent to success
        warning,
        error,
        fatal,
        internal
    } ;

    //!     \return
    //!         A reference to the one and only instance of the class.
    // -----------------------------------------------------------------------
    static program &    instance() noexcept ;

    //!     \return
    //!         An integer to be passed to \c std::exit() or returned
    //!         from \c main(). This corresponds to the most severe
    //!         error reported by client code to the \c program class
    //!         through the \c declare_error() member function.
    //!
    //!     If the system supports it, the various gravities will be
    //!     distinguished in the exit code; if not, all you get is
    //!     \c EXIT_SUCCESS or \c EXIT_FAILURE.
    //!
    //!     <strong>Important</strong>: this function also attempts to
    //!     flush \c std::cout, and calls \c declare_error( fatal ) if
    //!     the flush fails (for this reason, it is not \c const).
    // -----------------------------------------------------------------------
    int                 exit_code() ;

    //!     Sets the program name from the arguments to \c main(), if
    //!     <tt>argv[ 0 ]</tt> points to a non-empty name (i.e. if
    //!     <tt>argc > 0 && argv[ 0 ][ 0 ] != '\0'</tt>). Otherwise does
    //!     nothing.
    //!
    //!     If the name is set, any leading path is stripped.
    //!
    //!     \pre
    //!         No name was set before
    //!
    //!     \post
    //!         \e none
    // -----------------------------------------------------------------------
    void                set_name( int argc, char const * const * argv ) ;

    //!     Sets the program name from the arguments to \c main(), if
    //!     <tt>argv[ 0 ]</tt> points to a non-empty name; otherwise
    //!     sets it from \c fallback.
    //!
    //!     In any case, any leading path is stripped.
    //!
    //!     \pre
    //!         <tt>! fallback.empty()</tt> and no name was set before
    //!
    //!     \post
    //!         <tt>name().is_valid()</tt>
    // -----------------------------------------------------------------------
    void                set_name( int argc, char const * const * argv,
                                  std::string const & fallback ) ;

    //!     Sets the program name to \c name, with any leading path
    //!     stripped.
    //!
    //!     \pre
    //!         <tt>! name.empty()</tt> and no name was set before
    //!
    //!     \post
    //!         <tt>name().is_valid()</tt>
    // -----------------------------------------------------------------------
    void                set_name( std::string const & name ) ;

    //!     \return
    //!         The program name set by \c set_name(). An invalid \c
    //!         maybe if the name was never set.
    // -----------------------------------------------------------------------
    maybe< std::string >
                        name() const ;

    //!     Declares a program error.
    //!
    //!     \param g
    //!         The gravity of the error. If the gravity is higher
    //!         than any seen previously, it is saved to be used in
    //!         \c exit_code().
    //!
    //!     If the gravity is \c fatal or higher, this will also
    //!     terminate the program by calling \c program::terminate()
    //!     (when the gravity is \c fatal) or \c std::abort() (when it
    //!     is \c internal).
    // -----------------------------------------------------------------------
    void                declare_error( gravity g ) ;

    //!     Triggers the termination of the program with the exit
    //!     code which corresponds to the maximum value seen until
    //!     now. This function calls the function specified by
    //!     set_terminate_handler(), if set_terminate_handler() has
    //!     been called; otherwise, it calls \c std::exit().
    // -----------------------------------------------------------------------
    [[ noreturn ]] void terminate() ;

    //!     Sets \c *user_function as the "terminate handler", i.e. as
    //!     the function which is called, with the exit code as an
    //!     argument, if there is a fatal error or if the user calls
    //!     \c program::terminate(). This makes it possible for the user
    //!     to avoid calling the default terminate handler, which is \c
    //!     std::exit() (and thus to avoid \e not calling destructors of
    //!     local objects), for example, by raising an exception with the
    //!     argument, having taken the precaution to encapsulate the
    //!     entire contents of \c main() with:
    //!
    //!     \code
    //!         try {
    //!             breeze::program::instance().set_terminate_handler(
    //!                                             raise_int_exception ) ;
    //!             // ...
    //!         } catch ( int exit_code ) {
    //!             return exit_code ;
    //!         }
    //!     \endcode
    //!
    //!     \note
    //!         The terminate handler should not return, or \c
    //!         std::abort() will be called immediately after.
    // -----------------------------------------------------------------------
    void                set_terminate_handler( void (*user_function)( int ) ) ;

private:
    void                do_set_name( std::string const & name ) ;

    gravity             m_max_gravity ;
    maybe< std::string >
                        m_program_name ;
    void (*             m_terminate_handler)( int ) ;
} ;