生物技术

开发平台：
C/C++

ncbireg.hpp：源码内容
							/*
 * ===========================================================================
 * PRODUCTION $Log: ncbireg.hpp,v $
 * PRODUCTION Revision 1000.0  2003/10/29 15:05:14  gouriano
 * PRODUCTION PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R1.32
 * PRODUCTION
 * ===========================================================================
 */
#ifndef CORELIB___NCBIREG__HPP
#define CORELIB___NCBIREG__HPP
/*  $Id: ncbireg.hpp,v 1000.0 2003/10/29 15:05:14 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Denis Vakatov
 *
 */
/// @file ncbireg.hpp
/// Process information in the NCBI Registry, including working with
/// configuration files.
///
/// Classes to perform NCBI Registry operations including:
/// - Read and parse configuration file
/// - Search, edit, etc. the retrieved configuration information
/// - Write information back to configuration file
///
/// The Registry is defined as a text file with sections and entries in the 
/// form of "name=value" strings in each section. 
///
/// For an explanation of the syntax of the Registry file, see the
/// C++ Toolkit documentation.
#include <corelib/ncbistd.hpp>
#include <list>
#include <map>
/** @addtogroup Registry
 *
 * @{
 */
BEGIN_NCBI_SCOPE
/////////////////////////////////////////////////////////////////////////////
///
/// CRegistryException --
///
/// Define exceptions generated by CNcbiRegistry.
///
/// CRegistryException inherits its basic functionality from
/// CCParseTemplException<CCoreException> and defines additional error codes
/// for the Registry.
class NCBI_XNCBI_EXPORT CRegistryException :
    public CParseTemplException<CCoreException>
{
public:
    /// Error types that the Registry can generate.
    enum EErrCode {
        eSection,   ///< Section error
        eEntry,     ///< Entry error
        eValue,     ///< Value error
        eErr        ///< Other error
    };
    /// Translate from the error code value to its string representation.
    virtual const char* GetErrCodeString(void) const
    {
        switch (GetErrCode()) {
        case eSection: return "eSection";
        case eEntry:   return "eEntry";
        case eValue:   return "eValue";
        case eErr:     return "eErr";
        default:       return CException::GetErrCodeString();
        }
    }
    // Standard exception boilerplate code
    NCBI_EXCEPTION_DEFAULT2(CRegistryException,
                            CParseTemplException<CCoreException>,
                            std::string::size_type);
};
/////////////////////////////////////////////////////////////////////////////
///
/// CNcbiRegistry --
///
/// Define the Registry.
///
/// Load, access, modify and store runtime information (usually used to
/// work with configuration files).
class NCBI_XNCBI_EXPORT CNcbiRegistry
{
public:
    /// Registry parameter settings.
    ///
    /// A Registry parameter can be either transient or persistent,
    /// overridable or not overridable, truncatable or not truncatable.
    enum EFlags {
        eTransient   = 0x1,     ///< Transient -- Wont be saved (by Write())
        ePersistent  = 0x100,   ///< Persistent -- Saved when file is written
        eOverride    = 0x2,     ///< Existing value can be overriden
        eNoOverride  = 0x200,   ///< Cannot change existing value
        eTruncate    = 0x4,     ///< Leading, trailing blanks can be truncated
        eNoTruncate  = 0x400    ///< Cannot truncate parameter value
    };
    typedef int TFlags;  ///< Binary OR of "EFlags"
    /// Constructor.
    CNcbiRegistry(void);
    /// Destructor.
    ~CNcbiRegistry(void);
    /// Constructor.
    ///
    /// @param is
    ///   Input stream to load the Registry from.
    ///   NOTE:  if the stream is a file, it must be opened in binary mode!
    /// @param flags
    ///   How parameters are stored. The default is to store all parameters as
    ///   persistent unless the  "eTransient" flag is set in which case the
    ///   newly retrieved parameters is stored as transient.
    /// @sa
    ///   Read()
    CNcbiRegistry(CNcbiIstream& is, TFlags flags = 0); 
    /// Verify if Registry is empty.
    ///
    /// @return
    ///   TRUE if the registry contains no entries.
    bool Empty(void) const;
    /// Verify if persistent values have been modified.
    ///
    /// @return
    ///   TRUE if the persistent part of the registry (i.e. persistent
    ///   value(s) and the all-registry comment) was modified since:
    ///   - the last successful Write(), or
    ///   - the registry creation and maybe immediate read after the creation.
    bool Modified(void) const;
    /// Read and parse the stream "is", and merge its content with current
    /// Registry entries.
    ///
    /// Once the Registry has been initialized by the constructor, it is 
    /// possible to load other parameters from other files using this method.
    /// @param is
    ///   Input stream to read and parse.
    ///   NOTE:  if the stream is a file, it must be opened in binary mode!
    /// @param flags
    ///   How parameters are stored. The default is for all values to be read
    ///   as persistent with the capability of overriding any previously
    ///   loaded value associated with the same name. The default can be
    ///   modified by specifying "eTransient", "eNoOverride" or 
    ///   "eTransient | eNoOverride". If there is a conflict between the old
    ///   and the new(loaded) entry value and if "eNoOverride" flag is set,
    ///   then just ignore the new value; otherwise, replace the old value by
    ///   the new one. If "eTransient" flag is set, then store the newly
    ///   retrieved parameters as transient;  otherwise, store them as
    ///   persistent.
    /// @sa
    ///   Write()
    void Read(CNcbiIstream& is, TFlags flags = 0);
    /// Write the registry content to output stream.
    /// @param os
    ///   Output stream to write the registry to.
    ///   NOTE:  if the stream is a file, it must be opened in binary mode!
    /// @return
    ///   TRUE if operation is successful.
    /// @sa
    ///   Read()
    bool Write(CNcbiOstream& os) const;
    /// Reset the registry content.
    void Clear(void);
    /// Get the parameter value.
    ///
    /// Get the parameter with the specified "name" from the specified 
    /// "section".  First, search for the transient parameter value, and if
    /// cannot find in there, then continue the search in the non-transient
    /// paramters. If "ePersistent" flag is set in "flags", then don't search
    /// in the transient transient parameters at all.
    /// @param section
    ///   Section name to search under.
    /// @param name
    ///   Parameter name to search for.
    /// @param flags
    ///   To control search.
    /// @return
    ///   The parameter value, or empty string if the parameter is not found.
    /// @sa
    ///   GetString()
    const string& Get(const string& section, const string& name,
                      TFlags flags = 0) const;
    /// Get the parameter string value.
    ///
    /// Similar to the "Get()", but if the configuration parameter is not
    /// found, then return 'default_value' rather than empty string.
    /// @sa
    ///   Get()
    const string GetString(const string& section, const string& name,
                           const string& default_value, TFlags flags = 0)
        const;
    /// What to do if parameter value is present but cannot be converted into
    /// the requested type.
    enum EErrAction {
        eThrow,   ///< Throw an exception if an error occurs
        eErrPost, ///< Log the error message and return default value
        eReturn   ///< Return default value
    };
    /// Get integer value of specified parameter name.
    ///
    /// Like "GetString()", plus convert the value into integer.
    /// @param err_action
    ///   What to do if error encountered in converting parameter value.
    /// @sa
    ///   GetString()
    int GetInt(const string& section, const string& name,
               int default_value, TFlags flags = 0,
               EErrAction err_action = eThrow) const;
    /// Get boolean value of specified parameter name.
    ///
    /// Like "GetString()", plus convert the value into boolean.
    /// @param err_action
    ///   What to do if error encountered in converting parameter value.
    /// @sa
    ///   GetString()
    bool GetBool(const string& section, const string& name,
                 bool default_value,  TFlags flags = 0,
                 EErrAction err_action = eThrow) const;
    /// Get double value of specified parameter name.
    ///
    /// Like "GetString()", plus convert the value into double.
    /// @param err_action
    ///   What to do if error encountered in converting parameter value.
    /// @sa
    ///   GetString()
    double GetDouble(const string& section, const string& name,
                     double default_value, TFlags flags = 0,
                     EErrAction err_action = eThrow) const;
    /// Set the configuration parameter value.
    ///
    /// Unset the parameter if specified "value" is empty.
    ///
    /// @param value
    ///   Value that the parameter is set to.
    /// @param flags
    ///   To control search.
    ///   Valid flags := { ePersistent, eNoOverride, eTruncate }
    ///   If there was already an entry with the same <section,name> key:
    ///     if "eNoOverride" flag is set then do not override old value
    ///     and return FALSE;  else override the old value and return TRUE.
    ///   If "ePersistent" flag is set then store the entry as persistent;
    ///     else store it as transient.
    ///   If "eTruncate" flag is set then truncate the leading and trailing
    ///     spaces -- " rtv" (NOTE:  'n' is not considered a space!).
    /// @param comment
    ///   Optional comment string describing parameter.
    /// @return
    ///   TRUE if specified parameter is set; FALSE otherwise.
    bool Set(const string& section, const string& name, const string& value,
             TFlags flags = 0, const string& comment = kEmptyStr);
    /// Set comment "comment" for the registry entry "section:name".
    ///
    /// @param comment
    ///   Comment string value.
    ///   Set to kEmptyStr to delete the comment.
    /// @param section
    ///   Section name.
    ///   If "section" is empty string, then set as the registry comment.
    /// @param name
    ///   Parameter name.
    ///   If "name" is empty string, then set as the "section" comment.
    /// @return
    ///   FALSE if "section" and/or "name" do not exist in registry.
    bool SetComment(const string& comment,
                    const string& section = kEmptyStr,
                    const string& name    = kEmptyStr);
    /// Get comment of the registry entry "section:name".
    ///
    /// @param section
    ///   Section name.
    ///   If passed empty string, then get the registry comment.
    /// @param name
    ///   Parameter name.
    ///   If empty string, then get the "section" comment.
    /// @return
    ///   Comment string. If not found, return an empty string.
    const string& GetComment(const string& section = kEmptyStr,
                             const string& name    = kEmptyStr) const;
    /// Enumerate section names.
    ///
    /// Write all section names to the "sections" list.
    /// Previous contents of the list are erased.
    void EnumerateSections(list<string>* sections) const;
    /// Enumerate parameter names for a specfiied section.
    ///
    /// Write all parameter names for specified "section" to the "entries"
    /// list. Previous contents of the list are erased.
    void EnumerateEntries(const string& section, list<string>* entries) const;
private:
    /// Hold values for Registry entry.
    struct TRegEntry {
        string persistent;  ///< Non-transient value
        string transient;   ///< Transient value
        string comment;     ///< Entry's comment string
    };
    /// Define Registry section as a map of entry parameter names
    /// and the parameter values.
    typedef map<string, TRegEntry,   PNocase>  TRegSection; 
    /// Define Registry as a map of section names and section
    /// values (TRegSection).
    typedef map<string, TRegSection, PNocase>  TRegistry;
    TRegistry    m_Registry;  ///< Internal representation of registry.
    string       m_Comment;   ///< All-registry comment
    mutable bool m_Modified;  ///< Persistent value(s) changed
    mutable bool m_Written;   ///< Method Write() was called at least once
    /// Helper method to set registry entry value and comment string.
    void x_SetValue(TRegEntry& entry, const string& value,
                    TFlags flags, const string& comment);
    /// Helper method to check if the registry contains only transient entries
    /// and comments.
    bool x_IsAllTransient(void) const;
    /// Private copy constructor to prohibit default intitialization.
    CNcbiRegistry(const CNcbiRegistry&);
    /// Private assignment operator to prohibit default assignment.
    CNcbiRegistry& operator= (const CNcbiRegistry&);
};
END_NCBI_SCOPE
/* @} */
/*
 * ===========================================================================
 * $Log: ncbireg.hpp,v $
 * Revision 1000.0  2003/10/29 15:05:14  gouriano
 * PRODUCTION: IMPORTED [ORIGINAL] Dev-tree R1.32
 *
 * Revision 1.32  2003/10/20 21:55:05  vakatov
 * CNcbiRegistry::GetComment() -- make it "const"
 *
 * Revision 1.31  2003/08/18 18:44:07  siyan
 * Minor comment changes.
 *
 * Revision 1.30  2003/08/14 12:25:28  siyan
 * Made previous documentation changes consistent.
 * Best not to mix the ///< style with @param style for parameter documentation
 * as Doxygen may not always render this correctly.
 *
 * Revision 1.29  2003/08/12 19:00:39  vakatov
 * Fixed comments and code layout
 *
 * Revision 1.27  2003/07/21 18:42:38  siyan
 * Documentation changes.
 *
 * Revision 1.26  2003/04/07 19:40:03  ivanov
 * Rollback to R1.24
 *
 * Revision 1.25  2003/04/07 16:08:41  ivanov
 * Added more thread-safety to CNcbiRegistry:: methods -- mutex protection.
 * Get() and GetComment() returns "string", not "string&".
 *
 * Revision 1.24  2003/04/01 14:20:28  siyan
 * Added doxygen support
 *
 * Revision 1.23  2003/02/28 19:24:42  vakatov
 * Get rid of redundant "const" in the return type of GetInt/Bool/Double()
 *
 * Revision 1.22  2003/02/24 19:54:51  gouriano
 * use template-based exceptions instead of errno and parse exceptions
 *
 * Revision 1.21  2003/01/17 20:46:28  vakatov
 * Fixed/improved description of "EErrAction"
 *
 * Revision 1.20  2003/01/17 20:26:59  kuznets
 * CNcbiRegistry added ErrPost error action
 *
 * Revision 1.19  2003/01/17 17:31:20  vakatov
 * CNcbiRegistry::GetString() to return "string", not "string&" -- for safety
 *
 * Revision 1.18  2002/12/30 23:23:06  vakatov
 * + GetString(), GetInt(), GetBool(), GetDouble() -- with defaults,
 * conversions and error handling control (to extend Get()'s functionality).
 *
 * Revision 1.17  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.16  2002/04/11 20:39:18  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.15  2001/09/11 00:46:56  vakatov
 * Fixes to R1.14:
 *   Renamed HasChanged() to Modified(), refined and extended its functionality
 *   Made Write() be "const" again
 *
 * Revision 1.14  2001/09/10 16:35:02  ivanov
 * Added method HasChanged()
 *
 * Revision 1.13  2001/06/22 21:50:20  ivanov
 * Added (with Denis Vakatov) ability for read/write the registry file
 * with comments. Also added functions GetComment() and SetComment().
 *
 * Revision 1.12  2001/05/17 14:54:01  lavr
 * Typos corrected
 *
 * Revision 1.11  2001/04/09 17:39:20  grichenk
 * CNcbiRegistry::Get() return type reverted to "const string&"
 *
 * Revision 1.10  2001/04/06 15:46:29  grichenk
 * Added thread-safety to CNcbiRegistry:: methods
 *
 * Revision 1.9  1999/09/02 21:53:23  vakatov
 * Allow '-' and '.' in the section/entry name
 *
 * Revision 1.8  1999/07/07 14:17:05  vakatov
 * CNcbiRegistry::  made the section and entry names be case-insensitive
 *
 * Revision 1.7  1999/07/06 15:26:31  vakatov
 * CNcbiRegistry::
 *   - allow multi-line values
 *   - allow values starting and ending with space symbols
 *   - introduced EFlags/TFlags for optional parameters in the class
 *     member functions -- rather than former numerous boolean parameters
 *
 * Revision 1.6  1998/12/28 17:56:28  vakatov
 * New CVS and development tree structure for the NCBI C++ projects
 *
 * Revision 1.5  1998/12/10 22:59:46  vakatov
 * CNcbiRegistry:: API is ready(and by-and-large tested)
 * ===========================================================================
 */
#endif  /* CORELIB___NCBIREG__HPP */

						