Dogcows Code - chaz/yoink/blob - src/stlplus/subsystems/ini_manager.hpp

   1 #ifndef STLPLUS_INI_MANAGER
   2 #define STLPLUS_INI_MANAGER
   3 ////////////////////////////////////////////////////////////////////////////////
   4
   5 //   Author:    Andy Rushton
   6 //   Copyright: (c) Southampton University 1999-2004
   7 //              (c) Andy Rushton           2004-2009
   8 //   License:   BSD License, see ../docs/license.html
   9
  10 //   A subsystem for managing INI (i.e. .ini) files
  11 //   An INI file has the following format
  12
  13 //     file           ::= header { section }*
  14 //     header         ::= { comment | blank }*
  15 //     section        ::= section_header { declaration | comment | blank }*
  16 //     section_header ::= '[' title ']' '\n'
  17 //     declaration    ::= variable '=' value '\n'
  18 //     comment        ::= ';' text '\n'
  19 //     blank          ::= '\n'
  20 //     title          ::= [~']']*
  21 //     variable       ::= [~'=']*
  22 //     value          ::= .*
  23 //     text           ::= .*
  24
  25 //   Whitespace is trimmed from the leading and trailing ends of title, variable and value
  26 //   Note: a header is represented internally as a Clint section (i.e. a section with no name)
  27
  28 ////////////////////////////////////////////////////////////////////////////////
  29 #include "subsystems_fixes.hpp"
  30 #include <vector>
  31 #include <string>
  32 #include <iostream>
  33
  34 namespace stlplus
  35 {
  36
  37   ////////////////////////////////////////////////////////////////////////////////
  38   // Internals
  39
  40   class ini_manager_body;
  41
  42   ////////////////////////////////////////////////////////////////////////////////
  43   // Ini-file manager class
  44
  45   class ini_manager
  46   {
  47   public:
  48
  49     ini_manager(void);
  50
  51     explicit ini_manager(const std::vector<std::string>& filenames);
  52
  53     ini_manager(const ini_manager&);
  54     ini_manager& operator= (const ini_manager&);
  55
  56     ~ini_manager(void);
  57
  58     //////////////////////////////////////////////////////////////////////////////
  59     // file management
  60
  61     // add files starting with the most local file (e.g. the current project) which has depth 0
  62     // and working back to the most global (e.g. the installation settings) which has a depth of size()-1
  63     // This does nothing if the file has already been loaded - it is not permitted to manage the same file twice.
  64     // Returns true if the file loaded okay or was already loaded (it is counted as successful if the file did
  65     // not exist, only read errors cause a failure)
  66     bool add_file(const std::string& filename);
  67
  68     // as above, returns false if *none* of the files were added
  69     // filenames[0] is the local file, and so on
  70     bool add_files(const std::vector<std::string>& filenames);
  71
  72     // saves modified ini files - returns true if all modified files were written successfully
  73     bool save(void);
  74
  75     // get the number of files being managed
  76     unsigned size(void) const;
  77
  78     // get the ini filename associated with a depth
  79     std::string filename(unsigned depth = 0) const;
  80
  81     // test whether a file in the ini manager is writable
  82     bool writable(unsigned depth = 0) const;
  83
  84     // test whether a file is empty
  85     // An ini file is considered empty if it has no named sections and the header is empty or missing
  86     bool empty(unsigned depth = 0) const;
  87
  88     // erase the ini file from the ini manager and from the disk
  89     bool erase(unsigned depth = 0);
  90
  91     // remove the file from the ini manager but do not erase it from the disk
  92     bool remove(unsigned depth = 0);
  93
  94     //////////////////////////////////////////////////////////////////////////////
  95     // section management
  96
  97     // returns the union of all section names in all of the ini files
  98     std::vector<std::string> section_names(void) const;
  99
 100     // returns the section names in one of the ini files
 101     std::vector<std::string> section_names(unsigned depth) const;
 102
 103     // tests whether a section is found in any of the ini files
 104     bool section_exists(const std::string& title) const;
 105
 106     // tests whether the section is found in the specific ini file
 107     bool section_exists(const std::string& title, unsigned depth) const;
 108
 109     // adds a section to the specified ini file - does nothing if it is already present
 110     bool add_section(const std::string& section, unsigned depth = 0);
 111
 112     // test whether a section is empty
 113     bool empty_section(const std::string& section, unsigned depth = 0);
 114
 115     // removes a section from the specified ini file if it exists there but cannot remove it from any other file
 116     bool erase_section(const std::string& section, unsigned depth = 0);
 117
 118     // removes all the contents of a section from the specified ini file but keeps the empty section
 119     bool clear_section(const std::string& section, unsigned depth = 0);
 120
 121     //////////////////////////////////////////////////////////////////////////////
 122     // variable management
 123
 124     // test whether a variable exists in any of the ini files
 125     bool variable_exists(const std::string& section, const std::string variable) const;
 126
 127     // test whether a variable exists in specified ini file
 128     bool variable_exists(const std::string& section, const std::string variable, unsigned depth) const;
 129
 130     // get the union of all variables declared in all ini files
 131     std::vector<std::string> variable_names(const std::string& section) const;
 132
 133     // get the set of all varaibale names from one file
 134     std::vector<std::string> variable_names(const std::string& section, unsigned depth) const;
 135
 136     // get the depth of the first ini file to define a variable
 137     // returns 0 if defined in the local ini file, etc. Returns (unsigned)-1 if the variable doesn't exist
 138     unsigned variable_depth(const std::string& section, const std::string variable) const;
 139
 140     // get the filename that first defines the variable
 141     std::string variable_filename(const std::string& section, const std::string variable) const;
 142     // ditto for its linenumber within that file
 143     unsigned variable_linenumber(const std::string& section, const std::string variable) const;
 144
 145     // get the value of a variable as a single unprocessed string
 146     // if the variable does not exist the string will be empty, but beware that
 147     // you also get an empty string if a variable exists but has no value
 148     // you can differentiate between the two cases by using variable_exists_all above
 149     std::string variable_value(const std::string& section, const std::string variable) const;
 150
 151     // get the value from the specified file
 152     std::string variable_value(const std::string& section, const std::string variable, unsigned depth) const;
 153
 154     // get the value of a variable as a processed string
 155     // processing splits the value at commas and furthermore supports quoted strings (so that values can contain commas for example)
 156     // quoted strings are dequoted before they are added to the result
 157     // the result is a vector of dequoted strings, one per value in the comma-separated list
 158     std::vector<std::string> variable_values(const std::string& section, const std::string variable) const;
 159
 160     // get the processed variable from the specified file
 161     std::vector<std::string> variable_values(const std::string& section, const std::string variable, unsigned depth) const;
 162
 163     // add a variable to the specified file
 164     bool add_variable(const std::string& section, const std::string& variable, const std::string& value, unsigned depth = 0);
 165
 166     // add a variable as a processed string
 167     // processing means that the values in the string vector are converted into a comma-separated list
 168     // values containing reserved characters are automatically quoted - so you should not even try to quote them yourself
 169     bool add_variable(const std::string& section, const std::string& variable, const std::vector<std::string>& values, unsigned depth = 0);
 170
 171     // erase a variable from the specified file
 172     // this does not remove the variable from other ini files, so the variable may still exist
 173     // to mask a global variable, set the variable to an empty string instead
 174     bool erase_variable(const std::string& section, const std::string& variable, unsigned depth = 0);
 175
 176     //////////////////////////////////////////////////////////////////////////////
 177     // sundry line-entry management
 178
 179     // add a comment to the specified ini file
 180     bool add_comment(const std::string& section, const std::string& comment, unsigned depth = 0);
 181
 182     // add a blank line to the specified ini file
 183     bool add_blank(const std::string& section, unsigned depth = 0);
 184
 185     bool print(std::ostream&) const;
 186
 187   private:
 188     friend class ini_manager_body;
 189     ini_manager_body* m_body;
 190   };
 191
 192   ////////////////////////////////////////////////////////////////////////////////
 193   // diagnostic print routine
 194
 195   std::ostream& operator << (std::ostream&, const ini_manager&);
 196
 197   ////////////////////////////////////////////////////////////////////////////////
 198
 199 } // end namespace stlplus
 200
 201 #endif