libs/glibmm2/glib/src/keyfile.hg

   1 /* Copyright(C) 2006 The gtkmm Development Team
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Library General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2 of the License, or(at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Library General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Library General Public
  14  * License along with this library; if not, write to the Free
  15  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16  */
  17
  18 _DEFS(glibmm,glib)
  19
  20 #include <glibmm/ustring.h>
  21 #include <glibmm/arrayhandle.h>
  22 #include <glibmm/error.h>
  23 #include <glibmm/utility.h>
  24 #include <glib.h>
  25
  26 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  27 extern "C" { typedef struct _GKeyFile GKeyFile; }
  28 #endif
  29
  30 namespace Glib
  31 {
  32
  33   _WRAP_ENUM(KeyFileFlags, GKeyFileFlags, NO_GTYPE)
  34
  35 /** Exception class for KeyFile errors.
  36  */
  37 _WRAP_GERROR(KeyFileError, GKeyFileError, G_KEY_FILE_ERROR, NO_GTYPE)
  38
  39 /** This class lets you parse, edit or create files containing groups of key-value pairs, which we call key files
  40  * for lack of a better name. Several freedesktop.org specifications use key files now, e.g the Desktop Entry
  41  * Specification and the Icon Theme Specification.
  42  *
  43  * The syntax of key files is described in detail in the Desktop Entry Specification, here is a quick summary: Key
  44  * files consists of groups of key-value pairs, interspersed with comments.
  45  *
  46  * @code
  47  * # this is just an example
  48  * # there can be comments before the first group
  49  *
  50  * [First Group]
  51  *
  52  * Name=Key File Example\tthis value shows\nescaping
  53  *
  54  * # localized strings are stored in multiple key-value pairs
  55  * Welcome=Hello
  56  * Welcome[de]=Hallo
  57  * Welcome[fr]=Bonjour
  58  * Welcome[it]=Ciao
  59  *
  60  * [Another Group]
  61  *
  62  * Numbers=2;20;-200;0
  63  *
  64  * Booleans=true;false;true;true
  65  * @endcode
  66  *
  67  * Lines beginning with a '#' and blank lines are considered comments.
  68  *
  69  * Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by
  70  * the start of the next group or the end of the file. Each key-value pair must be contained in a group.
  71  *
  72  * Key-value pairs generally have the form key=value, with the exception of localized strings, which have the form
  73  * key[locale]=value. Space before and after the '=' character are ignored. Newline, tab, carriage return and
  74  * backslash characters in value are escaped as \\n, \\t, \\r, and \\\\, respectively. To preserve leading spaces in
  75  * values, these can also be escaped as \\s.
  76  *
  77  * Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are
  78  * separated by a separator character, typically ';' or ','. To use the list separator character in a value in a
  79  * list, it has to be escaped by prefixing it with a backslash.
  80  *
  81  * This syntax is obviously inspired by the .ini files commonly met on Windows, but there are some important
  82  * differences:
  83  * - .ini files use the ';' character to begin comments, key files use the '#' character.
  84  * - Key files allow only comments before the first group.
  85  * - Key files are always encoded in UTF-8.
  86  * - Key and Group names are case-sensitive, for example a group called [GROUP] is a different group from [group].
  87  *
  88  * Note that in contrast to the Desktop Entry Specification, groups in key files may contain the same key multiple
  89  * times; the last entry wins. Key files may also contain multiple groups with the same name; they are merged
  90  * together. Another difference is that keys and group names in key files are not restricted to ASCII characters.
  91  *
  92  * @newin2p14
  93  */
  94 class KeyFile
  95 {
  96   _CLASS_GENERIC(KeyFile, GKeyFile)
  97 public:
  98
  99   /** Creates a new, empty KeyFile object.
 100    */
 101   KeyFile();
 102
 103   /** Destructor
 104    */
 105   ~KeyFile();
 106   _IGNORE(g_key_file_free)
 107
 108   /** Creates a glibmm KeyFile wrapper for a GKeyFile object.
 109    * Note, when using this that when the wrapper is deleted,
 110    * it will not automatically deleted the GKeyFile unless you
 111    * set the delete_c_instance boolean to true.
 112    * @param castitem The C instance to wrap
 113    * @param delete_c_instance If the C instance should be deleted when
 114    * the wrapper is deleted.
 115    */
 116   KeyFile(GKeyFile* castitem, bool takes_ownership = false);
 117
 118 public:
 119
 120   _WRAP_METHOD(bool load_from_file(const std::string& filename, KeyFileFlags flags = Glib::KEY_FILE_NONE), g_key_file_load_from_file, errthrow)
 121
 122   /** Loads a KeyFile from memory
 123    * @param data The data to use as a KeyFile
 124    * @param flags Bitwise combination of the flags to use for the KeyFile
 125    * @return true if the KeyFile was successfully loaded, false otherwise
 126    * @throw Glib::KeyFileError
 127    */
 128
 129   bool load_from_data(const Glib::ustring& data, KeyFileFlags flags = Glib::KEY_FILE_NONE);
 130   _IGNORE(g_key_file_load_from_data)
 131
 132   //TODO:
 133   /*
 134   gboolean g_key_file_load_from_dirs          (GKeyFile             *key_file,
 135                                              const gchar          *file,
 136                                              const gchar         **search_dirs,
 137                                              gchar               **full_path,
 138                                              GKeyFileFlags         flags,
 139                                              GError              **error);
 140   */
 141
 142   /** Looks for a KeyFile named @a file in the paths returned from
 143    * g_get_user_data_dir() and g_get_system_data_dirs() and loads them
 144    * into the keyfile object, placing the full path to the file in
 145    * @a full_path.
 146    * @param file The file to search for
 147    * @param full_path Return location for a string containing the full path of the file
 148    * @param flags Bitwise combination of the flags to use for the KeyFile
 149    * @return true if the KeyFile was successfully loaded, false otherwise
 150    * @throw Glib::KeyFileError
 151    * @throw Glib::FileError
 152    */
 153   bool load_from_data_dirs(const std::string& file, std::string& full_path, KeyFileFlags flags = Glib::KEY_FILE_NONE);
 154   _IGNORE(g_key_file_load_from_data_dirs)
 155
 156   /** Outputs the KeyFile as a string
 157    * @return A string object holding the contents of KeyFile
 158    */
 159   Glib::ustring to_data();
 160   _IGNORE(g_key_file_to_data)
 161
 162   _WRAP_METHOD(Glib::ustring get_start_group() const, g_key_file_get_start_group)
 163
 164   /** Gets a list of all groups in the KeyFile
 165    * @returns A list containing the names of the groups
 166    */
 167   Glib::ArrayHandle<Glib::ustring> get_groups() const;
 168   _IGNORE(g_key_file_get_groups)
 169
 170   /** Gets a list of all keys from the group @a group_name.
 171    * @param group_name The name of a group
 172    * @returns A list containing the names of the keys in @a group_name
 173    */
 174   Glib::ArrayHandle<Glib::ustring> get_keys(const Glib::ustring& group_name) const;
 175   _IGNORE(g_key_file_get_keys)
 176
 177   _WRAP_METHOD(bool has_group(const Glib::ustring& group_name) const, g_key_file_has_group)
 178   _WRAP_METHOD(bool has_key(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_has_key, errthrow)
 179
 180   _WRAP_METHOD(Glib::ustring get_value(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_value, errthrow)
 181   _WRAP_METHOD(Glib::ustring get_string(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_string, errthrow)
 182
 183   /** Gets the value associated with @a key under @a group_name translated
 184   * into the current locale.
 185   */
 186   Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key) const;
 187
 188   _WRAP_METHOD(Glib::ustring get_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const, g_key_file_get_locale_string, errthrow)
 189   _WRAP_METHOD(bool get_boolean(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_boolean, errthrow)
 190
 191   /** Gets the value in the first group, under @a key, interpreting it as
 192    * an integer.
 193    * @param key The name of the key
 194    * @return The value of @a key as an integer
 195    * @throws Glib::KeyFileError
 196    */
 197 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 198   int get_integer(const Glib::ustring& key) const;
 199 #else
 200   int get_integer(const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 201 #endif
 202   _WRAP_METHOD(int get_integer(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_integer, errthrow)
 203
 204   /** Gets the value in the first group, under @a key, interpreting it as
 205    * a double.
 206    * @param key The name of the key
 207    * @return The value of @a key as an double
 208    * @throws Glib::KeyFileError
 209    *
 210    * @newin2p14
 211    */
 212 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 213   double get_double(const Glib::ustring& key) const;
 214 #else
 215   double get_double(const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 216 #endif
 217   _WRAP_METHOD(double get_double(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_double, errthrow)
 218
 219   _WRAP_METHOD(void set_double(const Glib::ustring& group_name, const Glib::ustring& key, double value), g_key_file_set_double)
 220
 221   /** Associates a new double value with @a key under the start group.
 222    * If @a key  cannot be found then it is created.
 223    *
 224    * @newin2p12
 225    * @param key A key.
 226    * @param value An double value.
 227    */
 228   void set_double(const Glib::ustring& key, double value);
 229
 230   /** Returns the values associated with @a key under @a group_name
 231    * @param group_name The name of a group
 232    * @param key The name of a key
 233    * @return A list containing the values requested
 234    * @throws Glib::KeyFileError
 235    */
 236 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 237   Glib::ArrayHandle<Glib::ustring> get_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 238 #else
 239   Glib::ArrayHandle<Glib::ustring> get_string_list(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 240 #endif
 241   _IGNORE(g_key_file_get_string_list)
 242
 243   /** Returns the values associated with @a key under @a group_name
 244    * translated into the current locale, if available.
 245    * @param group_name The name of a group
 246    * @param key The name of a key
 247    * @return A list containing the values requested
 248    * @throws Glib::KeyFileError
 249    */
 250 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 251   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 252 #else
 253   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, std::auto_ptr<Glib::Error>& error) const;
 254 #endif
 255
 256   /** Returns the values associated with @a key under @a group_name
 257    * translated into @a locale, if available.
 258    * @param group_name The name of a group
 259    * @param key The name of a key
 260    * @param locale The name of a locale
 261    * @return A list containing the values requested
 262    * @throws Glib::KeyFileError
 263    */
 264 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 265   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale) const;
 266 #else
 267   Glib::ArrayHandle<Glib::ustring> get_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, std::auto_ptr<Glib::Error>& error) const;
 268 #endif
 269   _IGNORE(g_key_file_get_locale_string_list)
 270
 271   /** Returns the values associated with @a key under @a group_name
 272    * @param group_name The name of a group
 273    * @param key The name of a key
 274    * @return A list of booleans
 275    * @throws Glib::KeyFileError
 276    */
 277 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 278   Glib::ArrayHandle<bool> get_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 279 #else
 280   Glib::ArrayHandle<bool> get_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key,
 281                                            std::auto_ptr<Glib::Error>& error) const;
 282 #endif
 283   _IGNORE(g_key_file_get_boolean_list)
 284
 285   /** Returns the values associated with @a key under @a group_name
 286    * @param group_name The name of a group
 287    * @param key The name of a key
 288    * @return A list of integers
 289    * @throws Glib::KeyFileError
 290    */
 291 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 292   Glib::ArrayHandle<int> get_integer_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 293 #else
 294   Glib::ArrayHandle<int> get_integer_list(const Glib::ustring& group_name, const Glib::ustring& key,
 295                                           std::auto_ptr<Glib::Error>& error) const;
 296 #endif
 297   _IGNORE(g_key_file_get_integer_list)
 298
 299   /** Returns the values associated with @a key under @a group_name
 300    * @param group_name The name of a group
 301    * @param key The name of a key
 302    * @return A list of doubles
 303    * @throws Glib::KeyFileError
 304    */
 305 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 306   Glib::ArrayHandle<double> get_double_list(const Glib::ustring& group_name, const Glib::ustring& key) const;
 307 #else
 308   Glib::ArrayHandle<double> get_double_list(const Glib::ustring& group_name, const Glib::ustring& key,
 309                                             std::auto_ptr<Glib::Error>& error) const;
 310 #endif
 311   _IGNORE(g_key_file_get_double_list)
 312
 313   /** Get comment from top of file
 314    * @return The comment
 315    */
 316 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 317   Glib::ustring get_comment() const;
 318 #else
 319   Glib::ustring get_comment(std::auto_ptr<Glib::Error>& error) const;
 320 #endif
 321
 322   /** Get comment from above a group
 323    * @param group_name The group
 324    * @return The comment
 325    */
 326 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 327   Glib::ustring get_comment(const Glib::ustring& group_name) const;
 328 #else
 329   Glib::ustring get_comment(const Glib::ustring& group_name, std::auto_ptr<Glib::Error>& error) const;
 330 #endif
 331
 332   _WRAP_METHOD(Glib::ustring get_comment(const Glib::ustring& group_name, const Glib::ustring& key) const, g_key_file_get_comment, errthrow)
 333
 334   _WRAP_METHOD(void set_list_separator(gchar separator), g_key_file_set_list_separator)
 335   _WRAP_METHOD(void set_value(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& value), g_key_file_set_value)
 336   _WRAP_METHOD(void set_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& string), g_key_file_set_string)
 337   _WRAP_METHOD(void set_locale_string(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ustring& string), g_key_file_set_locale_string)
 338   _WRAP_METHOD(void set_boolean(const Glib::ustring& group_name, const Glib::ustring& key, bool value), g_key_file_set_boolean)
 339   _WRAP_METHOD(void set_integer(const Glib::ustring& group_name, const Glib::ustring& key, int value), g_key_file_set_integer)
 340
 341   /** Sets a list of string values for @a key under @a group_name. If
 342    * key cannot be found it is created. If @a group_name cannot be found
 343    * it is created.
 344    * @param group_name The name of a group
 345    * @param key The name of a key
 346    * @param list A list holding objects of type Glib::ustring
 347    */
 348   void set_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<Glib::ustring>& list);
 349   _IGNORE(g_key_file_set_string_list)
 350
 351   /** Sets a list of string values for the @a key under @a group_name and marks
 352    * them as being for @a locale. If the @a key or @a group_name cannot be
 353    * found, they are created.
 354    * @param group_name The name of a group
 355    * @param key The name of a key
 356    * @param locale A locale
 357    * @param list A list holding objects of type Glib::ustring
 358    */
 359   void set_locale_string_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& locale, const Glib::ArrayHandle<Glib::ustring>& list);
 360   _IGNORE(g_key_file_set_locale_string_list)
 361
 362   /** Sets a list of booleans for the @a key under @a group_name.
 363    * If either the @a key or @a group_name cannot be found they are created.
 364    * @param group_name The name of a group
 365    * @param key The name of a key
 366    * @param list A list holding object of type bool
 367    */
 368   void set_boolean_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<bool>& list);
 369   _IGNORE(g_key_file_set_boolean_list)
 370
 371   /** Sets a list of integers for the @a key under @a group_name.
 372    * If either the @a key or @a group_name cannot be found they are created.
 373    * @param group_name The name of a group
 374    * @param key The name of a key
 375    * @param list A list holding object of type int
 376    */
 377   void set_integer_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<int>& list);
 378   _IGNORE(g_key_file_set_integer_list)
 379
 380   /** Sets a list of doubles for the @a key under @a group_name.
 381    * If either the @a key or @a group_name cannot be found they are created.
 382    * @param group_name The name of a group
 383    * @param key The name of a key
 384    * @param list A list holding object of type int
 385    *
 386    * @newin2p14
 387    */
 388   void set_double_list(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ArrayHandle<double>& list);
 389   _IGNORE(g_key_file_set_double_list)
 390
 391
 392   /** Places @a comment at the start of the file, before the first group.
 393    * @param comment The Comment
 394    */
 395 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 396   void set_comment(const Glib::ustring& comment);
 397 #else
 398   void set_comment(const Glib::ustring& comment, std::auto_ptr<Glib::Error>& error);
 399 #endif
 400
 401   /** Places @a comment above @a group_name.
 402    * @param group_name The Group the comment should be above
 403    * @param comment The comment
 404    */
 405 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 406   void set_comment(const Glib::ustring& group_name, const Glib::ustring& comment);
 407 #else
 408   void set_comment(const Glib::ustring& group_name, const Glib::ustring& comment,
 409                    std::auto_ptr<Glib::Error>& error);
 410 #endif
 411
 412   /** Places a comment above @a key from @a group_name.
 413    * @param key Key comment should be above
 414    * @param group_name Group comment is in
 415    * @param comment The comment
 416    */
 417   _WRAP_METHOD(void set_comment(const Glib::ustring& group_name, const Glib::ustring& key, const Glib::ustring& comment), g_key_file_set_comment, errthrow)
 418
 419   _WRAP_METHOD(void remove_comment(const Glib::ustring& group_name, const Glib::ustring& key), g_key_file_remove_comment, errthrow)
 420   _WRAP_METHOD(void remove_key(const Glib::ustring& group_name, const Glib::ustring& key), g_key_file_remove_key, errthrow)
 421   _WRAP_METHOD(void remove_group(const Glib::ustring& group_name), g_key_file_remove_group, errthrow)
 422
 423   GKeyFile*       gobj()       { return gobject_; }
 424   const GKeyFile* gobj() const { return gobject_; }
 425
 426 protected:
 427   GKeyFile* gobject_;
 428   bool owns_gobject_;
 429
 430 private:
 431   // noncopyable
 432   KeyFile(const KeyFile&);
 433   KeyFile& operator=(const KeyFile&);
 434 };
 435
 436 } // namespace Glib
 437