inifile.hh revision 2632:1bb2f91485ea
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///
52class 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__
209