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 <functional>
  34 #include <list>
  35 #include <string>
  36 #include <unordered_map>
  37 #include <vector>
  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 std::unordered_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         EntryTable::const_iterator begin() const;
 138         EntryTable::const_iterator end() const;
 139     };
 140
 141     /// SectionTable type.  Map of strings to Section object pointers.
 142     typedef std::unordered_map<std::string, Section *> SectionTable;
 143
 144   protected:
 145     /// Hash of section names to Section object pointers.
 146     SectionTable table;
 147
 148     /// Look up section with the given name, creating a new section if
 149     /// not found.
 150     /// @retval Pointer to section object.
 151     Section *addSection(const std::string &sectionName);
 152
 153     /// Look up section with the given name.
 154     /// @retval Pointer to section object, or NULL if not found.
 155     Section *findSection(const std::string &sectionName) const;
 156
 157   public:
 158     /// Constructor.
 159     IniFile();
 160
 161     /// Destructor.
 162     ~IniFile();
 163
 164     /// Load parameter settings from given istream.  This is a helper
 165     /// function for load(string) and loadCPP(), which open a file
 166     /// and then pass it here.
 167     /// @retval True if successful, false if errors were encountered.
 168     bool load(std::istream &f);
 169
 170     /// Load the specified file.
 171     /// Parameter settings found in the file will be merged with any
 172     /// already defined in this object.
 173     /// @param file The path of the file to load.
 174     /// @retval True if successful, false if errors were encountered.
 175     bool load(const std::string &file);
 176
 177     /// Take string of the form "<section>:<parameter>=<value>" or
 178     /// "<section>:<parameter>+=<value>" and add to database.
 179     /// @retval True if successful, false if parse error.
 180     bool add(const std::string &s);
 181
 182     /// Find value corresponding to given section and entry names.
 183     /// Value is returned by reference in 'value' param.
 184     /// @retval True if found, false if not.
 185     bool find(const std::string &section, const std::string &entry,
 186               std::string &value) const;
 187
 188     /// Determine whether the entry exists within named section exists
 189     /// in the .ini file.
 190     /// @return True if the section exists.
 191     bool entryExists(const std::string &section,
 192                      const std::string &entry) const;
 193
 194     /// Determine whether the named section exists in the .ini file.
 195     /// Note that the 'Section' class is (intentionally) not public,
 196     /// so all clients can do is get a bool that says whether there
 197     /// are any values in that section or not.
 198     /// @return True if the section exists.
 199     bool sectionExists(const std::string &section) const;
 200
 201     /// Push all section names into the given vector
 202     void getSectionNames(std::vector<std::string> &list) const;
 203
 204     /// Print unreferenced entries in object.  Iteratively calls
 205     /// printUnreferend() on all the constituent sections.
 206     bool printUnreferenced();
 207
 208     /// Dump contents to cout.  For debugging.
 209     void dump();
 210
 211     /// Visitor callback that receives key/value pairs.
 212     using VisitSectionCallback = std::function<void(
 213         const std::string&, const std::string&)>;
 214
 215     /// Iterate over key/value pairs of the given section.
 216     void visitSection(const std::string &sectionName, VisitSectionCallback cb);
 217 };
 218
 219 #endif // __INIFILE_HH__