Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members

environment.h

00001 // environment.h
00002 #ifndef s11n_ENVIRONMENT_H_INCLUDED
00003 #define s11n_ENVIRONMENT_H_INCLUDED 1
00004 
00005 // License: Public Domain
00006 // Author: stephan@s11n.net
00007 
00008 #include <s11n/property_store.h>
00009 
00010 namespace s11n {
00011 
00012 /**
00013 environment is an OO front-end to getenv()-like functionality. It provides some
00014 type-casting-like functionality, so you can easily read in environment vars which have,
00015 e.g., numeric values.
00016 */
00017 class environment : public property_store
00018 {
00019  public:
00020         /**
00021            Returns a reference to a shared object containing the
00022            keys/values from the given char ** (defaults to 'environ',
00023            from &lt;unistd.h&gt;, which represents the shell's
00024            environment). The input array is not changed, but is not
00025            const because environ is not const. See 'man 5 environ' for
00026            info about the default environment array.
00027 
00028            Calling it with a non-0 parameter will clear the current
00029            environment settings and parse them from the passed-in
00030            array, which is expected to be in the form:
00031 
00032 <pre>
00033 "KEY1=VAL1",
00034 "KEY2=VALUE TWO",
00035 ...
00036 0
00037 </pre>
00038 
00039              The returned object has propagate_sets() == true.
00040 
00041              Tip: s11n::s11n_node::serialize_properties() can
00042              de/serialize this object.
00043          */
00044         static environment & env( char ** = 0 );
00045 
00046 
00047         /**
00048            Re-implemented to pass the key/val to ::setenv() (so
00049            subshells can access them).
00050 
00051            Changes are not written back to the global shell
00052            environment (using setenv()) unless propagate_sets() has
00053            been set to true.
00054          */
00055         virtual void set_string( const std::string &key, std::string val );
00056 
00057         /**
00058            Overridden to call unsetenv() if propagate_sets() has been set.
00059 
00060            Note that the parent class' clear_properties() does not
00061            call unset(), so calling clear_properties() on this object
00062            will not hose the global environment even if
00063            propagate_sets() is true.
00064         */
00065         virtual bool unset( const std::string & key );
00066 
00067         /**
00068            Parsed env vars out of text, replacing them with their
00069            values. Accepts variable tokens in these forms:
00070 
00071            ${VAR}
00072            $VAR
00073 
00074            e.g., $foo correspond's to the value returned by
00075            this->get_string("foo").
00076 
00077            Referencing a variable which is not set does not
00078            expand the variable to an empty value: it is left
00079            as-is. Thus expanding $FOO when "FOO" is not set
00080            will result in "$FOO".
00081 
00082            To get a dollar sign into the resulting string, escape
00083            it with a single backslash: this keeps it from being
00084            parsed as a $variable.
00085          */
00086         std::string expand_vars( const std::string & text ) const;
00087 
00088         /**
00089            Exactly like expand_vars() but directly modifies
00090            the input string. Returns the number of variables
00091            expanded.
00092         */
00093         size_t expand_vars_inline( std::string & text ) const;
00094 
00095         /**
00096            If set to true then calls to set_string() will
00097            also make a call to setenv(), effectively propagating
00098            changes back into the main environment.
00099 
00100            The default is false.
00101         */
00102         void propagate_sets( bool );
00103 
00104        /**
00105            Does conventions-compliant tilde/HOME expansion on the
00106            given input.
00107 
00108            Returns true if it modifies the string, else false.
00109 
00110            Bug: it only works on single tokens. That is,
00111            the input must be only one token long, where whitespace
00112            delimits tokens.
00113          */
00114           bool expand_tilde_home( std::string & ) const;
00115 
00116         environment();
00117         virtual ~environment();
00118 
00119  private:
00120         environment( const environment & ); // intentionally unimplemented.
00121         bool m_propagate;
00122 };
00123 
00124 } // namespace s11n
00125 #endif // s11n_ENVIRONMENT_H_INCLUDED

Generated on Tue Oct 26 18:25:59 2004 for s11n by  doxygen 1.3.9.1