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