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

key_value_parser.h

00001 // Author: stephan beal <stephan@s11n.net>
00002 // License: Public Domain
00003 #ifndef s11n_KEYVALUEPARSER_H
00004 #define s11n_KEYVALUEPARSER_H
00005 
00006 #include <string>
00007 #include <map>
00008 #include <list>
00009 
00010 namespace s11n
00011 {
00012     using namespace std;
00013 
00014     /**
00015            key_value_parser is a class for parsing "key=value"-style lines,
00016            like those which would come from a configuration file.
00017         */
00018     class key_value_parser
00019     {
00020           public:
00021                 /**
00022                    Creates a new key_value_parser and runs parse( line ).
00023                 */
00024         explicit key_value_parser( const string & line );
00025                 /**
00026                    Creates an empty key_value_parser.
00027                 */
00028                 key_value_parser();
00029                 virtual ~key_value_parser(){}
00030 
00031         /**
00032                    Parses 'line' into a key/value pair. To be parseable the line must be in the form:
00033 
00034                    key=value
00035 
00036                    Extra whitespace around the '=' removed, as are leading and
00037                    trailing whitespace around the key and value. This behaviour is
00038                    arguable but probably desireable in most cases (it is in all of
00039                    mine, and i wrote the damned thing ;).
00040 
00041                    todo: add a whitespace removal policy as optional 3rd argument?
00042 
00043                    delimiter is the string which separates the key and
00044                    value, so a line in the format:
00045     
00046                        key{alternateDelimiter}value...
00047     
00048                    (minus the braces) is parseable. alternateDelimiter can be a set
00049                    of possible delimiters, such as " \t".
00050 
00051                    That is:
00052                    parse( "one;two",";" )
00053                    results in key() == "one" and value() == "two"
00054 
00055                    This function returns false if it does not consider the line to be parseable.
00056                    Use key() and value() to get the parsed values. Use line() to get the whole
00057                    string passed to parse (as if you'd ever need it, though subclasses might).
00058                    line() /is/ guaranteed to be set to line by this call, unlike key() and value().
00059        
00060                    If this function returns false, the values returned by key() and value()
00061                    cannot be considered reliable (i.e., they are undefined).
00062 
00063                    This function will return false if a line contains
00064                    no key (like '=value'), but empty values are not an
00065                    error (i.e., they will not cause this function to
00066                    return false). BUG: in some cases (when delimiter
00067                    is a space) a no-value key can fail to parse.
00068                 */
00069         bool parse( const string & line, const string & delimiter = "=" );
00070 
00071 
00072         /**
00073                    Returns the parsed-out key. Only valid if parse() returned true.
00074                 */
00075         inline const string & key() const
00076         {
00077             return this->m_key;
00078         }
00079 
00080                 /**
00081                    Sets this object's key().
00082                 */
00083         inline void key( const string & v )
00084         {
00085             this->m_key = v;
00086         }
00087         /**
00088                    Returns the parsed-out value (may be empty). Only valid if parse() returned true.
00089                 */
00090         inline const string & value() const
00091         {
00092             return this->m_val;
00093         }
00094                 /**
00095                    Sets this object's value().
00096                 */
00097         inline void value( const string & v )
00098         {
00099             this->m_val = v;
00100         }
00101         /**
00102                    Returns the last whole line passed to parse().
00103                 */
00104         inline const string & line() const
00105         {
00106             return this->m_line;
00107         }
00108 
00109           private:
00110         string m_key;
00111         string m_val;
00112         string m_line;
00113         string::const_iterator strIt;
00114     };
00115 
00116         /**
00117            enters k.key()=k.value() into os.
00118         */
00119         std::ostream & operator <<( std::ostream & os, const key_value_parser & );
00120 
00121 };              // namespace s11n
00122 #endif // s11n_KEYVALUEPARSER_H

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