1 /* gkeyfile.c - key file parser
3 * Copyright 2004 Red Hat, Inc.
5 * Written by Ray Strode <rstrode@redhat.com>
6 * Matthias Clasen <mclasen@redhat.com>
8 * GLib is free software; you can redistribute it and/or modify it
9 * under the terms of the GNU Lesser General Public License as
10 * published by the Free Software Foundation; either version 2 of the
11 * License, or (at your option) any later version.
13 * GLib is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with GLib; see the file COPYING.LIB. If not,
20 * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
35 #include <sys/types.h>
47 #include "gfileutils.h"
53 #include "gmessages.h"
56 #include "gstrfuncs.h"
59 typedef struct _GKeyFileGroup GKeyFileGroup;
65 gchar *start_group_name;
67 GKeyFileGroup *current_group;
69 GString *parse_buffer; /* Holds up to one line of not-yet-parsed data */
71 /* Used for sizing the output buffer during serialization
73 gsize approximate_size;
80 typedef struct _GKeyFileKeyValuePair GKeyFileKeyValuePair;
84 const gchar *name; /* NULL for above first group (which will be comments) */
86 GKeyFileKeyValuePair *comment; /* Special comment that is stuck to the top of a group */
88 GList *key_value_pairs;
90 /* Used in parallel with key_value_pairs for
91 * increased lookup performance
93 GHashTable *lookup_map;
96 struct _GKeyFileKeyValuePair
98 gchar *key; /* NULL for comments */
102 static gint find_file_in_data_dirs (const gchar *file,
106 static gboolean g_key_file_load_from_fd (GKeyFile *key_file,
110 static GList *g_key_file_lookup_group_node (GKeyFile *key_file,
111 const gchar *group_name);
112 static GKeyFileGroup *g_key_file_lookup_group (GKeyFile *key_file,
113 const gchar *group_name);
115 static GList *g_key_file_lookup_key_value_pair_node (GKeyFile *key_file,
116 GKeyFileGroup *group,
118 static GKeyFileKeyValuePair *g_key_file_lookup_key_value_pair (GKeyFile *key_file,
119 GKeyFileGroup *group,
122 static void g_key_file_remove_group_node (GKeyFile *entry,
124 static void g_key_file_remove_key_value_pair_node (GKeyFile *key_file,
125 GKeyFileGroup *group,
128 static void g_key_file_add_key (GKeyFile *entry,
129 const gchar *group_name,
132 static void g_key_file_add_group (GKeyFile *entry,
133 const gchar *group_name);
134 static void g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair);
135 static gboolean g_key_file_line_is_comment (const gchar *line);
136 static gboolean g_key_file_line_is_group (const gchar *line);
137 static gboolean g_key_file_line_is_key_value_pair (const gchar *line);
138 static gchar *g_key_file_parse_value_as_string (GKeyFile *entry,
142 static gchar *g_key_file_parse_string_as_value (GKeyFile *entry,
144 gboolean escape_separator);
145 static gint g_key_file_parse_value_as_integer (GKeyFile *entry,
148 static gchar *g_key_file_parse_integer_as_value (GKeyFile *entry,
150 static gboolean g_key_file_parse_value_as_boolean (GKeyFile *entry,
153 static gchar *g_key_file_parse_boolean_as_value (GKeyFile *entry,
155 static gchar *g_key_file_parse_value_as_comment (GKeyFile *key_file,
157 static gchar *g_key_file_parse_comment_as_value (GKeyFile *key_file,
158 const gchar *comment);
159 static void g_key_file_parse_key_value_pair (GKeyFile *entry,
163 static void g_key_file_parse_comment (GKeyFile *entry,
167 static void g_key_file_parse_group (GKeyFile *entry,
171 static gchar *key_get_locale (const gchar *key);
172 static void g_key_file_parse_data (GKeyFile *entry,
176 static void g_key_file_flush_parse_buffer (GKeyFile *entry,
181 g_key_file_error_quark (void)
183 static GQuark error_quark = 0;
185 if (error_quark == 0)
186 error_quark = g_quark_from_static_string ("g-key-file-error-quark");
192 g_key_file_init (GKeyFile *key_file)
194 key_file->current_group = g_new0 (GKeyFileGroup, 1);
195 key_file->groups = g_list_prepend (NULL, key_file->current_group);
196 key_file->start_group_name = NULL;
197 key_file->parse_buffer = g_string_sized_new (128);
198 key_file->approximate_size = 0;
199 key_file->list_separator = ';';
204 g_key_file_clear (GKeyFile *key_file)
206 GList *tmp, *group_node;
208 if (key_file->parse_buffer)
209 g_string_free (key_file->parse_buffer, TRUE);
211 g_free (key_file->start_group_name);
213 tmp = key_file->groups;
218 g_key_file_remove_group_node (key_file, group_node);
221 g_assert (key_file->groups == NULL);
228 * Creates a new empty #GKeyFile object. Use g_key_file_load_from_file(),
229 * g_key_file_load_from_data() or g_key_file_load_from_data_dirs() to
230 * read an existing key file.
232 * Return value: an empty #GKeyFile.
237 g_key_file_new (void)
241 key_file = g_new0 (GKeyFile, 1);
242 g_key_file_init (key_file);
248 * g_key_file_set_list_separator:
249 * @key_file: a #GKeyFile
250 * @separator: the separator
252 * Sets the character which is used to separate
253 * values in lists. Typically ';' or ',' are used
254 * as separators. The default list separator is ';'.
259 g_key_file_set_list_separator (GKeyFile *key_file,
262 key_file->list_separator = separator;
266 /* Iterates through all the directories in *dirs trying to
267 * open file. When it successfully locates and opens a file it
268 * returns the file descriptor to the open file. It also
269 * outputs the absolute path of the file in output_file and
270 * leaves the unchecked directories in *dirs.
273 find_file_in_data_dirs (const gchar *file,
278 gchar **data_dirs, *data_dir, *path;
289 while (data_dirs && (data_dir = *data_dirs) && fd < 0)
291 gchar *candidate_file, *sub_dir;
293 candidate_file = (gchar *) file;
294 sub_dir = g_strdup ("");
295 while (candidate_file != NULL && fd < 0)
299 path = g_build_filename (data_dir, sub_dir,
300 candidate_file, NULL);
302 fd = g_open (path, O_RDONLY, 0);
310 candidate_file = strchr (candidate_file, '-');
312 if (candidate_file == NULL)
318 sub_dir = g_strndup (file, candidate_file - file - 1);
320 for (p = sub_dir; *p != '\0'; p++)
323 *p = G_DIR_SEPARATOR;
334 g_set_error (error, G_KEY_FILE_ERROR,
335 G_KEY_FILE_ERROR_NOT_FOUND,
336 _("Valid key file could not be "
337 "found in data dirs"));
340 if (output_file != NULL && fd > 0)
341 *output_file = g_strdup (path);
347 g_key_file_load_from_fd (GKeyFile *key_file,
352 GError *key_file_error = NULL;
354 struct stat stat_buf;
355 gchar read_buf[4096];
357 if (fstat (fd, &stat_buf) < 0)
359 g_set_error (error, G_FILE_ERROR,
360 g_file_error_from_errno (errno),
361 "%s", g_strerror (errno));
365 if ((stat_buf.st_mode & S_IFMT) != S_IFREG)
367 g_set_error (error, G_KEY_FILE_ERROR,
368 G_KEY_FILE_ERROR_PARSE,
369 _("Not a regular file"));
373 if (stat_buf.st_size == 0)
375 g_set_error (error, G_KEY_FILE_ERROR,
376 G_KEY_FILE_ERROR_PARSE,
381 if (key_file->approximate_size > 0)
383 g_key_file_clear (key_file);
384 g_key_file_init (key_file);
386 key_file->flags = flags;
391 bytes_read = read (fd, read_buf, 4096);
393 if (bytes_read == 0) /* End of File */
398 if (errno == EINTR || errno == EAGAIN)
401 g_set_error (error, G_FILE_ERROR,
402 g_file_error_from_errno (errno),
403 "%s", g_strerror (errno));
407 g_key_file_parse_data (key_file,
408 read_buf, bytes_read,
411 while (!key_file_error);
415 g_propagate_error (error, key_file_error);
419 g_key_file_flush_parse_buffer (key_file, &key_file_error);
423 g_propagate_error (error, key_file_error);
431 * g_key_file_load_from_file:
432 * @key_file: an empty #GKeyFile struct
433 * @file: the path of a filename to load, in the GLib file name encoding
434 * @flags: flags from #GKeyFileFlags
435 * @error: return location for a #GError, or %NULL
437 * Loads a key file into an empty #GKeyFile structure.
438 * If the file could not be loaded then %error is set to
439 * either a #GFileError or #GKeyFileError.
441 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
445 g_key_file_load_from_file (GKeyFile *key_file,
450 GError *key_file_error = NULL;
453 g_return_val_if_fail (key_file != NULL, FALSE);
454 g_return_val_if_fail (file != NULL, FALSE);
456 fd = g_open (file, O_RDONLY, 0);
460 g_set_error (error, G_FILE_ERROR,
461 g_file_error_from_errno (errno),
462 "%s", g_strerror (errno));
466 g_key_file_load_from_fd (key_file, fd, flags, &key_file_error);
471 g_propagate_error (error, key_file_error);
479 * g_key_file_load_from_data:
480 * @key_file: an empty #GKeyFile struct
481 * @data: key file loaded in memory.
482 * @length: the length of @data in bytes
483 * @flags: flags from #GKeyFileFlags
484 * @error: return location for a #GError, or %NULL
486 * Loads a key file from memory into an empty #GKeyFile structure.
487 * If the object cannot be created then %error is set to a #GKeyFileError.
489 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
493 g_key_file_load_from_data (GKeyFile *key_file,
499 GError *key_file_error = NULL;
501 g_return_val_if_fail (key_file != NULL, FALSE);
502 g_return_val_if_fail (data != NULL, FALSE);
503 g_return_val_if_fail (length != 0, FALSE);
505 if (key_file->approximate_size > 0)
507 g_key_file_clear (key_file);
508 g_key_file_init (key_file);
510 key_file->flags = flags;
512 g_key_file_parse_data (key_file, data, length, &key_file_error);
516 g_propagate_error (error, key_file_error);
520 g_key_file_flush_parse_buffer (key_file, &key_file_error);
524 g_propagate_error (error, key_file_error);
532 * g_key_file_load_from_data_dirs:
533 * @key_file: an empty #GKeyFile struct
534 * @file: a relative path to a filename to open and parse
535 * @full_path: return location for a string containing the full path
536 * of the file, or %NULL
537 * @flags: flags from #GKeyFileFlags
538 * @error: return location for a #GError, or %NULL
540 * This function looks for a key file named @file in the paths
541 * returned from g_get_user_data_dir() and g_get_system_data_dirs(),
542 * loads the file into @key_file and returns the file's full path in
543 * @full_path. If the file could not be loaded then an %error is
544 * set to either a #GFileError or #GKeyFileError.
546 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
550 g_key_file_load_from_data_dirs (GKeyFile *key_file,
556 GError *key_file_error = NULL;
557 gchar **all_data_dirs, **data_dirs;
558 const gchar * user_data_dir;
559 const gchar * const * system_data_dirs;
565 g_return_val_if_fail (key_file != NULL, FALSE);
566 g_return_val_if_fail (!g_path_is_absolute (file), FALSE);
568 user_data_dir = g_get_user_data_dir ();
569 system_data_dirs = g_get_system_data_dirs ();
570 all_data_dirs = g_new0 (gchar *, g_strv_length ((gchar **)system_data_dirs) + 2);
573 all_data_dirs[i++] = g_strdup (user_data_dir);
576 while (system_data_dirs[j] != NULL)
577 all_data_dirs[i++] = g_strdup (system_data_dirs[j++]);
580 data_dirs = all_data_dirs;
581 while (*data_dirs != NULL && !found_file)
583 fd = find_file_in_data_dirs (file, &output_path, &data_dirs,
589 g_propagate_error (error, key_file_error);
593 found_file = g_key_file_load_from_fd (key_file, fd, flags,
599 g_propagate_error (error, key_file_error);
600 g_free (output_path);
605 *full_path = output_path;
608 g_strfreev (all_data_dirs);
614 * @key_file: a #GKeyFile
621 g_key_file_free (GKeyFile *key_file)
623 g_return_if_fail (key_file != NULL);
625 g_key_file_clear (key_file);
629 /* If G_KEY_FILE_KEEP_TRANSLATIONS is not set, only returns
630 * true for locales that match those in g_get_language_names().
633 g_key_file_locale_is_interesting (GKeyFile *key_file,
636 const gchar * const * current_locales;
639 if (key_file->flags & G_KEY_FILE_KEEP_TRANSLATIONS)
642 current_locales = g_get_language_names ();
644 for (i = 0; current_locales[i] != NULL; i++)
646 if (g_ascii_strcasecmp (current_locales[i], locale) == 0)
654 g_key_file_parse_line (GKeyFile *key_file,
659 GError *parse_error = NULL;
662 g_return_if_fail (key_file != NULL);
663 g_return_if_fail (line != NULL);
665 line_start = (gchar *) line;
666 while (g_ascii_isspace (*line_start))
669 if (g_key_file_line_is_comment (line_start))
670 g_key_file_parse_comment (key_file, line, length, &parse_error);
671 else if (g_key_file_line_is_group (line_start))
672 g_key_file_parse_group (key_file, line_start,
673 length - (line_start - line),
675 else if (g_key_file_line_is_key_value_pair (line_start))
676 g_key_file_parse_key_value_pair (key_file, line_start,
677 length - (line_start - line),
681 g_set_error (error, G_KEY_FILE_ERROR,
682 G_KEY_FILE_ERROR_PARSE,
683 _("Key file contains line '%s' which is not "
684 "a key-value pair, group, or comment"), line);
689 g_propagate_error (error, parse_error);
693 g_key_file_parse_comment (GKeyFile *key_file,
698 GKeyFileKeyValuePair *pair;
700 if (!(key_file->flags & G_KEY_FILE_KEEP_COMMENTS))
703 g_assert (key_file->current_group != NULL);
705 pair = g_new0 (GKeyFileKeyValuePair, 1);
708 pair->value = g_strndup (line, length);
710 key_file->current_group->key_value_pairs =
711 g_list_prepend (key_file->current_group->key_value_pairs, pair);
715 g_key_file_parse_group (GKeyFile *key_file,
721 const gchar *group_name_start, *group_name_end;
723 /* advance past opening '['
725 group_name_start = line + 1;
726 group_name_end = line + length - 1;
728 while (*group_name_end != ']')
731 group_name = g_strndup (group_name_start,
732 group_name_end - group_name_start);
734 if (key_file->start_group_name == NULL)
735 key_file->start_group_name = g_strdup (group_name);
737 g_key_file_add_group (key_file, group_name);
742 g_key_file_parse_key_value_pair (GKeyFile *key_file,
747 gchar *key, *value, *key_end, *value_start, *locale;
748 gsize key_len, value_len;
750 if (key_file->current_group == NULL || key_file->current_group->name == NULL)
752 g_set_error (error, G_KEY_FILE_ERROR,
753 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
754 _("Key file does not start with a group"));
758 key_end = value_start = strchr (line, '=');
760 g_assert (key_end != NULL);
765 /* Pull the key name from the line (chomping trailing whitespace)
767 while (g_ascii_isspace (*key_end))
770 key_len = key_end - line + 2;
772 g_assert (key_len <= length);
774 key = g_strndup (line, key_len - 1);
776 /* Pull the value from the line (chugging leading whitespace)
778 while (g_ascii_isspace (*value_start))
781 value_len = line + length - value_start + 1;
783 value = g_strndup (value_start, value_len);
785 g_assert (key_file->start_group_name != NULL);
787 if (key_file->current_group
788 && key_file->current_group->name
789 && strcmp (key_file->start_group_name,
790 key_file->current_group->name) == 0
791 && strcmp (key, "Encoding") == 0)
793 if (g_ascii_strcasecmp (value, "UTF-8") != 0)
795 g_set_error (error, G_KEY_FILE_ERROR,
796 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
797 _("Key file contains unsupported encoding '%s'"), value);
805 /* Is this key a translation? If so, is it one that we care about?
807 locale = key_get_locale (key);
809 if (locale == NULL || g_key_file_locale_is_interesting (key_file, locale))
810 g_key_file_add_key (key_file, key_file->current_group->name, key, value);
818 key_get_locale (const gchar *key)
822 locale = g_strrstr (key, "[");
824 if (locale && strlen (locale) <= 2)
828 locale = g_strndup (locale + 1, strlen (locale) - 2);
834 g_key_file_parse_data (GKeyFile *key_file,
842 g_return_if_fail (key_file != NULL);
843 g_return_if_fail (data != NULL);
847 for (i = 0; i < length; i++)
851 /* When a newline is encountered flush the parse buffer so that the
852 * line can be parsed. Note that completely blank lines won't show
853 * up in the parse buffer, so they get parsed directly.
855 if (key_file->parse_buffer->len > 0)
856 g_key_file_flush_parse_buffer (key_file, &parse_error);
858 g_key_file_parse_comment (key_file, "", 1, &parse_error);
862 g_propagate_error (error, parse_error);
867 g_string_append_c (key_file->parse_buffer, data[i]);
870 key_file->approximate_size += length;
874 g_key_file_flush_parse_buffer (GKeyFile *key_file,
877 GError *file_error = NULL;
879 g_return_if_fail (key_file != NULL);
883 if (key_file->parse_buffer->len > 0)
885 g_key_file_parse_line (key_file, key_file->parse_buffer->str,
886 key_file->parse_buffer->len,
888 g_string_erase (key_file->parse_buffer, 0, -1);
892 g_propagate_error (error, file_error);
899 * g_key_file_to_data:
900 * @key_file: a #GKeyFile
901 * @length: return location for the length of the
902 * returned string, or %NULL
903 * @error: return location for a #GError, or %NULL
905 * This function outputs @key_file as a string.
907 * Return value: a newly allocated string holding
908 * the contents of the #GKeyFile
913 g_key_file_to_data (GKeyFile *key_file,
917 GString *data_string;
919 GList *group_node, *key_file_node;
921 g_return_val_if_fail (key_file != NULL, NULL);
923 data_string = g_string_sized_new (2 * key_file->approximate_size);
925 for (group_node = g_list_last (key_file->groups);
927 group_node = group_node->prev)
929 GKeyFileGroup *group;
931 group = (GKeyFileGroup *) group_node->data;
933 if (group->comment != NULL)
934 g_string_append_printf (data_string, "%s\n", group->comment->value);
935 if (group->name != NULL)
936 g_string_append_printf (data_string, "[%s]\n", group->name);
938 for (key_file_node = g_list_last (group->key_value_pairs);
939 key_file_node != NULL;
940 key_file_node = key_file_node->prev)
942 GKeyFileKeyValuePair *pair;
944 pair = (GKeyFileKeyValuePair *) key_file_node->data;
946 if (pair->key != NULL)
947 g_string_append_printf (data_string, "%s=%s\n", pair->key, pair->value);
949 g_string_append_printf (data_string, "%s\n", pair->value);
954 *length = data_string->len;
956 data = data_string->str;
958 g_string_free (data_string, FALSE);
964 * g_key_file_get_keys:
965 * @key_file: a #GKeyFile
966 * @group_name: a group name, or %NULL
967 * @length: return location for the number of keys returned, or %NULL
968 * @error: return location for a #GError, or %NULL
970 * Returns all keys for the group name @group_name. If @group_name is
971 * %NULL, the start group is used. The array of returned keys will be
972 * %NULL-terminated, so @length may optionally be %NULL.
974 * Return value: a newly-allocated %NULL-terminated array of
975 * strings. Use g_strfreev() to free it.
980 g_key_file_get_keys (GKeyFile *key_file,
981 const gchar *group_name,
985 GKeyFileGroup *group;
990 g_return_val_if_fail (key_file != NULL, NULL);
991 g_return_val_if_fail (group_name != NULL, NULL);
993 group = g_key_file_lookup_group (key_file, group_name);
997 g_set_error (error, G_KEY_FILE_ERROR,
998 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
999 _("Key file does not have group '%s'"),
1004 num_keys = g_list_length (group->key_value_pairs);
1006 keys = (gchar **) g_new0 (gchar **, num_keys + 1);
1008 tmp = group->key_value_pairs;
1009 for (i = 0; i < num_keys; i++)
1011 GKeyFileKeyValuePair *pair;
1013 pair = (GKeyFileKeyValuePair *) tmp->data;
1014 keys[i] = g_strdup (pair->key);
1027 * g_key_file_get_start_group:
1028 * @key_file: a #GKeyFile
1030 * Returns the name of the start group of the file.
1032 * Return value: The start group of the key file.
1037 g_key_file_get_start_group (GKeyFile *key_file)
1039 g_return_val_if_fail (key_file != NULL, NULL);
1041 return g_strdup (key_file->start_group_name);
1045 * g_key_file_get_groups:
1046 * @key_file: a #GKeyFile
1047 * @length: return location for the number of returned groups, or %NULL
1049 * Returns all groups in the key file loaded with @key_file. The
1050 * array of returned groups will be %NULL-terminated, so @length may
1051 * optionally be %NULL.
1053 * Return value: a newly-allocated %NULL-terminated array of strings.
1054 * Use g_strfreev() to free it.
1058 g_key_file_get_groups (GKeyFile *key_file,
1063 gsize i, num_groups;
1065 g_return_val_if_fail (key_file != NULL, NULL);
1067 num_groups = g_list_length (key_file->groups);
1069 g_assert (num_groups > 0);
1071 /* Only need num_groups instead of num_groups + 1
1072 * because the first group of the file (last in the
1073 * list) is always the comment group at the top,
1076 groups = (gchar **) g_new0 (gchar **, num_groups);
1078 group_node = g_list_last (key_file->groups);
1080 g_assert (((GKeyFileGroup *) group_node->data)->name == NULL);
1083 for (group_node = group_node->prev;
1085 group_node = group_node->prev)
1087 GKeyFileGroup *group;
1089 group = (GKeyFileGroup *) group_node->data;
1091 g_assert (group->name != NULL);
1093 groups[i++] = g_strdup (group->name);
1104 * g_key_file_get_value:
1105 * @key_file: a #GKeyFile
1106 * @group_name: a group name
1108 * @error: return location for a #GError, or #NULL
1110 * Returns the value associated with @key under @group_name.
1111 * In the event the key cannot be found, %NULL is returned and
1112 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1113 * event that the @group_name cannot be found, %NULL is returned
1114 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1116 * Return value: a string or %NULL if the specified key cannot be
1122 g_key_file_get_value (GKeyFile *key_file,
1123 const gchar *group_name,
1127 GKeyFileGroup *group;
1128 GKeyFileKeyValuePair *pair;
1129 gchar *value = NULL;
1131 g_return_val_if_fail (key_file != NULL, NULL);
1132 g_return_val_if_fail (group_name != NULL, NULL);
1133 g_return_val_if_fail (key != NULL, NULL);
1135 group = g_key_file_lookup_group (key_file, group_name);
1139 g_set_error (error, G_KEY_FILE_ERROR,
1140 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1141 _("Key file does not have group '%s'"),
1146 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1149 value = g_strdup (pair->value);
1151 g_set_error (error, G_KEY_FILE_ERROR,
1152 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
1153 _("Key file does not have key '%s'"), key);
1159 * g_key_file_set_value:
1160 * @key_file: a #GKeyFile
1161 * @group_name: a group name
1165 * Associates a new value with @key under @group_name.
1166 * If @key cannot be found then it is created. If @group_name
1167 * cannot be found then it is created as well.
1172 g_key_file_set_value (GKeyFile *key_file,
1173 const gchar *group_name,
1177 GKeyFileGroup *group;
1178 GKeyFileKeyValuePair *pair;
1180 g_return_if_fail (key_file != NULL);
1181 g_return_if_fail (key != NULL);
1182 g_return_if_fail (value != NULL);
1184 if (!g_key_file_has_key (key_file, group_name, key, NULL))
1185 g_key_file_add_key (key_file, group_name, key, value);
1188 group = g_key_file_lookup_group (key_file, group_name);
1189 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1190 g_free (pair->value);
1191 pair->value = g_strdup (value);
1196 * g_key_file_get_string:
1197 * @key_file: a #GKeyFile
1198 * @group_name: a group name
1200 * @error: return location for a #GError, or #NULL
1202 * Returns the value associated with @key under @group_name.
1203 * In the event the key cannot be found, %NULL is returned and
1204 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1205 * event that the @group_name cannot be found, %NULL is returned
1206 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1208 * Return value: a string or %NULL if the specified key cannot be
1214 g_key_file_get_string (GKeyFile *key_file,
1215 const gchar *group_name,
1219 gchar *value, *string_value;
1220 GError *key_file_error;
1222 g_return_val_if_fail (key_file != NULL, NULL);
1223 g_return_val_if_fail (group_name != NULL, NULL);
1224 g_return_val_if_fail (key != NULL, NULL);
1226 key_file_error = NULL;
1228 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1232 g_propagate_error (error, key_file_error);
1236 if (!g_utf8_validate (value, -1, NULL))
1238 g_set_error (error, G_KEY_FILE_ERROR,
1239 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1240 _("Key file contains key '%s' with value '%s' "
1241 "which is not UTF-8"), key, value);
1246 string_value = g_key_file_parse_value_as_string (key_file, value, NULL,
1252 if (g_error_matches (key_file_error,
1254 G_KEY_FILE_ERROR_INVALID_VALUE))
1256 g_set_error (error, G_KEY_FILE_ERROR,
1257 G_KEY_FILE_ERROR_INVALID_VALUE,
1258 _("Key file contains key '%s' "
1259 "which has value that cannot be interpreted."),
1261 g_error_free (key_file_error);
1264 g_propagate_error (error, key_file_error);
1267 return string_value;
1271 * g_key_file_set_string:
1272 * @key_file: a #GKeyFile
1273 * @group_name: a group name
1277 * Associates a new string value with @key under @group_name.
1278 * If @key cannot be found then it is created. If @group_name
1279 * cannot be found then it is created as well.
1284 g_key_file_set_string (GKeyFile *key_file,
1285 const gchar *group_name,
1287 const gchar *string)
1291 g_return_if_fail (key_file != NULL);
1292 g_return_if_fail (group_name != NULL);
1293 g_return_if_fail (key != NULL);
1294 g_return_if_fail (string != NULL);
1296 value = g_key_file_parse_string_as_value (key_file, string, FALSE);
1297 g_key_file_set_value (key_file, group_name, key, value);
1302 * g_key_file_get_string_list:
1303 * @key_file: a #GKeyFile
1304 * @group_name: a group name
1306 * @length: return location for the number of returned strings, or %NULL
1307 * @error: return location for a #GError, or %NULL
1309 * Returns the values associated with @key under @group_name.
1310 * In the event the key cannot be found, %NULL is returned and
1311 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1312 * event that the @group_name cannot be found, %NULL is returned
1313 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1315 * Return value: a %NULL-terminated string array or %NULL if the specified
1316 * key cannot be found. The array should be freed with g_strfreev().
1321 g_key_file_get_string_list (GKeyFile *key_file,
1322 const gchar *group_name,
1327 GError *key_file_error = NULL;
1328 gchar *value, *string_value, **values;
1330 GSList *p, *pieces = NULL;
1332 g_return_val_if_fail (key_file != NULL, NULL);
1333 g_return_val_if_fail (group_name != NULL, NULL);
1334 g_return_val_if_fail (key != NULL, NULL);
1336 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1340 g_propagate_error (error, key_file_error);
1344 if (!g_utf8_validate (value, -1, NULL))
1346 g_set_error (error, G_KEY_FILE_ERROR,
1347 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1348 _("Key file contains key '%s' with value '%s' "
1349 "which is not UTF-8"), key, value);
1354 string_value = g_key_file_parse_value_as_string (key_file, value, &pieces, &key_file_error);
1356 g_free (string_value);
1360 if (g_error_matches (key_file_error,
1362 G_KEY_FILE_ERROR_INVALID_VALUE))
1364 g_set_error (error, G_KEY_FILE_ERROR,
1365 G_KEY_FILE_ERROR_INVALID_VALUE,
1366 _("Key file contains key '%s' "
1367 "which has value that cannot be interpreted."),
1369 g_error_free (key_file_error);
1372 g_propagate_error (error, key_file_error);
1375 len = g_slist_length (pieces);
1376 values = g_new0 (gchar *, len + 1);
1377 for (p = pieces, i = 0; p; p = p->next)
1378 values[i++] = p->data;
1381 g_slist_free (pieces);
1390 * g_key_file_set_string_list:
1391 * @key_file: a #GKeyFile
1392 * @group_name: a group name
1394 * @list: an array of locale string values
1395 * @length: number of locale string values in @list
1397 * Associates a list of string values for @key under @group_name.
1398 * If the @key cannot be found then it is created.
1403 g_key_file_set_string_list (GKeyFile *key_file,
1404 const gchar *group_name,
1406 const gchar * const list[],
1409 GString *value_list;
1412 g_return_if_fail (key_file != NULL);
1413 g_return_if_fail (group_name != NULL);
1414 g_return_if_fail (key != NULL);
1415 g_return_if_fail (list != NULL);
1417 value_list = g_string_sized_new (length * 128);
1418 for (i = 0; list[i] != NULL && i < length; i++)
1422 value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
1423 g_string_append (value_list, value);
1424 g_string_append_c (value_list, key_file->list_separator);
1429 g_key_file_set_value (key_file, group_name, key, value_list->str);
1430 g_string_free (value_list, TRUE);
1434 * g_key_file_set_locale_string:
1435 * @key_file: a #GKeyFile
1436 * @group_name: a group name
1441 * Associates a string value for @key and @locale under
1442 * @group_name. If the translation for @key cannot be found
1443 * then it is created.
1448 g_key_file_set_locale_string (GKeyFile *key_file,
1449 const gchar *group_name,
1451 const gchar *locale,
1452 const gchar *string)
1454 gchar *full_key, *value;
1456 g_return_if_fail (key_file != NULL);
1457 g_return_if_fail (group_name != NULL);
1458 g_return_if_fail (key != NULL);
1459 g_return_if_fail (locale != NULL);
1460 g_return_if_fail (string != NULL);
1462 value = g_key_file_parse_string_as_value (key_file, string, FALSE);
1463 full_key = g_strdup_printf ("%s[%s]", key, locale);
1464 g_key_file_set_value (key_file, group_name, full_key, value);
1469 extern GSList *_g_compute_locale_variants (const gchar *locale);
1472 * g_key_file_get_locale_string:
1473 * @key_file: a #GKeyFile
1474 * @group_name: a group name
1476 * @locale: a locale or %NULL
1477 * @error: return location for a #GError, or %NULL
1479 * Returns the value associated with @key under @group_name
1480 * translated in the given @locale if available. If @locale is
1481 * %NULL then the current locale is assumed. If @key cannot be
1482 * found then %NULL is returned and @error is set to
1483 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
1484 * with @key cannot be interpreted or no suitable translation can
1485 * be found then the untranslated value is returned and @error is
1486 * set to #G_KEY_FILE_ERROR_INVALID_VALUE and
1487 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND, respectively. In the
1488 * event that the @group_name cannot be found, %NULL is returned
1489 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1491 * Return value: a string or %NULL if the specified key cannot be
1496 g_key_file_get_locale_string (GKeyFile *key_file,
1497 const gchar *group_name,
1499 const gchar *locale,
1502 gchar *candidate_key, *translated_value;
1503 GError *key_file_error;
1505 gboolean free_languages = FALSE;
1508 g_return_val_if_fail (key_file != NULL, NULL);
1509 g_return_val_if_fail (group_name != NULL, NULL);
1510 g_return_val_if_fail (key != NULL, NULL);
1512 candidate_key = NULL;
1513 translated_value = NULL;
1514 key_file_error = NULL;
1516 if (!g_key_file_has_group (key_file, group_name))
1518 g_set_error (error, G_KEY_FILE_ERROR,
1519 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1520 _("Key file does not have group '%s'"),
1529 list = _g_compute_locale_variants (locale);
1531 languages = g_new0 (gchar *, g_slist_length (list) + 1);
1532 for (l = list, i = 0; l; l = l->next, i++)
1533 languages[i] = l->data;
1534 languages[i] = NULL;
1536 g_slist_free (list);
1537 free_languages = TRUE;
1541 languages = (gchar **) g_get_language_names ();
1542 free_languages = FALSE;
1545 for (i = 0; languages[i]; i++)
1547 candidate_key = g_strdup_printf ("%s[%s]", key, languages[i]);
1549 translated_value = g_key_file_get_string (key_file,
1551 candidate_key, NULL);
1552 g_free (candidate_key);
1554 if (translated_value)
1558 if (translated_value && !g_utf8_validate (translated_value, -1, NULL))
1560 g_set_error (error, G_KEY_FILE_ERROR,
1561 G_KEY_FILE_ERROR_INVALID_VALUE,
1562 _("Key file contains key '%s' "
1563 "which has value that cannot be interpreted."),
1565 g_free (translated_value);
1566 translated_value = NULL;
1569 /* Fallback to untranslated key
1571 if (!translated_value)
1573 translated_value = g_key_file_get_string (key_file, group_name, key,
1576 if (!translated_value)
1577 g_propagate_error (error, key_file_error);
1579 g_set_error (error, G_KEY_FILE_ERROR,
1580 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
1581 _("Key file contains no translated value "
1582 "for key '%s' with locale '%s'."),
1587 g_strfreev (languages);
1589 return translated_value;
1593 * g_key_file_get_locale_string_list:
1594 * @key_file: a #GKeyFile
1595 * @group_name: a group name
1598 * @length: return location for the number of returned strings or %NULL
1599 * @error: return location for a #GError or %NULL
1601 * Returns the values associated with @key under @group_name
1602 * translated in the given @locale if available. If @locale is
1603 * %NULL then the current locale is assumed. If @key cannot be
1604 * found then %NULL is returned and @error is set to
1605 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
1606 * with @key cannot be interpreted or no suitable translations
1607 * can be found then the untranslated values are returned and
1608 * @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE and
1609 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND, respectively. In the
1610 * event that the @group_name cannot be found, %NULL is returned
1611 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1612 * The returned array is %NULL-terminated, so @length may optionally be %NULL.
1614 * Return value: a newly allocated %NULL-terminated string array
1615 * or %NULL if the key isn't found. The string array should be freed
1616 * with g_strfreev().
1621 g_key_file_get_locale_string_list (GKeyFile *key_file,
1622 const gchar *group_name,
1624 const gchar *locale,
1628 GError *key_file_error;
1629 gchar **values, *value;
1631 g_return_val_if_fail (key_file != NULL, NULL);
1632 g_return_val_if_fail (group_name != NULL, NULL);
1633 g_return_val_if_fail (key != NULL, NULL);
1635 key_file_error = NULL;
1637 value = g_key_file_get_locale_string (key_file, group_name,
1642 g_propagate_error (error, key_file_error);
1647 if (value[strlen (value) - 1] == ';')
1648 value[strlen (value) - 1] = '\0';
1650 values = g_strsplit (value, ";", 0);
1655 *length = g_strv_length (values);
1661 * g_key_file_set_locale_string_list:
1662 * @key_file: a #GKeyFile
1663 * @group_name: a group name
1666 * @list: a %NULL-terminated array of locale string values
1667 * @length: the length of @list
1669 * Associates a list of string values for @key and @locale under
1670 * @group_name. If the translation for @key cannot be found then
1676 g_key_file_set_locale_string_list (GKeyFile *key_file,
1677 const gchar *group_name,
1679 const gchar *locale,
1680 const gchar * const list[],
1683 GString *value_list;
1687 g_return_if_fail (key_file != NULL);
1688 g_return_if_fail (group_name != NULL);
1689 g_return_if_fail (key != NULL);
1690 g_return_if_fail (locale != NULL);
1691 g_return_if_fail (length != 0);
1693 value_list = g_string_sized_new (length * 128);
1694 for (i = 0; list[i] != NULL && i < length; i++)
1698 value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
1700 g_string_append (value_list, value);
1701 g_string_append_c (value_list, ';');
1706 full_key = g_strdup_printf ("%s[%s]", key, locale);
1707 g_key_file_set_value (key_file, group_name, full_key, value_list->str);
1709 g_string_free (value_list, TRUE);
1713 * g_key_file_get_boolean:
1714 * @key_file: a #GKeyFile
1715 * @group_name: a group name
1717 * @error: return location for a #GError
1719 * Returns the value associated with @key under @group_name as a
1720 * boolean. If @key cannot be found then the return value is
1721 * undefined and @error is set to
1722 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
1723 * associated with @key cannot be interpreted as a boolean then
1724 * the return value is also undefined and @error is set to
1725 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1727 * Return value: the value associated with the key as a boolean
1731 g_key_file_get_boolean (GKeyFile *key_file,
1732 const gchar *group_name,
1736 GError *key_file_error = NULL;
1738 gboolean bool_value;
1740 g_return_val_if_fail (key_file != NULL, FALSE);
1741 g_return_val_if_fail (group_name != NULL, FALSE);
1742 g_return_val_if_fail (key != NULL, FALSE);
1744 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1748 g_propagate_error (error, key_file_error);
1752 bool_value = g_key_file_parse_value_as_boolean (key_file, value,
1758 if (g_error_matches (key_file_error,
1760 G_KEY_FILE_ERROR_INVALID_VALUE))
1762 g_set_error (error, G_KEY_FILE_ERROR,
1763 G_KEY_FILE_ERROR_INVALID_VALUE,
1764 _("Key file contains key '%s' "
1765 "which has value that cannot be interpreted."),
1767 g_error_free (key_file_error);
1770 g_propagate_error (error, key_file_error);
1777 * g_key_file_set_boolean:
1778 * @key_file: a #GKeyFile
1779 * @group_name: a group name
1781 * @value: %TRUE or %FALSE
1783 * Associates a new boolean value with @key under @group_name.
1784 * If @key cannot be found then it is created.
1789 g_key_file_set_boolean (GKeyFile *key_file,
1790 const gchar *group_name,
1796 g_return_if_fail (key_file != NULL);
1797 g_return_if_fail (group_name != NULL);
1798 g_return_if_fail (key != NULL);
1800 result = g_key_file_parse_boolean_as_value (key_file, value);
1801 g_key_file_set_value (key_file, group_name, key, result);
1806 * g_key_file_get_boolean_list:
1807 * @key_file: a #GKeyFile
1808 * @group_name: a group name
1810 * @length: the number of booleans returned
1811 * @error: return location for a #GError
1813 * Returns the values associated with @key under @group_name as
1814 * booleans. If @key cannot be found then the return value is
1815 * undefined and @error is set to
1816 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values
1817 * associated with @key cannot be interpreted as booleans then
1818 * the return value is also undefined and @error is set to
1819 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1821 * Return value: the values associated with the key as a boolean
1826 g_key_file_get_boolean_list (GKeyFile *key_file,
1827 const gchar *group_name,
1832 GError *key_file_error;
1834 gboolean *bool_values;
1837 g_return_val_if_fail (key_file != NULL, NULL);
1838 g_return_val_if_fail (group_name != NULL, NULL);
1839 g_return_val_if_fail (key != NULL, NULL);
1841 key_file_error = NULL;
1843 values = g_key_file_get_string_list (key_file, group_name, key,
1844 &num_bools, &key_file_error);
1847 g_propagate_error (error, key_file_error);
1852 bool_values = g_new0 (gboolean, num_bools);
1854 for (i = 0; i < num_bools; i++)
1856 bool_values[i] = g_key_file_parse_value_as_boolean (key_file,
1862 g_propagate_error (error, key_file_error);
1863 g_strfreev (values);
1864 g_free (bool_values);
1869 g_strfreev (values);
1872 *length = num_bools;
1878 * g_key_file_set_boolean_list:
1879 * @key_file: a #GKeyFile
1880 * @group_name: a group name
1882 * @list: an array of boolean values
1883 * @length: length of @list
1885 * Associates a list of boolean values with @key under
1886 * @group_name. If @key cannot be found then it is created.
1891 g_key_file_set_boolean_list (GKeyFile *key_file,
1892 const gchar *group_name,
1897 GString *value_list;
1900 g_return_if_fail (key_file != NULL);
1901 g_return_if_fail (group_name != NULL);
1902 g_return_if_fail (key != NULL);
1903 g_return_if_fail (list != NULL);
1905 value_list = g_string_sized_new (length * 8);
1906 for (i = 0; i < length; i++)
1910 value = g_key_file_parse_boolean_as_value (key_file, list[i]);
1912 g_string_append (value_list, value);
1913 g_string_append_c (value_list, key_file->list_separator);
1918 g_key_file_set_value (key_file, group_name, key, value_list->str);
1919 g_string_free (value_list, TRUE);
1923 * g_key_file_get_integer:
1924 * @key_file: a #GKeyFile
1925 * @group_name: a group name
1927 * @error: return location for a #GError
1929 * Returns the value associated with @key under @group_name as an
1930 * integer. If @key cannot be found then the return value is
1931 * undefined and @error is set to
1932 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
1933 * associated with @key cannot be interpreted as an integer then
1934 * the return value is also undefined and @error is set to
1935 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1937 * Return value: the value associated with the key as an integer.
1942 g_key_file_get_integer (GKeyFile *key_file,
1943 const gchar *group_name,
1947 GError *key_file_error;
1951 g_return_val_if_fail (key_file != NULL, -1);
1952 g_return_val_if_fail (group_name != NULL, -1);
1953 g_return_val_if_fail (key != NULL, -1);
1955 key_file_error = NULL;
1957 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1961 g_propagate_error (error, key_file_error);
1965 int_value = g_key_file_parse_value_as_integer (key_file, value,
1971 if (g_error_matches (key_file_error,
1973 G_KEY_FILE_ERROR_INVALID_VALUE))
1975 g_set_error (error, G_KEY_FILE_ERROR,
1976 G_KEY_FILE_ERROR_INVALID_VALUE,
1977 _("Key file contains key '%s' in group '%s' "
1978 "which has value that cannot be interpreted."), key,
1980 g_error_free (key_file_error);
1983 g_propagate_error (error, key_file_error);
1990 * g_key_file_set_integer:
1991 * @key_file: a #GKeyFile
1992 * @group_name: a group name
1994 * @value: an integer value
1996 * Associates a new integer value with @key under @group_name.
1997 * If @key cannot be found then it is created.
2002 g_key_file_set_integer (GKeyFile *key_file,
2003 const gchar *group_name,
2009 g_return_if_fail (key_file != NULL);
2010 g_return_if_fail (group_name != NULL);
2011 g_return_if_fail (key != NULL);
2013 result = g_key_file_parse_integer_as_value (key_file, value);
2014 g_key_file_set_value (key_file, group_name, key, result);
2019 * g_key_file_get_integer_list:
2020 * @key_file: a #GKeyFile
2021 * @group_name: a group name
2023 * @length: the number of integers returned
2024 * @error: return location for a #GError
2026 * Returns the values associated with @key under @group_name as
2027 * integers. If @key cannot be found then the return value is
2028 * undefined and @error is set to
2029 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values
2030 * associated with @key cannot be interpreted as integers then
2031 * the return value is also undefined and @error is set to
2032 * #G_KEY_FILE_ERROR_INVALID_VALUE.
2034 * Return value: the values associated with the key as a integer
2039 g_key_file_get_integer_list (GKeyFile *key_file,
2040 const gchar *group_name,
2045 GError *key_file_error = NULL;
2050 g_return_val_if_fail (key_file != NULL, NULL);
2051 g_return_val_if_fail (group_name != NULL, NULL);
2052 g_return_val_if_fail (key != NULL, NULL);
2054 values = g_key_file_get_string_list (key_file, group_name, key,
2055 &num_ints, &key_file_error);
2058 g_propagate_error (error, key_file_error);
2063 int_values = g_new0 (gint, num_ints);
2065 for (i = 0; i < num_ints; i++)
2067 int_values[i] = g_key_file_parse_value_as_integer (key_file,
2073 g_propagate_error (error, key_file_error);
2074 g_strfreev (values);
2075 g_free (int_values);
2080 g_strfreev (values);
2089 * g_key_file_set_integer_list:
2090 * @key_file: a #GKeyFile
2091 * @group_name: a group name
2093 * @list: an array of integer values
2094 * @length: number of integer values in @list
2096 * Associates a list of integer values with @key under
2097 * @group_name. If @key cannot be found then it is created.
2102 g_key_file_set_integer_list (GKeyFile *key_file,
2103 const gchar *group_name,
2111 g_return_if_fail (key_file != NULL);
2112 g_return_if_fail (group_name != NULL);
2113 g_return_if_fail (key != NULL);
2114 g_return_if_fail (list != NULL);
2116 values = g_string_sized_new (length * 16);
2117 for (i = 0; i < length; i++)
2121 value = g_key_file_parse_integer_as_value (key_file, list[i]);
2123 g_string_append (values, value);
2124 g_string_append_c (values, ';');
2129 g_key_file_set_value (key_file, group_name, key, values->str);
2130 g_string_free (values, TRUE);
2134 g_key_file_set_key_comment (GKeyFile *key_file,
2135 const gchar *group_name,
2137 const gchar *comment,
2140 GKeyFileGroup *group;
2141 GKeyFileKeyValuePair *pair;
2142 GList *key_node, *comment_node, *tmp;
2144 group = g_key_file_lookup_group (key_file, group_name);
2147 g_set_error (error, G_KEY_FILE_ERROR,
2148 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2149 _("Key file does not have group '%s'"),
2155 /* First find the key the comments are supposed to be
2158 key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
2160 if (key_node == NULL)
2162 g_set_error (error, G_KEY_FILE_ERROR,
2163 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2164 _("Key file does not have key '%s' in group '%s'"),
2169 /* Then find all the comments already associated with the
2172 tmp = key_node->next;
2175 GKeyFileKeyValuePair *pair;
2177 pair = (GKeyFileKeyValuePair *) tmp->data;
2179 if (pair->key != NULL)
2184 g_key_file_remove_key_value_pair_node (key_file, group,
2188 if (comment == NULL)
2191 /* Now we can add our new comment
2193 pair = g_new0 (GKeyFileKeyValuePair, 1);
2196 pair->value = g_key_file_parse_comment_as_value (key_file, comment);
2198 key_node = g_list_insert (key_node, pair, 1);
2202 g_key_file_set_group_comment (GKeyFile *key_file,
2203 const gchar *group_name,
2204 const gchar *comment,
2207 GKeyFileGroup *group;
2209 group = g_key_file_lookup_group (key_file, group_name);
2212 g_set_error (error, G_KEY_FILE_ERROR,
2213 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2214 _("Key file does not have group '%s'"),
2220 /* First remove any existing comment
2224 g_key_file_key_value_pair_free (group->comment);
2225 group->comment = NULL;
2228 if (comment == NULL)
2231 /* Now we can add our new comment
2233 group->comment = g_new0 (GKeyFileKeyValuePair, 1);
2235 group->comment->key = NULL;
2236 group->comment->value = g_key_file_parse_comment_as_value (key_file, comment);
2240 g_key_file_set_top_comment (GKeyFile *key_file,
2241 const gchar *comment,
2245 GKeyFileGroup *group;
2246 GKeyFileKeyValuePair *pair;
2248 /* The last group in the list should be the top (comments only)
2251 g_assert (key_file->groups != NULL);
2252 group_node = g_list_last (key_file->groups);
2253 group = (GKeyFileGroup *) group_node->data;
2254 g_assert (group->name == NULL);
2256 /* Note all keys must be comments at the top of
2257 * the file, so we can just free it all.
2259 if (group->key_value_pairs != NULL)
2261 g_list_foreach (group->key_value_pairs,
2262 (GFunc) g_key_file_key_value_pair_free,
2264 g_list_free (group->key_value_pairs);
2265 group->key_value_pairs = NULL;
2268 if (comment == NULL)
2271 pair = g_new0 (GKeyFileKeyValuePair, 1);
2274 pair->value = g_key_file_parse_comment_as_value (key_file, comment);
2276 group->key_value_pairs =
2277 g_list_prepend (group->key_value_pairs, pair);
2281 * g_key_file_set_comment:
2282 * @key_file: a #GKeyFile
2283 * @group_name: a group name
2285 * @comment: a comment
2286 * @error: return location for a #GError
2288 * Places a comment above @key from @group_name.
2289 * @group_name. If @key is %NULL then @comment will
2290 * be written above @group_name. If both @key
2291 * and @group_name are NULL, then @comment will
2292 * be written above the first group in the file.
2297 g_key_file_set_comment (GKeyFile *key_file,
2298 const gchar *group_name,
2300 const gchar *comment,
2303 g_return_if_fail (key_file != NULL);
2305 if (group_name != NULL && key != NULL)
2306 g_key_file_set_key_comment (key_file, group_name, key, comment, error);
2307 else if (group_name != NULL)
2308 g_key_file_set_group_comment (key_file, group_name, comment, error);
2310 g_key_file_set_top_comment (key_file, comment, error);
2312 if (comment != NULL)
2313 key_file->approximate_size += strlen (comment);
2317 g_key_file_get_key_comment (GKeyFile *key_file,
2318 const gchar *group_name,
2322 GKeyFileGroup *group;
2323 GList *key_node, *tmp;
2327 group = g_key_file_lookup_group (key_file, group_name);
2330 g_set_error (error, G_KEY_FILE_ERROR,
2331 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2332 _("Key file does not have group '%s'"),
2338 /* First find the key the comments are supposed to be
2341 key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
2343 if (key_node == NULL)
2345 g_set_error (error, G_KEY_FILE_ERROR,
2346 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2347 _("Key file does not have key '%s' in group '%s'"),
2354 /* Then find all the comments already associated with the
2355 * key and concatentate them.
2357 tmp = key_node->next;
2360 GKeyFileKeyValuePair *pair;
2362 pair = (GKeyFileKeyValuePair *) tmp->data;
2364 if (pair->key != NULL)
2368 string = g_string_sized_new (512);
2370 comment = g_key_file_parse_value_as_comment (key_file, pair->value);
2371 g_string_append (string, comment);
2379 comment = string->str;
2380 g_string_free (string, FALSE);
2389 g_key_file_get_group_comment (GKeyFile *key_file,
2390 const gchar *group_name,
2393 GKeyFileGroup *group;
2395 group = g_key_file_lookup_group (key_file, group_name);
2398 g_set_error (error, G_KEY_FILE_ERROR,
2399 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2400 _("Key file does not have group '%s'"),
2407 return g_strdup (group->comment->value);
2413 g_key_file_get_top_comment (GKeyFile *key_file,
2416 GList *group_node, *tmp;
2417 GKeyFileGroup *group;
2421 /* The last group in the list should be the top (comments only)
2424 g_assert (key_file->groups != NULL);
2425 group_node = g_list_last (key_file->groups);
2426 group = (GKeyFileGroup *) group_node->data;
2427 g_assert (group->name == NULL);
2431 /* Then find all the comments already associated with the
2432 * key and concatentate them.
2434 tmp = group->key_value_pairs;
2437 GKeyFileKeyValuePair *pair;
2439 pair = (GKeyFileKeyValuePair *) tmp->data;
2441 if (pair->key != NULL)
2445 string = g_string_sized_new (512);
2447 comment = g_key_file_parse_value_as_comment (key_file, pair->value);
2448 g_string_append (string, comment);
2456 comment = string->str;
2457 g_string_free (string, FALSE);
2466 * g_key_file_get_comment:
2467 * @key_file: a #GKeyFile
2468 * @group_name: a group name
2470 * @error: return location for a #GError
2472 * Retreives a comment above @key from @group_name.
2473 * @group_name. If @key is %NULL then @comment will
2474 * be read from above @group_name. If both @key
2475 * and @group_name are NULL, then @comment will
2476 * be read from above the first group in the file.
2479 * Returns: a comment that should be freed with g_free()
2482 g_key_file_get_comment (GKeyFile *key_file,
2483 const gchar *group_name,
2487 g_return_val_if_fail (key_file != NULL, NULL);
2489 if (group_name != NULL && key != NULL)
2490 return g_key_file_get_key_comment (key_file, group_name, key, error);
2491 else if (group_name != NULL)
2492 return g_key_file_get_group_comment (key_file, group_name, error);
2494 return g_key_file_get_top_comment (key_file, error);
2498 * g_key_file_remove_comment:
2499 * @key_file: a #GKeyFile
2500 * @group_name: a group name
2502 * @error: return location for a #GError
2504 * Removes a comment above @key from @group_name.
2505 * @group_name. If @key is %NULL then @comment will
2506 * be written above @group_name. If both @key
2507 * and @group_name are NULL, then @comment will
2508 * be written above the first group in the file.
2514 g_key_file_remove_comment (GKeyFile *key_file,
2515 const gchar *group_name,
2519 g_return_if_fail (key_file != NULL);
2521 if (group_name != NULL && key != NULL)
2522 g_key_file_set_key_comment (key_file, group_name, key, NULL, error);
2523 else if (group_name != NULL)
2524 g_key_file_set_group_comment (key_file, group_name, NULL, error);
2526 g_key_file_set_top_comment (key_file, NULL, error);
2530 * g_key_file_has_group:
2531 * @key_file: a #GKeyFile
2532 * @group_name: a group name
2534 * Looks whether the key file has the group @group_name.
2536 * Return value: %TRUE if @group_name is a part of @key_file, %FALSE
2541 g_key_file_has_group (GKeyFile *key_file,
2542 const gchar *group_name)
2545 GKeyFileGroup *group;
2547 g_return_val_if_fail (key_file != NULL, FALSE);
2548 g_return_val_if_fail (group_name != NULL, FALSE);
2550 for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
2552 group = (GKeyFileGroup *) tmp->data;
2553 if (group && group->name && (strcmp (group->name, group_name) == 0))
2561 * g_key_file_has_key:
2562 * @key_file: a #GKeyFile
2563 * @group_name: a group name
2565 * @error: return location for a #GError
2567 * Looks whether the key file has the key @key in the group
2570 * Return value: %TRUE if @key is a part of @group_name, %FALSE
2576 g_key_file_has_key (GKeyFile *key_file,
2577 const gchar *group_name,
2581 GKeyFileKeyValuePair *pair;
2582 GKeyFileGroup *group;
2584 g_return_val_if_fail (key_file != NULL, FALSE);
2585 g_return_val_if_fail (key != NULL, FALSE);
2586 g_return_val_if_fail (group_name != NULL, FALSE);
2588 group = g_key_file_lookup_group (key_file, group_name);
2592 g_set_error (error, G_KEY_FILE_ERROR,
2593 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2594 _("Key file does not have group '%s'"),
2600 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
2602 return pair != NULL;
2606 g_key_file_add_group (GKeyFile *key_file,
2607 const gchar *group_name)
2609 GKeyFileGroup *group;
2611 g_return_if_fail (key_file != NULL);
2612 g_return_if_fail (group_name != NULL);
2613 g_return_if_fail (g_key_file_lookup_group (key_file, group_name) == NULL);
2615 group = g_new0 (GKeyFileGroup, 1);
2616 group->name = g_strdup (group_name);
2617 group->lookup_map = g_hash_table_new (g_str_hash, g_str_equal);
2618 key_file->groups = g_list_prepend (key_file->groups, group);
2619 key_file->approximate_size += strlen (group_name) + 3;
2620 key_file->current_group = group;
2622 if (key_file->start_group_name == NULL)
2623 key_file->start_group_name = g_strdup (group_name);
2627 g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair)
2632 g_free (pair->value);
2637 /* Be careful not to call this function on a node with data in the
2638 * lookup map without removing it from the lookup map, first.
2640 * Some current cases where this warning is not a concern are
2642 * - the node being removed is a comment node
2643 * - the entire lookup map is getting destroyed soon after
2647 g_key_file_remove_key_value_pair_node (GKeyFile *key_file,
2648 GKeyFileGroup *group,
2652 GKeyFileKeyValuePair *pair;
2654 pair = (GKeyFileKeyValuePair *) pair_node->data;
2656 group->key_value_pairs = g_list_remove_link (group->key_value_pairs, pair_node);
2658 if (pair->key != NULL)
2659 key_file->approximate_size -= strlen (pair->key) + 1;
2661 g_assert (pair->value != NULL);
2662 key_file->approximate_size -= strlen (pair->value);
2664 g_key_file_key_value_pair_free (pair);
2666 g_list_free_1 (pair_node);
2670 g_key_file_remove_group_node (GKeyFile *key_file,
2673 GKeyFileGroup *group;
2676 group = (GKeyFileGroup *) group_node->data;
2678 /* If the current group gets deleted make the current group the first
2681 if (key_file->current_group == group)
2683 /* groups should always contain at least the top comment group,
2684 * unless g_key_file_clear has been called
2686 if (key_file->groups)
2687 key_file->current_group = (GKeyFileGroup *) key_file->groups->data;
2689 key_file->current_group = NULL;
2692 key_file->groups = g_list_remove_link (key_file->groups, group_node);
2694 if (group->name != NULL)
2695 key_file->approximate_size -= strlen (group->name) + 3;
2697 tmp = group->key_value_pairs;
2704 g_key_file_remove_key_value_pair_node (key_file, group, pair_node);
2707 g_assert (group->key_value_pairs == NULL);
2709 if (group->lookup_map)
2711 g_hash_table_destroy (group->lookup_map);
2712 group->lookup_map = NULL;
2715 g_free ((gchar *) group->name);
2717 g_list_free_1 (group_node);
2721 * g_key_file_remove_group:
2722 * @key_file: a #GKeyFile
2723 * @group_name: a group name
2724 * @error: return location for a #GError or %NULL
2726 * Removes the specified group, @group_name,
2727 * from the key file.
2732 g_key_file_remove_group (GKeyFile *key_file,
2733 const gchar *group_name,
2738 g_return_if_fail (key_file != NULL);
2739 g_return_if_fail (group_name != NULL);
2741 group_node = g_key_file_lookup_group_node (key_file, group_name);
2744 g_set_error (error, G_KEY_FILE_ERROR,
2745 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2746 _("Key file does not have group '%s'"),
2749 g_key_file_remove_group_node (key_file, group_node);
2753 g_key_file_add_key (GKeyFile *key_file,
2754 const gchar *group_name,
2758 GKeyFileGroup *group;
2759 GKeyFileKeyValuePair *pair;
2761 group = g_key_file_lookup_group (key_file, group_name);
2765 g_key_file_add_group (key_file, group_name);
2766 group = (GKeyFileGroup *) key_file->groups->data;
2769 pair = g_new0 (GKeyFileKeyValuePair, 1);
2771 pair->key = g_strdup (key);
2772 pair->value = g_strdup (value);
2774 g_hash_table_replace (group->lookup_map, pair->key, pair);
2775 group->key_value_pairs = g_list_prepend (group->key_value_pairs, pair);
2776 key_file->approximate_size += strlen (key) + strlen (value) + 2;
2780 * g_key_file_remove_key:
2781 * @key_file: a #GKeyFile
2782 * @group_name: a group name
2783 * @key: a key name to remove
2784 * @error: return location for a #GError or %NULL
2786 * Removes @key in @group_name from the key file.
2791 g_key_file_remove_key (GKeyFile *key_file,
2792 const gchar *group_name,
2796 GKeyFileGroup *group;
2797 GKeyFileKeyValuePair *pair;
2799 g_return_if_fail (key_file != NULL);
2800 g_return_if_fail (group_name != NULL);
2801 g_return_if_fail (key != NULL);
2805 if (group_name == NULL)
2806 group = key_file->current_group;
2808 group = g_key_file_lookup_group (key_file, group_name);
2812 g_set_error (error, G_KEY_FILE_ERROR,
2813 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2814 _("Key file does not have group '%s'"),
2819 group->key_value_pairs = g_list_remove (group->key_value_pairs, key_file);
2820 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
2824 g_set_error (error, G_KEY_FILE_ERROR,
2825 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2826 _("Key file does not have key '%s' in group '%s'"), key, group_name);
2830 g_hash_table_remove (group->lookup_map, pair->key);
2832 key_file->approximate_size -= strlen (pair->key) + strlen (pair->value) + 2;
2833 g_key_file_key_value_pair_free (pair);
2837 g_key_file_lookup_group_node (GKeyFile *key_file,
2838 const gchar *group_name)
2840 GKeyFileGroup *group;
2844 for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
2846 group = (GKeyFileGroup *) tmp->data;
2848 if (group && group->name && strcmp (group->name, group_name) == 0)
2857 static GKeyFileGroup *
2858 g_key_file_lookup_group (GKeyFile *key_file,
2859 const gchar *group_name)
2863 group_node = g_key_file_lookup_group_node (key_file, group_name);
2865 if (group_node != NULL)
2866 return (GKeyFileGroup *) group_node->data;
2872 g_key_file_lookup_key_value_pair_node (GKeyFile *key_file,
2873 GKeyFileGroup *group,
2878 for (key_node = group->key_value_pairs;
2880 key_node = key_node->next)
2882 GKeyFileKeyValuePair *pair;
2884 pair = (GKeyFileKeyValuePair *) key_node->data;
2886 if (pair->key && strcmp (pair->key, key) == 0)
2893 static GKeyFileKeyValuePair *
2894 g_key_file_lookup_key_value_pair (GKeyFile *key_file,
2895 GKeyFileGroup *group,
2898 return (GKeyFileKeyValuePair *) g_hash_table_lookup (group->lookup_map, key);
2901 /* Lines starting with # or consisting entirely of whitespace are merely
2902 * recorded, not parsed. This function assumes all leading whitespace
2903 * has been stripped.
2906 g_key_file_line_is_comment (const gchar *line)
2908 return (*line == '#' || *line == '\0' || *line == '\n');
2911 /* A group in a key file is made up of a starting '[' followed by one
2912 * or more letters making up the group name followed by ']'.
2915 g_key_file_line_is_group (const gchar *line)
2923 p = g_utf8_next_char (p);
2928 p = g_utf8_next_char (p);
2930 /* Group name must be non-empty
2935 while (*p && *p != ']')
2936 p = g_utf8_next_char (p);
2945 g_key_file_line_is_key_value_pair (const gchar *line)
2949 p = (gchar *) g_utf8_strchr (line, -1, '=');
2954 /* Key must be non-empty
2963 g_key_file_parse_value_as_string (GKeyFile *key_file,
2968 GError *parse_error = NULL;
2969 gchar *string_value, *p, *q0, *q;
2971 string_value = g_new0 (gchar, strlen (value) + 1);
2973 p = (gchar *) value;
2974 q0 = q = string_value;
3004 if (pieces && *p == key_file->list_separator)
3005 *q = key_file->list_separator;
3011 if (parse_error == NULL)
3019 g_set_error (error, G_KEY_FILE_ERROR,
3020 G_KEY_FILE_ERROR_INVALID_VALUE,
3021 _("Key file contains invalid escape "
3022 "sequence '%s'"), sequence);
3031 if (pieces && (*p == key_file->list_separator))
3033 *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
3042 if (p[-1] == '\\' && error == NULL)
3043 g_set_error (error, G_KEY_FILE_ERROR,
3044 G_KEY_FILE_ERROR_INVALID_VALUE,
3045 _("Key file contains escape character at end of line"));
3051 *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
3052 *pieces = g_slist_reverse (*pieces);
3055 return string_value;
3059 g_key_file_parse_string_as_value (GKeyFile *key_file,
3060 const gchar *string,
3061 gboolean escape_separator)
3063 gchar *value, *p, *q;
3066 length = strlen (string) + 1;
3068 /* Worst case would be that every character needs to be escaped.
3069 * In other words every character turns to two characters
3071 value = g_new0 (gchar, 2 * length);
3073 p = (gchar *) string;
3075 while (p < (string + length - 1))
3077 gchar escaped_character[3] = { '\\', 0, 0 };
3082 escaped_character[1] = 's';
3083 strcpy (q, escaped_character);
3087 escaped_character[1] = 'n';
3088 strcpy (q, escaped_character);
3092 escaped_character[1] = 't';
3093 strcpy (q, escaped_character);
3097 escaped_character[1] = 'r';
3098 strcpy (q, escaped_character);
3102 escaped_character[1] = '\\';
3103 strcpy (q, escaped_character);
3107 if (escape_separator && *p == key_file->list_separator)
3109 escaped_character[1] = key_file->list_separator;
3110 strcpy (q, escaped_character);
3128 g_key_file_parse_value_as_integer (GKeyFile *key_file,
3132 gchar *end_of_valid_int;
3135 int_value = strtol (value, &end_of_valid_int, 0);
3137 if (*end_of_valid_int != '\0')
3138 g_set_error (error, G_KEY_FILE_ERROR,
3139 G_KEY_FILE_ERROR_INVALID_VALUE,
3140 _("Value '%s' cannot be interpreted as a number."), value);
3146 g_key_file_parse_integer_as_value (GKeyFile *key_file,
3150 return g_strdup_printf ("%d", value);
3154 g_key_file_parse_value_as_boolean (GKeyFile *key_file,
3160 if (strcmp (value, "true") == 0 || strcmp (value, "1") == 0)
3162 else if (strcmp (value, "false") == 0 || strcmp (value, "0") == 0)
3166 g_set_error (error, G_KEY_FILE_ERROR,
3167 G_KEY_FILE_ERROR_INVALID_VALUE,
3168 _("Value '%s' cannot be interpreted as a boolean."), value);
3174 g_key_file_parse_boolean_as_value (GKeyFile *key_file,
3178 return g_strdup ("true");
3180 return g_strdup ("false");
3184 g_key_file_parse_value_as_comment (GKeyFile *key_file,
3188 gchar **lines, *comment;
3191 string = g_string_sized_new (512);
3193 lines = g_strsplit (value, "\n", 0);
3195 for (i = 0; lines[i] != NULL; i++)
3197 if (lines[i][0] != '#')
3198 g_string_append_printf (string, "%s\n", lines[i]);
3200 g_string_append_printf (string, "%s\n", lines[i] + 1);
3204 comment = string->str;
3206 g_string_free (string, FALSE);
3212 g_key_file_parse_comment_as_value (GKeyFile *key_file,
3213 const gchar *comment)
3216 gchar **lines, *value;
3219 string = g_string_sized_new (512);
3221 lines = g_strsplit (comment, "\n", 0);
3223 for (i = 0; lines[i] != NULL; i++)
3224 g_string_append_printf (string, "#%s%s", lines[i],
3225 lines[i + 1] == NULL? "" : "\n");
3228 value = string->str;
3230 g_string_free (string, FALSE);