glib/gkeyfile.c

   1 /* gkeyfile.c - key file parser
   2  *
   3  *  Copyright 2004  Red Hat, Inc.
   4  *  Copyright 2009-2010  Collabora Ltd.
   5  *  Copyright 2009  Nokia Corporation
   6  *
   7  * Written by Ray Strode <rstrode@redhat.com>
   8  *            Matthias Clasen <mclasen@redhat.com>
   9  *
  10  * GLib is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as
  12  * published by the Free Software Foundation; either version 2 of the
  13  * License, or (at your option) any later version.
  14  *
  15  * GLib is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GLib; see the file COPYING.LIB.  If not,
  22  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23  *   Boston, MA 02111-1307, USA.
  24  */
  25
  26 #include "config.h"
  27
  28 #include "gkeyfile.h"
  29 #include "gutils.h"
  30
  31 #include <errno.h>
  32 #include <fcntl.h>
  33 #include <locale.h>
  34 #include <string.h>
  35 #include <stdio.h>
  36 #include <stdlib.h>
  37 #include <sys/types.h>
  38 #include <sys/stat.h>
  39 #ifdef HAVE_UNISTD_H
  40 #include <unistd.h>
  41 #endif
  42 #ifdef G_OS_WIN32
  43 #include <io.h>
  44
  45 #define fstat(a,b) _fstati64(a,b)
  46 #define stat _stati64
  47
  48 #ifndef S_ISREG
  49 #define S_ISREG(mode) ((mode)&_S_IFREG)
  50 #endif
  51
  52 #endif  /* G_OS_WIN23 */
  53
  54 #include "gconvert.h"
  55 #include "gdataset.h"
  56 #include "gerror.h"
  57 #include "gfileutils.h"
  58 #include "ghash.h"
  59 #include "glibintl.h"
  60 #include "glist.h"
  61 #include "gslist.h"
  62 #include "gmem.h"
  63 #include "gmessages.h"
  64 #include "gstdio.h"
  65 #include "gstring.h"
  66 #include "gstrfuncs.h"
  67 #include "gutils.h"
  68
  69
  70 /**
  71  * SECTION:keyfile
  72  * @title: Key-value file parser
  73  * @short_description: parses .ini-like config files
  74  *
  75  * #GKeyFile lets you parse, edit or create files containing groups of
  76  * key-value pairs, which we call <firstterm>key files</firstterm> for
  77  * lack of a better name. Several freedesktop.org specifications use
  78  * key files now, e.g the
  79  * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
  80  * Entry Specification</ulink> and the
  81  * <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
  82  * Theme Specification</ulink>.
  83  *
  84  * The syntax of key files is described in detail in the
  85  * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
  86  * Entry Specification</ulink>, here is a quick summary: Key files
  87  * consists of groups of key-value pairs, interspersed with comments.
  88  *
  89  * |[
  90  * # this is just an example
  91  * # there can be comments before the first group
  92  *
  93  * [First Group]
  94  *
  95  * Name=Key File Example\tthis value shows\nescaping
  96  *
  97  * # localized strings are stored in multiple key-value pairs
  98  * Welcome=Hello
  99  * Welcome[de]=Hallo
 100  * Welcome[fr_FR]=Bonjour
 101  * Welcome[it]=Ciao
 102  * Welcome[be@latin]=Hello
 103  *
 104  * [Another Group]
 105  *
 106  * Numbers=2;20;-200;0
 107  *
 108  * Booleans=true;false;true;true
 109  * ]|
 110  *
 111  * Lines beginning with a '#' and blank lines are considered comments.
 112  *
 113  * Groups are started by a header line containing the group name enclosed
 114  * in '[' and ']', and ended implicitly by the start of the next group or
 115  * the end of the file. Each key-value pair must be contained in a group.
 116  *
 117  * Key-value pairs generally have the form <literal>key=value</literal>,
 118  * with the exception of localized strings, which have the form
 119  * <literal>key[locale]=value</literal>, with a locale identifier of the
 120  * form <literal>lang_COUNTRY@MODIFIER</literal> where
 121  * <literal>COUNTRY</literal> and <literal>MODIFIER</literal> are optional.
 122  * Space before and after the '=' character are ignored. Newline, tab,
 123  * carriage return and backslash characters in value are escaped as \n,
 124  * \t, \r, and \\, respectively. To preserve leading spaces in values,
 125  * these can also be escaped as \s.
 126  *
 127  * Key files can store strings (possibly with localized variants), integers,
 128  * booleans and lists of these. Lists are separated by a separator character,
 129  * typically ';' or ','. To use the list separator character in a value in
 130  * a list, it has to be escaped by prefixing it with a backslash.
 131  *
 132  * This syntax is obviously inspired by the .ini files commonly met
 133  * on Windows, but there are some important differences:
 134  * <itemizedlist>
 135  *   <listitem>.ini files use the ';' character to begin comments,
 136  *     key files use the '#' character.</listitem>
 137  *   <listitem>Key files do not allow for ungrouped keys meaning only
 138  *     comments can precede the first group.</listitem>
 139  *   <listitem>Key files are always encoded in UTF-8.</listitem>
 140  *   <listitem>Key and Group names are case-sensitive. For example, a
 141  *     group called <literal>[GROUP]</literal> is a different from
 142  *     <literal>[group]</literal>.</listitem>
 143  *   <listitem>.ini files don't have a strongly typed boolean entry type,
 144  *     they only have GetProfileInt(). In key files, only
 145  *     <literal>true</literal> and <literal>false</literal> (in lower case)
 146  *     are allowed.</listitem>
 147  *  </itemizedlist>
 148  *
 149  * Note that in contrast to the
 150  * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
 151  * Entry Specification</ulink>, groups in key files may contain the same
 152  * key multiple times; the last entry wins. Key files may also contain
 153  * multiple groups with the same name; they are merged together.
 154  * Another difference is that keys and group names in key files are not
 155  * restricted to ASCII characters.
 156  */
 157
 158 /**
 159  * G_KEY_FILE_ERROR:
 160  *
 161  * Error domain for key file parsing. Errors in this domain will
 162  * be from the #GKeyFileError enumeration.
 163  *
 164  * See #GError for information on error domains.
 165  */
 166
 167 /**
 168  * GKeyFileError:
 169  * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in
 170  *     an unknown encoding
 171  * @G_KEY_FILE_ERROR_PARSE: document was ill-formed
 172  * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
 173  * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
 174  * @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found
 175  * @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed
 176  *
 177  * Error codes returned by key file parsing.
 178  */
 179
 180 /**
 181  * GKeyFileFlags:
 182  * @G_KEY_FILE_NONE: No flags, default behaviour
 183  * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the
 184  *     (possibly modified) contents of the key file back to a file;
 185  *     otherwise all comments will be lost when the key file is
 186  *     written back.
 187  * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the
 188  *     (possibly modified) contents of the key file back to a file;
 189  *     otherwise only the translations for the current language will be
 190  *     written back.
 191  *
 192  * Flags which influence the parsing.
 193  */
 194
 195 /**
 196  * G_KEY_FILE_DESKTOP_GROUP:
 197  *
 198  * The name of the main group of a desktop entry file, as defined in the
 199  * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
 200  * Entry Specification</ulink>. Consult the specification for more
 201  * details about the meanings of the keys below.
 202  *
 203  * Since: 2.14
 204  */
 205
 206 /**
 207  * G_KEY_FILE_DESKTOP_KEY_TYPE:
 208  *
 209  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 210  * giving the type of the desktop entry. Usually
 211  * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
 212  * #G_KEY_FILE_DESKTOP_TYPE_LINK, or
 213  * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
 214  *
 215  * Since: 2.14
 216  */
 217
 218 /**
 219  * G_KEY_FILE_DESKTOP_KEY_VERSION:
 220  *
 221  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 222  * giving the version of the Desktop Entry Specification used for
 223  * the desktop entry file.
 224  *
 225  * Since: 2.14
 226  */
 227
 228 /**
 229  * G_KEY_FILE_DESKTOP_KEY_NAME:
 230  *
 231  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
 232  * string giving the specific name of the desktop entry.
 233  *
 234  * Since: 2.14
 235  */
 236
 237 /**
 238  * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
 239  *
 240  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
 241  * string giving the generic name of the desktop entry.
 242  *
 243  * Since: 2.14
 244  */
 245
 246 /**
 247  * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
 248  *
 249  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
 250  * stating whether the desktop entry should be shown in menus.
 251  *
 252  * Since: 2.14
 253  */
 254
 255 /**
 256  * G_KEY_FILE_DESKTOP_KEY_COMMENT:
 257  *
 258  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
 259  * string giving the tooltip for the desktop entry.
 260  *
 261  * Since: 2.14
 262  */
 263
 264 /**
 265  * G_KEY_FILE_DESKTOP_KEY_ICON:
 266  *
 267  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
 268  * string giving the name of the icon to be displayed for the desktop
 269  * entry.
 270  *
 271  * Since: 2.14
 272  */
 273
 274 /**
 275  * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
 276  *
 277  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
 278  * stating whether the desktop entry has been deleted by the user.
 279  *
 280  * Since: 2.14
 281  */
 282
 283 /**
 284  * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
 285  *
 286  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
 287  * strings identifying the environments that should display the
 288  * desktop entry.
 289  *
 290  * Since: 2.14
 291  */
 292
 293 /**
 294  * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
 295  *
 296  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
 297  * strings identifying the environments that should not display the
 298  * desktop entry.
 299  *
 300  * Since: 2.14
 301  */
 302
 303 /**
 304  * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
 305  *
 306  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 307  * giving the file name of a binary on disk used to determine if the
 308  * program is actually installed. It is only valid for desktop entries
 309  * with the <literal>Application</literal> type.
 310  *
 311  * Since: 2.14
 312  */
 313
 314 /**
 315  * G_KEY_FILE_DESKTOP_KEY_EXEC:
 316  *
 317  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 318  * giving the command line to execute. It is only valid for desktop
 319  * entries with the <literal>Application</literal> type.
 320  *
 321  * Since: 2.14
 322  */
 323
 324  /**
 325   * G_KEY_FILE_DESKTOP_KEY_PATH:
 326   *
 327   * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 328   * containing the working directory to run the program in. It is only
 329   * valid for desktop entries with the <literal>Application</literal> type.
 330   *
 331   * Since: 2.14
 332   */
 333
 334 /**
 335  * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
 336  *
 337  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
 338  * stating whether the program should be run in a terminal window.
 339  * It is only valid for desktop entries with the
 340  * <literal>Application</literal> type.
 341  *
 342  * Since: 2.14
 343  */
 344
 345 /**
 346  * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
 347  *
 348  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
 349  * of strings giving the MIME types supported by this desktop entry.
 350  *
 351  * Since: 2.14
 352  */
 353
 354 /**
 355  * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
 356  *
 357  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
 358  * of strings giving the categories in which the desktop entry
 359  * should be shown in a menu.
 360  *
 361  * Since: 2.14
 362  */
 363
 364 /**
 365  * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
 366  *
 367  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
 368  * stating whether the application supports the <ulink
 369  * url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup
 370  * Notification Protocol Specification</ulink>.
 371  *
 372  * Since: 2.14
 373  */
 374
 375 /**
 376  * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
 377  *
 378  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string
 379  * identifying the WM class or name hint of a window that the application
 380  * will create, which can be used to emulate Startup Notification with
 381  * older applications.
 382  *
 383  * Since: 2.14
 384  */
 385
 386 /**
 387  * G_KEY_FILE_DESKTOP_KEY_URL :
 388  *
 389  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
 390  * giving the URL to access. It is only valid for desktop entries
 391  * with the <literal>Link</literal> type.
 392  *
 393  * Since: 2.14
 394  */
 395
 396 /**
 397  * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
 398  *
 399  * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
 400  * entries representing applications.
 401  *
 402  * Since: 2.14
 403  */
 404
 405 /**
 406  * G_KEY_FILE_DESKTOP_TYPE_LINK:
 407  *
 408  * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
 409  * entries representing links to documents.
 410  *
 411  * Since: 2.14
 412  */
 413
 414 /**
 415  * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
 416  *
 417  * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
 418  * entries representing directories.
 419  *
 420  * Since: 2.14
 421  */
 422
 423 typedef struct _GKeyFileGroup GKeyFileGroup;
 424
 425 /**
 426  * GKeyFile:
 427  *
 428  * The GKeyFile struct contains only private data
 429  * and should not be accessed directly.
 430  */
 431 struct _GKeyFile
 432 {
 433   GList *groups;
 434   GHashTable *group_hash;
 435
 436   GKeyFileGroup *start_group;
 437   GKeyFileGroup *current_group;
 438
 439   GString *parse_buffer; /* Holds up to one line of not-yet-parsed data */
 440
 441   /* Used for sizing the output buffer during serialization */
 442   gsize approximate_size;
 443
 444   gchar list_separator;
 445
 446   GKeyFileFlags flags;
 447
 448   gchar **locales;
 449
 450   volatile gint ref_count;
 451 };
 452
 453 typedef struct _GKeyFileKeyValuePair GKeyFileKeyValuePair;
 454
 455 struct _GKeyFileGroup
 456 {
 457   const gchar *name;  /* NULL for above first group (which will be comments) */
 458
 459   GKeyFileKeyValuePair *comment; /* Special comment that is stuck to the top of a group */
 460   gboolean has_trailing_blank_line;
 461
 462   GList *key_value_pairs;
 463
 464   /* Used in parallel with key_value_pairs for
 465    * increased lookup performance
 466    */
 467   GHashTable *lookup_map;
 468 };
 469
 470 struct _GKeyFileKeyValuePair
 471 {
 472   gchar *key;  /* NULL for comments */
 473   gchar *value;
 474 };
 475
 476 static gint                  find_file_in_data_dirs            (const gchar            *file,
 477                                                                 const gchar           **data_dirs,
 478                                                                 gchar                 **output_file,
 479                                                                 GError                **error);
 480 static gboolean              g_key_file_load_from_fd           (GKeyFile               *key_file,
 481                                                                 gint                    fd,
 482                                                                 GKeyFileFlags           flags,
 483                                                                 GError                **error);
 484 static GList                *g_key_file_lookup_group_node      (GKeyFile               *key_file,
 485                                                                 const gchar            *group_name);
 486 static GKeyFileGroup        *g_key_file_lookup_group           (GKeyFile               *key_file,
 487                                                                 const gchar            *group_name);
 488
 489 static GList                *g_key_file_lookup_key_value_pair_node  (GKeyFile       *key_file,
 490                                                                      GKeyFileGroup  *group,
 491                                                                      const gchar    *key);
 492 static GKeyFileKeyValuePair *g_key_file_lookup_key_value_pair       (GKeyFile       *key_file,
 493                                                                      GKeyFileGroup  *group,
 494                                                                      const gchar    *key);
 495
 496 static void                  g_key_file_remove_group_node          (GKeyFile      *key_file,
 497                                                                     GList         *group_node);
 498 static void                  g_key_file_remove_key_value_pair_node (GKeyFile      *key_file,
 499                                                                     GKeyFileGroup *group,
 500                                                                     GList         *pair_node);
 501
 502 static void                  g_key_file_add_key_value_pair     (GKeyFile               *key_file,
 503                                                                 GKeyFileGroup          *group,
 504                                                                 GKeyFileKeyValuePair   *pair);
 505 static void                  g_key_file_add_key                (GKeyFile               *key_file,
 506                                                                 GKeyFileGroup          *group,
 507                                                                 const gchar            *key,
 508                                                                 const gchar            *value);
 509 static void                  g_key_file_add_group              (GKeyFile               *key_file,
 510                                                                 const gchar            *group_name);
 511 static gboolean              g_key_file_is_group_name          (const gchar *name);
 512 static gboolean              g_key_file_is_key_name            (const gchar *name);
 513 static void                  g_key_file_key_value_pair_free    (GKeyFileKeyValuePair   *pair);
 514 static gboolean              g_key_file_line_is_comment        (const gchar            *line);
 515 static gboolean              g_key_file_line_is_group          (const gchar            *line);
 516 static gboolean              g_key_file_line_is_key_value_pair (const gchar            *line);
 517 static gchar                *g_key_file_parse_value_as_string  (GKeyFile               *key_file,
 518                                                                 const gchar            *value,
 519                                                                 GSList                **separators,
 520                                                                 GError                **error);
 521 static gchar                *g_key_file_parse_string_as_value  (GKeyFile               *key_file,
 522                                                                 const gchar            *string,
 523                                                                 gboolean                escape_separator);
 524 static gint                  g_key_file_parse_value_as_integer (GKeyFile               *key_file,
 525                                                                 const gchar            *value,
 526                                                                 GError                **error);
 527 static gchar                *g_key_file_parse_integer_as_value (GKeyFile               *key_file,
 528                                                                 gint                    value);
 529 static gdouble               g_key_file_parse_value_as_double  (GKeyFile               *key_file,
 530                                                                 const gchar            *value,
 531                                                                 GError                **error);
 532 static gboolean              g_key_file_parse_value_as_boolean (GKeyFile               *key_file,
 533                                                                 const gchar            *value,
 534                                                                 GError                **error);
 535 static gchar                *g_key_file_parse_boolean_as_value (GKeyFile               *key_file,
 536                                                                 gboolean                value);
 537 static gchar                *g_key_file_parse_value_as_comment (GKeyFile               *key_file,
 538                                                                 const gchar            *value);
 539 static gchar                *g_key_file_parse_comment_as_value (GKeyFile               *key_file,
 540                                                                 const gchar            *comment);
 541 static void                  g_key_file_parse_key_value_pair   (GKeyFile               *key_file,
 542                                                                 const gchar            *line,
 543                                                                 gsize                   length,
 544                                                                 GError                **error);
 545 static void                  g_key_file_parse_comment          (GKeyFile               *key_file,
 546                                                                 const gchar            *line,
 547                                                                 gsize                   length,
 548                                                                 GError                **error);
 549 static void                  g_key_file_parse_group            (GKeyFile               *key_file,
 550                                                                 const gchar            *line,
 551                                                                 gsize                   length,
 552                                                                 GError                **error);
 553 static gchar                *key_get_locale                    (const gchar            *key);
 554 static void                  g_key_file_parse_data             (GKeyFile               *key_file,
 555                                                                 const gchar            *data,
 556                                                                 gsize                   length,
 557                                                                 GError                **error);
 558 static void                  g_key_file_flush_parse_buffer     (GKeyFile               *key_file,
 559                                                                 GError                **error);
 560
 561
 562 GQuark
 563 g_key_file_error_quark (void)
 564 {
 565   return g_quark_from_static_string ("g-key-file-error-quark");
 566 }
 567
 568 static void
 569 g_key_file_init (GKeyFile *key_file)
 570 {
 571   key_file->current_group = g_slice_new0 (GKeyFileGroup);
 572   key_file->groups = g_list_prepend (NULL, key_file->current_group);
 573   key_file->group_hash = g_hash_table_new (g_str_hash, g_str_equal);
 574   key_file->start_group = NULL;
 575   key_file->parse_buffer = g_string_sized_new (128);
 576   key_file->approximate_size = 0;
 577   key_file->list_separator = ';';
 578   key_file->flags = 0;
 579   key_file->locales = g_strdupv ((gchar **)g_get_language_names ());
 580 }
 581
 582 static void
 583 g_key_file_clear (GKeyFile *key_file)
 584 {
 585   GList *tmp, *group_node;
 586
 587   if (key_file->locales)
 588     {
 589       g_strfreev (key_file->locales);
 590       key_file->locales = NULL;
 591     }
 592
 593   if (key_file->parse_buffer)
 594     {
 595       g_string_free (key_file->parse_buffer, TRUE);
 596       key_file->parse_buffer = NULL;
 597     }
 598
 599   tmp = key_file->groups;
 600   while (tmp != NULL)
 601     {
 602       group_node = tmp;
 603       tmp = tmp->next;
 604       g_key_file_remove_group_node (key_file, group_node);
 605     }
 606
 607   if (key_file->group_hash != NULL)
 608     {
 609       g_hash_table_destroy (key_file->group_hash);
 610       key_file->group_hash = NULL;
 611     }
 612
 613   g_warn_if_fail (key_file->groups == NULL);
 614 }
 615
 616
 617 /**
 618  * g_key_file_new:
 619  *
 620  * Creates a new empty #GKeyFile object. Use
 621  * g_key_file_load_from_file(), g_key_file_load_from_data(),
 622  * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to
 623  * read an existing key file.
 624  *
 625  * Return value: (transfer full): an empty #GKeyFile.
 626  *
 627  * Since: 2.6
 628  **/
 629 GKeyFile *
 630 g_key_file_new (void)
 631 {
 632   GKeyFile *key_file;
 633
 634   key_file = g_slice_new0 (GKeyFile);
 635   key_file->ref_count = 1;
 636   g_key_file_init (key_file);
 637
 638   return key_file;
 639 }
 640
 641 /**
 642  * g_key_file_set_list_separator:
 643  * @key_file: a #GKeyFile
 644  * @separator: the separator
 645  *
 646  * Sets the character which is used to separate
 647  * values in lists. Typically ';' or ',' are used
 648  * as separators. The default list separator is ';'.
 649  *
 650  * Since: 2.6
 651  */
 652 void
 653 g_key_file_set_list_separator (GKeyFile *key_file,
 654                                gchar     separator)
 655 {
 656   g_return_if_fail (key_file != NULL);
 657
 658   key_file->list_separator = separator;
 659 }
 660
 661
 662 /* Iterates through all the directories in *dirs trying to
 663  * open file.  When it successfully locates and opens a file it
 664  * returns the file descriptor to the open file.  It also
 665  * outputs the absolute path of the file in output_file.
 666  */
 667 static gint
 668 find_file_in_data_dirs (const gchar   *file,
 669                         const gchar  **dirs,
 670                         gchar        **output_file,
 671                         GError       **error)
 672 {
 673   const gchar **data_dirs, *data_dir;
 674   gchar *path;
 675   gint fd;
 676
 677   path = NULL;
 678   fd = -1;
 679
 680   if (dirs == NULL)
 681     return fd;
 682
 683   data_dirs = dirs;
 684
 685   while (data_dirs && (data_dir = *data_dirs) && fd == -1)
 686     {
 687       gchar *candidate_file, *sub_dir;
 688
 689       candidate_file = (gchar *) file;
 690       sub_dir = g_strdup ("");
 691       while (candidate_file != NULL && fd == -1)
 692         {
 693           gchar *p;
 694
 695           path = g_build_filename (data_dir, sub_dir,
 696                                    candidate_file, NULL);
 697
 698           fd = g_open (path, O_RDONLY, 0);
 699
 700           if (fd == -1)
 701             {
 702               g_free (path);
 703               path = NULL;
 704             }
 705
 706           candidate_file = strchr (candidate_file, '-');
 707
 708           if (candidate_file == NULL)
 709             break;
 710
 711           candidate_file++;
 712
 713           g_free (sub_dir);
 714           sub_dir = g_strndup (file, candidate_file - file - 1);
 715
 716           for (p = sub_dir; *p != '\0'; p++)
 717             {
 718               if (*p == '-')
 719                 *p = G_DIR_SEPARATOR;
 720             }
 721         }
 722       g_free (sub_dir);
 723       data_dirs++;
 724     }
 725
 726   if (fd == -1)
 727     {
 728       g_set_error_literal (error, G_KEY_FILE_ERROR,
 729                            G_KEY_FILE_ERROR_NOT_FOUND,
 730                            _("Valid key file could not be "
 731                              "found in search dirs"));
 732     }
 733
 734   if (output_file != NULL && fd > 0)
 735     *output_file = g_strdup (path);
 736
 737   g_free (path);
 738
 739   return fd;
 740 }
 741
 742 static gboolean
 743 g_key_file_load_from_fd (GKeyFile       *key_file,
 744                          gint            fd,
 745                          GKeyFileFlags   flags,
 746                          GError        **error)
 747 {
 748   GError *key_file_error = NULL;
 749   gssize bytes_read;
 750   struct stat stat_buf;
 751   gchar read_buf[4096];
 752
 753   if (fstat (fd, &stat_buf) < 0)
 754     {
 755       g_set_error_literal (error, G_FILE_ERROR,
 756                            g_file_error_from_errno (errno),
 757                            g_strerror (errno));
 758       return FALSE;
 759     }
 760
 761   if (!S_ISREG (stat_buf.st_mode))
 762     {
 763       g_set_error_literal (error, G_KEY_FILE_ERROR,
 764                            G_KEY_FILE_ERROR_PARSE,
 765                            _("Not a regular file"));
 766       return FALSE;
 767     }
 768
 769   if (key_file->approximate_size > 0)
 770     {
 771       g_key_file_clear (key_file);
 772       g_key_file_init (key_file);
 773     }
 774   key_file->flags = flags;
 775
 776   do
 777     {
 778       bytes_read = read (fd, read_buf, 4096);
 779
 780       if (bytes_read == 0)  /* End of File */
 781         break;
 782
 783       if (bytes_read < 0)
 784         {
 785           if (errno == EINTR || errno == EAGAIN)
 786             continue;
 787
 788           g_set_error_literal (error, G_FILE_ERROR,
 789                                g_file_error_from_errno (errno),
 790                                g_strerror (errno));
 791           return FALSE;
 792         }
 793
 794       g_key_file_parse_data (key_file,
 795                              read_buf, bytes_read,
 796                              &key_file_error);
 797     }
 798   while (!key_file_error);
 799
 800   if (key_file_error)
 801     {
 802       g_propagate_error (error, key_file_error);
 803       return FALSE;
 804     }
 805
 806   g_key_file_flush_parse_buffer (key_file, &key_file_error);
 807
 808   if (key_file_error)
 809     {
 810       g_propagate_error (error, key_file_error);
 811       return FALSE;
 812     }
 813
 814   return TRUE;
 815 }
 816
 817 /**
 818  * g_key_file_load_from_file:
 819  * @key_file: an empty #GKeyFile struct
 820  * @file: (type filename): the path of a filename to load, in the GLib filename encoding
 821  * @flags: flags from #GKeyFileFlags
 822  * @error: return location for a #GError, or %NULL
 823  *
 824  * Loads a key file into an empty #GKeyFile structure.
 825  * If the file could not be loaded then %error is set to
 826  * either a #GFileError or #GKeyFileError.
 827  *
 828  * Return value: %TRUE if a key file could be loaded, %FALSE otherwise
 829  *
 830  * Since: 2.6
 831  **/
 832 gboolean
 833 g_key_file_load_from_file (GKeyFile       *key_file,
 834                            const gchar    *file,
 835                            GKeyFileFlags   flags,
 836                            GError        **error)
 837 {
 838   GError *key_file_error = NULL;
 839   gint fd;
 840
 841   g_return_val_if_fail (key_file != NULL, FALSE);
 842   g_return_val_if_fail (file != NULL, FALSE);
 843
 844   fd = g_open (file, O_RDONLY, 0);
 845
 846   if (fd == -1)
 847     {
 848       g_set_error_literal (error, G_FILE_ERROR,
 849                            g_file_error_from_errno (errno),
 850                            g_strerror (errno));
 851       return FALSE;
 852     }
 853
 854   g_key_file_load_from_fd (key_file, fd, flags, &key_file_error);
 855   close (fd);
 856
 857   if (key_file_error)
 858     {
 859       g_propagate_error (error, key_file_error);
 860       return FALSE;
 861     }
 862
 863   return TRUE;
 864 }
 865
 866 /**
 867  * g_key_file_load_from_data:
 868  * @key_file: an empty #GKeyFile struct
 869  * @data: (array length=length): key file loaded in memory
 870  * @length: the length of @data in bytes
 871  * @flags: flags from #GKeyFileFlags
 872  * @error: return location for a #GError, or %NULL
 873  *
 874  * Loads a key file from memory into an empty #GKeyFile structure.
 875  * If the object cannot be created then %error is set to a #GKeyFileError.
 876  *
 877  * Return value: %TRUE if a key file could be loaded, %FALSE otherwise
 878  *
 879  * Since: 2.6
 880  **/
 881 gboolean
 882 g_key_file_load_from_data (GKeyFile       *key_file,
 883                            const gchar    *data,
 884                            gsize           length,
 885                            GKeyFileFlags   flags,
 886                            GError        **error)
 887 {
 888   GError *key_file_error = NULL;
 889
 890   g_return_val_if_fail (key_file != NULL, FALSE);
 891   g_return_val_if_fail (data != NULL, FALSE);
 892   g_return_val_if_fail (length != 0, FALSE);
 893
 894   if (length == (gsize)-1)
 895     length = strlen (data);
 896
 897   if (key_file->approximate_size > 0)
 898     {
 899       g_key_file_clear (key_file);
 900       g_key_file_init (key_file);
 901     }
 902   key_file->flags = flags;
 903
 904   g_key_file_parse_data (key_file, data, length, &key_file_error);
 905
 906   if (key_file_error)
 907     {
 908       g_propagate_error (error, key_file_error);
 909       return FALSE;
 910     }
 911
 912   g_key_file_flush_parse_buffer (key_file, &key_file_error);
 913
 914   if (key_file_error)
 915     {
 916       g_propagate_error (error, key_file_error);
 917       return FALSE;
 918     }
 919
 920   return TRUE;
 921 }
 922
 923 /**
 924  * g_key_file_load_from_dirs:
 925  * @key_file: an empty #GKeyFile struct
 926  * @file: (type filename): a relative path to a filename to open and parse
 927  * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search
 928  * @full_path: (out) (type filename): return location for a string containing the full path
 929  *   of the file, or %NULL
 930  * @flags: flags from #GKeyFileFlags
 931  * @error: return location for a #GError, or %NULL
 932  *
 933  * This function looks for a key file named @file in the paths
 934  * specified in @search_dirs, loads the file into @key_file and
 935  * returns the file's full path in @full_path.  If the file could not
 936  * be loaded then an %error is set to either a #GFileError or
 937  * #GKeyFileError.
 938  *
 939  * Return value: %TRUE if a key file could be loaded, %FALSE otherwise
 940  *
 941  * Since: 2.14
 942  **/
 943 gboolean
 944 g_key_file_load_from_dirs (GKeyFile       *key_file,
 945                            const gchar    *file,
 946                            const gchar   **search_dirs,
 947                            gchar         **full_path,
 948                            GKeyFileFlags   flags,
 949                            GError        **error)
 950 {
 951   GError *key_file_error = NULL;
 952   const gchar **data_dirs;
 953   gchar *output_path;
 954   gint fd;
 955   gboolean found_file;
 956
 957   g_return_val_if_fail (key_file != NULL, FALSE);
 958   g_return_val_if_fail (!g_path_is_absolute (file), FALSE);
 959   g_return_val_if_fail (search_dirs != NULL, FALSE);
 960
 961   found_file = FALSE;
 962   data_dirs = search_dirs;
 963   output_path = NULL;
 964   while (*data_dirs != NULL && !found_file)
 965     {
 966       g_free (output_path);
 967
 968       fd = find_file_in_data_dirs (file, data_dirs, &output_path,
 969                                    &key_file_error);
 970
 971       if (fd == -1)
 972         {
 973           if (key_file_error)
 974             g_propagate_error (error, key_file_error);
 975           break;
 976         }
 977
 978       found_file = g_key_file_load_from_fd (key_file, fd, flags,
 979                                             &key_file_error);
 980       close (fd);
 981
 982       if (key_file_error)
 983         {
 984           g_propagate_error (error, key_file_error);
 985           break;
 986         }
 987     }
 988
 989   if (found_file && full_path)
 990     *full_path = output_path;
 991   else
 992     g_free (output_path);
 993
 994   return found_file;
 995 }
 996
 997 /**
 998  * g_key_file_load_from_data_dirs:
 999  * @key_file: an empty #GKeyFile struct
1000  * @file: (type filename): a relative path to a filename to open and parse
1001  * @full_path: (out) (type filename): return location for a string containing the full path
1002  *   of the file, or %NULL
1003  * @flags: flags from #GKeyFileFlags
1004  * @error: return location for a #GError, or %NULL
1005  *
1006  * This function looks for a key file named @file in the paths
1007  * returned from g_get_user_data_dir() and g_get_system_data_dirs(),
1008  * loads the file into @key_file and returns the file's full path in
1009  * @full_path.  If the file could not be loaded then an %error is
1010  * set to either a #GFileError or #GKeyFileError.
1011  *
1012  * Return value: %TRUE if a key file could be loaded, %FALSE othewise
1013  * Since: 2.6
1014  **/
1015 gboolean
1016 g_key_file_load_from_data_dirs (GKeyFile       *key_file,
1017                                 const gchar    *file,
1018                                 gchar         **full_path,
1019                                 GKeyFileFlags   flags,
1020                                 GError        **error)
1021 {
1022   gchar **all_data_dirs;
1023   const gchar * user_data_dir;
1024   const gchar * const * system_data_dirs;
1025   gsize i, j;
1026   gboolean found_file;
1027
1028   g_return_val_if_fail (key_file != NULL, FALSE);
1029   g_return_val_if_fail (!g_path_is_absolute (file), FALSE);
1030
1031   user_data_dir = g_get_user_data_dir ();
1032   system_data_dirs = g_get_system_data_dirs ();
1033   all_data_dirs = g_new (gchar *, g_strv_length ((gchar **)system_data_dirs) + 2);
1034
1035   i = 0;
1036   all_data_dirs[i++] = g_strdup (user_data_dir);
1037
1038   j = 0;
1039   while (system_data_dirs[j] != NULL)
1040     all_data_dirs[i++] = g_strdup (system_data_dirs[j++]);
1041   all_data_dirs[i] = NULL;
1042
1043   found_file = g_key_file_load_from_dirs (key_file,
1044                                           file,
1045                                           (const gchar **)all_data_dirs,
1046                                           full_path,
1047                                           flags,
1048                                           error);
1049
1050   g_strfreev (all_data_dirs);
1051
1052   return found_file;
1053 }
1054
1055 /**
1056  * g_key_file_ref: (skip)
1057  * @key_file: a #GKeyFile
1058  *
1059  * Increases the reference count of @key_file.
1060  *
1061  * Returns: the same @key_file.
1062  *
1063  * Since: 2.32
1064  **/
1065 GKeyFile *
1066 g_key_file_ref (GKeyFile *key_file)
1067 {
1068   g_return_val_if_fail (key_file != NULL, NULL);
1069
1070   g_atomic_int_inc (&key_file->ref_count);
1071
1072   return key_file;
1073 }
1074
1075 /**
1076  * g_key_file_free: (skip)
1077  * @key_file: a #GKeyFile
1078  *
1079  * Clears all keys and groups from @key_file, and decreases the
1080  * reference count by 1. If the reference count reaches zero,
1081  * frees the key file and all its allocated memory.
1082  *
1083  * Since: 2.6
1084  **/
1085 void
1086 g_key_file_free (GKeyFile *key_file)
1087 {
1088   g_return_if_fail (key_file != NULL);
1089
1090   g_key_file_clear (key_file);
1091   g_key_file_unref (key_file);
1092 }
1093
1094 /**
1095  * g_key_file_unref:
1096  * @key_file: a #GKeyFile
1097  *
1098  * Decreases the reference count of @key_file by 1. If the reference count
1099  * reaches zero, frees the key file and all its allocated memory.
1100  *
1101  * Since: 2.32
1102  **/
1103 void
1104 g_key_file_unref (GKeyFile *key_file)
1105 {
1106   g_return_if_fail (key_file != NULL);
1107
1108   if (g_atomic_int_dec_and_test (&key_file->ref_count))
1109     {
1110       g_key_file_clear (key_file);
1111       g_slice_free (GKeyFile, key_file);
1112     }
1113 }
1114
1115 /* If G_KEY_FILE_KEEP_TRANSLATIONS is not set, only returns
1116  * true for locales that match those in g_get_language_names().
1117  */
1118 static gboolean
1119 g_key_file_locale_is_interesting (GKeyFile    *key_file,
1120                                   const gchar *locale)
1121 {
1122   gsize i;
1123
1124   if (key_file->flags & G_KEY_FILE_KEEP_TRANSLATIONS)
1125     return TRUE;
1126
1127   for (i = 0; key_file->locales[i] != NULL; i++)
1128     {
1129       if (g_ascii_strcasecmp (key_file->locales[i], locale) == 0)
1130         return TRUE;
1131     }
1132
1133   return FALSE;
1134 }
1135
1136 static void
1137 g_key_file_parse_line (GKeyFile     *key_file,
1138                        const gchar  *line,
1139                        gsize         length,
1140                        GError      **error)
1141 {
1142   GError *parse_error = NULL;
1143   gchar *line_start;
1144
1145   g_return_if_fail (key_file != NULL);
1146   g_return_if_fail (line != NULL);
1147
1148   line_start = (gchar *) line;
1149   while (g_ascii_isspace (*line_start))
1150     line_start++;
1151
1152   if (g_key_file_line_is_comment (line_start))
1153     g_key_file_parse_comment (key_file, line, length, &parse_error);
1154   else if (g_key_file_line_is_group (line_start))
1155     g_key_file_parse_group (key_file, line_start,
1156                             length - (line_start - line),
1157                             &parse_error);
1158   else if (g_key_file_line_is_key_value_pair (line_start))
1159     g_key_file_parse_key_value_pair (key_file, line_start,
1160                                      length - (line_start - line),
1161                                      &parse_error);
1162   else
1163     {
1164       gchar *line_utf8 = _g_utf8_make_valid (line);
1165       g_set_error (error, G_KEY_FILE_ERROR,
1166                    G_KEY_FILE_ERROR_PARSE,
1167                    _("Key file contains line '%s' which is not "
1168                      "a key-value pair, group, or comment"),
1169                    line_utf8);
1170       g_free (line_utf8);
1171
1172       return;
1173     }
1174
1175   if (parse_error)
1176     g_propagate_error (error, parse_error);
1177 }
1178
1179 static void
1180 g_key_file_parse_comment (GKeyFile     *key_file,
1181                           const gchar  *line,
1182                           gsize         length,
1183                           GError      **error)
1184 {
1185   GKeyFileKeyValuePair *pair;
1186
1187   if (!(key_file->flags & G_KEY_FILE_KEEP_COMMENTS))
1188     return;
1189
1190   g_warn_if_fail (key_file->current_group != NULL);
1191
1192   pair = g_slice_new (GKeyFileKeyValuePair);
1193   pair->key = NULL;
1194   pair->value = g_strndup (line, length);
1195
1196   key_file->current_group->key_value_pairs =
1197     g_list_prepend (key_file->current_group->key_value_pairs, pair);
1198
1199   if (length == 0 || line[0] != '#')
1200     key_file->current_group->has_trailing_blank_line = TRUE;
1201 }
1202
1203 static void
1204 g_key_file_parse_group (GKeyFile     *key_file,
1205                         const gchar  *line,
1206                         gsize         length,
1207                         GError      **error)
1208 {
1209   gchar *group_name;
1210   const gchar *group_name_start, *group_name_end;
1211
1212   /* advance past opening '['
1213    */
1214   group_name_start = line + 1;
1215   group_name_end = line + length - 1;
1216
1217   while (*group_name_end != ']')
1218     group_name_end--;
1219
1220   group_name = g_strndup (group_name_start,
1221                           group_name_end - group_name_start);
1222
1223   if (!g_key_file_is_group_name (group_name))
1224     {
1225       g_set_error (error, G_KEY_FILE_ERROR,
1226                    G_KEY_FILE_ERROR_PARSE,
1227                    _("Invalid group name: %s"), group_name);
1228       g_free (group_name);
1229       return;
1230     }
1231
1232   g_key_file_add_group (key_file, group_name);
1233   g_free (group_name);
1234 }
1235
1236 static void
1237 g_key_file_parse_key_value_pair (GKeyFile     *key_file,
1238                                  const gchar  *line,
1239                                  gsize         length,
1240                                  GError      **error)
1241 {
1242   gchar *key, *value, *key_end, *value_start, *locale;
1243   gsize key_len, value_len;
1244
1245   if (key_file->current_group == NULL || key_file->current_group->name == NULL)
1246     {
1247       g_set_error_literal (error, G_KEY_FILE_ERROR,
1248                            G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1249                            _("Key file does not start with a group"));
1250       return;
1251     }
1252
1253   key_end = value_start = strchr (line, '=');
1254
1255   g_warn_if_fail (key_end != NULL);
1256
1257   key_end--;
1258   value_start++;
1259
1260   /* Pull the key name from the line (chomping trailing whitespace)
1261    */
1262   while (g_ascii_isspace (*key_end))
1263     key_end--;
1264
1265   key_len = key_end - line + 2;
1266
1267   g_warn_if_fail (key_len <= length);
1268
1269   key = g_strndup (line, key_len - 1);
1270
1271   if (!g_key_file_is_key_name (key))
1272     {
1273       g_set_error (error, G_KEY_FILE_ERROR,
1274                    G_KEY_FILE_ERROR_PARSE,
1275                    _("Invalid key name: %s"), key);
1276       g_free (key);
1277       return;
1278     }
1279
1280   /* Pull the value from the line (chugging leading whitespace)
1281    */
1282   while (g_ascii_isspace (*value_start))
1283     value_start++;
1284
1285   value_len = line + length - value_start + 1;
1286
1287   value = g_strndup (value_start, value_len);
1288
1289   g_warn_if_fail (key_file->start_group != NULL);
1290
1291   if (key_file->current_group
1292       && key_file->current_group->name
1293       && strcmp (key_file->start_group->name,
1294                  key_file->current_group->name) == 0
1295       && strcmp (key, "Encoding") == 0)
1296     {
1297       if (g_ascii_strcasecmp (value, "UTF-8") != 0)
1298         {
1299           gchar *value_utf8 = _g_utf8_make_valid (value);
1300           g_set_error (error, G_KEY_FILE_ERROR,
1301                        G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1302                        _("Key file contains unsupported "
1303                          "encoding '%s'"), value_utf8);
1304           g_free (value_utf8);
1305
1306           g_free (key);
1307           g_free (value);
1308           return;
1309         }
1310     }
1311
1312   /* Is this key a translation? If so, is it one that we care about?
1313    */
1314   locale = key_get_locale (key);
1315
1316   if (locale == NULL || g_key_file_locale_is_interesting (key_file, locale))
1317     {
1318       GKeyFileKeyValuePair *pair;
1319
1320       pair = g_slice_new (GKeyFileKeyValuePair);
1321       pair->key = key;
1322       pair->value = value;
1323
1324       g_key_file_add_key_value_pair (key_file, key_file->current_group, pair);
1325     }
1326   else
1327     {
1328       g_free (key);
1329       g_free (value);
1330     }
1331
1332   g_free (locale);
1333 }
1334
1335 static gchar *
1336 key_get_locale (const gchar *key)
1337 {
1338   gchar *locale;
1339
1340   locale = g_strrstr (key, "[");
1341
1342   if (locale && strlen (locale) <= 2)
1343     locale = NULL;
1344
1345   if (locale)
1346     locale = g_strndup (locale + 1, strlen (locale) - 2);
1347
1348   return locale;
1349 }
1350
1351 static void
1352 g_key_file_parse_data (GKeyFile     *key_file,
1353                        const gchar  *data,
1354                        gsize         length,
1355                        GError      **error)
1356 {
1357   GError *parse_error;
1358   gsize i;
1359
1360   g_return_if_fail (key_file != NULL);
1361   g_return_if_fail (data != NULL);
1362
1363   parse_error = NULL;
1364
1365   i = 0;
1366   while (i < length)
1367     {
1368       if (data[i] == '\n')
1369         {
1370           if (key_file->parse_buffer->len > 0
1371               && (key_file->parse_buffer->str[key_file->parse_buffer->len - 1]
1372                   == '\r'))
1373             g_string_erase (key_file->parse_buffer,
1374                             key_file->parse_buffer->len - 1,
1375                             1);
1376
1377           /* When a newline is encountered flush the parse buffer so that the
1378            * line can be parsed.  Note that completely blank lines won't show
1379            * up in the parse buffer, so they get parsed directly.
1380            */
1381           if (key_file->parse_buffer->len > 0)
1382             g_key_file_flush_parse_buffer (key_file, &parse_error);
1383           else
1384             g_key_file_parse_comment (key_file, "", 1, &parse_error);
1385
1386           if (parse_error)
1387             {
1388               g_propagate_error (error, parse_error);
1389               return;
1390             }
1391           i++;
1392         }
1393       else
1394         {
1395           const gchar *start_of_line;
1396           const gchar *end_of_line;
1397           gsize line_length;
1398
1399           start_of_line = data + i;
1400           end_of_line = memchr (start_of_line, '\n', length - i);
1401
1402           if (end_of_line == NULL)
1403             end_of_line = data + length;
1404
1405           line_length = end_of_line - start_of_line;
1406
1407           g_string_append_len (key_file->parse_buffer, start_of_line, line_length);
1408           i += line_length;
1409         }
1410     }
1411
1412   key_file->approximate_size += length;
1413 }
1414
1415 static void
1416 g_key_file_flush_parse_buffer (GKeyFile  *key_file,
1417                                GError   **error)
1418 {
1419   GError *file_error = NULL;
1420
1421   g_return_if_fail (key_file != NULL);
1422
1423   file_error = NULL;
1424
1425   if (key_file->parse_buffer->len > 0)
1426     {
1427       g_key_file_parse_line (key_file, key_file->parse_buffer->str,
1428                              key_file->parse_buffer->len,
1429                              &file_error);
1430       g_string_erase (key_file->parse_buffer, 0, -1);
1431
1432       if (file_error)
1433         {
1434           g_propagate_error (error, file_error);
1435           return;
1436         }
1437     }
1438 }
1439
1440 /**
1441  * g_key_file_to_data:
1442  * @key_file: a #GKeyFile
1443  * @length: (out) (allow-none): return location for the length of the
1444  *   returned string, or %NULL
1445  * @error: return location for a #GError, or %NULL
1446  *
1447  * This function outputs @key_file as a string.
1448  *
1449  * Note that this function never reports an error,
1450  * so it is safe to pass %NULL as @error.
1451  *
1452  * Return value: a newly allocated string holding
1453  *   the contents of the #GKeyFile
1454  *
1455  * Since: 2.6
1456  **/
1457 gchar *
1458 g_key_file_to_data (GKeyFile  *key_file,
1459                     gsize     *length,
1460                     GError   **error)
1461 {
1462   GString *data_string;
1463   GList *group_node, *key_file_node;
1464   gboolean has_blank_line = TRUE;
1465
1466   g_return_val_if_fail (key_file != NULL, NULL);
1467
1468   data_string = g_string_sized_new (2 * key_file->approximate_size);
1469
1470   for (group_node = g_list_last (key_file->groups);
1471        group_node != NULL;
1472        group_node = group_node->prev)
1473     {
1474       GKeyFileGroup *group;
1475
1476       group = (GKeyFileGroup *) group_node->data;
1477
1478       /* separate groups by at least an empty line */
1479       if (!has_blank_line)
1480         g_string_append_c (data_string, '\n');
1481       has_blank_line = group->has_trailing_blank_line;
1482
1483       if (group->comment != NULL)
1484         g_string_append_printf (data_string, "%s\n", group->comment->value);
1485
1486       if (group->name != NULL)
1487         g_string_append_printf (data_string, "[%s]\n", group->name);
1488
1489       for (key_file_node = g_list_last (group->key_value_pairs);
1490            key_file_node != NULL;
1491            key_file_node = key_file_node->prev)
1492         {
1493           GKeyFileKeyValuePair *pair;
1494
1495           pair = (GKeyFileKeyValuePair *) key_file_node->data;
1496
1497           if (pair->key != NULL)
1498             g_string_append_printf (data_string, "%s=%s\n", pair->key, pair->value);
1499           else
1500             g_string_append_printf (data_string, "%s\n", pair->value);
1501         }
1502     }
1503
1504   if (length)
1505     *length = data_string->len;
1506
1507   return g_string_free (data_string, FALSE);
1508 }
1509
1510 /**
1511  * g_key_file_get_keys:
1512  * @key_file: a #GKeyFile
1513  * @group_name: a group name
1514  * @length: (out): return location for the number of keys returned, or %NULL
1515  * @error: return location for a #GError, or %NULL
1516  *
1517  * Returns all keys for the group name @group_name.  The array of
1518  * returned keys will be %NULL-terminated, so @length may
1519  * optionally be %NULL. In the event that the @group_name cannot
1520  * be found, %NULL is returned and @error is set to
1521  * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1522  *
1523  * Return value: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
1524  *     Use g_strfreev() to free it.
1525  *
1526  * Since: 2.6
1527  **/
1528 gchar **
1529 g_key_file_get_keys (GKeyFile     *key_file,
1530                      const gchar  *group_name,
1531                      gsize        *length,
1532                      GError      **error)
1533 {
1534   GKeyFileGroup *group;
1535   GList *tmp;
1536   gchar **keys;
1537   gsize i, num_keys;
1538
1539   g_return_val_if_fail (key_file != NULL, NULL);
1540   g_return_val_if_fail (group_name != NULL, NULL);
1541
1542   group = g_key_file_lookup_group (key_file, group_name);
1543
1544   if (!group)
1545     {
1546       g_set_error (error, G_KEY_FILE_ERROR,
1547                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1548                    _("Key file does not have group '%s'"),
1549                    group_name ? group_name : "(null)");
1550       return NULL;
1551     }
1552
1553   num_keys = 0;
1554   for (tmp = group->key_value_pairs; tmp; tmp = tmp->next)
1555     {
1556       GKeyFileKeyValuePair *pair;
1557
1558       pair = (GKeyFileKeyValuePair *) tmp->data;
1559
1560       if (pair->key)
1561         num_keys++;
1562     }
1563
1564   keys = g_new (gchar *, num_keys + 1);
1565
1566   i = num_keys - 1;
1567   for (tmp = group->key_value_pairs; tmp; tmp = tmp->next)
1568     {
1569       GKeyFileKeyValuePair *pair;
1570
1571       pair = (GKeyFileKeyValuePair *) tmp->data;
1572
1573       if (pair->key)
1574         {
1575           keys[i] = g_strdup (pair->key);
1576           i--;
1577         }
1578     }
1579
1580   keys[num_keys] = NULL;
1581
1582   if (length)
1583     *length = num_keys;
1584
1585   return keys;
1586 }
1587
1588 /**
1589  * g_key_file_get_start_group:
1590  * @key_file: a #GKeyFile
1591  *
1592  * Returns the name of the start group of the file.
1593  *
1594  * Return value: The start group of the key file.
1595  *
1596  * Since: 2.6
1597  **/
1598 gchar *
1599 g_key_file_get_start_group (GKeyFile *key_file)
1600 {
1601   g_return_val_if_fail (key_file != NULL, NULL);
1602
1603   if (key_file->start_group)
1604     return g_strdup (key_file->start_group->name);
1605
1606   return NULL;
1607 }
1608
1609 /**
1610  * g_key_file_get_groups:
1611  * @key_file: a #GKeyFile
1612  * @length: (out) (allow-none): return location for the number of returned groups, or %NULL
1613  *
1614  * Returns all groups in the key file loaded with @key_file.
1615  * The array of returned groups will be %NULL-terminated, so
1616  * @length may optionally be %NULL.
1617  *
1618  * Return value: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
1619  *   Use g_strfreev() to free it.
1620  * Since: 2.6
1621  **/
1622 gchar **
1623 g_key_file_get_groups (GKeyFile *key_file,
1624                        gsize    *length)
1625 {
1626   GList *group_node;
1627   gchar **groups;
1628   gsize i, num_groups;
1629
1630   g_return_val_if_fail (key_file != NULL, NULL);
1631
1632   num_groups = g_list_length (key_file->groups);
1633
1634   g_return_val_if_fail (num_groups > 0, NULL);
1635
1636   group_node = g_list_last (key_file->groups);
1637
1638   g_return_val_if_fail (((GKeyFileGroup *) group_node->data)->name == NULL, NULL);
1639
1640   /* Only need num_groups instead of num_groups + 1
1641    * because the first group of the file (last in the
1642    * list) is always the comment group at the top,
1643    * which we skip
1644    */
1645   groups = g_new (gchar *, num_groups);
1646
1647
1648   i = 0;
1649   for (group_node = group_node->prev;
1650        group_node != NULL;
1651        group_node = group_node->prev)
1652     {
1653       GKeyFileGroup *group;
1654
1655       group = (GKeyFileGroup *) group_node->data;
1656
1657       g_warn_if_fail (group->name != NULL);
1658
1659       groups[i++] = g_strdup (group->name);
1660     }
1661   groups[i] = NULL;
1662
1663   if (length)
1664     *length = i;
1665
1666   return groups;
1667 }
1668
1669 /**
1670  * g_key_file_get_value:
1671  * @key_file: a #GKeyFile
1672  * @group_name: a group name
1673  * @key: a key
1674  * @error: return location for a #GError, or %NULL
1675  *
1676  * Returns the raw value associated with @key under @group_name.
1677  * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string.
1678  *
1679  * In the event the key cannot be found, %NULL is returned and
1680  * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND.  In the
1681  * event that the @group_name cannot be found, %NULL is returned
1682  * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1683  *
1684  *
1685  * Return value: a newly allocated string or %NULL if the specified
1686  *  key cannot be found.
1687  *
1688  * Since: 2.6
1689  **/
1690 gchar *
1691 g_key_file_get_value (GKeyFile     *key_file,
1692                       const gchar  *group_name,
1693                       const gchar  *key,
1694                       GError      **error)
1695 {
1696   GKeyFileGroup *group;
1697   GKeyFileKeyValuePair *pair;
1698   gchar *value = NULL;
1699
1700   g_return_val_if_fail (key_file != NULL, NULL);
1701   g_return_val_if_fail (group_name != NULL, NULL);
1702   g_return_val_if_fail (key != NULL, NULL);
1703
1704   group = g_key_file_lookup_group (key_file, group_name);
1705
1706   if (!group)
1707     {
1708       g_set_error (error, G_KEY_FILE_ERROR,
1709                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1710                    _("Key file does not have group '%s'"),
1711                    group_name ? group_name : "(null)");
1712       return NULL;
1713     }
1714
1715   pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1716
1717   if (pair)
1718     value = g_strdup (pair->value);
1719   else
1720     g_set_error (error, G_KEY_FILE_ERROR,
1721                  G_KEY_FILE_ERROR_KEY_NOT_FOUND,
1722                  _("Key file does not have key '%s'"), key);
1723
1724   return value;
1725 }
1726
1727 /**
1728  * g_key_file_set_value:
1729  * @key_file: a #GKeyFile
1730  * @group_name: a group name
1731  * @key: a key
1732  * @value: a string
1733  *
1734  * Associates a new value with @key under @group_name.
1735  *
1736  * If @key cannot be found then it is created. If @group_name cannot
1737  * be found then it is created. To set an UTF-8 string which may contain
1738  * characters that need escaping (such as newlines or spaces), use
1739  * g_key_file_set_string().
1740  *
1741  * Since: 2.6
1742  **/
1743 void
1744 g_key_file_set_value (GKeyFile    *key_file,
1745                       const gchar *group_name,
1746                       const gchar *key,
1747                       const gchar *value)
1748 {
1749   GKeyFileGroup *group;
1750   GKeyFileKeyValuePair *pair;
1751
1752   g_return_if_fail (key_file != NULL);
1753   g_return_if_fail (g_key_file_is_group_name (group_name));
1754   g_return_if_fail (g_key_file_is_key_name (key));
1755   g_return_if_fail (value != NULL);
1756
1757   group = g_key_file_lookup_group (key_file, group_name);
1758
1759   if (!group)
1760     {
1761       g_key_file_add_group (key_file, group_name);
1762       group = (GKeyFileGroup *) key_file->groups->data;
1763
1764       g_key_file_add_key (key_file, group, key, value);
1765     }
1766   else
1767     {
1768       pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1769
1770       if (!pair)
1771         g_key_file_add_key (key_file, group, key, value);
1772       else
1773         {
1774           g_free (pair->value);
1775           pair->value = g_strdup (value);
1776         }
1777     }
1778 }
1779
1780 /**
1781  * g_key_file_get_string:
1782  * @key_file: a #GKeyFile
1783  * @group_name: a group name
1784  * @key: a key
1785  * @error: return location for a #GError, or %NULL
1786  *
1787  * Returns the string value associated with @key under @group_name.
1788  * Unlike g_key_file_get_value(), this function handles escape sequences
1789  * like \s.
1790  *
1791  * In the event the key cannot be found, %NULL is returned and
1792  * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND.  In the
1793  * event that the @group_name cannot be found, %NULL is returned
1794  * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1795  *
1796  * Return value: a newly allocated string or %NULL if the specified
1797  *   key cannot be found.
1798  *
1799  * Since: 2.6
1800  **/
1801 gchar *
1802 g_key_file_get_string (GKeyFile     *key_file,
1803                        const gchar  *group_name,
1804                        const gchar  *key,
1805                        GError      **error)
1806 {
1807   gchar *value, *string_value;
1808   GError *key_file_error;
1809
1810   g_return_val_if_fail (key_file != NULL, NULL);
1811   g_return_val_if_fail (group_name != NULL, NULL);
1812   g_return_val_if_fail (key != NULL, NULL);
1813
1814   key_file_error = NULL;
1815
1816   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1817
1818   if (key_file_error)
1819     {
1820       g_propagate_error (error, key_file_error);
1821       return NULL;
1822     }
1823
1824   if (!g_utf8_validate (value, -1, NULL))
1825     {
1826       gchar *value_utf8 = _g_utf8_make_valid (value);
1827       g_set_error (error, G_KEY_FILE_ERROR,
1828                    G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1829                    _("Key file contains key '%s' with value '%s' "
1830                      "which is not UTF-8"), key, value_utf8);
1831       g_free (value_utf8);
1832       g_free (value);
1833
1834       return NULL;
1835     }
1836
1837   string_value = g_key_file_parse_value_as_string (key_file, value, NULL,
1838                                                    &key_file_error);
1839   g_free (value);
1840
1841   if (key_file_error)
1842     {
1843       if (g_error_matches (key_file_error,
1844                            G_KEY_FILE_ERROR,
1845                            G_KEY_FILE_ERROR_INVALID_VALUE))
1846         {
1847           g_set_error (error, G_KEY_FILE_ERROR,
1848                        G_KEY_FILE_ERROR_INVALID_VALUE,
1849                        _("Key file contains key '%s' "
1850                          "which has a value that cannot be interpreted."),
1851                        key);
1852           g_error_free (key_file_error);
1853         }
1854       else
1855         g_propagate_error (error, key_file_error);
1856     }
1857
1858   return string_value;
1859 }
1860
1861 /**
1862  * g_key_file_set_string:
1863  * @key_file: a #GKeyFile
1864  * @group_name: a group name
1865  * @key: a key
1866  * @string: a string
1867  *
1868  * Associates a new string value with @key under @group_name.
1869  * If @key cannot be found then it is created.
1870  * If @group_name cannot be found then it is created.
1871  * Unlike g_key_file_set_value(), this function handles characters
1872  * that need escaping, such as newlines.
1873  *
1874  * Since: 2.6
1875  **/
1876 void
1877 g_key_file_set_string (GKeyFile    *key_file,
1878                        const gchar *group_name,
1879                        const gchar *key,
1880                        const gchar *string)
1881 {
1882   gchar *value;
1883
1884   g_return_if_fail (key_file != NULL);
1885   g_return_if_fail (string != NULL);
1886
1887   value = g_key_file_parse_string_as_value (key_file, string, FALSE);
1888   g_key_file_set_value (key_file, group_name, key, value);
1889   g_free (value);
1890 }
1891
1892 /**
1893  * g_key_file_get_string_list:
1894  * @key_file: a #GKeyFile
1895  * @group_name: a group name
1896  * @key: a key
1897  * @length: (out) (allow-none): return location for the number of returned strings, or %NULL
1898  * @error: return location for a #GError, or %NULL
1899  *
1900  * Returns the values associated with @key under @group_name.
1901  *
1902  * In the event the key cannot be found, %NULL is returned and
1903  * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND.  In the
1904  * event that the @group_name cannot be found, %NULL is returned
1905  * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1906  *
1907  * Return value: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
1908  *  a %NULL-terminated string array or %NULL if the specified
1909  *  key cannot be found. The array should be freed with g_strfreev().
1910  *
1911  * Since: 2.6
1912  **/
1913 gchar **
1914 g_key_file_get_string_list (GKeyFile     *key_file,
1915                             const gchar  *group_name,
1916                             const gchar  *key,
1917                             gsize        *length,
1918                             GError      **error)
1919 {
1920   GError *key_file_error = NULL;
1921   gchar *value, *string_value, **values;
1922   gint i, len;
1923   GSList *p, *pieces = NULL;
1924
1925   g_return_val_if_fail (key_file != NULL, NULL);
1926   g_return_val_if_fail (group_name != NULL, NULL);
1927   g_return_val_if_fail (key != NULL, NULL);
1928
1929   if (length)
1930     *length = 0;
1931
1932   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1933
1934   if (key_file_error)
1935     {
1936       g_propagate_error (error, key_file_error);
1937       return NULL;
1938     }
1939
1940   if (!g_utf8_validate (value, -1, NULL))
1941     {
1942       gchar *value_utf8 = _g_utf8_make_valid (value);
1943       g_set_error (error, G_KEY_FILE_ERROR,
1944                    G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1945                    _("Key file contains key '%s' with value '%s' "
1946                      "which is not UTF-8"), key, value_utf8);
1947       g_free (value_utf8);
1948       g_free (value);
1949
1950       return NULL;
1951     }
1952
1953   string_value = g_key_file_parse_value_as_string (key_file, value, &pieces, &key_file_error);
1954   g_free (value);
1955   g_free (string_value);
1956
1957   if (key_file_error)
1958     {
1959       if (g_error_matches (key_file_error,
1960                            G_KEY_FILE_ERROR,
1961                            G_KEY_FILE_ERROR_INVALID_VALUE))
1962         {
1963           g_set_error (error, G_KEY_FILE_ERROR,
1964                        G_KEY_FILE_ERROR_INVALID_VALUE,
1965                        _("Key file contains key '%s' "
1966                          "which has a value that cannot be interpreted."),
1967                        key);
1968           g_error_free (key_file_error);
1969         }
1970       else
1971         g_propagate_error (error, key_file_error);
1972
1973       g_slist_free_full (pieces, g_free);
1974       return NULL;
1975     }
1976
1977   len = g_slist_length (pieces);
1978   values = g_new (gchar *, len + 1);
1979   for (p = pieces, i = 0; p; p = p->next)
1980     values[i++] = p->data;
1981   values[len] = NULL;
1982
1983   g_slist_free (pieces);
1984
1985   if (length)
1986     *length = len;
1987
1988   return values;
1989 }
1990
1991 /**
1992  * g_key_file_set_string_list:
1993  * @key_file: a #GKeyFile
1994  * @group_name: a group name
1995  * @key: a key
1996  * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values
1997  * @length: number of string values in @list
1998  *
1999  * Associates a list of string values for @key under @group_name.
2000  * If @key cannot be found then it is created.
2001  * If @group_name cannot be found then it is created.
2002  *
2003  * Since: 2.6
2004  **/
2005 void
2006 g_key_file_set_string_list (GKeyFile            *key_file,
2007                             const gchar         *group_name,
2008                             const gchar         *key,
2009                             const gchar * const  list[],
2010                             gsize                length)
2011 {
2012   GString *value_list;
2013   gsize i;
2014
2015   g_return_if_fail (key_file != NULL);
2016   g_return_if_fail (list != NULL || length == 0);
2017
2018   value_list = g_string_sized_new (length * 128);
2019   for (i = 0; i < length && list[i] != NULL; i++)
2020     {
2021       gchar *value;
2022
2023       value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
2024       g_string_append (value_list, value);
2025       g_string_append_c (value_list, key_file->list_separator);
2026
2027       g_free (value);
2028     }
2029
2030   g_key_file_set_value (key_file, group_name, key, value_list->str);
2031   g_string_free (value_list, TRUE);
2032 }
2033
2034 /**
2035  * g_key_file_set_locale_string:
2036  * @key_file: a #GKeyFile
2037  * @group_name: a group name
2038  * @key: a key
2039  * @locale: a locale identifier
2040  * @string: a string
2041  *
2042  * Associates a string value for @key and @locale under @group_name.
2043  * If the translation for @key cannot be found then it is created.
2044  *
2045  * Since: 2.6
2046  **/
2047 void
2048 g_key_file_set_locale_string (GKeyFile     *key_file,
2049                               const gchar  *group_name,
2050                               const gchar  *key,
2051                               const gchar  *locale,
2052                               const gchar  *string)
2053 {
2054   gchar *full_key, *value;
2055
2056   g_return_if_fail (key_file != NULL);
2057   g_return_if_fail (key != NULL);
2058   g_return_if_fail (locale != NULL);
2059   g_return_if_fail (string != NULL);
2060
2061   value = g_key_file_parse_string_as_value (key_file, string, FALSE);
2062   full_key = g_strdup_printf ("%s[%s]", key, locale);
2063   g_key_file_set_value (key_file, group_name, full_key, value);
2064   g_free (full_key);
2065   g_free (value);
2066 }
2067
2068 /**
2069  * g_key_file_get_locale_string:
2070  * @key_file: a #GKeyFile
2071  * @group_name: a group name
2072  * @key: a key
2073  * @locale: (allow-none): a locale identifier or %NULL
2074  * @error: return location for a #GError, or %NULL
2075  *
2076  * Returns the value associated with @key under @group_name
2077  * translated in the given @locale if available.  If @locale is
2078  * %NULL then the current locale is assumed.
2079  *
2080  * If @key cannot be found then %NULL is returned and @error is set
2081  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
2082  * with @key cannot be interpreted or no suitable translation can
2083  * be found then the untranslated value is returned.
2084  *
2085  * Return value: a newly allocated string or %NULL if the specified
2086  *   key cannot be found.
2087  *
2088  * Since: 2.6
2089  **/
2090 gchar *
2091 g_key_file_get_locale_string (GKeyFile     *key_file,
2092                               const gchar  *group_name,
2093                               const gchar  *key,
2094                               const gchar  *locale,
2095                               GError      **error)
2096 {
2097   gchar *candidate_key, *translated_value;
2098   GError *key_file_error;
2099   gchar **languages;
2100   gboolean free_languages = FALSE;
2101   gint i;
2102
2103   g_return_val_if_fail (key_file != NULL, NULL);
2104   g_return_val_if_fail (group_name != NULL, NULL);
2105   g_return_val_if_fail (key != NULL, NULL);
2106
2107   candidate_key = NULL;
2108   translated_value = NULL;
2109   key_file_error = NULL;
2110
2111   if (locale)
2112     {
2113       languages = g_get_locale_variants (locale);
2114       free_languages = TRUE;
2115     }
2116   else
2117     {
2118       languages = (gchar **) g_get_language_names ();
2119       free_languages = FALSE;
2120     }
2121
2122   for (i = 0; languages[i]; i++)
2123     {
2124       candidate_key = g_strdup_printf ("%s[%s]", key, languages[i]);
2125
2126       translated_value = g_key_file_get_string (key_file,
2127                                                 group_name,
2128                                                 candidate_key, NULL);
2129       g_free (candidate_key);
2130
2131       if (translated_value)
2132         break;
2133
2134       g_free (translated_value);
2135       translated_value = NULL;
2136    }
2137
2138   /* Fallback to untranslated key
2139    */
2140   if (!translated_value)
2141     {
2142       translated_value = g_key_file_get_string (key_file, group_name, key,
2143                                                 &key_file_error);
2144
2145       if (!translated_value)
2146         g_propagate_error (error, key_file_error);
2147     }
2148
2149   if (free_languages)
2150     g_strfreev (languages);
2151
2152   return translated_value;
2153 }
2154
2155 /**
2156  * g_key_file_get_locale_string_list:
2157  * @key_file: a #GKeyFile
2158  * @group_name: a group name
2159  * @key: a key
2160  * @locale: (allow-none): a locale identifier or %NULL
2161  * @length: (out) (allow-none): return location for the number of returned strings or %NULL
2162  * @error: return location for a #GError or %NULL
2163  *
2164  * Returns the values associated with @key under @group_name
2165  * translated in the given @locale if available.  If @locale is
2166  * %NULL then the current locale is assumed.
2167
2168  * If @key cannot be found then %NULL is returned and @error is set
2169  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
2170  * with @key cannot be interpreted or no suitable translations
2171  * can be found then the untranslated values are returned. The
2172  * returned array is %NULL-terminated, so @length may optionally
2173  * be %NULL.
2174  *
2175  * Return value: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
2176  *   or %NULL if the key isn't found. The string array should be freed
2177  *   with g_strfreev().
2178  *
2179  * Since: 2.6
2180  **/
2181 gchar **
2182 g_key_file_get_locale_string_list (GKeyFile     *key_file,
2183                                    const gchar  *group_name,
2184                                    const gchar  *key,
2185                                    const gchar  *locale,
2186                                    gsize        *length,
2187                                    GError      **error)
2188 {
2189   GError *key_file_error;
2190   gchar **values, *value;
2191   char list_separator[2];
2192   gsize len;
2193
2194   g_return_val_if_fail (key_file != NULL, NULL);
2195   g_return_val_if_fail (group_name != NULL, NULL);
2196   g_return_val_if_fail (key != NULL, NULL);
2197
2198   key_file_error = NULL;
2199
2200   value = g_key_file_get_locale_string (key_file, group_name,
2201                                         key, locale,
2202                                         &key_file_error);
2203
2204   if (key_file_error)
2205     g_propagate_error (error, key_file_error);
2206
2207   if (!value)
2208     {
2209       if (length)
2210         *length = 0;
2211       return NULL;
2212     }
2213
2214   len = strlen (value);
2215   if (value[len - 1] == key_file->list_separator)
2216     value[len - 1] = '\0';
2217
2218   list_separator[0] = key_file->list_separator;
2219   list_separator[1] = '\0';
2220   values = g_strsplit (value, list_separator, 0);
2221
2222   g_free (value);
2223
2224   if (length)
2225     *length = g_strv_length (values);
2226
2227   return values;
2228 }
2229
2230 /**
2231  * g_key_file_set_locale_string_list:
2232  * @key_file: a #GKeyFile
2233  * @group_name: a group name
2234  * @key: a key
2235  * @locale: a locale identifier
2236  * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values
2237  * @length: the length of @list
2238  *
2239  * Associates a list of string values for @key and @locale under
2240  * @group_name.  If the translation for @key cannot be found then
2241  * it is created.
2242  *
2243  * Since: 2.6
2244  **/
2245 void
2246 g_key_file_set_locale_string_list (GKeyFile            *key_file,
2247                                    const gchar         *group_name,
2248                                    const gchar         *key,
2249                                    const gchar         *locale,
2250                                    const gchar * const  list[],
2251                                    gsize                length)
2252 {
2253   GString *value_list;
2254   gchar *full_key;
2255   gsize i;
2256
2257   g_return_if_fail (key_file != NULL);
2258   g_return_if_fail (key != NULL);
2259   g_return_if_fail (locale != NULL);
2260   g_return_if_fail (length != 0);
2261
2262   value_list = g_string_sized_new (length * 128);
2263   for (i = 0; i < length && list[i] != NULL; i++)
2264     {
2265       gchar *value;
2266
2267       value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
2268       g_string_append (value_list, value);
2269       g_string_append_c (value_list, key_file->list_separator);
2270
2271       g_free (value);
2272     }
2273
2274   full_key = g_strdup_printf ("%s[%s]", key, locale);
2275   g_key_file_set_value (key_file, group_name, full_key, value_list->str);
2276   g_free (full_key);
2277   g_string_free (value_list, TRUE);
2278 }
2279
2280 /**
2281  * g_key_file_get_boolean:
2282  * @key_file: a #GKeyFile
2283  * @group_name: a group name
2284  * @key: a key
2285  * @error: return location for a #GError
2286  *
2287  * Returns the value associated with @key under @group_name as a
2288  * boolean.
2289  *
2290  * If @key cannot be found then %FALSE is returned and @error is set
2291  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
2292  * associated with @key cannot be interpreted as a boolean then %FALSE
2293  * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2294  *
2295  * Return value: the value associated with the key as a boolean,
2296  *    or %FALSE if the key was not found or could not be parsed.
2297  *
2298  * Since: 2.6
2299  **/
2300 gboolean
2301 g_key_file_get_boolean (GKeyFile     *key_file,
2302                         const gchar  *group_name,
2303                         const gchar  *key,
2304                         GError      **error)
2305 {
2306   GError *key_file_error = NULL;
2307   gchar *value;
2308   gboolean bool_value;
2309
2310   g_return_val_if_fail (key_file != NULL, FALSE);
2311   g_return_val_if_fail (group_name != NULL, FALSE);
2312   g_return_val_if_fail (key != NULL, FALSE);
2313
2314   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2315
2316   if (!value)
2317     {
2318       g_propagate_error (error, key_file_error);
2319       return FALSE;
2320     }
2321
2322   bool_value = g_key_file_parse_value_as_boolean (key_file, value,
2323                                                   &key_file_error);
2324   g_free (value);
2325
2326   if (key_file_error)
2327     {
2328       if (g_error_matches (key_file_error,
2329                            G_KEY_FILE_ERROR,
2330                            G_KEY_FILE_ERROR_INVALID_VALUE))
2331         {
2332           g_set_error (error, G_KEY_FILE_ERROR,
2333                        G_KEY_FILE_ERROR_INVALID_VALUE,
2334                        _("Key file contains key '%s' "
2335                          "which has a value that cannot be interpreted."),
2336                        key);
2337           g_error_free (key_file_error);
2338         }
2339       else
2340         g_propagate_error (error, key_file_error);
2341     }
2342
2343   return bool_value;
2344 }
2345
2346 /**
2347  * g_key_file_set_boolean:
2348  * @key_file: a #GKeyFile
2349  * @group_name: a group name
2350  * @key: a key
2351  * @value: %TRUE or %FALSE
2352  *
2353  * Associates a new boolean value with @key under @group_name.
2354  * If @key cannot be found then it is created.
2355  *
2356  * Since: 2.6
2357  **/
2358 void
2359 g_key_file_set_boolean (GKeyFile    *key_file,
2360                         const gchar *group_name,
2361                         const gchar *key,
2362                         gboolean     value)
2363 {
2364   gchar *result;
2365
2366   g_return_if_fail (key_file != NULL);
2367
2368   result = g_key_file_parse_boolean_as_value (key_file, value);
2369   g_key_file_set_value (key_file, group_name, key, result);
2370   g_free (result);
2371 }
2372
2373 /**
2374  * g_key_file_get_boolean_list:
2375  * @key_file: a #GKeyFile
2376  * @group_name: a group name
2377  * @key: a key
2378  * @length: (out): the number of booleans returned
2379  * @error: return location for a #GError
2380  *
2381  * Returns the values associated with @key under @group_name as
2382  * booleans.
2383  *
2384  * If @key cannot be found then %NULL is returned and @error is set to
2385  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2386  * with @key cannot be interpreted as booleans then %NULL is returned
2387  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2388  *
2389  * Return value: (array length=length) (element-type gboolean) (transfer container):
2390  *    the values associated with the key as a list of booleans, or %NULL if the
2391  *    key was not found or could not be parsed. The returned list of booleans
2392  *    should be freed with g_free() when no longer needed.
2393  *
2394  * Since: 2.6
2395  **/
2396 gboolean *
2397 g_key_file_get_boolean_list (GKeyFile     *key_file,
2398                              const gchar  *group_name,
2399                              const gchar  *key,
2400                              gsize        *length,
2401                              GError      **error)
2402 {
2403   GError *key_file_error;
2404   gchar **values;
2405   gboolean *bool_values;
2406   gsize i, num_bools;
2407
2408   g_return_val_if_fail (key_file != NULL, NULL);
2409   g_return_val_if_fail (group_name != NULL, NULL);
2410   g_return_val_if_fail (key != NULL, NULL);
2411
2412   if (length)
2413     *length = 0;
2414
2415   key_file_error = NULL;
2416
2417   values = g_key_file_get_string_list (key_file, group_name, key,
2418                                        &num_bools, &key_file_error);
2419
2420   if (key_file_error)
2421     g_propagate_error (error, key_file_error);
2422
2423   if (!values)
2424     return NULL;
2425
2426   bool_values = g_new (gboolean, num_bools);
2427
2428   for (i = 0; i < num_bools; i++)
2429     {
2430       bool_values[i] = g_key_file_parse_value_as_boolean (key_file,
2431                                                           values[i],
2432                                                           &key_file_error);
2433
2434       if (key_file_error)
2435         {
2436           g_propagate_error (error, key_file_error);
2437           g_strfreev (values);
2438           g_free (bool_values);
2439
2440           return NULL;
2441         }
2442     }
2443   g_strfreev (values);
2444
2445   if (length)
2446     *length = num_bools;
2447
2448   return bool_values;
2449 }
2450
2451 /**
2452  * g_key_file_set_boolean_list:
2453  * @key_file: a #GKeyFile
2454  * @group_name: a group name
2455  * @key: a key
2456  * @list: (array length=length): an array of boolean values
2457  * @length: length of @list
2458  *
2459  * Associates a list of boolean values with @key under @group_name.
2460  * If @key cannot be found then it is created.
2461  * If @group_name is %NULL, the start_group is used.
2462  *
2463  * Since: 2.6
2464  **/
2465 void
2466 g_key_file_set_boolean_list (GKeyFile    *key_file,
2467                              const gchar *group_name,
2468                              const gchar *key,
2469                              gboolean     list[],
2470                              gsize        length)
2471 {
2472   GString *value_list;
2473   gsize i;
2474
2475   g_return_if_fail (key_file != NULL);
2476   g_return_if_fail (list != NULL);
2477
2478   value_list = g_string_sized_new (length * 8);
2479   for (i = 0; i < length; i++)
2480     {
2481       gchar *value;
2482
2483       value = g_key_file_parse_boolean_as_value (key_file, list[i]);
2484
2485       g_string_append (value_list, value);
2486       g_string_append_c (value_list, key_file->list_separator);
2487
2488       g_free (value);
2489     }
2490
2491   g_key_file_set_value (key_file, group_name, key, value_list->str);
2492   g_string_free (value_list, TRUE);
2493 }
2494
2495 /**
2496  * g_key_file_get_integer:
2497  * @key_file: a #GKeyFile
2498  * @group_name: a group name
2499  * @key: a key
2500  * @error: return location for a #GError
2501  *
2502  * Returns the value associated with @key under @group_name as an
2503  * integer.
2504  *
2505  * If @key cannot be found then 0 is returned and @error is set to
2506  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
2507  * with @key cannot be interpreted as an integer then 0 is returned
2508  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2509  *
2510  * Return value: the value associated with the key as an integer, or
2511  *     0 if the key was not found or could not be parsed.
2512  *
2513  * Since: 2.6
2514  **/
2515 gint
2516 g_key_file_get_integer (GKeyFile     *key_file,
2517                         const gchar  *group_name,
2518                         const gchar  *key,
2519                         GError      **error)
2520 {
2521   GError *key_file_error;
2522   gchar *value;
2523   gint int_value;
2524
2525   g_return_val_if_fail (key_file != NULL, -1);
2526   g_return_val_if_fail (group_name != NULL, -1);
2527   g_return_val_if_fail (key != NULL, -1);
2528
2529   key_file_error = NULL;
2530
2531   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2532
2533   if (key_file_error)
2534     {
2535       g_propagate_error (error, key_file_error);
2536       return 0;
2537     }
2538
2539   int_value = g_key_file_parse_value_as_integer (key_file, value,
2540                                                  &key_file_error);
2541   g_free (value);
2542
2543   if (key_file_error)
2544     {
2545       if (g_error_matches (key_file_error,
2546                            G_KEY_FILE_ERROR,
2547                            G_KEY_FILE_ERROR_INVALID_VALUE))
2548         {
2549           g_set_error (error, G_KEY_FILE_ERROR,
2550                        G_KEY_FILE_ERROR_INVALID_VALUE,
2551                        _("Key file contains key '%s' in group '%s' "
2552                          "which has a value that cannot be interpreted."),
2553                          key, group_name);
2554           g_error_free (key_file_error);
2555         }
2556       else
2557         g_propagate_error (error, key_file_error);
2558     }
2559
2560   return int_value;
2561 }
2562
2563 /**
2564  * g_key_file_set_integer:
2565  * @key_file: a #GKeyFile
2566  * @group_name: a group name
2567  * @key: a key
2568  * @value: an integer value
2569  *
2570  * Associates a new integer value with @key under @group_name.
2571  * If @key cannot be found then it is created.
2572  *
2573  * Since: 2.6
2574  **/
2575 void
2576 g_key_file_set_integer (GKeyFile    *key_file,
2577                         const gchar *group_name,
2578                         const gchar *key,
2579                         gint         value)
2580 {
2581   gchar *result;
2582
2583   g_return_if_fail (key_file != NULL);
2584
2585   result = g_key_file_parse_integer_as_value (key_file, value);
2586   g_key_file_set_value (key_file, group_name, key, result);
2587   g_free (result);
2588 }
2589
2590 /**
2591  * g_key_file_get_int64:
2592  * @key_file: a non-%NULL #GKeyFile
2593  * @group_name: a non-%NULL group name
2594  * @key: a non-%NULL key
2595  * @error: return location for a #GError
2596  *
2597  * Returns the value associated with @key under @group_name as a signed
2598  * 64-bit integer. This is similar to g_key_file_get_integer() but can return
2599  * 64-bit results without truncation.
2600  *
2601  * Returns: the value associated with the key as a signed 64-bit integer, or
2602  * 0 if the key was not found or could not be parsed.
2603  *
2604  * Since: 2.26
2605  */
2606 gint64
2607 g_key_file_get_int64 (GKeyFile     *key_file,
2608                       const gchar  *group_name,
2609                       const gchar  *key,
2610                       GError      **error)
2611 {
2612   gchar *s, *end;
2613   gint64 v;
2614
2615   g_return_val_if_fail (key_file != NULL, -1);
2616   g_return_val_if_fail (group_name != NULL, -1);
2617   g_return_val_if_fail (key != NULL, -1);
2618
2619   s = g_key_file_get_value (key_file, group_name, key, error);
2620
2621   if (s == NULL)
2622     return 0;
2623
2624   v = g_ascii_strtoll (s, &end, 10);
2625
2626   if (*s == '\0' || *end != '\0')
2627     {
2628       g_set_error (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_INVALID_VALUE,
2629                    _("Key '%s' in group '%s' has value '%s' "
2630                      "where %s was expected"),
2631                    key, group_name, s, "int64");
2632       return 0;
2633     }
2634
2635   g_free (s);
2636   return v;
2637 }
2638
2639 /**
2640  * g_key_file_set_int64:
2641  * @key_file: a #GKeyFile
2642  * @group_name: a group name
2643  * @key: a key
2644  * @value: an integer value
2645  *
2646  * Associates a new integer value with @key under @group_name.
2647  * If @key cannot be found then it is created.
2648  *
2649  * Since: 2.26
2650  **/
2651 void
2652 g_key_file_set_int64 (GKeyFile    *key_file,
2653                       const gchar *group_name,
2654                       const gchar *key,
2655                       gint64       value)
2656 {
2657   gchar *result;
2658
2659   g_return_if_fail (key_file != NULL);
2660
2661   result = g_strdup_printf ("%" G_GINT64_FORMAT, value);
2662   g_key_file_set_value (key_file, group_name, key, result);
2663   g_free (result);
2664 }
2665
2666 /**
2667  * g_key_file_get_uint64:
2668  * @key_file: a non-%NULL #GKeyFile
2669  * @group_name: a non-%NULL group name
2670  * @key: a non-%NULL key
2671  * @error: return location for a #GError
2672  *
2673  * Returns the value associated with @key under @group_name as an unsigned
2674  * 64-bit integer. This is similar to g_key_file_get_integer() but can return
2675  * large positive results without truncation.
2676  *
2677  * Returns: the value associated with the key as an unsigned 64-bit integer,
2678  * or 0 if the key was not found or could not be parsed.
2679  *
2680  * Since: 2.26
2681  */
2682 guint64
2683 g_key_file_get_uint64 (GKeyFile     *key_file,
2684                        const gchar  *group_name,
2685                        const gchar  *key,
2686                        GError      **error)
2687 {
2688   gchar *s, *end;
2689   guint64 v;
2690
2691   g_return_val_if_fail (key_file != NULL, -1);
2692   g_return_val_if_fail (group_name != NULL, -1);
2693   g_return_val_if_fail (key != NULL, -1);
2694
2695   s = g_key_file_get_value (key_file, group_name, key, error);
2696
2697   if (s == NULL)
2698     return 0;
2699
2700   v = g_ascii_strtoull (s, &end, 10);
2701
2702   if (*s == '\0' || *end != '\0')
2703     {
2704       g_set_error (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_INVALID_VALUE,
2705                    _("Key '%s' in group '%s' has value '%s' "
2706                      "where %s was expected"),
2707                    key, group_name, s, "uint64");
2708       return 0;
2709     }
2710
2711   g_free (s);
2712   return v;
2713 }
2714
2715 /**
2716  * g_key_file_set_uint64:
2717  * @key_file: a #GKeyFile
2718  * @group_name: a group name
2719  * @key: a key
2720  * @value: an integer value
2721  *
2722  * Associates a new integer value with @key under @group_name.
2723  * If @key cannot be found then it is created.
2724  *
2725  * Since: 2.26
2726  **/
2727 void
2728 g_key_file_set_uint64 (GKeyFile    *key_file,
2729                        const gchar *group_name,
2730                        const gchar *key,
2731                        guint64      value)
2732 {
2733   gchar *result;
2734
2735   g_return_if_fail (key_file != NULL);
2736
2737   result = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
2738   g_key_file_set_value (key_file, group_name, key, result);
2739   g_free (result);
2740 }
2741
2742 /**
2743  * g_key_file_get_integer_list:
2744  * @key_file: a #GKeyFile
2745  * @group_name: a group name
2746  * @key: a key
2747  * @length: (out): the number of integers returned
2748  * @error: return location for a #GError
2749  *
2750  * Returns the values associated with @key under @group_name as
2751  * integers.
2752  *
2753  * If @key cannot be found then %NULL is returned and @error is set to
2754  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2755  * with @key cannot be interpreted as integers then %NULL is returned
2756  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2757  *
2758  * Return value: (array length=length) (element-type gint) (transfer container):
2759  *     the values associated with the key as a list of integers, or %NULL if
2760  *     the key was not found or could not be parsed. The returned list of
2761  *     integers should be freed with g_free() when no longer needed.
2762  *
2763  * Since: 2.6
2764  **/
2765 gint *
2766 g_key_file_get_integer_list (GKeyFile     *key_file,
2767                              const gchar  *group_name,
2768                              const gchar  *key,
2769                              gsize        *length,
2770                              GError      **error)
2771 {
2772   GError *key_file_error = NULL;
2773   gchar **values;
2774   gint *int_values;
2775   gsize i, num_ints;
2776
2777   g_return_val_if_fail (key_file != NULL, NULL);
2778   g_return_val_if_fail (group_name != NULL, NULL);
2779   g_return_val_if_fail (key != NULL, NULL);
2780
2781   if (length)
2782     *length = 0;
2783
2784   values = g_key_file_get_string_list (key_file, group_name, key,
2785                                        &num_ints, &key_file_error);
2786
2787   if (key_file_error)
2788     g_propagate_error (error, key_file_error);
2789
2790   if (!values)
2791     return NULL;
2792
2793   int_values = g_new (gint, num_ints);
2794
2795   for (i = 0; i < num_ints; i++)
2796     {
2797       int_values[i] = g_key_file_parse_value_as_integer (key_file,
2798                                                          values[i],
2799                                                          &key_file_error);
2800
2801       if (key_file_error)
2802         {
2803           g_propagate_error (error, key_file_error);
2804           g_strfreev (values);
2805           g_free (int_values);
2806
2807           return NULL;
2808         }
2809     }
2810   g_strfreev (values);
2811
2812   if (length)
2813     *length = num_ints;
2814
2815   return int_values;
2816 }
2817
2818 /**
2819  * g_key_file_set_integer_list:
2820  * @key_file: a #GKeyFile
2821  * @group_name: a group name
2822  * @key: a key
2823  * @list: (array length=length): an array of integer values
2824  * @length: number of integer values in @list
2825  *
2826  * Associates a list of integer values with @key under @group_name.
2827  * If @key cannot be found then it is created.
2828  *
2829  * Since: 2.6
2830  **/
2831 void
2832 g_key_file_set_integer_list (GKeyFile    *key_file,
2833                              const gchar *group_name,
2834                              const gchar *key,
2835                              gint         list[],
2836                              gsize        length)
2837 {
2838   GString *values;
2839   gsize i;
2840
2841   g_return_if_fail (key_file != NULL);
2842   g_return_if_fail (list != NULL);
2843
2844   values = g_string_sized_new (length * 16);
2845   for (i = 0; i < length; i++)
2846     {
2847       gchar *value;
2848
2849       value = g_key_file_parse_integer_as_value (key_file, list[i]);
2850
2851       g_string_append (values, value);
2852       g_string_append_c (values, key_file->list_separator);
2853
2854       g_free (value);
2855     }
2856
2857   g_key_file_set_value (key_file, group_name, key, values->str);
2858   g_string_free (values, TRUE);
2859 }
2860
2861 /**
2862  * g_key_file_get_double:
2863  * @key_file: a #GKeyFile
2864  * @group_name: a group name
2865  * @key: a key
2866  * @error: return location for a #GError
2867  *
2868  * Returns the value associated with @key under @group_name as a
2869  * double. If @group_name is %NULL, the start_group is used.
2870  *
2871  * If @key cannot be found then 0.0 is returned and @error is set to
2872  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
2873  * with @key cannot be interpreted as a double then 0.0 is returned
2874  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2875  *
2876  * Return value: the value associated with the key as a double, or
2877  *     0.0 if the key was not found or could not be parsed.
2878  *
2879  * Since: 2.12
2880  **/
2881 gdouble
2882 g_key_file_get_double  (GKeyFile     *key_file,
2883                         const gchar  *group_name,
2884                         const gchar  *key,
2885                         GError      **error)
2886 {
2887   GError *key_file_error;
2888   gchar *value;
2889   gdouble double_value;
2890
2891   g_return_val_if_fail (key_file != NULL, -1);
2892   g_return_val_if_fail (group_name != NULL, -1);
2893   g_return_val_if_fail (key != NULL, -1);
2894
2895   key_file_error = NULL;
2896
2897   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2898
2899   if (key_file_error)
2900     {
2901       g_propagate_error (error, key_file_error);
2902       return 0;
2903     }
2904
2905   double_value = g_key_file_parse_value_as_double (key_file, value,
2906                                                   &key_file_error);
2907   g_free (value);
2908
2909   if (key_file_error)
2910     {
2911       if (g_error_matches (key_file_error,
2912                            G_KEY_FILE_ERROR,
2913                            G_KEY_FILE_ERROR_INVALID_VALUE))
2914         {
2915           g_set_error (error, G_KEY_FILE_ERROR,
2916                        G_KEY_FILE_ERROR_INVALID_VALUE,
2917                        _("Key file contains key '%s' in group '%s' "
2918                          "which has a value that cannot be interpreted."),
2919                        key, group_name);
2920           g_error_free (key_file_error);
2921         }
2922       else
2923         g_propagate_error (error, key_file_error);
2924     }
2925
2926   return double_value;
2927 }
2928
2929 /**
2930  * g_key_file_set_double:
2931  * @key_file: a #GKeyFile
2932  * @group_name: a group name
2933  * @key: a key
2934  * @value: an double value
2935  *
2936  * Associates a new double value with @key under @group_name.
2937  * If @key cannot be found then it is created.
2938  *
2939  * Since: 2.12
2940  **/
2941 void
2942 g_key_file_set_double  (GKeyFile    *key_file,
2943                         const gchar *group_name,
2944                         const gchar *key,
2945                         gdouble      value)
2946 {
2947   gchar result[G_ASCII_DTOSTR_BUF_SIZE];
2948
2949   g_return_if_fail (key_file != NULL);
2950
2951   g_ascii_dtostr (result, sizeof (result), value);
2952   g_key_file_set_value (key_file, group_name, key, result);
2953 }
2954
2955 /**
2956  * g_key_file_get_double_list:
2957  * @key_file: a #GKeyFile
2958  * @group_name: a group name
2959  * @key: a key
2960  * @length: (out): the number of doubles returned
2961  * @error: return location for a #GError
2962  *
2963  * Returns the values associated with @key under @group_name as
2964  * doubles.
2965  *
2966  * If @key cannot be found then %NULL is returned and @error is set to
2967  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2968  * with @key cannot be interpreted as doubles then %NULL is returned
2969  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2970  *
2971  * Return value: (array length=length) (element-type gdouble) (transfer container):
2972  *     the values associated with the key as a list of doubles, or %NULL if the
2973  *     key was not found or could not be parsed. The returned list of doubles
2974  *     should be freed with g_free() when no longer needed.
2975  *
2976  * Since: 2.12
2977  **/
2978 gdouble *
2979 g_key_file_get_double_list  (GKeyFile     *key_file,
2980                              const gchar  *group_name,
2981                              const gchar  *key,
2982                              gsize        *length,
2983                              GError      **error)
2984 {
2985   GError *key_file_error = NULL;
2986   gchar **values;
2987   gdouble *double_values;
2988   gsize i, num_doubles;
2989
2990   g_return_val_if_fail (key_file != NULL, NULL);
2991   g_return_val_if_fail (group_name != NULL, NULL);
2992   g_return_val_if_fail (key != NULL, NULL);
2993
2994   if (length)
2995     *length = 0;
2996
2997   values = g_key_file_get_string_list (key_file, group_name, key,
2998                                        &num_doubles, &key_file_error);
2999
3000   if (key_file_error)
3001     g_propagate_error (error, key_file_error);
3002
3003   if (!values)
3004     return NULL;
3005
3006   double_values = g_new (gdouble, num_doubles);
3007
3008   for (i = 0; i < num_doubles; i++)
3009     {
3010       double_values[i] = g_key_file_parse_value_as_double (key_file,
3011                                                            values[i],
3012                                                            &key_file_error);
3013
3014       if (key_file_error)
3015         {
3016           g_propagate_error (error, key_file_error);
3017           g_strfreev (values);
3018           g_free (double_values);
3019
3020           return NULL;
3021         }
3022     }
3023   g_strfreev (values);
3024
3025   if (length)
3026     *length = num_doubles;
3027
3028   return double_values;
3029 }
3030
3031 /**
3032  * g_key_file_set_double_list:
3033  * @key_file: a #GKeyFile
3034  * @group_name: a group name
3035  * @key: a key
3036  * @list: (array length=length): an array of double values
3037  * @length: number of double values in @list
3038  *
3039  * Associates a list of double values with @key under
3040  * @group_name.  If @key cannot be found then it is created.
3041  *
3042  * Since: 2.12
3043  **/
3044 void
3045 g_key_file_set_double_list (GKeyFile    *key_file,
3046                             const gchar *group_name,
3047                             const gchar *key,
3048                             gdouble      list[],
3049                             gsize        length)
3050 {
3051   GString *values;
3052   gsize i;
3053
3054   g_return_if_fail (key_file != NULL);
3055   g_return_if_fail (list != NULL);
3056
3057   values = g_string_sized_new (length * 16);
3058   for (i = 0; i < length; i++)
3059     {
3060       gchar result[G_ASCII_DTOSTR_BUF_SIZE];
3061
3062       g_ascii_dtostr( result, sizeof (result), list[i] );
3063
3064       g_string_append (values, result);
3065       g_string_append_c (values, key_file->list_separator);
3066     }
3067
3068   g_key_file_set_value (key_file, group_name, key, values->str);
3069   g_string_free (values, TRUE);
3070 }
3071
3072 static gboolean
3073 g_key_file_set_key_comment (GKeyFile     *key_file,
3074                             const gchar  *group_name,
3075                             const gchar  *key,
3076                             const gchar  *comment,
3077                             GError      **error)
3078 {
3079   GKeyFileGroup *group;
3080   GKeyFileKeyValuePair *pair;
3081   GList *key_node, *comment_node, *tmp;
3082
3083   group = g_key_file_lookup_group (key_file, group_name);
3084   if (!group)
3085     {
3086       g_set_error (error, G_KEY_FILE_ERROR,
3087                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3088                    _("Key file does not have group '%s'"),
3089                    group_name ? group_name : "(null)");
3090
3091       return FALSE;
3092     }
3093
3094   /* First find the key the comments are supposed to be
3095    * associated with
3096    */
3097   key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
3098
3099   if (key_node == NULL)
3100     {
3101       g_set_error (error, G_KEY_FILE_ERROR,
3102                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3103                    _("Key file does not have key '%s' in group '%s'"),
3104                    key, group->name);
3105       return FALSE;
3106     }
3107
3108   /* Then find all the comments already associated with the
3109    * key and free them
3110    */
3111   tmp = key_node->next;
3112   while (tmp != NULL)
3113     {
3114       pair = (GKeyFileKeyValuePair *) tmp->data;
3115
3116       if (pair->key != NULL)
3117         break;
3118
3119       comment_node = tmp;
3120       tmp = tmp->next;
3121       g_key_file_remove_key_value_pair_node (key_file, group,
3122                                              comment_node);
3123     }
3124
3125   if (comment == NULL)
3126     return TRUE;
3127
3128   /* Now we can add our new comment
3129    */
3130   pair = g_slice_new (GKeyFileKeyValuePair);
3131   pair->key = NULL;
3132   pair->value = g_key_file_parse_comment_as_value (key_file, comment);
3133
3134   key_node = g_list_insert (key_node, pair, 1);
3135
3136   return TRUE;
3137 }
3138
3139 static gboolean
3140 g_key_file_set_group_comment (GKeyFile     *key_file,
3141                               const gchar  *group_name,
3142                               const gchar  *comment,
3143                               GError      **error)
3144 {
3145   GKeyFileGroup *group;
3146
3147   g_return_val_if_fail (g_key_file_is_group_name (group_name), FALSE);
3148
3149   group = g_key_file_lookup_group (key_file, group_name);
3150   if (!group)
3151     {
3152       g_set_error (error, G_KEY_FILE_ERROR,
3153                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3154                    _("Key file does not have group '%s'"),
3155                    group_name ? group_name : "(null)");
3156
3157       return FALSE;
3158     }
3159
3160   /* First remove any existing comment
3161    */
3162   if (group->comment)
3163     {
3164       g_key_file_key_value_pair_free (group->comment);
3165       group->comment = NULL;
3166     }
3167
3168   if (comment == NULL)
3169     return TRUE;
3170
3171   /* Now we can add our new comment
3172    */
3173   group->comment = g_slice_new (GKeyFileKeyValuePair);
3174   group->comment->key = NULL;
3175   group->comment->value = g_key_file_parse_comment_as_value (key_file, comment);
3176
3177   return TRUE;
3178 }
3179
3180 static gboolean
3181 g_key_file_set_top_comment (GKeyFile     *key_file,
3182                             const gchar  *comment,
3183                             GError      **error)
3184 {
3185   GList *group_node;
3186   GKeyFileGroup *group;
3187   GKeyFileKeyValuePair *pair;
3188
3189   /* The last group in the list should be the top (comments only)
3190    * group in the file
3191    */
3192   g_warn_if_fail (key_file->groups != NULL);
3193   group_node = g_list_last (key_file->groups);
3194   group = (GKeyFileGroup *) group_node->data;
3195   g_warn_if_fail (group->name == NULL);
3196
3197   /* Note all keys must be comments at the top of
3198    * the file, so we can just free it all.
3199    */
3200   g_list_free_full (group->key_value_pairs, (GDestroyNotify) g_key_file_key_value_pair_free);
3201   group->key_value_pairs = NULL;
3202
3203   if (comment == NULL)
3204      return TRUE;
3205
3206   pair = g_slice_new (GKeyFileKeyValuePair);
3207   pair->key = NULL;
3208   pair->value = g_key_file_parse_comment_as_value (key_file, comment);
3209
3210   group->key_value_pairs =
3211     g_list_prepend (group->key_value_pairs, pair);
3212
3213   return TRUE;
3214 }
3215
3216 /**
3217  * g_key_file_set_comment:
3218  * @key_file: a #GKeyFile
3219  * @group_name: (allow-none): a group name, or %NULL
3220  * @key: (allow-none): a key
3221  * @comment: a comment
3222  * @error: return location for a #GError
3223  *
3224  * Places a comment above @key from @group_name.
3225  * If @key is %NULL then @comment will be written above @group_name.
3226  * If both @key and @group_name  are %NULL, then @comment will be
3227  * written above the first group in the file.
3228  *
3229  * Returns: %TRUE if the comment was written, %FALSE otherwise
3230  *
3231  * Since: 2.6
3232  **/
3233 gboolean
3234 g_key_file_set_comment (GKeyFile     *key_file,
3235                         const gchar  *group_name,
3236                         const gchar  *key,
3237                         const gchar  *comment,
3238                         GError      **error)
3239 {
3240   g_return_val_if_fail (key_file != NULL, FALSE);
3241
3242   if (group_name != NULL && key != NULL)
3243     {
3244       if (!g_key_file_set_key_comment (key_file, group_name, key, comment, error))
3245         return FALSE;
3246     }
3247   else if (group_name != NULL)
3248     {
3249       if (!g_key_file_set_group_comment (key_file, group_name, comment, error))
3250         return FALSE;
3251     }
3252   else
3253     {
3254       if (!g_key_file_set_top_comment (key_file, comment, error))
3255         return FALSE;
3256     }
3257
3258   if (comment != NULL)
3259     key_file->approximate_size += strlen (comment);
3260
3261   return TRUE;
3262 }
3263
3264 static gchar *
3265 g_key_file_get_key_comment (GKeyFile     *key_file,
3266                             const gchar  *group_name,
3267                             const gchar  *key,
3268                             GError      **error)
3269 {
3270   GKeyFileGroup *group;
3271   GKeyFileKeyValuePair *pair;
3272   GList *key_node, *tmp;
3273   GString *string;
3274   gchar *comment;
3275
3276   g_return_val_if_fail (g_key_file_is_group_name (group_name), NULL);
3277
3278   group = g_key_file_lookup_group (key_file, group_name);
3279   if (!group)
3280     {
3281       g_set_error (error, G_KEY_FILE_ERROR,
3282                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3283                    _("Key file does not have group '%s'"),
3284                    group_name ? group_name : "(null)");
3285
3286       return NULL;
3287     }
3288
3289   /* First find the key the comments are supposed to be
3290    * associated with
3291    */
3292   key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
3293
3294   if (key_node == NULL)
3295     {
3296       g_set_error (error, G_KEY_FILE_ERROR,
3297                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3298                    _("Key file does not have key '%s' in group '%s'"),
3299                    key, group->name);
3300       return NULL;
3301     }
3302
3303   string = NULL;
3304
3305   /* Then find all the comments already associated with the
3306    * key and concatentate them.
3307    */
3308   tmp = key_node->next;
3309   if (!key_node->next)
3310     return NULL;
3311
3312   pair = (GKeyFileKeyValuePair *) tmp->data;
3313   if (pair->key != NULL)
3314     return NULL;
3315
3316   while (tmp->next)
3317     {
3318       pair = (GKeyFileKeyValuePair *) tmp->next->data;
3319
3320       if (pair->key != NULL)
3321         break;
3322
3323       tmp = tmp->next;
3324     }
3325
3326   while (tmp != key_node)
3327     {
3328       pair = (GKeyFileKeyValuePair *) tmp->data;
3329
3330       if (string == NULL)
3331         string = g_string_sized_new (512);
3332
3333       comment = g_key_file_parse_value_as_comment (key_file, pair->value);
3334       g_string_append (string, comment);
3335       g_free (comment);
3336
3337       tmp = tmp->prev;
3338     }
3339
3340   if (string != NULL)
3341     {
3342       comment = string->str;
3343       g_string_free (string, FALSE);
3344     }
3345   else
3346     comment = NULL;
3347
3348   return comment;
3349 }
3350
3351 static gchar *
3352 get_group_comment (GKeyFile       *key_file,
3353                    GKeyFileGroup  *group,
3354                    GError        **error)
3355 {
3356   GString *string;
3357   GList *tmp;
3358   gchar *comment;
3359
3360   string = NULL;
3361
3362   tmp = group->key_value_pairs;
3363   while (tmp)
3364     {
3365       GKeyFileKeyValuePair *pair;
3366
3367       pair = (GKeyFileKeyValuePair *) tmp->data;
3368
3369       if (pair->key != NULL)
3370         {
3371           tmp = tmp->prev;
3372           break;
3373         }
3374
3375       if (tmp->next == NULL)
3376         break;
3377
3378       tmp = tmp->next;
3379     }
3380
3381   while (tmp != NULL)
3382     {
3383       GKeyFileKeyValuePair *pair;
3384
3385       pair = (GKeyFileKeyValuePair *) tmp->data;
3386
3387       if (string == NULL)
3388         string = g_string_sized_new (512);
3389
3390       comment = g_key_file_parse_value_as_comment (key_file, pair->value);
3391       g_string_append (string, comment);
3392       g_free (comment);
3393
3394       tmp = tmp->prev;
3395     }
3396
3397   if (string != NULL)
3398     return g_string_free (string, FALSE);
3399
3400   return NULL;
3401 }
3402
3403 static gchar *
3404 g_key_file_get_group_comment (GKeyFile     *key_file,
3405                               const gchar  *group_name,
3406                               GError      **error)
3407 {
3408   GList *group_node;
3409   GKeyFileGroup *group;
3410
3411   group = g_key_file_lookup_group (key_file, group_name);
3412   if (!group)
3413     {
3414       g_set_error (error, G_KEY_FILE_ERROR,
3415                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3416                    _("Key file does not have group '%s'"),
3417                    group_name ? group_name : "(null)");
3418
3419       return NULL;
3420     }
3421
3422   if (group->comment)
3423     return g_strdup (group->comment->value);
3424
3425   group_node = g_key_file_lookup_group_node (key_file, group_name);
3426   group_node = group_node->next;
3427   group = (GKeyFileGroup *)group_node->data;
3428   return get_group_comment (key_file, group, error);
3429 }
3430
3431 static gchar *
3432 g_key_file_get_top_comment (GKeyFile  *key_file,
3433                             GError   **error)
3434 {
3435   GList *group_node;
3436   GKeyFileGroup *group;
3437
3438   /* The last group in the list should be the top (comments only)
3439    * group in the file
3440    */
3441   g_warn_if_fail (key_file->groups != NULL);
3442   group_node = g_list_last (key_file->groups);
3443   group = (GKeyFileGroup *) group_node->data;
3444   g_warn_if_fail (group->name == NULL);
3445
3446   return get_group_comment (key_file, group, error);
3447 }
3448
3449 /**
3450  * g_key_file_get_comment:
3451  * @key_file: a #GKeyFile
3452  * @group_name: a group name, or %NULL
3453  * @key: a key
3454  * @error: return location for a #GError
3455  *
3456  * Retrieves a comment above @key from @group_name.
3457  * If @key is %NULL then @comment will be read from above
3458  * @group_name. If both @key and @group_name are %NULL, then
3459  * @comment will be read from above the first group in the file.
3460  *
3461  * Returns: a comment that should be freed with g_free()
3462  *
3463  * Since: 2.6
3464  **/
3465 gchar *
3466 g_key_file_get_comment (GKeyFile     *key_file,
3467                         const gchar  *group_name,
3468                         const gchar  *key,
3469                         GError      **error)
3470 {
3471   g_return_val_if_fail (key_file != NULL, NULL);
3472
3473   if (group_name != NULL && key != NULL)
3474     return g_key_file_get_key_comment (key_file, group_name, key, error);
3475   else if (group_name != NULL)
3476     return g_key_file_get_group_comment (key_file, group_name, error);
3477   else
3478     return g_key_file_get_top_comment (key_file, error);
3479 }
3480
3481 /**
3482  * g_key_file_remove_comment:
3483  * @key_file: a #GKeyFile
3484  * @group_name: (allow-none): a group name, or %NULL
3485  * @key: (allow-none): a key
3486  * @error: return location for a #GError
3487  *
3488  * Removes a comment above @key from @group_name.
3489  * If @key is %NULL then @comment will be removed above @group_name.
3490  * If both @key and @group_name are %NULL, then @comment will
3491  * be removed above the first group in the file.
3492  *
3493  * Returns: %TRUE if the comment was removed, %FALSE otherwise
3494  *
3495  * Since: 2.6
3496  **/
3497
3498 gboolean
3499 g_key_file_remove_comment (GKeyFile     *key_file,
3500                            const gchar  *group_name,
3501                            const gchar  *key,
3502                            GError      **error)
3503 {
3504   g_return_val_if_fail (key_file != NULL, FALSE);
3505
3506   if (group_name != NULL && key != NULL)
3507     return g_key_file_set_key_comment (key_file, group_name, key, NULL, error);
3508   else if (group_name != NULL)
3509     return g_key_file_set_group_comment (key_file, group_name, NULL, error);
3510   else
3511     return g_key_file_set_top_comment (key_file, NULL, error);
3512 }
3513
3514 /**
3515  * g_key_file_has_group:
3516  * @key_file: a #GKeyFile
3517  * @group_name: a group name
3518  *
3519  * Looks whether the key file has the group @group_name.
3520  *
3521  * Return value: %TRUE if @group_name is a part of @key_file, %FALSE
3522  * otherwise.
3523  * Since: 2.6
3524  **/
3525 gboolean
3526 g_key_file_has_group (GKeyFile    *key_file,
3527                       const gchar *group_name)
3528 {
3529   g_return_val_if_fail (key_file != NULL, FALSE);
3530   g_return_val_if_fail (group_name != NULL, FALSE);
3531
3532   return g_key_file_lookup_group (key_file, group_name) != NULL;
3533 }
3534
3535 /* This code remains from a historical attempt to add a new public API
3536  * which respects the GError rules.
3537  */
3538 static gboolean
3539 g_key_file_has_key_full (GKeyFile     *key_file,
3540                          const gchar  *group_name,
3541                          const gchar  *key,
3542                          gboolean     *has_key,
3543                          GError      **error)
3544 {
3545   GKeyFileKeyValuePair *pair;
3546   GKeyFileGroup *group;
3547
3548   g_return_val_if_fail (key_file != NULL, FALSE);
3549   g_return_val_if_fail (group_name != NULL, FALSE);
3550   g_return_val_if_fail (key != NULL, FALSE);
3551
3552   group = g_key_file_lookup_group (key_file, group_name);
3553
3554   if (!group)
3555     {
3556       g_set_error (error, G_KEY_FILE_ERROR,
3557                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3558                    _("Key file does not have group '%s'"),
3559                    group_name ? group_name : "(null)");
3560
3561       return FALSE;
3562     }
3563
3564   pair = g_key_file_lookup_key_value_pair (key_file, group, key);
3565
3566   if (has_key)
3567     *has_key = pair != NULL;
3568   return TRUE;
3569 }
3570
3571 /**
3572  * g_key_file_has_key: (skip)
3573  * @key_file: a #GKeyFile
3574  * @group_name: a group name
3575  * @key: a key name
3576  * @error: return location for a #GError
3577  *
3578  * Looks whether the key file has the key @key in the group
3579  * @group_name.
3580  *
3581  * <note>This function does not follow the rules for #GError strictly;
3582  * the return value both carries meaning and signals an error.  To use
3583  * this function, you must pass a #GError pointer in @error, and check
3584  * whether it is not %NULL to see if an error occurred.</note>
3585  *
3586  * Language bindings should use g_key_file_get_value() to test whether
3587  * or not a key exists.
3588  *
3589  * Return value: %TRUE if @key is a part of @group_name, %FALSE
3590  * otherwise.
3591  *
3592  * Since: 2.6
3593  **/
3594 gboolean
3595 g_key_file_has_key (GKeyFile     *key_file,
3596                     const gchar  *group_name,
3597                     const gchar  *key,
3598                     GError      **error)
3599 {
3600   GError *temp_error = NULL;
3601   gboolean has_key;
3602
3603   if (g_key_file_has_key_full (key_file, group_name, key, &has_key, &temp_error))
3604     {
3605       return has_key;
3606     }
3607   else
3608     {
3609       g_propagate_error (error, temp_error);
3610       return FALSE;
3611     }
3612 }
3613
3614 static void
3615 g_key_file_add_group (GKeyFile    *key_file,
3616                       const gchar *group_name)
3617 {
3618   GKeyFileGroup *group;
3619
3620   g_return_if_fail (key_file != NULL);
3621   g_return_if_fail (g_key_file_is_group_name (group_name));
3622
3623   group = g_key_file_lookup_group (key_file, group_name);
3624   if (group != NULL)
3625     {
3626       key_file->current_group = group;
3627       return;
3628     }
3629
3630   group = g_slice_new0 (GKeyFileGroup);
3631   group->name = g_strdup (group_name);
3632   group->lookup_map = g_hash_table_new (g_str_hash, g_str_equal);
3633   key_file->groups = g_list_prepend (key_file->groups, group);
3634   key_file->approximate_size += strlen (group_name) + 3;
3635   key_file->current_group = group;
3636
3637   if (key_file->start_group == NULL)
3638     key_file->start_group = group;
3639
3640   g_hash_table_insert (key_file->group_hash, (gpointer)group->name, group);
3641 }
3642
3643 static void
3644 g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair)
3645 {
3646   if (pair != NULL)
3647     {
3648       g_free (pair->key);
3649       g_free (pair->value);
3650       g_slice_free (GKeyFileKeyValuePair, pair);
3651     }
3652 }
3653
3654 /* Be careful not to call this function on a node with data in the
3655  * lookup map without removing it from the lookup map, first.
3656  *
3657  * Some current cases where this warning is not a concern are
3658  * when:
3659  *   - the node being removed is a comment node
3660  *   - the entire lookup map is getting destroyed soon after
3661  *     anyway.
3662  */
3663 static void
3664 g_key_file_remove_key_value_pair_node (GKeyFile      *key_file,
3665                                        GKeyFileGroup *group,
3666                                        GList         *pair_node)
3667 {
3668
3669   GKeyFileKeyValuePair *pair;
3670
3671   pair = (GKeyFileKeyValuePair *) pair_node->data;
3672
3673   group->key_value_pairs = g_list_remove_link (group->key_value_pairs, pair_node);
3674
3675   if (pair->key != NULL)
3676     key_file->approximate_size -= strlen (pair->key) + 1;
3677
3678   g_warn_if_fail (pair->value != NULL);
3679   key_file->approximate_size -= strlen (pair->value);
3680
3681   g_key_file_key_value_pair_free (pair);
3682
3683   g_list_free_1 (pair_node);
3684 }
3685
3686 static void
3687 g_key_file_remove_group_node (GKeyFile *key_file,
3688                               GList    *group_node)
3689 {
3690   GKeyFileGroup *group;
3691   GList *tmp;
3692
3693   group = (GKeyFileGroup *) group_node->data;
3694
3695   if (group->name)
3696     g_hash_table_remove (key_file->group_hash, group->name);
3697
3698   /* If the current group gets deleted make the current group the last
3699    * added group.
3700    */
3701   if (key_file->current_group == group)
3702     {
3703       /* groups should always contain at least the top comment group,
3704        * unless g_key_file_clear has been called
3705        */
3706       if (key_file->groups)
3707         key_file->current_group = (GKeyFileGroup *) key_file->groups->data;
3708       else
3709         key_file->current_group = NULL;
3710     }
3711
3712   /* If the start group gets deleted make the start group the first
3713    * added group.
3714    */
3715   if (key_file->start_group == group)
3716     {
3717       tmp = g_list_last (key_file->groups);
3718       while (tmp != NULL)
3719         {
3720           if (tmp != group_node &&
3721               ((GKeyFileGroup *) tmp->data)->name != NULL)
3722             break;
3723
3724           tmp = tmp->prev;
3725         }
3726
3727       if (tmp)
3728         key_file->start_group = (GKeyFileGroup *) tmp->data;
3729       else
3730         key_file->start_group = NULL;
3731     }
3732
3733   key_file->groups = g_list_remove_link (key_file->groups, group_node);
3734
3735   if (group->name != NULL)
3736     key_file->approximate_size -= strlen (group->name) + 3;
3737
3738   tmp = group->key_value_pairs;
3739   while (tmp != NULL)
3740     {
3741       GList *pair_node;
3742
3743       pair_node = tmp;
3744       tmp = tmp->next;
3745       g_key_file_remove_key_value_pair_node (key_file, group, pair_node);
3746     }
3747
3748   g_warn_if_fail (group->key_value_pairs == NULL);
3749
3750   if (group->comment)
3751     {
3752       g_key_file_key_value_pair_free (group->comment);
3753       group->comment = NULL;
3754     }
3755
3756   if (group->lookup_map)
3757     {
3758       g_hash_table_destroy (group->lookup_map);
3759       group->lookup_map = NULL;
3760     }
3761
3762   g_free ((gchar *) group->name);
3763   g_slice_free (GKeyFileGroup, group);
3764   g_list_free_1 (group_node);
3765 }
3766
3767 /**
3768  * g_key_file_remove_group:
3769  * @key_file: a #GKeyFile
3770  * @group_name: a group name
3771  * @error: return location for a #GError or %NULL
3772  *
3773  * Removes the specified group, @group_name,
3774  * from the key file.
3775  *
3776  * Returns: %TRUE if the group was removed, %FALSE otherwise
3777  *
3778  * Since: 2.6
3779  **/
3780 gboolean
3781 g_key_file_remove_group (GKeyFile     *key_file,
3782                          const gchar  *group_name,
3783                          GError      **error)
3784 {
3785   GList *group_node;
3786
3787   g_return_val_if_fail (key_file != NULL, FALSE);
3788   g_return_val_if_fail (group_name != NULL, FALSE);
3789
3790   group_node = g_key_file_lookup_group_node (key_file, group_name);
3791
3792   if (!group_node)
3793     {
3794       g_set_error (error, G_KEY_FILE_ERROR,
3795                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3796                    _("Key file does not have group '%s'"),
3797                    group_name);
3798       return FALSE;
3799     }
3800
3801   g_key_file_remove_group_node (key_file, group_node);
3802
3803   return TRUE;
3804 }
3805
3806 static void
3807 g_key_file_add_key_value_pair (GKeyFile             *key_file,
3808                                GKeyFileGroup        *group,
3809                                GKeyFileKeyValuePair *pair)
3810 {
3811   g_hash_table_replace (group->lookup_map, pair->key, pair);
3812   group->key_value_pairs = g_list_prepend (group->key_value_pairs, pair);
3813   group->has_trailing_blank_line = FALSE;
3814   key_file->approximate_size += strlen (pair->key) + strlen (pair->value) + 2;
3815 }
3816
3817 static void
3818 g_key_file_add_key (GKeyFile      *key_file,
3819                     GKeyFileGroup *group,
3820                     const gchar   *key,
3821                     const gchar   *value)
3822 {
3823   GKeyFileKeyValuePair *pair;
3824
3825   pair = g_slice_new (GKeyFileKeyValuePair);
3826   pair->key = g_strdup (key);
3827   pair->value = g_strdup (value);
3828
3829   g_key_file_add_key_value_pair (key_file, group, pair);
3830 }
3831
3832 /**
3833  * g_key_file_remove_key:
3834  * @key_file: a #GKeyFile
3835  * @group_name: a group name
3836  * @key: a key name to remove
3837  * @error: return location for a #GError or %NULL
3838  *
3839  * Removes @key in @group_name from the key file.
3840  *
3841  * Returns: %TRUE if the key was removed, %FALSE otherwise
3842  *
3843  * Since: 2.6
3844  **/
3845 gboolean
3846 g_key_file_remove_key (GKeyFile     *key_file,
3847                        const gchar  *group_name,
3848                        const gchar  *key,
3849                        GError      **error)
3850 {
3851   GKeyFileGroup *group;
3852   GKeyFileKeyValuePair *pair;
3853
3854   g_return_val_if_fail (key_file != NULL, FALSE);
3855   g_return_val_if_fail (group_name != NULL, FALSE);
3856   g_return_val_if_fail (key != NULL, FALSE);
3857
3858   pair = NULL;
3859
3860   group = g_key_file_lookup_group (key_file, group_name);
3861   if (!group)
3862     {
3863       g_set_error (error, G_KEY_FILE_ERROR,
3864                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3865                    _("Key file does not have group '%s'"),
3866                    group_name ? group_name : "(null)");
3867       return FALSE;
3868     }
3869
3870   pair = g_key_file_lookup_key_value_pair (key_file, group, key);
3871
3872   if (!pair)
3873     {
3874       g_set_error (error, G_KEY_FILE_ERROR,
3875                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3876                    _("Key file does not have key '%s' in group '%s'"),
3877                    key, group->name);
3878       return FALSE;
3879     }
3880
3881   key_file->approximate_size -= strlen (pair->key) + strlen (pair->value) + 2;
3882
3883   group->key_value_pairs = g_list_remove (group->key_value_pairs, pair);
3884   g_hash_table_remove (group->lookup_map, pair->key);
3885   g_key_file_key_value_pair_free (pair);
3886
3887   return TRUE;
3888 }
3889
3890 static GList *
3891 g_key_file_lookup_group_node (GKeyFile    *key_file,
3892                               const gchar *group_name)
3893 {
3894   GKeyFileGroup *group;
3895   GList *tmp;
3896
3897   for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
3898     {
3899       group = (GKeyFileGroup *) tmp->data;
3900
3901       if (group && group->name && strcmp (group->name, group_name) == 0)
3902         break;
3903     }
3904
3905   return tmp;
3906 }
3907
3908 static GKeyFileGroup *
3909 g_key_file_lookup_group (GKeyFile    *key_file,
3910                          const gchar *group_name)
3911 {
3912   return (GKeyFileGroup *)g_hash_table_lookup (key_file->group_hash, group_name);
3913 }
3914
3915 static GList *
3916 g_key_file_lookup_key_value_pair_node (GKeyFile       *key_file,
3917                                        GKeyFileGroup  *group,
3918                                        const gchar    *key)
3919 {
3920   GList *key_node;
3921
3922   for (key_node = group->key_value_pairs;
3923        key_node != NULL;
3924        key_node = key_node->next)
3925     {
3926       GKeyFileKeyValuePair *pair;
3927
3928       pair = (GKeyFileKeyValuePair *) key_node->data;
3929
3930       if (pair->key && strcmp (pair->key, key) == 0)
3931         break;
3932     }
3933
3934   return key_node;
3935 }
3936
3937 static GKeyFileKeyValuePair *
3938 g_key_file_lookup_key_value_pair (GKeyFile      *key_file,
3939                                   GKeyFileGroup *group,
3940                                   const gchar   *key)
3941 {
3942   return (GKeyFileKeyValuePair *) g_hash_table_lookup (group->lookup_map, key);
3943 }
3944
3945 /* Lines starting with # or consisting entirely of whitespace are merely
3946  * recorded, not parsed. This function assumes all leading whitespace
3947  * has been stripped.
3948  */
3949 static gboolean
3950 g_key_file_line_is_comment (const gchar *line)
3951 {
3952   return (*line == '#' || *line == '\0' || *line == '\n');
3953 }
3954
3955 static gboolean
3956 g_key_file_is_group_name (const gchar *name)
3957 {
3958   gchar *p, *q;
3959
3960   if (name == NULL)
3961     return FALSE;
3962
3963   p = q = (gchar *) name;
3964   while (*q && *q != ']' && *q != '[' && !g_ascii_iscntrl (*q))
3965     q = g_utf8_find_next_char (q, NULL);
3966
3967   if (*q != '\0' || q == p)
3968     return FALSE;
3969
3970   return TRUE;
3971 }
3972
3973 static gboolean
3974 g_key_file_is_key_name (const gchar *name)
3975 {
3976   gchar *p, *q;
3977
3978   if (name == NULL)
3979     return FALSE;
3980
3981   p = q = (gchar *) name;
3982   /* We accept a little more than the desktop entry spec says,
3983    * since gnome-vfs uses mime-types as keys in its cache.
3984    */
3985   while (*q && *q != '=' && *q != '[' && *q != ']')
3986     q = g_utf8_find_next_char (q, NULL);
3987
3988   /* No empty keys, please */
3989   if (q == p)
3990     return FALSE;
3991
3992   /* We accept spaces in the middle of keys to not break
3993    * existing apps, but we don't tolerate initial or final
3994    * spaces, which would lead to silent corruption when
3995    * rereading the file.
3996    */
3997   if (*p == ' ' || q[-1] == ' ')
3998     return FALSE;
3999
4000   if (*q == '[')
4001     {
4002       q++;
4003       while (*q && (g_unichar_isalnum (g_utf8_get_char_validated (q, -1)) || *q == '-' || *q == '_' || *q == '.' || *q == '@'))
4004         q = g_utf8_find_next_char (q, NULL);
4005
4006       if (*q != ']')
4007         return FALSE;
4008
4009       q++;
4010     }
4011
4012   if (*q != '\0')
4013     return FALSE;
4014
4015   return TRUE;
4016 }
4017
4018 /* A group in a key file is made up of a starting '[' followed by one
4019  * or more letters making up the group name followed by ']'.
4020  */
4021 static gboolean
4022 g_key_file_line_is_group (const gchar *line)
4023 {
4024   gchar *p;
4025
4026   p = (gchar *) line;
4027   if (*p != '[')
4028     return FALSE;
4029
4030   p++;
4031
4032   while (*p && *p != ']')
4033     p = g_utf8_find_next_char (p, NULL);
4034
4035   if (*p != ']')
4036     return FALSE;
4037
4038   /* silently accept whitespace after the ] */
4039   p = g_utf8_find_next_char (p, NULL);
4040   while (*p == ' ' || *p == '\t')
4041     p = g_utf8_find_next_char (p, NULL);
4042
4043   if (*p)
4044     return FALSE;
4045
4046   return TRUE;
4047 }
4048
4049 static gboolean
4050 g_key_file_line_is_key_value_pair (const gchar *line)
4051 {
4052   gchar *p;
4053
4054   p = (gchar *) g_utf8_strchr (line, -1, '=');
4055
4056   if (!p)
4057     return FALSE;
4058
4059   /* Key must be non-empty
4060    */
4061   if (*p == line[0])
4062     return FALSE;
4063
4064   return TRUE;
4065 }
4066
4067 static gchar *
4068 g_key_file_parse_value_as_string (GKeyFile     *key_file,
4069                                   const gchar  *value,
4070                                   GSList      **pieces,
4071                                   GError      **error)
4072 {
4073   gchar *string_value, *p, *q0, *q;
4074
4075   string_value = g_new (gchar, strlen (value) + 1);
4076
4077   p = (gchar *) value;
4078   q0 = q = string_value;
4079   while (*p)
4080     {
4081       if (*p == '\\')
4082         {
4083           p++;
4084
4085           switch (*p)
4086             {
4087             case 's':
4088               *q = ' ';
4089               break;
4090
4091             case 'n':
4092               *q = '\n';
4093               break;
4094
4095             case 't':
4096               *q = '\t';
4097               break;
4098
4099             case 'r':
4100               *q = '\r';
4101               break;
4102
4103             case '\\':
4104               *q = '\\';
4105               break;
4106
4107             case '\0':
4108               g_set_error_literal (error, G_KEY_FILE_ERROR,
4109                                    G_KEY_FILE_ERROR_INVALID_VALUE,
4110                                    _("Key file contains escape character "
4111                                      "at end of line"));
4112               break;
4113
4114             default:
4115               if (pieces && *p == key_file->list_separator)
4116                 *q = key_file->list_separator;
4117               else
4118                 {
4119                   *q++ = '\\';
4120                   *q = *p;
4121
4122                   if (*error == NULL)
4123                     {
4124                       gchar sequence[3];
4125
4126                       sequence[0] = '\\';
4127                       sequence[1] = *p;
4128                       sequence[2] = '\0';
4129
4130                       g_set_error (error, G_KEY_FILE_ERROR,
4131                                    G_KEY_FILE_ERROR_INVALID_VALUE,
4132                                    _("Key file contains invalid escape "
4133                                      "sequence '%s'"), sequence);
4134                     }
4135                 }
4136               break;
4137             }
4138         }
4139       else
4140         {
4141           *q = *p;
4142           if (pieces && (*p == key_file->list_separator))
4143             {
4144               *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
4145               q0 = q + 1;
4146             }
4147         }
4148
4149       if (*p == '\0')
4150         break;
4151
4152       q++;
4153       p++;
4154     }
4155
4156   *q = '\0';
4157   if (pieces)
4158   {
4159     if (q0 < q)
4160       *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
4161     *pieces = g_slist_reverse (*pieces);
4162   }
4163
4164   return string_value;
4165 }
4166
4167 static gchar *
4168 g_key_file_parse_string_as_value (GKeyFile    *key_file,
4169                                   const gchar *string,
4170                                   gboolean     escape_separator)
4171 {
4172   gchar *value, *p, *q;
4173   gsize length;
4174   gboolean parsing_leading_space;
4175
4176   length = strlen (string) + 1;
4177
4178   /* Worst case would be that every character needs to be escaped.
4179    * In other words every character turns to two characters
4180    */
4181   value = g_new (gchar, 2 * length);
4182
4183   p = (gchar *) string;
4184   q = value;
4185   parsing_leading_space = TRUE;
4186   while (p < (string + length - 1))
4187     {
4188       gchar escaped_character[3] = { '\\', 0, 0 };
4189
4190       switch (*p)
4191         {
4192         case ' ':
4193           if (parsing_leading_space)
4194             {
4195               escaped_character[1] = 's';
4196               strcpy (q, escaped_character);
4197               q += 2;
4198             }
4199           else
4200             {
4201               *q = *p;
4202               q++;
4203             }
4204           break;
4205         case '\t':
4206           if (parsing_leading_space)
4207             {
4208               escaped_character[1] = 't';
4209               strcpy (q, escaped_character);
4210               q += 2;
4211             }
4212           else
4213             {
4214               *q = *p;
4215               q++;
4216             }
4217           break;
4218         case '\n':
4219           escaped_character[1] = 'n';
4220           strcpy (q, escaped_character);
4221           q += 2;
4222           break;
4223         case '\r':
4224           escaped_character[1] = 'r';
4225           strcpy (q, escaped_character);
4226           q += 2;
4227           break;
4228         case '\\':
4229           escaped_character[1] = '\\';
4230           strcpy (q, escaped_character);
4231           q += 2;
4232           parsing_leading_space = FALSE;
4233           break;
4234         default:
4235           if (escape_separator && *p == key_file->list_separator)
4236             {
4237               escaped_character[1] = key_file->list_separator;
4238               strcpy (q, escaped_character);
4239               q += 2;
4240               parsing_leading_space = TRUE;
4241             }
4242           else
4243             {
4244               *q = *p;
4245               q++;
4246               parsing_leading_space = FALSE;
4247             }
4248           break;
4249         }
4250       p++;
4251     }
4252   *q = '\0';
4253
4254   return value;
4255 }
4256
4257 static gint
4258 g_key_file_parse_value_as_integer (GKeyFile     *key_file,
4259                                    const gchar  *value,
4260                                    GError      **error)
4261 {
4262   gchar *eof_int;
4263   glong long_value;
4264   gint int_value;
4265
4266   errno = 0;
4267   long_value = strtol (value, &eof_int, 10);
4268
4269   if (*value == '\0' || (*eof_int != '\0' && !g_ascii_isspace(*eof_int)))
4270     {
4271       gchar *value_utf8 = _g_utf8_make_valid (value);
4272       g_set_error (error, G_KEY_FILE_ERROR,
4273                    G_KEY_FILE_ERROR_INVALID_VALUE,
4274                    _("Value '%s' cannot be interpreted "
4275                      "as a number."), value_utf8);
4276       g_free (value_utf8);
4277
4278       return 0;
4279     }
4280
4281   int_value = long_value;
4282   if (int_value != long_value || errno == ERANGE)
4283     {
4284       gchar *value_utf8 = _g_utf8_make_valid (value);
4285       g_set_error (error,
4286                    G_KEY_FILE_ERROR,
4287                    G_KEY_FILE_ERROR_INVALID_VALUE,
4288                    _("Integer value '%s' out of range"),
4289                    value_utf8);
4290       g_free (value_utf8);
4291
4292       return 0;
4293     }
4294
4295   return int_value;
4296 }
4297
4298 static gchar *
4299 g_key_file_parse_integer_as_value (GKeyFile *key_file,
4300                                    gint      value)
4301
4302 {
4303   return g_strdup_printf ("%d", value);
4304 }
4305
4306 static gdouble
4307 g_key_file_parse_value_as_double  (GKeyFile     *key_file,
4308                                    const gchar  *value,
4309                                    GError      **error)
4310 {
4311   gchar *end_of_valid_d;
4312   gdouble double_value = 0;
4313
4314   double_value = g_ascii_strtod (value, &end_of_valid_d);
4315
4316   if (*end_of_valid_d != '\0' || end_of_valid_d == value)
4317     {
4318       gchar *value_utf8 = _g_utf8_make_valid (value);
4319       g_set_error (error, G_KEY_FILE_ERROR,
4320                    G_KEY_FILE_ERROR_INVALID_VALUE,
4321                    _("Value '%s' cannot be interpreted "
4322                      "as a float number."),
4323                    value_utf8);
4324       g_free (value_utf8);
4325     }
4326
4327   return double_value;
4328 }
4329
4330 static gboolean
4331 g_key_file_parse_value_as_boolean (GKeyFile     *key_file,
4332                                    const gchar  *value,
4333                                    GError      **error)
4334 {
4335   gchar *value_utf8;
4336
4337   if (strcmp (value, "true") == 0 || strcmp (value, "1") == 0)
4338     return TRUE;
4339   else if (strcmp (value, "false") == 0 || strcmp (value, "0") == 0)
4340     return FALSE;
4341
4342   value_utf8 = _g_utf8_make_valid (value);
4343   g_set_error (error, G_KEY_FILE_ERROR,
4344                G_KEY_FILE_ERROR_INVALID_VALUE,
4345                _("Value '%s' cannot be interpreted "
4346                  "as a boolean."), value_utf8);
4347   g_free (value_utf8);
4348
4349   return FALSE;
4350 }
4351
4352 static gchar *
4353 g_key_file_parse_boolean_as_value (GKeyFile *key_file,
4354                                    gboolean  value)
4355 {
4356   if (value)
4357     return g_strdup ("true");
4358   else
4359     return g_strdup ("false");
4360 }
4361
4362 static gchar *
4363 g_key_file_parse_value_as_comment (GKeyFile    *key_file,
4364                                    const gchar *value)
4365 {
4366   GString *string;
4367   gchar **lines;
4368   gsize i;
4369
4370   string = g_string_sized_new (512);
4371
4372   lines = g_strsplit (value, "\n", 0);
4373
4374   for (i = 0; lines[i] != NULL; i++)
4375     {
4376         if (lines[i][0] != '#')
4377            g_string_append_printf (string, "%s\n", lines[i]);
4378         else
4379            g_string_append_printf (string, "%s\n", lines[i] + 1);
4380     }
4381   g_strfreev (lines);
4382
4383   return g_string_free (string, FALSE);
4384 }
4385
4386 static gchar *
4387 g_key_file_parse_comment_as_value (GKeyFile      *key_file,
4388                                    const gchar   *comment)
4389 {
4390   GString *string;
4391   gchar **lines;
4392   gsize i;
4393
4394   string = g_string_sized_new (512);
4395
4396   lines = g_strsplit (comment, "\n", 0);
4397
4398   for (i = 0; lines[i] != NULL; i++)
4399     g_string_append_printf (string, "#%s%s", lines[i],
4400                             lines[i + 1] == NULL? "" : "\n");
4401   g_strfreev (lines);
4402
4403   return g_string_free (string, FALSE);
4404 }