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  * Authors: Nathan Binkert
  29  *          Steve Reinhardt
  30  */
  31
  32 #ifndef __INIFILE_HH__
  33 #define __INIFILE_HH__
  34
  35 #include <fstream>
  36 #include <list>
  37 #include <string>
  38 #include <unordered_map>
  39 #include <vector>
  40
  41 /**
  42  * @file
  43  * Declaration of IniFile object.
  44  * @todo Change comments to match documentation style.
  45  */
  46
  47 ///
  48 /// This class represents the contents of a ".ini" file.
  49 ///
  50 /// It's basically a two level lookup table: a set of named sections,
  51 /// where each section is a set of key/value pairs.  Section names,
  52 /// keys, and values are all uninterpreted strings.
  53 ///
  54 class IniFile
  55 {
  56   protected:
  57
  58     ///
  59     /// A single key/value pair.
  60     ///
  61     class Entry
  62     {
  63         std::string     value;          ///< The entry value.
  64         mutable bool    referenced;     ///< Has this entry been used?
  65
  66       public:
  67         /// Constructor.
  68         Entry(const std::string &v)
  69             : value(v), referenced(false)
  70         {
  71         }
  72
  73         /// Has this entry been used?
  74         bool isReferenced() { return referenced; }
  75
  76         /// Fetch the value.
  77         const std::string &getValue() const;
  78
  79         /// Set the value.
  80         void setValue(const std::string &v) { value = v; }
  81
  82         /// Append the given string to the value.  A space is inserted
  83         /// between the existing value and the new value.  Since this
  84         /// operation is typically used with values that are
  85         /// space-separated lists of tokens, this keeps the tokens
  86         /// separate.
  87         void appendValue(const std::string &v) { value += " "; value += v; }
  88     };
  89
  90     ///
  91     /// A section.
  92     ///
  93     class Section
  94     {
  95         /// EntryTable type.  Map of strings to Entry object pointers.
  96         typedef std::unordered_map<std::string, Entry *> EntryTable;
  97
  98         EntryTable      table;          ///< Table of entries.
  99         mutable bool    referenced;     ///< Has this section been used?
 100
 101       public:
 102         /// Constructor.
 103         Section()
 104             : table(), referenced(false)
 105         {
 106         }
 107
 108         /// Has this section been used?
 109         bool isReferenced() { return referenced; }
 110
 111         /// Add an entry to the table.  If an entry with the same name
 112         /// already exists, the 'append' parameter is checked If true,
 113         /// the new value will be appended to the existing entry.  If
 114         /// false, the new value will replace the existing entry.
 115         void addEntry(const std::string &entryName, const std::string &value,
 116                       bool append);
 117
 118         /// Add an entry to the table given a string assigment.
 119         /// Assignment should be of the form "param=value" or
 120         /// "param+=value" (for append).  This funciton parses the
 121         /// assignment statment and calls addEntry().
 122         /// @retval True for success, false if parse error.
 123         bool add(const std::string &assignment);
 124
 125         /// Find the entry with the given name.
 126         /// @retval Pointer to the entry object, or NULL if none.
 127         Entry *findEntry(const std::string &entryName) const;
 128
 129         /// Print the unreferenced entries in this section to cerr.
 130         /// Messages can be suppressed using "unref_section_ok" and
 131         /// "unref_entries_ok".
 132         /// @param sectionName Name of this section, for use in output message.
 133         /// @retval True if any entries were printed.
 134         bool printUnreferenced(const std::string &sectionName);
 135
 136         /// Print the contents of this section to cout (for debugging).
 137         void dump(const std::string &sectionName);
 138     };
 139
 140     /// SectionTable type.  Map of strings to Section object pointers.
 141     typedef std::unordered_map<std::string, Section *> SectionTable;
 142
 143   protected:
 144     /// Hash of section names to Section object pointers.
 145     SectionTable table;
 146
 147     /// Look up section with the given name, creating a new section if
 148     /// not found.
 149     /// @retval Pointer to section object.
 150     Section *addSection(const std::string &sectionName);
 151
 152     /// Look up section with the given name.
 153     /// @retval Pointer to section object, or NULL if not found.
 154     Section *findSection(const std::string &sectionName) const;
 155
 156   public:
 157     /// Constructor.
 158     IniFile();
 159
 160     /// Destructor.
 161     ~IniFile();
 162
 163     /// Load parameter settings from given istream.  This is a helper
 164     /// function for load(string) and loadCPP(), which open a file
 165     /// and then pass it here.
 166     /// @retval True if successful, false if errors were encountered.
 167     bool load(std::istream &f);
 168
 169     /// Load the specified file.
 170     /// Parameter settings found in the file will be merged with any
 171     /// already defined in this object.
 172     /// @param file The path of the file to load.
 173     /// @retval True if successful, false if errors were encountered.
 174     bool load(const std::string &file);
 175
 176     /// Take string of the form "<section>:<parameter>=<value>" or
 177     /// "<section>:<parameter>+=<value>" and add to database.
 178     /// @retval True if successful, false if parse error.
 179     bool add(const std::string &s);
 180
 181     /// Find value corresponding to given section and entry names.
 182     /// Value is returned by reference in 'value' param.
 183     /// @retval True if found, false if not.
 184     bool find(const std::string &section, const std::string &entry,
 185               std::string &value) const;
 186
 187     /// Determine whether the entry exists within named section exists
 188     /// in the .ini file.
 189     /// @return True if the section exists.
 190     bool entryExists(const std::string &section,
 191                      const std::string &entry) 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     /// Push all section names into the given vector
 201     void getSectionNames(std::vector<std::string> &list) const;
 202
 203     /// Print unreferenced entries in object.  Iteratively calls
 204     /// printUnreferend() on all the constituent sections.
 205     bool printUnreferenced();
 206
 207     /// Dump contents to cout.  For debugging.
 208     void dump();
 209 };
 210
 211 #endif // __INIFILE_HH__