2 * Copyright (c) 2001-2003 The Regents of The University of Michigan
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.
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.
29 #ifndef __INIFILE_HH__
30 #define __INIFILE_HH__
37 #include "base/hashmap.hh"
41 * Declaration of IniFile object.
42 * @todo Change comments to match documentation style.
46 /// This class represents the contents of a ".ini" file.
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.
57 /// A single key/value pair.
61 std::string value; ///< The entry value.
62 mutable bool referenced; ///< Has this entry been used?
66 Entry(const std::string &v)
67 : value(v), referenced(false)
71 /// Has this entry been used?
72 bool isReferenced() { return referenced; }
75 const std::string &getValue() const;
78 void setValue(const std::string &v) { value = v; }
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
85 void appendValue(const std::string &v) { value += " "; value += v; }
93 /// EntryTable type. Map of strings to Entry object pointers.
94 typedef m5::hash_map<std::string, Entry *> EntryTable;
96 EntryTable table; ///< Table of entries.
97 mutable bool referenced; ///< Has this section been used?
102 : table(), referenced(false)
106 /// Has this section been used?
107 bool isReferenced() { return referenced; }
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,
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);
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;
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 §ionName);
134 /// Print the contents of this section to cout (for debugging).
135 void dump(const std::string §ionName);
138 /// SectionTable type. Map of strings to Section object pointers.
139 typedef m5::hash_map<std::string, Section *> SectionTable;
142 /// Hash of section names to Section object pointers.
145 /// Look up section with the given name, creating a new section if
147 /// @retval Pointer to section object.
148 Section *addSection(const std::string §ionName);
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 §ionName) const;
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);
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);
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);
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);
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 §ion, const std::string &entry,
191 std::string &value) const;
193 /// Find value corresponding to given section and entry names,
194 /// following "default" links to other sections where possible.
195 /// Value is returned by reference in 'value' param.
196 /// @return True if found, false if not.
197 bool findDefault(const std::string §ion, const std::string &entry,
198 std::string &value) const;
201 * Find a value corresponding to the given section and entry names
202 * following "append" links to other sections where possible.
203 * @param section The section to start with.
204 * @param entry The entry to find.
205 * @param value The value found.
206 * @return True if the entry was found.
208 bool findAppend(const std::string §ion, const std::string &entry,
209 std::string &value) const;
211 /// Determine whether the named section exists in the .ini file.
212 /// Note that the 'Section' class is (intentionally) not public,
213 /// so all clients can do is get a bool that says whether there
214 /// are any values in that section or not.
215 /// @return True if the section exists.
216 bool sectionExists(const std::string §ion) const;
218 /// Print unreferenced entries in object. Iteratively calls
219 /// printUnreferend() on all the constituent sections.
220 bool printUnreferenced();
222 /// Dump contents to cout. For debugging.
226 #endif // __INIFILE_HH__