src/base/inifile.hh

   1 /*
   2  * Copyright (c) 2001-2005 The Regents of The University of Michigan
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met: redistributions of source code must retain the above copyright
   8  * notice, this list of conditions and the following disclaimer;
   9  * redistributions in binary form must reproduce the above copyright
  10  * notice, this list of conditions and the following disclaimer in the
  11  * documentation and/or other materials provided with the distribution;
  12  * neither the name of the copyright holders nor the names of its
  13  * contributors may be used to endorse or promote products derived from
  14  * this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 #ifndef __INIFILE_HH__
  30 #define __INIFILE_HH__
  31
  32 #include <fstream>
  33 #include <list>
  34 #include <string>
  35 #include <vector>
  36
  37 #include "base/hashmap.hh"
  38
  39 /**
  40  * @file
  41  * Declaration of IniFile object.
  42  * @todo Change comments to match documentation style.
  43  */
  44
  45 ///
  46 /// This class represents the contents of a ".ini" file.
  47 ///
  48 /// It's basically a two level lookup table: a set of named sections,
  49 /// where each section is a set of key/value pairs.  Section names,
  50 /// keys, and values are all uninterpreted strings.
  51 ///
  52 class IniFile
  53 {
  54   protected:
  55
  56     ///
  57     /// A single key/value pair.
  58     ///
  59     class Entry
  60     {
  61         std::string     value;          ///< The entry value.
  62         mutable bool    referenced;     ///< Has this entry been used?
  63
  64       public:
  65         /// Constructor.
  66         Entry(const std::string &v)
  67             : value(v), referenced(false)
  68         {
  69         }
  70
  71         /// Has this entry been used?
  72         bool isReferenced() { return referenced; }
  73
  74         /// Fetch the value.
  75         const std::string &getValue() const;
  76
  77         /// Set the value.
  78         void setValue(const std::string &v) { value = v; }
  79
  80         /// Append the given string to the value.  A space is inserted
  81         /// between the existing value and the new value.  Since this
  82         /// operation is typically used with values that are
  83         /// space-separated lists of tokens, this keeps the tokens
  84         /// separate.
  85         void appendValue(const std::string &v) { value += " "; value += v; }
  86     };
  87
  88     ///
  89     /// A section.
  90     ///
  91     class Section
  92     {
  93         /// EntryTable type.  Map of strings to Entry object pointers.
  94         typedef m5::hash_map<std::string, Entry *> EntryTable;
  95
  96         EntryTable      table;          ///< Table of entries.
  97         mutable bool    referenced;     ///< Has this section been used?
  98
  99       public:
 100         /// Constructor.
 101         Section()
 102             : table(), referenced(false)
 103         {
 104         }
 105
 106         /// Has this section been used?
 107         bool isReferenced() { return referenced; }
 108
 109         /// Add an entry to the table.  If an entry with the same name
 110         /// already exists, the 'append' parameter is checked If true,
 111         /// the new value will be appended to the existing entry.  If
 112         /// false, the new value will replace the existing entry.
 113         void addEntry(const std::string &entryName, const std::string &value,
 114                       bool append);
 115
 116         /// Add an entry to the table given a string assigment.
 117         /// Assignment should be of the form "param=value" or
 118         /// "param+=value" (for append).  This funciton parses the
 119         /// assignment statment and calls addEntry().
 120         /// @retval True for success, false if parse error.
 121         bool add(const std::string &assignment);
 122
 123         /// Find the entry with the given name.
 124         /// @retval Pointer to the entry object, or NULL if none.
 125         Entry *findEntry(const std::string &entryName) const;
 126
 127         /// Print the unreferenced entries in this section to cerr.
 128         /// Messages can be suppressed using "unref_section_ok" and
 129         /// "unref_entries_ok".
 130         /// @param sectionName Name of this section, for use in output message.
 131         /// @retval True if any entries were printed.
 132         bool printUnreferenced(const std::string &sectionName);
 133
 134         /// Print the contents of this section to cout (for debugging).
 135         void dump(const std::string &sectionName);
 136     };
 137
 138     /// SectionTable type.  Map of strings to Section object pointers.
 139     typedef m5::hash_map<std::string, Section *> SectionTable;
 140
 141   protected:
 142     /// Hash of section names to Section object pointers.
 143     SectionTable table;
 144
 145     /// Look up section with the given name, creating a new section if
 146     /// not found.
 147     /// @retval Pointer to section object.
 148     Section *addSection(const std::string &sectionName);
 149
 150     /// Look up section with the given name.
 151     /// @retval Pointer to section object, or NULL if not found.
 152     Section *findSection(const std::string &sectionName) const;
 153
 154   public:
 155     /// Constructor.
 156     IniFile();
 157
 158     /// Destructor.
 159     ~IniFile();
 160
 161     /// Load parameter settings from given istream.  This is a helper
 162     /// function for load(string) and loadCPP(), which open a file
 163     /// and then pass it here.
 164     /// @retval True if successful, false if errors were encountered.
 165     bool load(std::istream &f);
 166
 167     /// Load the specified file, passing it through the C preprocessor.
 168     /// Parameter settings found in the file will be merged with any
 169     /// already defined in this object.
 170     /// @param file The path of the file to load.
 171     /// @param cppFlags Vector of extra flags to pass to cpp.
 172     /// @retval True if successful, false if errors were encountered.
 173     bool loadCPP(const std::string &file, std::vector<char *> &cppFlags);
 174
 175     /// Load the specified file.
 176     /// Parameter settings found in the file will be merged with any
 177     /// already defined in this object.
 178     /// @param file The path of the file to load.
 179     /// @retval True if successful, false if errors were encountered.
 180     bool load(const std::string &file);
 181
 182     /// Take string of the form "<section>:<parameter>=<value>" or
 183     /// "<section>:<parameter>+=<value>" and add to database.
 184     /// @retval True if successful, false if parse error.
 185     bool add(const std::string &s);
 186
 187     /// Find value corresponding to given section and entry names.
 188     /// Value is returned by reference in 'value' param.
 189     /// @retval True if found, false if not.
 190     bool find(const std::string &section, const std::string &entry,
 191               std::string &value) const;
 192
 193     /// Determine whether the named section exists in the .ini file.
 194     /// Note that the 'Section' class is (intentionally) not public,
 195     /// so all clients can do is get a bool that says whether there
 196     /// are any values in that section or not.
 197     /// @return True if the section exists.
 198     bool sectionExists(const std::string &section) const;
 199
 200     /// Print unreferenced entries in object.  Iteratively calls
 201     /// printUnreferend() on all the constituent sections.
 202     bool printUnreferenced();
 203
 204     /// Dump contents to cout.  For debugging.
 205     void dump();
 206 };
 207
 208 #endif // __INIFILE_HH__