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       return NULL;
1974     }
1975
1976   len = g_slist_length (pieces);
1977   values = g_new (gchar *, len + 1);
1978   for (p = pieces, i = 0; p; p = p->next)
1979     values[i++] = p->data;
1980   values[len] = NULL;
1981
1982   g_slist_free (pieces);
1983
1984   if (length)
1985     *length = len;
1986
1987   return values;
1988 }
1989
1990 /**
1991  * g_key_file_set_string_list:
1992  * @key_file: a #GKeyFile
1993  * @group_name: a group name
1994  * @key: a key
1995  * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values
1996  * @length: number of string values in @list
1997  *
1998  * Associates a list of string values for @key under @group_name.
1999  * If @key cannot be found then it is created.
2000  * If @group_name cannot be found then it is created.
2001  *
2002  * Since: 2.6
2003  **/
2004 void
2005 g_key_file_set_string_list (GKeyFile            *key_file,
2006                             const gchar         *group_name,
2007                             const gchar         *key,
2008                             const gchar * const  list[],
2009                             gsize                length)
2010 {
2011   GString *value_list;
2012   gsize i;
2013
2014   g_return_if_fail (key_file != NULL);
2015   g_return_if_fail (list != NULL || length == 0);
2016
2017   value_list = g_string_sized_new (length * 128);
2018   for (i = 0; i < length && list[i] != NULL; i++)
2019     {
2020       gchar *value;
2021
2022       value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
2023       g_string_append (value_list, value);
2024       g_string_append_c (value_list, key_file->list_separator);
2025
2026       g_free (value);
2027     }
2028
2029   g_key_file_set_value (key_file, group_name, key, value_list->str);
2030   g_string_free (value_list, TRUE);
2031 }
2032
2033 /**
2034  * g_key_file_set_locale_string:
2035  * @key_file: a #GKeyFile
2036  * @group_name: a group name
2037  * @key: a key
2038  * @locale: a locale identifier
2039  * @string: a string
2040  *
2041  * Associates a string value for @key and @locale under @group_name.
2042  * If the translation for @key cannot be found then it is created.
2043  *
2044  * Since: 2.6
2045  **/
2046 void
2047 g_key_file_set_locale_string (GKeyFile     *key_file,
2048                               const gchar  *group_name,
2049                               const gchar  *key,
2050                               const gchar  *locale,
2051                               const gchar  *string)
2052 {
2053   gchar *full_key, *value;
2054
2055   g_return_if_fail (key_file != NULL);
2056   g_return_if_fail (key != NULL);
2057   g_return_if_fail (locale != NULL);
2058   g_return_if_fail (string != NULL);
2059
2060   value = g_key_file_parse_string_as_value (key_file, string, FALSE);
2061   full_key = g_strdup_printf ("%s[%s]", key, locale);
2062   g_key_file_set_value (key_file, group_name, full_key, value);
2063   g_free (full_key);
2064   g_free (value);
2065 }
2066
2067 /**
2068  * g_key_file_get_locale_string:
2069  * @key_file: a #GKeyFile
2070  * @group_name: a group name
2071  * @key: a key
2072  * @locale: (allow-none): a locale identifier or %NULL
2073  * @error: return location for a #GError, or %NULL
2074  *
2075  * Returns the value associated with @key under @group_name
2076  * translated in the given @locale if available.  If @locale is
2077  * %NULL then the current locale is assumed.
2078  *
2079  * If @key cannot be found then %NULL is returned and @error is set
2080  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
2081  * with @key cannot be interpreted or no suitable translation can
2082  * be found then the untranslated value is returned.
2083  *
2084  * Return value: a newly allocated string or %NULL if the specified
2085  *   key cannot be found.
2086  *
2087  * Since: 2.6
2088  **/
2089 gchar *
2090 g_key_file_get_locale_string (GKeyFile     *key_file,
2091                               const gchar  *group_name,
2092                               const gchar  *key,
2093                               const gchar  *locale,
2094                               GError      **error)
2095 {
2096   gchar *candidate_key, *translated_value;
2097   GError *key_file_error;
2098   gchar **languages;
2099   gboolean free_languages = FALSE;
2100   gint i;
2101
2102   g_return_val_if_fail (key_file != NULL, NULL);
2103   g_return_val_if_fail (group_name != NULL, NULL);
2104   g_return_val_if_fail (key != NULL, NULL);
2105
2106   candidate_key = NULL;
2107   translated_value = NULL;
2108   key_file_error = NULL;
2109
2110   if (locale)
2111     {
2112       languages = g_get_locale_variants (locale);
2113       free_languages = TRUE;
2114     }
2115   else
2116     {
2117       languages = (gchar **) g_get_language_names ();
2118       free_languages = FALSE;
2119     }
2120
2121   for (i = 0; languages[i]; i++)
2122     {
2123       candidate_key = g_strdup_printf ("%s[%s]", key, languages[i]);
2124
2125       translated_value = g_key_file_get_string (key_file,
2126                                                 group_name,
2127                                                 candidate_key, NULL);
2128       g_free (candidate_key);
2129
2130       if (translated_value)
2131         break;
2132
2133       g_free (translated_value);
2134       translated_value = NULL;
2135    }
2136
2137   /* Fallback to untranslated key
2138    */
2139   if (!translated_value)
2140     {
2141       translated_value = g_key_file_get_string (key_file, group_name, key,
2142                                                 &key_file_error);
2143
2144       if (!translated_value)
2145         g_propagate_error (error, key_file_error);
2146     }
2147
2148   if (free_languages)
2149     g_strfreev (languages);
2150
2151   return translated_value;
2152 }
2153
2154 /**
2155  * g_key_file_get_locale_string_list:
2156  * @key_file: a #GKeyFile
2157  * @group_name: a group name
2158  * @key: a key
2159  * @locale: (allow-none): a locale identifier or %NULL
2160  * @length: (out) (allow-none): return location for the number of returned strings or %NULL
2161  * @error: return location for a #GError or %NULL
2162  *
2163  * Returns the values associated with @key under @group_name
2164  * translated in the given @locale if available.  If @locale is
2165  * %NULL then the current locale is assumed.
2166
2167  * If @key cannot be found then %NULL is returned and @error is set
2168  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
2169  * with @key cannot be interpreted or no suitable translations
2170  * can be found then the untranslated values are returned. The
2171  * returned array is %NULL-terminated, so @length may optionally
2172  * be %NULL.
2173  *
2174  * Return value: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
2175  *   or %NULL if the key isn't found. The string array should be freed
2176  *   with g_strfreev().
2177  *
2178  * Since: 2.6
2179  **/
2180 gchar **
2181 g_key_file_get_locale_string_list (GKeyFile     *key_file,
2182                                    const gchar  *group_name,
2183                                    const gchar  *key,
2184                                    const gchar  *locale,
2185                                    gsize        *length,
2186                                    GError      **error)
2187 {
2188   GError *key_file_error;
2189   gchar **values, *value;
2190   char list_separator[2];
2191   gsize len;
2192
2193   g_return_val_if_fail (key_file != NULL, NULL);
2194   g_return_val_if_fail (group_name != NULL, NULL);
2195   g_return_val_if_fail (key != NULL, NULL);
2196
2197   key_file_error = NULL;
2198
2199   value = g_key_file_get_locale_string (key_file, group_name,
2200                                         key, locale,
2201                                         &key_file_error);
2202
2203   if (key_file_error)
2204     g_propagate_error (error, key_file_error);
2205
2206   if (!value)
2207     {
2208       if (length)
2209         *length = 0;
2210       return NULL;
2211     }
2212
2213   len = strlen (value);
2214   if (value[len - 1] == key_file->list_separator)
2215     value[len - 1] = '\0';
2216
2217   list_separator[0] = key_file->list_separator;
2218   list_separator[1] = '\0';
2219   values = g_strsplit (value, list_separator, 0);
2220
2221   g_free (value);
2222
2223   if (length)
2224     *length = g_strv_length (values);
2225
2226   return values;
2227 }
2228
2229 /**
2230  * g_key_file_set_locale_string_list:
2231  * @key_file: a #GKeyFile
2232  * @group_name: a group name
2233  * @key: a key
2234  * @locale: a locale identifier
2235  * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values
2236  * @length: the length of @list
2237  *
2238  * Associates a list of string values for @key and @locale under
2239  * @group_name.  If the translation for @key cannot be found then
2240  * it is created.
2241  *
2242  * Since: 2.6
2243  **/
2244 void
2245 g_key_file_set_locale_string_list (GKeyFile            *key_file,
2246                                    const gchar         *group_name,
2247                                    const gchar         *key,
2248                                    const gchar         *locale,
2249                                    const gchar * const  list[],
2250                                    gsize                length)
2251 {
2252   GString *value_list;
2253   gchar *full_key;
2254   gsize i;
2255
2256   g_return_if_fail (key_file != NULL);
2257   g_return_if_fail (key != NULL);
2258   g_return_if_fail (locale != NULL);
2259   g_return_if_fail (length != 0);
2260
2261   value_list = g_string_sized_new (length * 128);
2262   for (i = 0; i < length && list[i] != NULL; i++)
2263     {
2264       gchar *value;
2265
2266       value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
2267       g_string_append (value_list, value);
2268       g_string_append_c (value_list, key_file->list_separator);
2269
2270       g_free (value);
2271     }
2272
2273   full_key = g_strdup_printf ("%s[%s]", key, locale);
2274   g_key_file_set_value (key_file, group_name, full_key, value_list->str);
2275   g_free (full_key);
2276   g_string_free (value_list, TRUE);
2277 }
2278
2279 /**
2280  * g_key_file_get_boolean:
2281  * @key_file: a #GKeyFile
2282  * @group_name: a group name
2283  * @key: a key
2284  * @error: return location for a #GError
2285  *
2286  * Returns the value associated with @key under @group_name as a
2287  * boolean.
2288  *
2289  * If @key cannot be found then %FALSE is returned and @error is set
2290  * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
2291  * associated with @key cannot be interpreted as a boolean then %FALSE
2292  * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2293  *
2294  * Return value: the value associated with the key as a boolean,
2295  *    or %FALSE if the key was not found or could not be parsed.
2296  *
2297  * Since: 2.6
2298  **/
2299 gboolean
2300 g_key_file_get_boolean (GKeyFile     *key_file,
2301                         const gchar  *group_name,
2302                         const gchar  *key,
2303                         GError      **error)
2304 {
2305   GError *key_file_error = NULL;
2306   gchar *value;
2307   gboolean bool_value;
2308
2309   g_return_val_if_fail (key_file != NULL, FALSE);
2310   g_return_val_if_fail (group_name != NULL, FALSE);
2311   g_return_val_if_fail (key != NULL, FALSE);
2312
2313   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2314
2315   if (!value)
2316     {
2317       g_propagate_error (error, key_file_error);
2318       return FALSE;
2319     }
2320
2321   bool_value = g_key_file_parse_value_as_boolean (key_file, value,
2322                                                   &key_file_error);
2323   g_free (value);
2324
2325   if (key_file_error)
2326     {
2327       if (g_error_matches (key_file_error,
2328                            G_KEY_FILE_ERROR,
2329                            G_KEY_FILE_ERROR_INVALID_VALUE))
2330         {
2331           g_set_error (error, G_KEY_FILE_ERROR,
2332                        G_KEY_FILE_ERROR_INVALID_VALUE,
2333                        _("Key file contains key '%s' "
2334                          "which has a value that cannot be interpreted."),
2335                        key);
2336           g_error_free (key_file_error);
2337         }
2338       else
2339         g_propagate_error (error, key_file_error);
2340     }
2341
2342   return bool_value;
2343 }
2344
2345 /**
2346  * g_key_file_set_boolean:
2347  * @key_file: a #GKeyFile
2348  * @group_name: a group name
2349  * @key: a key
2350  * @value: %TRUE or %FALSE
2351  *
2352  * Associates a new boolean value with @key under @group_name.
2353  * If @key cannot be found then it is created.
2354  *
2355  * Since: 2.6
2356  **/
2357 void
2358 g_key_file_set_boolean (GKeyFile    *key_file,
2359                         const gchar *group_name,
2360                         const gchar *key,
2361                         gboolean     value)
2362 {
2363   gchar *result;
2364
2365   g_return_if_fail (key_file != NULL);
2366
2367   result = g_key_file_parse_boolean_as_value (key_file, value);
2368   g_key_file_set_value (key_file, group_name, key, result);
2369   g_free (result);
2370 }
2371
2372 /**
2373  * g_key_file_get_boolean_list:
2374  * @key_file: a #GKeyFile
2375  * @group_name: a group name
2376  * @key: a key
2377  * @length: (out): the number of booleans returned
2378  * @error: return location for a #GError
2379  *
2380  * Returns the values associated with @key under @group_name as
2381  * booleans.
2382  *
2383  * If @key cannot be found then %NULL is returned and @error is set to
2384  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2385  * with @key cannot be interpreted as booleans then %NULL is returned
2386  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2387  *
2388  * Return value: (array length=length) (element-type gboolean) (transfer container):
2389  *    the values associated with the key as a list of booleans, or %NULL if the
2390  *    key was not found or could not be parsed. The returned list of booleans
2391  *    should be freed with g_free() when no longer needed.
2392  *
2393  * Since: 2.6
2394  **/
2395 gboolean *
2396 g_key_file_get_boolean_list (GKeyFile     *key_file,
2397                              const gchar  *group_name,
2398                              const gchar  *key,
2399                              gsize        *length,
2400                              GError      **error)
2401 {
2402   GError *key_file_error;
2403   gchar **values;
2404   gboolean *bool_values;
2405   gsize i, num_bools;
2406
2407   g_return_val_if_fail (key_file != NULL, NULL);
2408   g_return_val_if_fail (group_name != NULL, NULL);
2409   g_return_val_if_fail (key != NULL, NULL);
2410
2411   if (length)
2412     *length = 0;
2413
2414   key_file_error = NULL;
2415
2416   values = g_key_file_get_string_list (key_file, group_name, key,
2417                                        &num_bools, &key_file_error);
2418
2419   if (key_file_error)
2420     g_propagate_error (error, key_file_error);
2421
2422   if (!values)
2423     return NULL;
2424
2425   bool_values = g_new (gboolean, num_bools);
2426
2427   for (i = 0; i < num_bools; i++)
2428     {
2429       bool_values[i] = g_key_file_parse_value_as_boolean (key_file,
2430                                                           values[i],
2431                                                           &key_file_error);
2432
2433       if (key_file_error)
2434         {
2435           g_propagate_error (error, key_file_error);
2436           g_strfreev (values);
2437           g_free (bool_values);
2438
2439           return NULL;
2440         }
2441     }
2442   g_strfreev (values);
2443
2444   if (length)
2445     *length = num_bools;
2446
2447   return bool_values;
2448 }
2449
2450 /**
2451  * g_key_file_set_boolean_list:
2452  * @key_file: a #GKeyFile
2453  * @group_name: a group name
2454  * @key: a key
2455  * @list: (array length=length): an array of boolean values
2456  * @length: length of @list
2457  *
2458  * Associates a list of boolean values with @key under @group_name.
2459  * If @key cannot be found then it is created.
2460  * If @group_name is %NULL, the start_group is used.
2461  *
2462  * Since: 2.6
2463  **/
2464 void
2465 g_key_file_set_boolean_list (GKeyFile    *key_file,
2466                              const gchar *group_name,
2467                              const gchar *key,
2468                              gboolean     list[],
2469                              gsize        length)
2470 {
2471   GString *value_list;
2472   gsize i;
2473
2474   g_return_if_fail (key_file != NULL);
2475   g_return_if_fail (list != NULL);
2476
2477   value_list = g_string_sized_new (length * 8);
2478   for (i = 0; i < length; i++)
2479     {
2480       gchar *value;
2481
2482       value = g_key_file_parse_boolean_as_value (key_file, list[i]);
2483
2484       g_string_append (value_list, value);
2485       g_string_append_c (value_list, key_file->list_separator);
2486
2487       g_free (value);
2488     }
2489
2490   g_key_file_set_value (key_file, group_name, key, value_list->str);
2491   g_string_free (value_list, TRUE);
2492 }
2493
2494 /**
2495  * g_key_file_get_integer:
2496  * @key_file: a #GKeyFile
2497  * @group_name: a group name
2498  * @key: a key
2499  * @error: return location for a #GError
2500  *
2501  * Returns the value associated with @key under @group_name as an
2502  * integer.
2503  *
2504  * If @key cannot be found then 0 is returned and @error is set to
2505  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
2506  * with @key cannot be interpreted as an integer then 0 is returned
2507  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2508  *
2509  * Return value: the value associated with the key as an integer, or
2510  *     0 if the key was not found or could not be parsed.
2511  *
2512  * Since: 2.6
2513  **/
2514 gint
2515 g_key_file_get_integer (GKeyFile     *key_file,
2516                         const gchar  *group_name,
2517                         const gchar  *key,
2518                         GError      **error)
2519 {
2520   GError *key_file_error;
2521   gchar *value;
2522   gint int_value;
2523
2524   g_return_val_if_fail (key_file != NULL, -1);
2525   g_return_val_if_fail (group_name != NULL, -1);
2526   g_return_val_if_fail (key != NULL, -1);
2527
2528   key_file_error = NULL;
2529
2530   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2531
2532   if (key_file_error)
2533     {
2534       g_propagate_error (error, key_file_error);
2535       return 0;
2536     }
2537
2538   int_value = g_key_file_parse_value_as_integer (key_file, value,
2539                                                  &key_file_error);
2540   g_free (value);
2541
2542   if (key_file_error)
2543     {
2544       if (g_error_matches (key_file_error,
2545                            G_KEY_FILE_ERROR,
2546                            G_KEY_FILE_ERROR_INVALID_VALUE))
2547         {
2548           g_set_error (error, G_KEY_FILE_ERROR,
2549                        G_KEY_FILE_ERROR_INVALID_VALUE,
2550                        _("Key file contains key '%s' in group '%s' "
2551                          "which has a value that cannot be interpreted."),
2552                          key, group_name);
2553           g_error_free (key_file_error);
2554         }
2555       else
2556         g_propagate_error (error, key_file_error);
2557     }
2558
2559   return int_value;
2560 }
2561
2562 /**
2563  * g_key_file_set_integer:
2564  * @key_file: a #GKeyFile
2565  * @group_name: a group name
2566  * @key: a key
2567  * @value: an integer value
2568  *
2569  * Associates a new integer value with @key under @group_name.
2570  * If @key cannot be found then it is created.
2571  *
2572  * Since: 2.6
2573  **/
2574 void
2575 g_key_file_set_integer (GKeyFile    *key_file,
2576                         const gchar *group_name,
2577                         const gchar *key,
2578                         gint         value)
2579 {
2580   gchar *result;
2581
2582   g_return_if_fail (key_file != NULL);
2583
2584   result = g_key_file_parse_integer_as_value (key_file, value);
2585   g_key_file_set_value (key_file, group_name, key, result);
2586   g_free (result);
2587 }
2588
2589 /**
2590  * g_key_file_get_int64:
2591  * @key_file: a non-%NULL #GKeyFile
2592  * @group_name: a non-%NULL group name
2593  * @key: a non-%NULL key
2594  * @error: return location for a #GError
2595  *
2596  * Returns the value associated with @key under @group_name as a signed
2597  * 64-bit integer. This is similar to g_key_file_get_integer() but can return
2598  * 64-bit results without truncation.
2599  *
2600  * Returns: the value associated with the key as a signed 64-bit integer, or
2601  * 0 if the key was not found or could not be parsed.
2602  *
2603  * Since: 2.26
2604  */
2605 gint64
2606 g_key_file_get_int64 (GKeyFile     *key_file,
2607                       const gchar  *group_name,
2608                       const gchar  *key,
2609                       GError      **error)
2610 {
2611   gchar *s, *end;
2612   gint64 v;
2613
2614   g_return_val_if_fail (key_file != NULL, -1);
2615   g_return_val_if_fail (group_name != NULL, -1);
2616   g_return_val_if_fail (key != NULL, -1);
2617
2618   s = g_key_file_get_value (key_file, group_name, key, error);
2619
2620   if (s == NULL)
2621     return 0;
2622
2623   v = g_ascii_strtoll (s, &end, 10);
2624
2625   if (*s == '\0' || *end != '\0')
2626     {
2627       g_set_error (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_INVALID_VALUE,
2628                    _("Key '%s' in group '%s' has value '%s' "
2629                      "where %s was expected"),
2630                    key, group_name, s, "int64");
2631       return 0;
2632     }
2633
2634   g_free (s);
2635   return v;
2636 }
2637
2638 /**
2639  * g_key_file_set_int64:
2640  * @key_file: a #GKeyFile
2641  * @group_name: a group name
2642  * @key: a key
2643  * @value: an integer value
2644  *
2645  * Associates a new integer value with @key under @group_name.
2646  * If @key cannot be found then it is created.
2647  *
2648  * Since: 2.26
2649  **/
2650 void
2651 g_key_file_set_int64 (GKeyFile    *key_file,
2652                       const gchar *group_name,
2653                       const gchar *key,
2654                       gint64       value)
2655 {
2656   gchar *result;
2657
2658   g_return_if_fail (key_file != NULL);
2659
2660   result = g_strdup_printf ("%" G_GINT64_FORMAT, value);
2661   g_key_file_set_value (key_file, group_name, key, result);
2662   g_free (result);
2663 }
2664
2665 /**
2666  * g_key_file_get_uint64:
2667  * @key_file: a non-%NULL #GKeyFile
2668  * @group_name: a non-%NULL group name
2669  * @key: a non-%NULL key
2670  * @error: return location for a #GError
2671  *
2672  * Returns the value associated with @key under @group_name as an unsigned
2673  * 64-bit integer. This is similar to g_key_file_get_integer() but can return
2674  * large positive results without truncation.
2675  *
2676  * Returns: the value associated with the key as an unsigned 64-bit integer,
2677  * or 0 if the key was not found or could not be parsed.
2678  *
2679  * Since: 2.26
2680  */
2681 guint64
2682 g_key_file_get_uint64 (GKeyFile     *key_file,
2683                        const gchar  *group_name,
2684                        const gchar  *key,
2685                        GError      **error)
2686 {
2687   gchar *s, *end;
2688   guint64 v;
2689
2690   g_return_val_if_fail (key_file != NULL, -1);
2691   g_return_val_if_fail (group_name != NULL, -1);
2692   g_return_val_if_fail (key != NULL, -1);
2693
2694   s = g_key_file_get_value (key_file, group_name, key, error);
2695
2696   if (s == NULL)
2697     return 0;
2698
2699   v = g_ascii_strtoull (s, &end, 10);
2700
2701   if (*s == '\0' || *end != '\0')
2702     {
2703       g_set_error (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_INVALID_VALUE,
2704                    _("Key '%s' in group '%s' has value '%s' "
2705                      "where %s was expected"),
2706                    key, group_name, s, "uint64");
2707       return 0;
2708     }
2709
2710   g_free (s);
2711   return v;
2712 }
2713
2714 /**
2715  * g_key_file_set_uint64:
2716  * @key_file: a #GKeyFile
2717  * @group_name: a group name
2718  * @key: a key
2719  * @value: an integer value
2720  *
2721  * Associates a new integer value with @key under @group_name.
2722  * If @key cannot be found then it is created.
2723  *
2724  * Since: 2.26
2725  **/
2726 void
2727 g_key_file_set_uint64 (GKeyFile    *key_file,
2728                        const gchar *group_name,
2729                        const gchar *key,
2730                        guint64      value)
2731 {
2732   gchar *result;
2733
2734   g_return_if_fail (key_file != NULL);
2735
2736   result = g_strdup_printf ("%" G_GUINT64_FORMAT, value);
2737   g_key_file_set_value (key_file, group_name, key, result);
2738   g_free (result);
2739 }
2740
2741 /**
2742  * g_key_file_get_integer_list:
2743  * @key_file: a #GKeyFile
2744  * @group_name: a group name
2745  * @key: a key
2746  * @length: (out): the number of integers returned
2747  * @error: return location for a #GError
2748  *
2749  * Returns the values associated with @key under @group_name as
2750  * integers.
2751  *
2752  * If @key cannot be found then %NULL is returned and @error is set to
2753  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2754  * with @key cannot be interpreted as integers then %NULL is returned
2755  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2756  *
2757  * Return value: (array length=length) (element-type gint) (transfer container):
2758  *     the values associated with the key as a list of integers, or %NULL if
2759  *     the key was not found or could not be parsed. The returned list of
2760  *     integers should be freed with g_free() when no longer needed.
2761  *
2762  * Since: 2.6
2763  **/
2764 gint *
2765 g_key_file_get_integer_list (GKeyFile     *key_file,
2766                              const gchar  *group_name,
2767                              const gchar  *key,
2768                              gsize        *length,
2769                              GError      **error)
2770 {
2771   GError *key_file_error = NULL;
2772   gchar **values;
2773   gint *int_values;
2774   gsize i, num_ints;
2775
2776   g_return_val_if_fail (key_file != NULL, NULL);
2777   g_return_val_if_fail (group_name != NULL, NULL);
2778   g_return_val_if_fail (key != NULL, NULL);
2779
2780   if (length)
2781     *length = 0;
2782
2783   values = g_key_file_get_string_list (key_file, group_name, key,
2784                                        &num_ints, &key_file_error);
2785
2786   if (key_file_error)
2787     g_propagate_error (error, key_file_error);
2788
2789   if (!values)
2790     return NULL;
2791
2792   int_values = g_new (gint, num_ints);
2793
2794   for (i = 0; i < num_ints; i++)
2795     {
2796       int_values[i] = g_key_file_parse_value_as_integer (key_file,
2797                                                          values[i],
2798                                                          &key_file_error);
2799
2800       if (key_file_error)
2801         {
2802           g_propagate_error (error, key_file_error);
2803           g_strfreev (values);
2804           g_free (int_values);
2805
2806           return NULL;
2807         }
2808     }
2809   g_strfreev (values);
2810
2811   if (length)
2812     *length = num_ints;
2813
2814   return int_values;
2815 }
2816
2817 /**
2818  * g_key_file_set_integer_list:
2819  * @key_file: a #GKeyFile
2820  * @group_name: a group name
2821  * @key: a key
2822  * @list: (array length=length): an array of integer values
2823  * @length: number of integer values in @list
2824  *
2825  * Associates a list of integer values with @key under @group_name.
2826  * If @key cannot be found then it is created.
2827  *
2828  * Since: 2.6
2829  **/
2830 void
2831 g_key_file_set_integer_list (GKeyFile    *key_file,
2832                              const gchar *group_name,
2833                              const gchar *key,
2834                              gint         list[],
2835                              gsize        length)
2836 {
2837   GString *values;
2838   gsize i;
2839
2840   g_return_if_fail (key_file != NULL);
2841   g_return_if_fail (list != NULL);
2842
2843   values = g_string_sized_new (length * 16);
2844   for (i = 0; i < length; i++)
2845     {
2846       gchar *value;
2847
2848       value = g_key_file_parse_integer_as_value (key_file, list[i]);
2849
2850       g_string_append (values, value);
2851       g_string_append_c (values, key_file->list_separator);
2852
2853       g_free (value);
2854     }
2855
2856   g_key_file_set_value (key_file, group_name, key, values->str);
2857   g_string_free (values, TRUE);
2858 }
2859
2860 /**
2861  * g_key_file_get_double:
2862  * @key_file: a #GKeyFile
2863  * @group_name: a group name
2864  * @key: a key
2865  * @error: return location for a #GError
2866  *
2867  * Returns the value associated with @key under @group_name as a
2868  * double. If @group_name is %NULL, the start_group is used.
2869  *
2870  * If @key cannot be found then 0.0 is returned and @error is set to
2871  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
2872  * with @key cannot be interpreted as a double then 0.0 is returned
2873  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2874  *
2875  * Return value: the value associated with the key as a double, or
2876  *     0.0 if the key was not found or could not be parsed.
2877  *
2878  * Since: 2.12
2879  **/
2880 gdouble
2881 g_key_file_get_double  (GKeyFile     *key_file,
2882                         const gchar  *group_name,
2883                         const gchar  *key,
2884                         GError      **error)
2885 {
2886   GError *key_file_error;
2887   gchar *value;
2888   gdouble double_value;
2889
2890   g_return_val_if_fail (key_file != NULL, -1);
2891   g_return_val_if_fail (group_name != NULL, -1);
2892   g_return_val_if_fail (key != NULL, -1);
2893
2894   key_file_error = NULL;
2895
2896   value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
2897
2898   if (key_file_error)
2899     {
2900       g_propagate_error (error, key_file_error);
2901       return 0;
2902     }
2903
2904   double_value = g_key_file_parse_value_as_double (key_file, value,
2905                                                   &key_file_error);
2906   g_free (value);
2907
2908   if (key_file_error)
2909     {
2910       if (g_error_matches (key_file_error,
2911                            G_KEY_FILE_ERROR,
2912                            G_KEY_FILE_ERROR_INVALID_VALUE))
2913         {
2914           g_set_error (error, G_KEY_FILE_ERROR,
2915                        G_KEY_FILE_ERROR_INVALID_VALUE,
2916                        _("Key file contains key '%s' in group '%s' "
2917                          "which has a value that cannot be interpreted."),
2918                        key, group_name);
2919           g_error_free (key_file_error);
2920         }
2921       else
2922         g_propagate_error (error, key_file_error);
2923     }
2924
2925   return double_value;
2926 }
2927
2928 /**
2929  * g_key_file_set_double:
2930  * @key_file: a #GKeyFile
2931  * @group_name: a group name
2932  * @key: a key
2933  * @value: an double value
2934  *
2935  * Associates a new double value with @key under @group_name.
2936  * If @key cannot be found then it is created.
2937  *
2938  * Since: 2.12
2939  **/
2940 void
2941 g_key_file_set_double  (GKeyFile    *key_file,
2942                         const gchar *group_name,
2943                         const gchar *key,
2944                         gdouble      value)
2945 {
2946   gchar result[G_ASCII_DTOSTR_BUF_SIZE];
2947
2948   g_return_if_fail (key_file != NULL);
2949
2950   g_ascii_dtostr (result, sizeof (result), value);
2951   g_key_file_set_value (key_file, group_name, key, result);
2952 }
2953
2954 /**
2955  * g_key_file_get_double_list:
2956  * @key_file: a #GKeyFile
2957  * @group_name: a group name
2958  * @key: a key
2959  * @length: (out): the number of doubles returned
2960  * @error: return location for a #GError
2961  *
2962  * Returns the values associated with @key under @group_name as
2963  * doubles.
2964  *
2965  * If @key cannot be found then %NULL is returned and @error is set to
2966  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
2967  * with @key cannot be interpreted as doubles then %NULL is returned
2968  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
2969  *
2970  * Return value: (array length=length) (element-type gdouble) (transfer container):
2971  *     the values associated with the key as a list of doubles, or %NULL if the
2972  *     key was not found or could not be parsed. The returned list of doubles
2973  *     should be freed with g_free() when no longer needed.
2974  *
2975  * Since: 2.12
2976  **/
2977 gdouble *
2978 g_key_file_get_double_list  (GKeyFile     *key_file,
2979                              const gchar  *group_name,
2980                              const gchar  *key,
2981                              gsize        *length,
2982                              GError      **error)
2983 {
2984   GError *key_file_error = NULL;
2985   gchar **values;
2986   gdouble *double_values;
2987   gsize i, num_doubles;
2988
2989   g_return_val_if_fail (key_file != NULL, NULL);
2990   g_return_val_if_fail (group_name != NULL, NULL);
2991   g_return_val_if_fail (key != NULL, NULL);
2992
2993   if (length)
2994     *length = 0;
2995
2996   values = g_key_file_get_string_list (key_file, group_name, key,
2997                                        &num_doubles, &key_file_error);
2998
2999   if (key_file_error)
3000     g_propagate_error (error, key_file_error);
3001
3002   if (!values)
3003     return NULL;
3004
3005   double_values = g_new (gdouble, num_doubles);
3006
3007   for (i = 0; i < num_doubles; i++)
3008     {
3009       double_values[i] = g_key_file_parse_value_as_double (key_file,
3010                                                            values[i],
3011                                                            &key_file_error);
3012
3013       if (key_file_error)
3014         {
3015           g_propagate_error (error, key_file_error);
3016           g_strfreev (values);
3017           g_free (double_values);
3018
3019           return NULL;
3020         }
3021     }
3022   g_strfreev (values);
3023
3024   if (length)
3025     *length = num_doubles;
3026
3027   return double_values;
3028 }
3029
3030 /**
3031  * g_key_file_set_double_list:
3032  * @key_file: a #GKeyFile
3033  * @group_name: a group name
3034  * @key: a key
3035  * @list: (array length=length): an array of double values
3036  * @length: number of double values in @list
3037  *
3038  * Associates a list of double values with @key under
3039  * @group_name.  If @key cannot be found then it is created.
3040  *
3041  * Since: 2.12
3042  **/
3043 void
3044 g_key_file_set_double_list (GKeyFile    *key_file,
3045                             const gchar *group_name,
3046                             const gchar *key,
3047                             gdouble      list[],
3048                             gsize        length)
3049 {
3050   GString *values;
3051   gsize i;
3052
3053   g_return_if_fail (key_file != NULL);
3054   g_return_if_fail (list != NULL);
3055
3056   values = g_string_sized_new (length * 16);
3057   for (i = 0; i < length; i++)
3058     {
3059       gchar result[G_ASCII_DTOSTR_BUF_SIZE];
3060
3061       g_ascii_dtostr( result, sizeof (result), list[i] );
3062
3063       g_string_append (values, result);
3064       g_string_append_c (values, key_file->list_separator);
3065     }
3066
3067   g_key_file_set_value (key_file, group_name, key, values->str);
3068   g_string_free (values, TRUE);
3069 }
3070
3071 static gboolean
3072 g_key_file_set_key_comment (GKeyFile     *key_file,
3073                             const gchar  *group_name,
3074                             const gchar  *key,
3075                             const gchar  *comment,
3076                             GError      **error)
3077 {
3078   GKeyFileGroup *group;
3079   GKeyFileKeyValuePair *pair;
3080   GList *key_node, *comment_node, *tmp;
3081
3082   group = g_key_file_lookup_group (key_file, group_name);
3083   if (!group)
3084     {
3085       g_set_error (error, G_KEY_FILE_ERROR,
3086                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3087                    _("Key file does not have group '%s'"),
3088                    group_name ? group_name : "(null)");
3089
3090       return FALSE;
3091     }
3092
3093   /* First find the key the comments are supposed to be
3094    * associated with
3095    */
3096   key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
3097
3098   if (key_node == NULL)
3099     {
3100       g_set_error (error, G_KEY_FILE_ERROR,
3101                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3102                    _("Key file does not have key '%s' in group '%s'"),
3103                    key, group->name);
3104       return FALSE;
3105     }
3106
3107   /* Then find all the comments already associated with the
3108    * key and free them
3109    */
3110   tmp = key_node->next;
3111   while (tmp != NULL)
3112     {
3113       pair = (GKeyFileKeyValuePair *) tmp->data;
3114
3115       if (pair->key != NULL)
3116         break;
3117
3118       comment_node = tmp;
3119       tmp = tmp->next;
3120       g_key_file_remove_key_value_pair_node (key_file, group,
3121                                              comment_node);
3122     }
3123
3124   if (comment == NULL)
3125     return TRUE;
3126
3127   /* Now we can add our new comment
3128    */
3129   pair = g_slice_new (GKeyFileKeyValuePair);
3130   pair->key = NULL;
3131   pair->value = g_key_file_parse_comment_as_value (key_file, comment);
3132
3133   key_node = g_list_insert (key_node, pair, 1);
3134
3135   return TRUE;
3136 }
3137
3138 static gboolean
3139 g_key_file_set_group_comment (GKeyFile     *key_file,
3140                               const gchar  *group_name,
3141                               const gchar  *comment,
3142                               GError      **error)
3143 {
3144   GKeyFileGroup *group;
3145
3146   g_return_val_if_fail (g_key_file_is_group_name (group_name), FALSE);
3147
3148   group = g_key_file_lookup_group (key_file, group_name);
3149   if (!group)
3150     {
3151       g_set_error (error, G_KEY_FILE_ERROR,
3152                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3153                    _("Key file does not have group '%s'"),
3154                    group_name ? group_name : "(null)");
3155
3156       return FALSE;
3157     }
3158
3159   /* First remove any existing comment
3160    */
3161   if (group->comment)
3162     {
3163       g_key_file_key_value_pair_free (group->comment);
3164       group->comment = NULL;
3165     }
3166
3167   if (comment == NULL)
3168     return TRUE;
3169
3170   /* Now we can add our new comment
3171    */
3172   group->comment = g_slice_new (GKeyFileKeyValuePair);
3173   group->comment->key = NULL;
3174   group->comment->value = g_key_file_parse_comment_as_value (key_file, comment);
3175
3176   return TRUE;
3177 }
3178
3179 static gboolean
3180 g_key_file_set_top_comment (GKeyFile     *key_file,
3181                             const gchar  *comment,
3182                             GError      **error)
3183 {
3184   GList *group_node;
3185   GKeyFileGroup *group;
3186   GKeyFileKeyValuePair *pair;
3187
3188   /* The last group in the list should be the top (comments only)
3189    * group in the file
3190    */
3191   g_warn_if_fail (key_file->groups != NULL);
3192   group_node = g_list_last (key_file->groups);
3193   group = (GKeyFileGroup *) group_node->data;
3194   g_warn_if_fail (group->name == NULL);
3195
3196   /* Note all keys must be comments at the top of
3197    * the file, so we can just free it all.
3198    */
3199   if (group->key_value_pairs != NULL)
3200     {
3201       g_list_foreach (group->key_value_pairs,
3202                       (GFunc) g_key_file_key_value_pair_free,
3203                       NULL);
3204       g_list_free (group->key_value_pairs);
3205       group->key_value_pairs = NULL;
3206     }
3207
3208   if (comment == NULL)
3209      return TRUE;
3210
3211   pair = g_slice_new (GKeyFileKeyValuePair);
3212   pair->key = NULL;
3213   pair->value = g_key_file_parse_comment_as_value (key_file, comment);
3214
3215   group->key_value_pairs =
3216     g_list_prepend (group->key_value_pairs, pair);
3217
3218   return TRUE;
3219 }
3220
3221 /**
3222  * g_key_file_set_comment:
3223  * @key_file: a #GKeyFile
3224  * @group_name: (allow-none): a group name, or %NULL
3225  * @key: (allow-none): a key
3226  * @comment: a comment
3227  * @error: return location for a #GError
3228  *
3229  * Places a comment above @key from @group_name.
3230  * If @key is %NULL then @comment will be written above @group_name.
3231  * If both @key and @group_name  are %NULL, then @comment will be
3232  * written above the first group in the file.
3233  *
3234  * Returns: %TRUE if the comment was written, %FALSE otherwise
3235  *
3236  * Since: 2.6
3237  **/
3238 gboolean
3239 g_key_file_set_comment (GKeyFile     *key_file,
3240                         const gchar  *group_name,
3241                         const gchar  *key,
3242                         const gchar  *comment,
3243                         GError      **error)
3244 {
3245   g_return_val_if_fail (key_file != NULL, FALSE);
3246
3247   if (group_name != NULL && key != NULL)
3248     {
3249       if (!g_key_file_set_key_comment (key_file, group_name, key, comment, error))
3250         return FALSE;
3251     }
3252   else if (group_name != NULL)
3253     {
3254       if (!g_key_file_set_group_comment (key_file, group_name, comment, error))
3255         return FALSE;
3256     }
3257   else
3258     {
3259       if (!g_key_file_set_top_comment (key_file, comment, error))
3260         return FALSE;
3261     }
3262
3263   if (comment != NULL)
3264     key_file->approximate_size += strlen (comment);
3265
3266   return TRUE;
3267 }
3268
3269 static gchar *
3270 g_key_file_get_key_comment (GKeyFile     *key_file,
3271                             const gchar  *group_name,
3272                             const gchar  *key,
3273                             GError      **error)
3274 {
3275   GKeyFileGroup *group;
3276   GKeyFileKeyValuePair *pair;
3277   GList *key_node, *tmp;
3278   GString *string;
3279   gchar *comment;
3280
3281   g_return_val_if_fail (g_key_file_is_group_name (group_name), NULL);
3282
3283   group = g_key_file_lookup_group (key_file, group_name);
3284   if (!group)
3285     {
3286       g_set_error (error, G_KEY_FILE_ERROR,
3287                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3288                    _("Key file does not have group '%s'"),
3289                    group_name ? group_name : "(null)");
3290
3291       return NULL;
3292     }
3293
3294   /* First find the key the comments are supposed to be
3295    * associated with
3296    */
3297   key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
3298
3299   if (key_node == NULL)
3300     {
3301       g_set_error (error, G_KEY_FILE_ERROR,
3302                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3303                    _("Key file does not have key '%s' in group '%s'"),
3304                    key, group->name);
3305       return NULL;
3306     }
3307
3308   string = NULL;
3309
3310   /* Then find all the comments already associated with the
3311    * key and concatentate them.
3312    */
3313   tmp = key_node->next;
3314   if (!key_node->next)
3315     return NULL;
3316
3317   pair = (GKeyFileKeyValuePair *) tmp->data;
3318   if (pair->key != NULL)
3319     return NULL;
3320
3321   while (tmp->next)
3322     {
3323       pair = (GKeyFileKeyValuePair *) tmp->next->data;
3324
3325       if (pair->key != NULL)
3326         break;
3327
3328       tmp = tmp->next;
3329     }
3330
3331   while (tmp != key_node)
3332     {
3333       pair = (GKeyFileKeyValuePair *) tmp->data;
3334
3335       if (string == NULL)
3336         string = g_string_sized_new (512);
3337
3338       comment = g_key_file_parse_value_as_comment (key_file, pair->value);
3339       g_string_append (string, comment);
3340       g_free (comment);
3341
3342       tmp = tmp->prev;
3343     }
3344
3345   if (string != NULL)
3346     {
3347       comment = string->str;
3348       g_string_free (string, FALSE);
3349     }
3350   else
3351     comment = NULL;
3352
3353   return comment;
3354 }
3355
3356 static gchar *
3357 get_group_comment (GKeyFile       *key_file,
3358                    GKeyFileGroup  *group,
3359                    GError        **error)
3360 {
3361   GString *string;
3362   GList *tmp;
3363   gchar *comment;
3364
3365   string = NULL;
3366
3367   tmp = group->key_value_pairs;
3368   while (tmp)
3369     {
3370       GKeyFileKeyValuePair *pair;
3371
3372       pair = (GKeyFileKeyValuePair *) tmp->data;
3373
3374       if (pair->key != NULL)
3375         {
3376           tmp = tmp->prev;
3377           break;
3378         }
3379
3380       if (tmp->next == NULL)
3381         break;
3382
3383       tmp = tmp->next;
3384     }
3385
3386   while (tmp != NULL)
3387     {
3388       GKeyFileKeyValuePair *pair;
3389
3390       pair = (GKeyFileKeyValuePair *) tmp->data;
3391
3392       if (string == NULL)
3393         string = g_string_sized_new (512);
3394
3395       comment = g_key_file_parse_value_as_comment (key_file, pair->value);
3396       g_string_append (string, comment);
3397       g_free (comment);
3398
3399       tmp = tmp->prev;
3400     }
3401
3402   if (string != NULL)
3403     return g_string_free (string, FALSE);
3404
3405   return NULL;
3406 }
3407
3408 static gchar *
3409 g_key_file_get_group_comment (GKeyFile     *key_file,
3410                               const gchar  *group_name,
3411                               GError      **error)
3412 {
3413   GList *group_node;
3414   GKeyFileGroup *group;
3415
3416   group = g_key_file_lookup_group (key_file, group_name);
3417   if (!group)
3418     {
3419       g_set_error (error, G_KEY_FILE_ERROR,
3420                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3421                    _("Key file does not have group '%s'"),
3422                    group_name ? group_name : "(null)");
3423
3424       return NULL;
3425     }
3426
3427   if (group->comment)
3428     return g_strdup (group->comment->value);
3429
3430   group_node = g_key_file_lookup_group_node (key_file, group_name);
3431   group_node = group_node->next;
3432   group = (GKeyFileGroup *)group_node->data;
3433   return get_group_comment (key_file, group, error);
3434 }
3435
3436 static gchar *
3437 g_key_file_get_top_comment (GKeyFile  *key_file,
3438                             GError   **error)
3439 {
3440   GList *group_node;
3441   GKeyFileGroup *group;
3442
3443   /* The last group in the list should be the top (comments only)
3444    * group in the file
3445    */
3446   g_warn_if_fail (key_file->groups != NULL);
3447   group_node = g_list_last (key_file->groups);
3448   group = (GKeyFileGroup *) group_node->data;
3449   g_warn_if_fail (group->name == NULL);
3450
3451   return get_group_comment (key_file, group, error);
3452 }
3453
3454 /**
3455  * g_key_file_get_comment:
3456  * @key_file: a #GKeyFile
3457  * @group_name: a group name, or %NULL
3458  * @key: a key
3459  * @error: return location for a #GError
3460  *
3461  * Retrieves a comment above @key from @group_name.
3462  * If @key is %NULL then @comment will be read from above
3463  * @group_name. If both @key and @group_name are %NULL, then
3464  * @comment will be read from above the first group in the file.
3465  *
3466  * Returns: a comment that should be freed with g_free()
3467  *
3468  * Since: 2.6
3469  **/
3470 gchar *
3471 g_key_file_get_comment (GKeyFile     *key_file,
3472                         const gchar  *group_name,
3473                         const gchar  *key,
3474                         GError      **error)
3475 {
3476   g_return_val_if_fail (key_file != NULL, NULL);
3477
3478   if (group_name != NULL && key != NULL)
3479     return g_key_file_get_key_comment (key_file, group_name, key, error);
3480   else if (group_name != NULL)
3481     return g_key_file_get_group_comment (key_file, group_name, error);
3482   else
3483     return g_key_file_get_top_comment (key_file, error);
3484 }
3485
3486 /**
3487  * g_key_file_remove_comment:
3488  * @key_file: a #GKeyFile
3489  * @group_name: (allow-none): a group name, or %NULL
3490  * @key: (allow-none): a key
3491  * @error: return location for a #GError
3492  *
3493  * Removes a comment above @key from @group_name.
3494  * If @key is %NULL then @comment will be removed above @group_name.
3495  * If both @key and @group_name are %NULL, then @comment will
3496  * be removed above the first group in the file.
3497  *
3498  * Returns: %TRUE if the comment was removed, %FALSE otherwise
3499  *
3500  * Since: 2.6
3501  **/
3502
3503 gboolean
3504 g_key_file_remove_comment (GKeyFile     *key_file,
3505                            const gchar  *group_name,
3506                            const gchar  *key,
3507                            GError      **error)
3508 {
3509   g_return_val_if_fail (key_file != NULL, FALSE);
3510
3511   if (group_name != NULL && key != NULL)
3512     return g_key_file_set_key_comment (key_file, group_name, key, NULL, error);
3513   else if (group_name != NULL)
3514     return g_key_file_set_group_comment (key_file, group_name, NULL, error);
3515   else
3516     return g_key_file_set_top_comment (key_file, NULL, error);
3517 }
3518
3519 /**
3520  * g_key_file_has_group:
3521  * @key_file: a #GKeyFile
3522  * @group_name: a group name
3523  *
3524  * Looks whether the key file has the group @group_name.
3525  *
3526  * Return value: %TRUE if @group_name is a part of @key_file, %FALSE
3527  * otherwise.
3528  * Since: 2.6
3529  **/
3530 gboolean
3531 g_key_file_has_group (GKeyFile    *key_file,
3532                       const gchar *group_name)
3533 {
3534   g_return_val_if_fail (key_file != NULL, FALSE);
3535   g_return_val_if_fail (group_name != NULL, FALSE);
3536
3537   return g_key_file_lookup_group (key_file, group_name) != NULL;
3538 }
3539
3540 /* This code remains from a historical attempt to add a new public API
3541  * which respects the GError rules.
3542  */
3543 static gboolean
3544 g_key_file_has_key_full (GKeyFile     *key_file,
3545                          const gchar  *group_name,
3546                          const gchar  *key,
3547                          gboolean     *has_key,
3548                          GError      **error)
3549 {
3550   GKeyFileKeyValuePair *pair;
3551   GKeyFileGroup *group;
3552
3553   g_return_val_if_fail (key_file != NULL, FALSE);
3554   g_return_val_if_fail (group_name != NULL, FALSE);
3555   g_return_val_if_fail (key != NULL, FALSE);
3556
3557   group = g_key_file_lookup_group (key_file, group_name);
3558
3559   if (!group)
3560     {
3561       g_set_error (error, G_KEY_FILE_ERROR,
3562                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3563                    _("Key file does not have group '%s'"),
3564                    group_name ? group_name : "(null)");
3565
3566       return FALSE;
3567     }
3568
3569   pair = g_key_file_lookup_key_value_pair (key_file, group, key);
3570
3571   if (has_key)
3572     *has_key = pair != NULL;
3573   return TRUE;
3574 }
3575
3576 /**
3577  * g_key_file_has_key: (skip)
3578  * @key_file: a #GKeyFile
3579  * @group_name: a group name
3580  * @key: a key name
3581  * @error: return location for a #GError
3582  *
3583  * Looks whether the key file has the key @key in the group
3584  * @group_name.
3585  *
3586  * <note>This function does not follow the rules for #GError strictly;
3587  * the return value both carries meaning and signals an error.  To use
3588  * this function, you must pass a #GError pointer in @error, and check
3589  * whether it is not %NULL to see if an error occurred.</note>
3590  *
3591  * Language bindings should use g_key_file_get_value() to test whether
3592  * or not a key exists.
3593  *
3594  * Return value: %TRUE if @key is a part of @group_name, %FALSE
3595  * otherwise.
3596  *
3597  * Since: 2.6
3598  **/
3599 gboolean
3600 g_key_file_has_key (GKeyFile     *key_file,
3601                     const gchar  *group_name,
3602                     const gchar  *key,
3603                     GError      **error)
3604 {
3605   GError *temp_error = NULL;
3606   gboolean has_key;
3607
3608   if (g_key_file_has_key_full (key_file, group_name, key, &has_key, &temp_error))
3609     {
3610       return has_key;
3611     }
3612   else
3613     {
3614       g_propagate_error (error, temp_error);
3615       return FALSE;
3616     }
3617 }
3618
3619 static void
3620 g_key_file_add_group (GKeyFile    *key_file,
3621                       const gchar *group_name)
3622 {
3623   GKeyFileGroup *group;
3624
3625   g_return_if_fail (key_file != NULL);
3626   g_return_if_fail (g_key_file_is_group_name (group_name));
3627
3628   group = g_key_file_lookup_group (key_file, group_name);
3629   if (group != NULL)
3630     {
3631       key_file->current_group = group;
3632       return;
3633     }
3634
3635   group = g_slice_new0 (GKeyFileGroup);
3636   group->name = g_strdup (group_name);
3637   group->lookup_map = g_hash_table_new (g_str_hash, g_str_equal);
3638   key_file->groups = g_list_prepend (key_file->groups, group);
3639   key_file->approximate_size += strlen (group_name) + 3;
3640   key_file->current_group = group;
3641
3642   if (key_file->start_group == NULL)
3643     key_file->start_group = group;
3644
3645   g_hash_table_insert (key_file->group_hash, (gpointer)group->name, group);
3646 }
3647
3648 static void
3649 g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair)
3650 {
3651   if (pair != NULL)
3652     {
3653       g_free (pair->key);
3654       g_free (pair->value);
3655       g_slice_free (GKeyFileKeyValuePair, pair);
3656     }
3657 }
3658
3659 /* Be careful not to call this function on a node with data in the
3660  * lookup map without removing it from the lookup map, first.
3661  *
3662  * Some current cases where this warning is not a concern are
3663  * when:
3664  *   - the node being removed is a comment node
3665  *   - the entire lookup map is getting destroyed soon after
3666  *     anyway.
3667  */
3668 static void
3669 g_key_file_remove_key_value_pair_node (GKeyFile      *key_file,
3670                                        GKeyFileGroup *group,
3671                                        GList         *pair_node)
3672 {
3673
3674   GKeyFileKeyValuePair *pair;
3675
3676   pair = (GKeyFileKeyValuePair *) pair_node->data;
3677
3678   group->key_value_pairs = g_list_remove_link (group->key_value_pairs, pair_node);
3679
3680   if (pair->key != NULL)
3681     key_file->approximate_size -= strlen (pair->key) + 1;
3682
3683   g_warn_if_fail (pair->value != NULL);
3684   key_file->approximate_size -= strlen (pair->value);
3685
3686   g_key_file_key_value_pair_free (pair);
3687
3688   g_list_free_1 (pair_node);
3689 }
3690
3691 static void
3692 g_key_file_remove_group_node (GKeyFile *key_file,
3693                               GList    *group_node)
3694 {
3695   GKeyFileGroup *group;
3696   GList *tmp;
3697
3698   group = (GKeyFileGroup *) group_node->data;
3699
3700   if (group->name)
3701     g_hash_table_remove (key_file->group_hash, group->name);
3702
3703   /* If the current group gets deleted make the current group the last
3704    * added group.
3705    */
3706   if (key_file->current_group == group)
3707     {
3708       /* groups should always contain at least the top comment group,
3709        * unless g_key_file_clear has been called
3710        */
3711       if (key_file->groups)
3712         key_file->current_group = (GKeyFileGroup *) key_file->groups->data;
3713       else
3714         key_file->current_group = NULL;
3715     }
3716
3717   /* If the start group gets deleted make the start group the first
3718    * added group.
3719    */
3720   if (key_file->start_group == group)
3721     {
3722       tmp = g_list_last (key_file->groups);
3723       while (tmp != NULL)
3724         {
3725           if (tmp != group_node &&
3726               ((GKeyFileGroup *) tmp->data)->name != NULL)
3727             break;
3728
3729           tmp = tmp->prev;
3730         }
3731
3732       if (tmp)
3733         key_file->start_group = (GKeyFileGroup *) tmp->data;
3734       else
3735         key_file->start_group = NULL;
3736     }
3737
3738   key_file->groups = g_list_remove_link (key_file->groups, group_node);
3739
3740   if (group->name != NULL)
3741     key_file->approximate_size -= strlen (group->name) + 3;
3742
3743   tmp = group->key_value_pairs;
3744   while (tmp != NULL)
3745     {
3746       GList *pair_node;
3747
3748       pair_node = tmp;
3749       tmp = tmp->next;
3750       g_key_file_remove_key_value_pair_node (key_file, group, pair_node);
3751     }
3752
3753   g_warn_if_fail (group->key_value_pairs == NULL);
3754
3755   if (group->lookup_map)
3756     {
3757       g_hash_table_destroy (group->lookup_map);
3758       group->lookup_map = NULL;
3759     }
3760
3761   g_free ((gchar *) group->name);
3762   g_slice_free (GKeyFileGroup, group);
3763   g_list_free_1 (group_node);
3764 }
3765
3766 /**
3767  * g_key_file_remove_group:
3768  * @key_file: a #GKeyFile
3769  * @group_name: a group name
3770  * @error: return location for a #GError or %NULL
3771  *
3772  * Removes the specified group, @group_name,
3773  * from the key file.
3774  *
3775  * Returns: %TRUE if the group was removed, %FALSE otherwise
3776  *
3777  * Since: 2.6
3778  **/
3779 gboolean
3780 g_key_file_remove_group (GKeyFile     *key_file,
3781                          const gchar  *group_name,
3782                          GError      **error)
3783 {
3784   GList *group_node;
3785
3786   g_return_val_if_fail (key_file != NULL, FALSE);
3787   g_return_val_if_fail (group_name != NULL, FALSE);
3788
3789   group_node = g_key_file_lookup_group_node (key_file, group_name);
3790
3791   if (!group_node)
3792     {
3793       g_set_error (error, G_KEY_FILE_ERROR,
3794                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3795                    _("Key file does not have group '%s'"),
3796                    group_name);
3797       return FALSE;
3798     }
3799
3800   g_key_file_remove_group_node (key_file, group_node);
3801
3802   return TRUE;
3803 }
3804
3805 static void
3806 g_key_file_add_key_value_pair (GKeyFile             *key_file,
3807                                GKeyFileGroup        *group,
3808                                GKeyFileKeyValuePair *pair)
3809 {
3810   g_hash_table_replace (group->lookup_map, pair->key, pair);
3811   group->key_value_pairs = g_list_prepend (group->key_value_pairs, pair);
3812   group->has_trailing_blank_line = FALSE;
3813   key_file->approximate_size += strlen (pair->key) + strlen (pair->value) + 2;
3814 }
3815
3816 static void
3817 g_key_file_add_key (GKeyFile      *key_file,
3818                     GKeyFileGroup *group,
3819                     const gchar   *key,
3820                     const gchar   *value)
3821 {
3822   GKeyFileKeyValuePair *pair;
3823
3824   pair = g_slice_new (GKeyFileKeyValuePair);
3825   pair->key = g_strdup (key);
3826   pair->value = g_strdup (value);
3827
3828   g_key_file_add_key_value_pair (key_file, group, pair);
3829 }
3830
3831 /**
3832  * g_key_file_remove_key:
3833  * @key_file: a #GKeyFile
3834  * @group_name: a group name
3835  * @key: a key name to remove
3836  * @error: return location for a #GError or %NULL
3837  *
3838  * Removes @key in @group_name from the key file.
3839  *
3840  * Returns: %TRUE if the key was removed, %FALSE otherwise
3841  *
3842  * Since: 2.6
3843  **/
3844 gboolean
3845 g_key_file_remove_key (GKeyFile     *key_file,
3846                        const gchar  *group_name,
3847                        const gchar  *key,
3848                        GError      **error)
3849 {
3850   GKeyFileGroup *group;
3851   GKeyFileKeyValuePair *pair;
3852
3853   g_return_val_if_fail (key_file != NULL, FALSE);
3854   g_return_val_if_fail (group_name != NULL, FALSE);
3855   g_return_val_if_fail (key != NULL, FALSE);
3856
3857   pair = NULL;
3858
3859   group = g_key_file_lookup_group (key_file, group_name);
3860   if (!group)
3861     {
3862       g_set_error (error, G_KEY_FILE_ERROR,
3863                    G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
3864                    _("Key file does not have group '%s'"),
3865                    group_name ? group_name : "(null)");
3866       return FALSE;
3867     }
3868
3869   pair = g_key_file_lookup_key_value_pair (key_file, group, key);
3870
3871   if (!pair)
3872     {
3873       g_set_error (error, G_KEY_FILE_ERROR,
3874                    G_KEY_FILE_ERROR_KEY_NOT_FOUND,
3875                    _("Key file does not have key '%s' in group '%s'"),
3876                    key, group->name);
3877       return FALSE;
3878     }
3879
3880   key_file->approximate_size -= strlen (pair->key) + strlen (pair->value) + 2;
3881
3882   group->key_value_pairs = g_list_remove (group->key_value_pairs, pair);
3883   g_hash_table_remove (group->lookup_map, pair->key);
3884   g_key_file_key_value_pair_free (pair);
3885
3886   return TRUE;
3887 }
3888
3889 static GList *
3890 g_key_file_lookup_group_node (GKeyFile    *key_file,
3891                               const gchar *group_name)
3892 {
3893   GKeyFileGroup *group;
3894   GList *tmp;
3895
3896   for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
3897     {
3898       group = (GKeyFileGroup *) tmp->data;
3899
3900       if (group && group->name && strcmp (group->name, group_name) == 0)
3901         break;
3902     }
3903
3904   return tmp;
3905 }
3906
3907 static GKeyFileGroup *
3908 g_key_file_lookup_group (GKeyFile    *key_file,
3909                          const gchar *group_name)
3910 {
3911   return (GKeyFileGroup *)g_hash_table_lookup (key_file->group_hash, group_name);
3912 }
3913
3914 static GList *
3915 g_key_file_lookup_key_value_pair_node (GKeyFile       *key_file,
3916                                        GKeyFileGroup  *group,
3917                                        const gchar    *key)
3918 {
3919   GList *key_node;
3920
3921   for (key_node = group->key_value_pairs;
3922        key_node != NULL;
3923        key_node = key_node->next)
3924     {
3925       GKeyFileKeyValuePair *pair;
3926
3927       pair = (GKeyFileKeyValuePair *) key_node->data;
3928
3929       if (pair->key && strcmp (pair->key, key) == 0)
3930         break;
3931     }
3932
3933   return key_node;
3934 }
3935
3936 static GKeyFileKeyValuePair *
3937 g_key_file_lookup_key_value_pair (GKeyFile      *key_file,
3938                                   GKeyFileGroup *group,
3939                                   const gchar   *key)
3940 {
3941   return (GKeyFileKeyValuePair *) g_hash_table_lookup (group->lookup_map, key);
3942 }
3943
3944 /* Lines starting with # or consisting entirely of whitespace are merely
3945  * recorded, not parsed. This function assumes all leading whitespace
3946  * has been stripped.
3947  */
3948 static gboolean
3949 g_key_file_line_is_comment (const gchar *line)
3950 {
3951   return (*line == '#' || *line == '\0' || *line == '\n');
3952 }
3953
3954 static gboolean
3955 g_key_file_is_group_name (const gchar *name)
3956 {
3957   gchar *p, *q;
3958
3959   if (name == NULL)
3960     return FALSE;
3961
3962   p = q = (gchar *) name;
3963   while (*q && *q != ']' && *q != '[' && !g_ascii_iscntrl (*q))
3964     q = g_utf8_find_next_char (q, NULL);
3965
3966   if (*q != '\0' || q == p)
3967     return FALSE;
3968
3969   return TRUE;
3970 }
3971
3972 static gboolean
3973 g_key_file_is_key_name (const gchar *name)
3974 {
3975   gchar *p, *q;
3976
3977   if (name == NULL)
3978     return FALSE;
3979
3980   p = q = (gchar *) name;
3981   /* We accept a little more than the desktop entry spec says,
3982    * since gnome-vfs uses mime-types as keys in its cache.
3983    */
3984   while (*q && *q != '=' && *q != '[' && *q != ']')
3985     q = g_utf8_find_next_char (q, NULL);
3986
3987   /* No empty keys, please */
3988   if (q == p)
3989     return FALSE;
3990
3991   /* We accept spaces in the middle of keys to not break
3992    * existing apps, but we don't tolerate initial or final
3993    * spaces, which would lead to silent corruption when
3994    * rereading the file.
3995    */
3996   if (*p == ' ' || q[-1] == ' ')
3997     return FALSE;
3998
3999   if (*q == '[')
4000     {
4001       q++;
4002       while (*q && (g_unichar_isalnum (g_utf8_get_char_validated (q, -1)) || *q == '-' || *q == '_' || *q == '.' || *q == '@'))
4003         q = g_utf8_find_next_char (q, NULL);
4004
4005       if (*q != ']')
4006         return FALSE;
4007
4008       q++;
4009     }
4010
4011   if (*q != '\0')
4012     return FALSE;
4013
4014   return TRUE;
4015 }
4016
4017 /* A group in a key file is made up of a starting '[' followed by one
4018  * or more letters making up the group name followed by ']'.
4019  */
4020 static gboolean
4021 g_key_file_line_is_group (const gchar *line)
4022 {
4023   gchar *p;
4024
4025   p = (gchar *) line;
4026   if (*p != '[')
4027     return FALSE;
4028
4029   p++;
4030
4031   while (*p && *p != ']')
4032     p = g_utf8_find_next_char (p, NULL);
4033
4034   if (*p != ']')
4035     return FALSE;
4036
4037   /* silently accept whitespace after the ] */
4038   p = g_utf8_find_next_char (p, NULL);
4039   while (*p == ' ' || *p == '\t')
4040     p = g_utf8_find_next_char (p, NULL);
4041
4042   if (*p)
4043     return FALSE;
4044
4045   return TRUE;
4046 }
4047
4048 static gboolean
4049 g_key_file_line_is_key_value_pair (const gchar *line)
4050 {
4051   gchar *p;
4052
4053   p = (gchar *) g_utf8_strchr (line, -1, '=');
4054
4055   if (!p)
4056     return FALSE;
4057
4058   /* Key must be non-empty
4059    */
4060   if (*p == line[0])
4061     return FALSE;
4062
4063   return TRUE;
4064 }
4065
4066 static gchar *
4067 g_key_file_parse_value_as_string (GKeyFile     *key_file,
4068                                   const gchar  *value,
4069                                   GSList      **pieces,
4070                                   GError      **error)
4071 {
4072   gchar *string_value, *p, *q0, *q;
4073
4074   string_value = g_new (gchar, strlen (value) + 1);
4075
4076   p = (gchar *) value;
4077   q0 = q = string_value;
4078   while (*p)
4079     {
4080       if (*p == '\\')
4081         {
4082           p++;
4083
4084           switch (*p)
4085             {
4086             case 's':
4087               *q = ' ';
4088               break;
4089
4090             case 'n':
4091               *q = '\n';
4092               break;
4093
4094             case 't':
4095               *q = '\t';
4096               break;
4097
4098             case 'r':
4099               *q = '\r';
4100               break;
4101
4102             case '\\':
4103               *q = '\\';
4104               break;
4105
4106             case '\0':
4107               g_set_error_literal (error, G_KEY_FILE_ERROR,
4108                                    G_KEY_FILE_ERROR_INVALID_VALUE,
4109                                    _("Key file contains escape character "
4110                                      "at end of line"));
4111               break;
4112
4113             default:
4114               if (pieces && *p == key_file->list_separator)
4115                 *q = key_file->list_separator;
4116               else
4117                 {
4118                   *q++ = '\\';
4119                   *q = *p;
4120
4121                   if (*error == NULL)
4122                     {
4123                       gchar sequence[3];
4124
4125                       sequence[0] = '\\';
4126                       sequence[1] = *p;
4127                       sequence[2] = '\0';
4128
4129                       g_set_error (error, G_KEY_FILE_ERROR,
4130                                    G_KEY_FILE_ERROR_INVALID_VALUE,
4131                                    _("Key file contains invalid escape "
4132                                      "sequence '%s'"), sequence);
4133                     }
4134                 }
4135               break;
4136             }
4137         }
4138       else
4139         {
4140           *q = *p;
4141           if (pieces && (*p == key_file->list_separator))
4142             {
4143               *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
4144               q0 = q + 1;
4145             }
4146         }
4147
4148       if (*p == '\0')
4149         break;
4150
4151       q++;
4152       p++;
4153     }
4154
4155   *q = '\0';
4156   if (pieces)
4157   {
4158     if (q0 < q)
4159       *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
4160     *pieces = g_slist_reverse (*pieces);
4161   }
4162
4163   return string_value;
4164 }
4165
4166 static gchar *
4167 g_key_file_parse_string_as_value (GKeyFile    *key_file,
4168                                   const gchar *string,
4169                                   gboolean     escape_separator)
4170 {
4171   gchar *value, *p, *q;
4172   gsize length;
4173   gboolean parsing_leading_space;
4174
4175   length = strlen (string) + 1;
4176
4177   /* Worst case would be that every character needs to be escaped.
4178    * In other words every character turns to two characters
4179    */
4180   value = g_new (gchar, 2 * length);
4181
4182   p = (gchar *) string;
4183   q = value;
4184   parsing_leading_space = TRUE;
4185   while (p < (string + length - 1))
4186     {
4187       gchar escaped_character[3] = { '\\', 0, 0 };
4188
4189       switch (*p)
4190         {
4191         case ' ':
4192           if (parsing_leading_space)
4193             {
4194               escaped_character[1] = 's';
4195               strcpy (q, escaped_character);
4196               q += 2;
4197             }
4198           else
4199             {
4200               *q = *p;
4201               q++;
4202             }
4203           break;
4204         case '\t':
4205           if (parsing_leading_space)
4206             {
4207               escaped_character[1] = 't';
4208               strcpy (q, escaped_character);
4209               q += 2;
4210             }
4211           else
4212             {
4213               *q = *p;
4214               q++;
4215             }
4216           break;
4217         case '\n':
4218           escaped_character[1] = 'n';
4219           strcpy (q, escaped_character);
4220           q += 2;
4221           break;
4222         case '\r':
4223           escaped_character[1] = 'r';
4224           strcpy (q, escaped_character);
4225           q += 2;
4226           break;
4227         case '\\':
4228           escaped_character[1] = '\\';
4229           strcpy (q, escaped_character);
4230           q += 2;
4231           parsing_leading_space = FALSE;
4232           break;
4233         default:
4234           if (escape_separator && *p == key_file->list_separator)
4235             {
4236               escaped_character[1] = key_file->list_separator;
4237               strcpy (q, escaped_character);
4238               q += 2;
4239               parsing_leading_space = TRUE;
4240             }
4241           else
4242             {
4243               *q = *p;
4244               q++;
4245               parsing_leading_space = FALSE;
4246             }
4247           break;
4248         }
4249       p++;
4250     }
4251   *q = '\0';
4252
4253   return value;
4254 }
4255
4256 static gint
4257 g_key_file_parse_value_as_integer (GKeyFile     *key_file,
4258                                    const gchar  *value,
4259                                    GError      **error)
4260 {
4261   gchar *eof_int;
4262   glong long_value;
4263   gint int_value;
4264
4265   errno = 0;
4266   long_value = strtol (value, &eof_int, 10);
4267
4268   if (*value == '\0' || (*eof_int != '\0' && !g_ascii_isspace(*eof_int)))
4269     {
4270       gchar *value_utf8 = _g_utf8_make_valid (value);
4271       g_set_error (error, G_KEY_FILE_ERROR,
4272                    G_KEY_FILE_ERROR_INVALID_VALUE,
4273                    _("Value '%s' cannot be interpreted "
4274                      "as a number."), value_utf8);
4275       g_free (value_utf8);
4276
4277       return 0;
4278     }
4279
4280   int_value = long_value;
4281   if (int_value != long_value || errno == ERANGE)
4282     {
4283       gchar *value_utf8 = _g_utf8_make_valid (value);
4284       g_set_error (error,
4285                    G_KEY_FILE_ERROR,
4286                    G_KEY_FILE_ERROR_INVALID_VALUE,
4287                    _("Integer value '%s' out of range"),
4288                    value_utf8);
4289       g_free (value_utf8);
4290
4291       return 0;
4292     }
4293
4294   return int_value;
4295 }
4296
4297 static gchar *
4298 g_key_file_parse_integer_as_value (GKeyFile *key_file,
4299                                    gint      value)
4300
4301 {
4302   return g_strdup_printf ("%d", value);
4303 }
4304
4305 static gdouble
4306 g_key_file_parse_value_as_double  (GKeyFile     *key_file,
4307                                    const gchar  *value,
4308                                    GError      **error)
4309 {
4310   gchar *end_of_valid_d;
4311   gdouble double_value = 0;
4312
4313   double_value = g_ascii_strtod (value, &end_of_valid_d);
4314
4315   if (*end_of_valid_d != '\0' || end_of_valid_d == value)
4316     {
4317       gchar *value_utf8 = _g_utf8_make_valid (value);
4318       g_set_error (error, G_KEY_FILE_ERROR,
4319                    G_KEY_FILE_ERROR_INVALID_VALUE,
4320                    _("Value '%s' cannot be interpreted "
4321                      "as a float number."),
4322                    value_utf8);
4323       g_free (value_utf8);
4324     }
4325
4326   return double_value;
4327 }
4328
4329 static gboolean
4330 g_key_file_parse_value_as_boolean (GKeyFile     *key_file,
4331                                    const gchar  *value,
4332                                    GError      **error)
4333 {
4334   gchar *value_utf8;
4335
4336   if (strcmp (value, "true") == 0 || strcmp (value, "1") == 0)
4337     return TRUE;
4338   else if (strcmp (value, "false") == 0 || strcmp (value, "0") == 0)
4339     return FALSE;
4340
4341   value_utf8 = _g_utf8_make_valid (value);
4342   g_set_error (error, G_KEY_FILE_ERROR,
4343                G_KEY_FILE_ERROR_INVALID_VALUE,
4344                _("Value '%s' cannot be interpreted "
4345                  "as a boolean."), value_utf8);
4346   g_free (value_utf8);
4347
4348   return FALSE;
4349 }
4350
4351 static gchar *
4352 g_key_file_parse_boolean_as_value (GKeyFile *key_file,
4353                                    gboolean  value)
4354 {
4355   if (value)
4356     return g_strdup ("true");
4357   else
4358     return g_strdup ("false");
4359 }
4360
4361 static gchar *
4362 g_key_file_parse_value_as_comment (GKeyFile    *key_file,
4363                                    const gchar *value)
4364 {
4365   GString *string;
4366   gchar **lines;
4367   gsize i;
4368
4369   string = g_string_sized_new (512);
4370
4371   lines = g_strsplit (value, "\n", 0);
4372
4373   for (i = 0; lines[i] != NULL; i++)
4374     {
4375         if (lines[i][0] != '#')
4376            g_string_append_printf (string, "%s\n", lines[i]);
4377         else
4378            g_string_append_printf (string, "%s\n", lines[i] + 1);
4379     }
4380   g_strfreev (lines);
4381
4382   return g_string_free (string, FALSE);
4383 }
4384
4385 static gchar *
4386 g_key_file_parse_comment_as_value (GKeyFile      *key_file,
4387                                    const gchar   *comment)
4388 {
4389   GString *string;
4390   gchar **lines;
4391   gsize i;
4392
4393   string = g_string_sized_new (512);
4394
4395   lines = g_strsplit (comment, "\n", 0);
4396
4397   for (i = 0; lines[i] != NULL; i++)
4398     g_string_append_printf (string, "#%s%s", lines[i],
4399                             lines[i + 1] == NULL? "" : "\n");
4400   g_strfreev (lines);
4401
4402   return g_string_free (string, FALSE);
4403 }