ncbienv.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbienv.hpp,v $
 * PRODUCTION Revision 1000.1  2004/02/12 21:44:43  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [CORE_001] Dev-tree R1.14
 * PRODUCTION
 * ===========================================================================
 */

#ifndef NCBIENV__HPP
#define NCBIENV__HPP

/*  $Id: ncbienv.hpp,v 1000.1 2004/02/12 21:44:43 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.
 *
 * ===========================================================================
 *
 * Authors:  Denis Vakatov, Eugene Vasilchenko
 *
 *
 */

/// @file ncbienv.hpp
/// Defines unified interface to application:
/// - Environment        -- CNcbiEnvironment
/// - Command-line args  -- CNcbiArguments


#include <corelib/ncbifile.hpp>
#include <corelib/ncbimtx.hpp>
#include <map>
#include <deque>

/// Avoid name clash with the NCBI C Toolkit.
#if !defined(NCBI_OS_UNIX)  ||  defined(HAVE_NCBI_C)
#  if defined(GetProgramName)
#    undef GetProgramName
#  endif
#  define GetProgramName GetProgramName
#  if defined(SetProgramName)
#    undef SetProgramName
#  endif
#  define SetProgramName SetProgramName
#endif


/** @addtogroup Environment
 *
 * @{
 */


BEGIN_NCBI_SCOPE


/////////////////////////////////////////////////////////////////////////////
///
/// CArgumentsException --
///
/// Define exceptions generated by CArgumentsApplication.
///
/// CArgumentsException inherits its basic functionality from CCoreException
/// and defines additional error codes for applications.

class NCBI_XNCBI_EXPORT CArgumentsException : public CCoreException
{
public:
    /// Error types that arguments processing can generate.
    enum EErrCode {
        eNegativeArgc,  ///< Negative argc value
        eNoArgs         ///< No arguments
    };

    /// Translate from the error code value to its string representation.
    virtual const char* GetErrCodeString(void) const
    {
        switch (GetErrCode()) {
        case eNegativeArgc:  return "eNegativeArgc";
        case eNoArgs:        return "eNoArgs";
        default:    return CException::GetErrCodeString();
        }
    }

    // Standard exception boilerplate code.
    NCBI_EXCEPTION_DEFAULT(CArgumentsException, CCoreException);
};



/////////////////////////////////////////////////////////////////////////////
///
/// CNcbiEnvironment --
///
/// Define the application environment.
///
/// CNcbiEnvironment provides a data structure for storing, accessing and
/// modifying the environment variables accessed by the C library routine
/// getenv().

class NCBI_XNCBI_EXPORT CNcbiEnvironment
{
public:
    /// Constructor.
    CNcbiEnvironment(void);

    /// Constructor with the envp parameter.
    CNcbiEnvironment(const char* const* envp);

    /// Destructor.
    virtual ~CNcbiEnvironment(void);

    /// Reset environment.
    ///
    /// Delete all cached entries, load new ones from "envp" (if not NULL).
    void Reset(const char* const* envp = 0);

    /// Get environment value by name.
    ///
    /// If environmnent value is not cached then call "Load(name)" to load
    /// the environmnent value.  The loaded name/value pair will then be
    /// cached, too, after the call to "Get()".
    const string& Get(const string& name) const;

    /// Set an environment variable by name
    ///
    /// This will throw an exception if setting the variable fails
    void Set(const string& name, const string& value);

protected:
    /// Load value of specified environment variable.
    virtual string Load(const string& name) const;

private:
    /// Cached environment <name,value> pair.
    mutable map<string, string> m_Cache;
};



/////////////////////////////////////////////////////////////////////////////
///
/// CNcbiArguments --
///
/// Store application command-line arguments & application name.
///
/// CNcbiArgument provides a data structure for storing and accessing the
/// command line arguments and application name.

class NCBI_XNCBI_EXPORT CNcbiArguments
{
public:
    /// Constructor.
    CNcbiArguments(int argc,                ///< Standard argument count
                   const char* const* argv, ///< Standard argument vector
                   const string& program_name = NcbiEmptyString
                                            ///< Program name
                  );

    /// Destructor.
    virtual ~CNcbiArguments(void);

    /// Copy constructor.
    CNcbiArguments(const CNcbiArguments& args);

    /// Assignment operator.
    CNcbiArguments& operator= (const CNcbiArguments& args);

    /// Reset arguments.
    ///
    /// Delete all cached args and program name.  Load new ones from "argc",
    /// "argv" and "program_name".
    void Reset(int argc,                    ///< Standard argument count
               const char* const* argv,     ///< Standard argument vector
               const string& program_name = NcbiEmptyString
                                            ///< Program name
              );

    /// Get size (number) of arguments.
    SIZE_TYPE Size(void) const { return m_Args.size(); }

    /// Get the argument specified by "pos".
    const string& operator[] (SIZE_TYPE pos) const { return m_Args[pos]; }

    /// Add a new argument.
    void Add(const string& arg);

    /// Get program name.
    const string& GetProgramName(EFollowLinks follow_links = eIgnoreLinks)
        const;

    /// Get program base name.
    string GetProgramBasename(EFollowLinks follow_links = eIgnoreLinks) const;

    /// Get program directory name.
    ///
    /// Program name includes the last '/'.
    string GetProgramDirname (EFollowLinks follow_links = eIgnoreLinks) const;

    /// Set program name.
    void SetProgramName(const string& program_name);

private:
    string        m_ProgramName;  ///< Program name if different from the
                                  ///< default m_Args[0]
    deque<string> m_Args;         ///< Queue of arguments

    mutable string     m_ResolvedName;
    mutable CFastMutex m_ResolvedNameMutex;
};


END_NCBI_SCOPE


/* @} */


/*
 * ===========================================================================
 * $Log: ncbienv.hpp,v $
 * Revision 1000.1  2004/02/12 21:44:43  gouriano
 * PRODUCTION: UPGRADED [CORE_001] Dev-tree R1.14
 *
 * Revision 1.14  2004/01/06 18:17:21  dicuccio
 * Added APIs for setting environment variables
 *
 * Revision 1.13  2003/10/01 14:32:09  ucko
 * +EFollowLinks
 *
 * Revision 1.12  2003/09/30 15:09:44  ucko
 * CNcbiArguments::GetProgram{Name,Basename,Dirname}: optionally resolve symlinks.
 *
 * Revision 1.11  2003/07/25 12:26:19  siyan
 * Documentation changes.
 *
 * Revision 1.10  2003/03/31 16:06:06  siyan
 * Added doxygen support
 *
 * Revision 1.9  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.8  2002/07/15 18:17:51  gouriano
 * renamed CNcbiException and its descendents
 *
 * Revision 1.7  2002/07/11 14:17:54  gouriano
 * exceptions replaced by CNcbiException-type ones
 *
 * Revision 1.6  2002/04/11 20:39:17  ivanov
 * CVS log moved to end of the file
 *
 * Revision 1.5  2001/04/13 02:59:31  vakatov
 * Do not apply R1.4 for non-UNIX platforms where we cannot configure
 * HAVE_NCBI_C yet
 *
 * Revision 1.4  2001/04/12 22:56:58  vakatov
 * [HAVE_NCBI_C]  Handle #GetProgramName and #SetProgramName to avoid
 *                name clash with the NCBI C Toolkit
 *
 * Revision 1.3  2000/08/31 23:50:04  vakatov
 * CNcbiArguments:: Inlined Size() and operator[];   use <deque>
 *
 * Revision 1.2  2000/01/20 16:36:02  vakatov
 * Added class CNcbiArguments::   application command-line arguments & name
 * Added CNcbiEnvironment::Reset(), and comments to CNcbiEnvironment::
 * Dont #include <ncbienv.inl>
 *
 * Revision 1.1  1999/05/04 16:14:06  vasilche
 * Fixed problems with program environment.
 * Added class CNcbiEnvironment for cached access to C environment.
 * ===========================================================================
 */

#endif  /* NCBIENV__HPP */