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