ncbiapp.hpp

ncbi源码

    /// If not set, a default of 0.0.0 (unknown) is used.
    void SetVersion(const CVersionInfo& version);

    /// Get the program version information.
    CVersionInfo GetVersion(void);

    /// Setup the command line argument descriptions.
    ///
    /// Call from the Init() method. The passed "arg_desc" will be owned
    /// by this class, and it will be deleted by ~CNcbiApplication(),
    /// or if SetupArgDescriptions() is called again.
    void SetupArgDescriptions(CArgDescriptions* arg_desc);

    /// Setup the application diagnostic stream.
    /// @return
    ///   TRUE if successful,  FALSE otherwise.
    bool SetupDiag(EAppDiagStream diag);

    /// Setup application specific diagnostic stream.
    ///
    /// Called from SetupDiag when it is passed the eDS_AppSpecific parameter.
    /// Currently, this calls SetupDiag(eDS_ToStderr) to setup diagonistic
    /// stream to the std error channel.
    /// @return
    ///   TRUE if successful, FALSE otherwise.
    virtual bool SetupDiag_AppSpecific(void);

    /// Load settings from the configuration file to the registry.
    ///
    /// This method is called from inside AppMain() to load (add) registry
    /// settings from the configuration file specified as the "conf" arg
    /// passed to AppMain(). The "conf" argument has the following special
    /// meanings:
    ///  - NULL      -- dont even try to load registry from any file at all;
    ///  - non-empty -- if "conf" contains a path, then try to load from the
    ///                 conf.file of name "conf" (only!). Else - see NOTE.
    ///                 TIP: if the path is not fully qualified then:
    ///                      if it starts from "../" or "./" -- look starting
    ///                      from the current working dir.
    ///  - empty     -- compose conf.file name from the application name
    ///                 plus ".ini". If it does not match an existing
    ///                 file, then try to strip file extensions, e.g. for
    ///                 "my_app.cgi.exe" -- try subsequently:
    ///                   "my_app.cgi.exe.ini", "my_app.cgi.ini", "my_app.ini".
    ///
    /// NOTE:
    /// If "conf" arg is empty or non-empty, but without path, then config file
    /// will be sought for in the following order:
    ///  - in the current work directory;
    ///  - in the dir defined by environment variable "NCBI";
    ///  - in the user home directory;
    ///  - in the program dir.
    ///
    /// Throw an exception if "conf" is non-empty, and cannot open file.
    /// Throw an exception if file exists, but contains invalid entries.
    /// @param reg
    ///   The loaded registry is returned via the reg parameter.
    /// @param conf
    ///   The configuration file to loaded the registry entries from.
    /// @param reg_flags
    ///   Flags for loading the registry
    /// @return
    ///   TRUE only if the file was non-NULL, found and successfully read.
    virtual bool LoadConfig(CNcbiRegistry& reg, const string* conf,
                            CNcbiRegistry::TFlags reg_flags);

    /// Load settings from the configuration file to the registry.
    ///
    /// CNcbiApplication::LoadConfig(reg, conf) just calls
    /// LoadConfig(reg, conf, 0).
    virtual bool LoadConfig(CNcbiRegistry& reg, const string* conf);


    /// Get the home directory for the current user.
    string GetHomeDir(void);

    /// Set program's display name.
    ///
    /// Set up application name suitable for display or as a basename for
    /// other files. It can also be set by the user when calling AppMain().
    void SetProgramDisplayName(const string& app_name);

    /// Find the application's executable file.
    ///
    /// Find the path and name of the executable file that this application is
    /// running from. Will be accesible by GetArguments.GetProgramName().
    /// @param argc	
    ///   Standard argument count "argc".
    /// @param argv
    ///   Standard argument vector "argv".
    /// @return
    ///   Name of application's executable file.
    string FindProgramExecutablePath(int argc, const char* const* argv);

    /// Honor debug settings.
    ///
    /// Read the [DEBUG] section of the specified registry and
    /// set the diagnostic settings as found in that section.
    /// Specifically, the method reads the settings for parameters:
    /// ABORT_ON_THROW, DIAG_POST_LEVEL, DIAG_MESSAGE_FILE.
    /// @param reg
    ///   Registry to read from. If NULL, use the current registry setting.
    void HonorDebugSettings(CNcbiRegistry* reg = 0);

private:
    /// Setup C++ standard I/O streams' behaviour.
    ///
    /// Called from AppMain() to do compiler-specific optimization
    /// for C++ I/O streams. For example, since SUN WorkShop STL stream
    /// library has significant performance loss when sync_with_stdio is
    /// TRUE (default), so we turn it off. Another, for GCC version greater
    /// than 3.00 we forcibly set cin stream buffer size to 4096 bytes -- which
    /// boosts the performance dramatically.
    void x_SetupStdio(void);

    static CNcbiApplication*   m_Instance;   ///< Current app. instance
    auto_ptr<CVersionInfo>     m_Version;    ///< Program version
    auto_ptr<CNcbiEnvironment> m_Environ;    ///< Cached application env.
    CNcbiRegistry*             m_Config;     ///< Guaranteed to be non-NULL
    bool                       m_OwnsConfig; ///< Whether to delete on destr.
    auto_ptr<CNcbiOstream>     m_DiagStream; ///< Opt., aux., see eDS_ToMemory
    auto_ptr<CNcbiArguments>   m_Arguments;  ///< Command-line arguments
    auto_ptr<CArgDescriptions> m_ArgDesc;    ///< Cmd.-line arg descriptions
    auto_ptr<CArgs>            m_Args;       ///< Parsed cmd.-line args
    bool                       m_DisableArgDesc;  ///< Arg desc. disabled
    THideStdArgs               m_HideArgs;   ///< Std cmd.-line flags to hide
    TStdioSetupFlags           m_StdioFlags; ///< Std C++ I/O adjustments
    char*                      m_CinBuffer;  ///< Cin buffer if changed
    string                     m_ProgramDisplayName;  ///< Display name of app
};


/* @} */



/////////////////////////////////////////////////////////////////////////////
//  IMPLEMENTATION of INLINE functions
/////////////////////////////////////////////////////////////////////////////


inline const CNcbiArguments& CNcbiApplication::GetArguments(void) const {
    return *m_Arguments;
}

inline const CArgs& CNcbiApplication::GetArgs(void) const {
    if ( !m_Args.get() ) {
        NCBI_THROW(CAppException, eUnsetArgs,
                   "Command-line argument description is not found");
    }
    return *m_Args;
}

inline const CNcbiEnvironment& CNcbiApplication::GetEnvironment(void) const {
    return *m_Environ;
}

inline CNcbiEnvironment& CNcbiApplication::SetEnvironment(void) {
    return *m_Environ;
}

inline const CNcbiRegistry& CNcbiApplication::GetConfig(void) const {
    return *m_Config;
}

inline CNcbiRegistry& CNcbiApplication::GetConfig(void) {
    return *m_Config;
}

inline string  CNcbiApplication::GetProgramDisplayName(void) const {
    return m_ProgramDisplayName;
}


END_NCBI_SCOPE



/*
 * ===========================================================================
 * $Log: ncbiapp.hpp,v $
 * Revision 1000.1  2004/02/12 21:44:20  gouriano
 * PRODUCTION: UPGRADED [CORE_001] Dev-tree R1.40
 *
 * Revision 1.40  2004/01/06 18:17:21  dicuccio
 * Added APIs for setting environment variables
 *
 * Revision 1.39  2003/09/29 20:27:59  vakatov
 * + LoadConfig(...., reg_flags)
 *
 * Revision 1.38  2003/08/05 19:59:10  ucko
 * With the new meta-registry setup, we don't necessarily own m_Config.
 *
 * Revision 1.37  2003/07/28 10:58:54  siyan
 * Minor comment changes.
 *
 * Revision 1.36  2003/07/17 00:05:33  siyan
 * Changed doc on some enum types so Doxygen picks them up better.
 *
 * Revision 1.35  2003/07/07 13:55:13  siyan
 * Added documentation and made documentation consistent. Made it easier
 * for Doxygen to pick up necessary documentation.
 *
 * Revision 1.34  2003/06/25 15:58:59  rsmith
 * factor out config file DEBUG settings into HonorDebugSettings
 *
 * Revision 1.33  2003/06/23 18:02:21  vakatov
 * CNcbiApplication::MacArgMunging() moved from header to the source file.
 * Fixed, reformatted and added comments.
 *
 * Revision 1.32  2003/06/16 13:52:27  rsmith
 * Add ProgramDisplayName member. Program name becomes real executable full
 * path. Handle Mac special arg handling better.
 *
 * Revision 1.31  2003/06/05 18:14:34  lavr
 * SetStdioFlags(): comment from impl not to call twice or not from ctor
 *
 * Revision 1.30  2003/03/31 13:26:00  siyan
 * Added doxygen support
 *
 * Revision 1.29  2003/03/19 19:36:09  gouriano
 * added optional adjustment of stdio streams
 *
 * Revision 1.28  2002/12/26 17:12:42  ivanov
 * Added version info and Set/GetVersion functions into CNcbiApplication class
 *
 * Revision 1.27  2002/12/18 22:53:21  dicuccio
 * Added export specifier for building DLLs in windows.  Added global list of
 * all such specifiers in mswin_exports.hpp, included through ncbistl.hpp
 *
 * Revision 1.26  2002/10/28 22:36:15  vakatov
 * Fixes in some comments
 *
 * Revision 1.25  2002/08/08 18:38:16  gouriano
 * added HideStdArgs function
 *
 * Revision 1.24  2002/08/02 20:11:51  gouriano
 * added possibility to disable arg descriptions
 *
 * Revision 1.23  2002/07/15 18:17:50  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.22  2002/07/11 14:17:53  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.21  2002/04/11 20:39:16  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.20  2002/01/10 16:51:52  ivanov
 * Changed LoadConfig() -- new method to search the config file
 *
 * Revision 1.19  2002/01/07 16:58:21  vakatov
 * CNcbiApplication::GetArgs() -- a clearer error message
 *
 * Revision 1.18  2001/05/17 14:50:13  lavr
 * Typos corrected
 *
 * Revision 1.17  2001/04/13 02:58:43  vakatov
 * Do not apply R1.16 for non-UNIX platforms where we cannot configure
 * HAVE_NCBI_C yet
 *
 * Revision 1.16  2001/04/12 22:55:09  vakatov
 * [HAVE_NCBI_C]  Handle #GetArgs to avoid name clash with the NCBI C Toolkit
 *
 * Revision 1.15  2000/11/24 23:33:10  vakatov
 * CNcbiApplication::  added SetupArgDescriptions() and GetArgs() to
 * setup cmd.-line argument description, and then to retrieve their
 * values, respectively. Also implements internal error handling and
 * printout of USAGE for the described arguments.
 *
 * Revision 1.14  2000/01/20 17:51:16  vakatov
 * Major redesign and expansion of the "CNcbiApplication" class to
 *  - embed application arguments   "CNcbiArguments"
 *  - embed application environment "CNcbiEnvironment"
 *  - allow auto-setup or "by choice" (see enum EAppDiagStream) of diagnostics
 *  - allow memory-resided "per application" temp. diagnostic buffer
 *  - allow one to specify exact name of the config.-file to load, or to
 *    ignore the config.file (via constructor's "conf" arg)
 *  - added detailed comments
 *
 * Revision 1.13  1999/12/29 21:20:16  vakatov
 * More intelligent lookup for the default config.file. -- try to strip off
 * file extensions if cannot find an exact match;  more comments and tracing
 *
 * Revision 1.12  1999/11/15 18:57:01  vakatov
 * Added <memory> (for "auto_ptr<>" template)
 *
 * Revision 1.11  1999/11/15 15:53:27  sandomir
 * Registry support moved from CCgiApplication to CNcbiApplication
 *
 * Revision 1.10  1999/04/27 14:49:50  vasilche
 * Added FastCGI interface.
 * CNcbiContext renamed to CCgiContext.
 *
 * Revision 1.9  1998/12/28 17:56:25  vakatov
 * New CVS and development tree structure for the NCBI C++ projects
 *
 * Revision 1.8  1998/12/09 17:30:12  sandomir
 * ncbicgi.hpp deleted from ncbiapp.hpp
 *
 * Revision 1.7  1998/12/09 16:49:56  sandomir
 * CCgiApplication added
 *
 * Revision 1.6  1998/12/07 23:46:52  vakatov
 * Merged with "cgiapp.hpp";  minor fixes
 *
 * Revision 1.4  1998/12/03 21:24:21  sandomir
 * NcbiApplication and CgiApplication updated
 *
 * Revision 1.3  1998/12/01 19:12:36  lewisg
 * added CCgiApplication
 *
 * Revision 1.2  1998/11/05 21:45:13  sandomir
 * std:: deleted
 *
 * Revision 1.1  1998/11/02 22:10:12  sandomir
 * CNcbiApplication added; netest sample updated
 * ===========================================================================
 */

#endif  /* CORELIB___NCBIAPP__HPP */