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.
33 #include <sys/types.h>
40 #include "gfileutils.h"
46 #include "gmessages.h"
48 #include "gstrfuncs.h"
51 typedef struct _GKeyFileGroup GKeyFileGroup;
57 gchar *start_group_name;
59 GKeyFileGroup *current_group;
61 GString *parse_buffer; /* Holds up to one line of not-yet-parsed data */
63 /* Used for sizing the output buffer during serialization
65 gsize approximate_size;
72 typedef struct _GKeyFileKeyValuePair GKeyFileKeyValuePair;
76 const gchar *name; /* NULL for above first group (which will be comments) */
78 GKeyFileKeyValuePair *comment; /* Special comment that is stuck to the top of a group */
80 GList *key_value_pairs;
82 /* Used in parallel with key_value_pairs for
83 * increased lookup performance
85 GHashTable *lookup_map;
88 struct _GKeyFileKeyValuePair
90 gchar *key; /* NULL for comments */
94 static gint find_file_in_data_dirs (const gchar *file,
98 static gboolean g_key_file_load_from_fd (GKeyFile *key_file,
102 static GList *g_key_file_lookup_group_node (GKeyFile *key_file,
103 const gchar *group_name);
104 static GKeyFileGroup *g_key_file_lookup_group (GKeyFile *key_file,
105 const gchar *group_name);
107 static GList *g_key_file_lookup_key_value_pair_node (GKeyFile *key_file,
108 GKeyFileGroup *group,
110 static GKeyFileKeyValuePair *g_key_file_lookup_key_value_pair (GKeyFile *key_file,
111 GKeyFileGroup *group,
114 static void g_key_file_remove_group_node (GKeyFile *entry,
116 static void g_key_file_remove_key_value_pair_node (GKeyFile *key_file,
117 GKeyFileGroup *group,
120 static void g_key_file_add_key (GKeyFile *entry,
121 const gchar *group_name,
124 static void g_key_file_add_group (GKeyFile *entry,
125 const gchar *group_name);
126 static void g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair);
127 static gboolean g_key_file_line_is_comment (const gchar *line);
128 static gboolean g_key_file_line_is_group (const gchar *line);
129 static gboolean g_key_file_line_is_key_value_pair (const gchar *line);
130 static gchar *g_key_file_parse_value_as_string (GKeyFile *entry,
134 static gchar *g_key_file_parse_string_as_value (GKeyFile *entry,
136 gboolean escape_separator);
137 static gint g_key_file_parse_value_as_integer (GKeyFile *entry,
140 static gchar *g_key_file_parse_integer_as_value (GKeyFile *entry,
142 static gboolean g_key_file_parse_value_as_boolean (GKeyFile *entry,
145 static gchar *g_key_file_parse_boolean_as_value (GKeyFile *entry,
147 static gchar *g_key_file_parse_value_as_comment (GKeyFile *key_file,
149 static gchar *g_key_file_parse_comment_as_value (GKeyFile *key_file,
150 const gchar *comment);
151 static void g_key_file_parse_key_value_pair (GKeyFile *entry,
155 static void g_key_file_parse_comment (GKeyFile *entry,
159 static void g_key_file_parse_group (GKeyFile *entry,
163 static gchar *key_get_locale (const gchar *key);
164 static void g_key_file_parse_data (GKeyFile *entry,
168 static void g_key_file_flush_parse_buffer (GKeyFile *entry,
173 g_key_file_error_quark (void)
175 static GQuark error_quark = 0;
177 if (error_quark == 0)
178 error_quark = g_quark_from_static_string ("g-key-file-error-quark");
184 g_key_file_init (GKeyFile *key_file)
186 key_file->current_group = g_new0 (GKeyFileGroup, 1);
187 key_file->groups = g_list_prepend (NULL, key_file->current_group);
188 key_file->start_group_name = NULL;
189 key_file->parse_buffer = g_string_sized_new (128);
190 key_file->approximate_size = 0;
191 key_file->list_separator = ';';
196 g_key_file_clear (GKeyFile *key_file)
198 GList *tmp, *group_node;
200 if (key_file->parse_buffer)
201 g_string_free (key_file->parse_buffer, TRUE);
203 g_free (key_file->start_group_name);
205 tmp = key_file->groups;
210 g_key_file_remove_group_node (key_file, group_node);
213 g_assert (key_file->groups == NULL);
220 * Creates a new empty #GKeyFile object. Use g_key_file_load_from_file(),
221 * g_key_file_load_from_data() or g_key_file_load_from_data_dirs() to
222 * read an existing key file.
224 * Return value: an empty #GKeyFile.
229 g_key_file_new (void)
233 key_file = g_new0 (GKeyFile, 1);
234 g_key_file_init (key_file);
240 * g_key_file_set_list_separator:
241 * @key_file: a #GKeyFile
242 * @separator: the separator
244 * Sets the character which is used to separate
245 * values in lists. Typically ';' or ',' are used
246 * as separators. The default list separator is ';'.
251 g_key_file_set_list_separator (GKeyFile *key_file,
254 key_file->list_separator = separator;
258 /* Iterates through all the directories in *dirs trying to
259 * open file. When it successfully locates and opens a file it
260 * returns the file descriptor to the open file. It also
261 * outputs the absolute path of the file in output_file and
262 * leaves the unchecked directories in *dirs.
265 find_file_in_data_dirs (const gchar *file,
270 gchar **data_dirs, *data_dir, *path;
283 while (data_dirs && (data_dir = *data_dirs) && fd < 0)
285 gchar *candidate_file, *sub_dir;
287 candidate_file = (gchar *) file;
288 sub_dir = g_strdup ("");
289 while (candidate_file != NULL && fd < 0)
293 path = g_build_filename (data_dir, sub_dir,
294 candidate_file, NULL);
296 fd = open (path, O_RDONLY);
298 if (output_file != NULL)
299 *output_file = g_strdup (path);
303 if (fd < 0 && file_error == NULL)
304 file_error = g_error_new (G_KEY_FILE_ERROR,
305 G_KEY_FILE_ERROR_NOT_FOUND,
306 _("Valid key file could not be "
307 "found in data dirs"));
309 candidate_file = strchr (candidate_file, '-');
311 if (candidate_file == NULL)
317 sub_dir = g_strndup (file, candidate_file - file - 1);
319 for (p = sub_dir; *p != '\0'; p++)
322 *p = G_DIR_SEPARATOR;
334 g_error_free (file_error);
336 g_propagate_error (error, file_error);
339 if (output_file && fd < 0)
341 g_free (*output_file);
349 g_key_file_load_from_fd (GKeyFile *key_file,
354 GError *key_file_error = NULL;
356 struct stat stat_buf;
357 gchar read_buf[4096];
359 if (key_file->approximate_size > 0)
361 g_key_file_clear (key_file);
362 g_key_file_init (key_file);
364 key_file->flags = flags;
366 fstat (fd, &stat_buf);
367 if (stat_buf.st_size == 0)
369 g_set_error (error, G_KEY_FILE_ERROR,
370 G_KEY_FILE_ERROR_PARSE,
378 bytes_read = read (fd, read_buf, 4096);
380 if (bytes_read == 0) /* End of File */
388 g_set_error (error, G_FILE_ERROR,
389 g_file_error_from_errno (errno),
390 _("Failed to read from file: %s"),
395 g_key_file_parse_data (key_file,
396 read_buf, bytes_read,
399 while (!key_file_error);
403 g_propagate_error (error, key_file_error);
407 g_key_file_flush_parse_buffer (key_file, &key_file_error);
411 g_propagate_error (error, key_file_error);
419 * g_key_file_load_from_file:
420 * @key_file: an empty #GKeyFile struct
421 * @file: the path of a filename to load
422 * @flags: flags from #GKeyFileFlags
423 * @error: return location for a #GError, or %NULL
425 * Loads a key file into an empty #GKeyFile structure.
426 * If the file could not be loaded then %error is set to
427 * either a #GFileError or #GKeyFileError.
429 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
433 g_key_file_load_from_file (GKeyFile *key_file,
438 GError *key_file_error = NULL;
441 g_return_val_if_fail (key_file != NULL, FALSE);
442 g_return_val_if_fail (file != NULL, FALSE);
444 if (!g_file_test (file, G_FILE_TEST_IS_REGULAR))
446 g_set_error (error, G_FILE_ERROR,
448 _("Failed to open file '%s': Not a regular file"),
453 fd = open (file, O_RDONLY);
457 g_set_error (error, G_FILE_ERROR,
458 g_file_error_from_errno (errno),
459 _("Failed to open file '%s': %s"),
460 file, g_strerror (errno));
464 g_key_file_load_from_fd (key_file, fd, flags, &key_file_error);
469 g_propagate_error (error, key_file_error);
477 * g_key_file_load_from_data:
478 * @key_file: an empty #GKeyFile struct
479 * @data: key file loaded in memory.
480 * @length: the length of @data in bytes
481 * @flags: flags from #GKeyFileFlags
482 * @error: return location for a #GError, or %NULL
484 * Loads a key file from memory into an empty #GKeyFile structure.
485 * If the object cannot be created then %error is set to a #GKeyFileError.
487 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
491 g_key_file_load_from_data (GKeyFile *key_file,
497 GError *key_file_error = NULL;
499 g_return_val_if_fail (data != NULL, FALSE);
500 g_return_val_if_fail (length != 0, FALSE);
502 if (key_file->approximate_size > 0)
504 g_key_file_clear (key_file);
505 g_key_file_init (key_file);
507 key_file->flags = flags;
509 g_key_file_parse_data (key_file, data, length, &key_file_error);
513 g_propagate_error (error, key_file_error);
517 g_key_file_flush_parse_buffer (key_file, &key_file_error);
521 g_propagate_error (error, key_file_error);
529 * g_key_file_load_from_data_dirs:
530 * @key_file: an empty #GKeyFile struct
531 * @file: a relative path to a filename to open and parse
532 * @full_path: return location for a string containing the full path
533 * of the file, or %NULL
534 * @flags: flags from #GKeyFileFlags
535 * @error: return location for a #GError, or %NULL
537 * This function looks for a key file named @file in the paths
538 * returned from g_get_user_data_dir() and g_get_system_data_dirs(),
539 * loads the file into @key_file and returns the file's full path in
540 * @full_path. If the file could not be loaded then an %error is
541 * set to either a #GFileError or #GKeyFileError.
543 * Return value: %TRUE if a key file could be loaded, %FALSE othewise
547 g_key_file_load_from_data_dirs (GKeyFile *key_file,
553 GError *key_file_error = NULL;
554 gchar **all_data_dirs, **data_dirs;
555 const gchar * user_data_dir;
556 const gchar * const * system_data_dirs;
562 g_return_val_if_fail (!g_path_is_absolute (file), FALSE);
564 user_data_dir = g_get_user_data_dir ();
565 system_data_dirs = g_get_system_data_dirs ();
566 all_data_dirs = g_new0 (gchar *, g_strv_length ((gchar **)system_data_dirs) + 1);
569 all_data_dirs[i++] = g_strdup (user_data_dir);
572 while (system_data_dirs[j] != NULL)
573 all_data_dirs[i++] = g_strdup (system_data_dirs[j++]);
576 data_dirs = all_data_dirs;
577 while (*data_dirs != NULL && !found_file)
579 fd = find_file_in_data_dirs (file, &output_path, &data_dirs,
585 g_propagate_error (error, key_file_error);
589 found_file = g_key_file_load_from_fd (key_file, fd, flags,
595 g_propagate_error (error, key_file_error);
596 g_free (output_path);
601 *full_path = output_path;
604 g_strfreev (all_data_dirs);
610 * @key_file: a #GKeyFile
617 g_key_file_free (GKeyFile *key_file)
619 g_return_if_fail (key_file != NULL);
621 g_key_file_clear (key_file);
625 /* If G_KEY_FILE_KEEP_TRANSLATIONS is not set, only returns
626 * true for locales that match those in g_get_language_names().
629 g_key_file_locale_is_interesting (GKeyFile *key_file,
632 const const gchar * const * current_locales;
635 if (key_file->flags & G_KEY_FILE_KEEP_TRANSLATIONS)
638 current_locales = g_get_language_names ();
640 for (i = 0; current_locales[i] != NULL; i++)
642 if (g_ascii_strcasecmp (current_locales[i], locale) == 0)
650 g_key_file_parse_line (GKeyFile *key_file,
655 GError *parse_error = NULL;
658 g_return_if_fail (key_file != NULL);
659 g_return_if_fail (line != NULL);
661 line_start = (gchar *) line;
662 while (g_ascii_isspace (*line_start))
665 if (g_key_file_line_is_comment (line_start))
666 g_key_file_parse_comment (key_file, line, length, &parse_error);
667 else if (g_key_file_line_is_group (line_start))
668 g_key_file_parse_group (key_file, line_start,
669 length - (line_start - line),
671 else if (g_key_file_line_is_key_value_pair (line_start))
672 g_key_file_parse_key_value_pair (key_file, line_start,
673 length - (line_start - line),
677 g_set_error (error, G_KEY_FILE_ERROR,
678 G_KEY_FILE_ERROR_PARSE,
679 _("Key file contains line '%s' which is not "
680 "a key-value pair, group, or comment"), line);
685 g_propagate_error (error, parse_error);
689 g_key_file_parse_comment (GKeyFile *key_file,
694 GKeyFileKeyValuePair *pair;
696 if (!(key_file->flags & G_KEY_FILE_KEEP_COMMENTS))
699 g_assert (key_file->current_group != NULL);
701 pair = g_new0 (GKeyFileKeyValuePair, 1);
704 pair->value = g_strndup (line, length);
706 key_file->current_group->key_value_pairs =
707 g_list_prepend (key_file->current_group->key_value_pairs, pair);
711 g_key_file_parse_group (GKeyFile *key_file,
717 const gchar *group_name_start, *group_name_end;
719 /* advance past opening '['
721 group_name_start = line + 1;
722 group_name_end = line + length - 1;
724 while (*group_name_end != ']')
727 group_name = g_strndup (group_name_start,
728 group_name_end - group_name_start);
730 if (key_file->start_group_name == NULL)
731 key_file->start_group_name = g_strdup (group_name);
733 g_key_file_add_group (key_file, group_name);
738 g_key_file_parse_key_value_pair (GKeyFile *key_file,
743 gchar *key, *value, *key_end, *value_start, *locale;
744 gsize key_len, value_len;
746 if (key_file->current_group == NULL || key_file->current_group->name == NULL)
748 g_set_error (error, G_KEY_FILE_ERROR,
749 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
750 _("Key file does not start with a group"));
754 key_end = value_start = strchr (line, '=');
756 g_assert (key_end != NULL);
761 /* Pull the key name from the line (chomping trailing whitespace)
763 while (g_ascii_isspace (*key_end))
766 key_len = key_end - line + 2;
768 g_assert (key_len <= length);
770 key = g_strndup (line, key_len - 1);
772 /* Pull the value from the line (chugging leading whitespace)
774 while (g_ascii_isspace (*value_start))
777 value_len = line + length - value_start + 1;
779 value = g_strndup (value_start, value_len);
781 g_assert (key_file->start_group_name != NULL);
783 if (key_file->current_group
784 && key_file->current_group->name
785 && strcmp (key_file->start_group_name,
786 key_file->current_group->name) == 0
787 && strcmp (key, "Encoding") == 0)
789 if (g_ascii_strcasecmp (value, "UTF-8") != 0)
791 g_set_error (error, G_KEY_FILE_ERROR,
792 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
793 _("Key file contains unsupported encoding '%s'"), value);
801 /* Is this key a translation? If so, is it one that we care about?
803 locale = key_get_locale (key);
805 if (locale == NULL || g_key_file_locale_is_interesting (key_file, locale))
806 g_key_file_add_key (key_file, key_file->current_group->name, key, value);
814 key_get_locale (const gchar *key)
818 locale = g_strrstr (key, "[");
820 if (locale && strlen (locale) <= 2)
824 locale = g_strndup (locale + 1, strlen (locale) - 2);
830 g_key_file_parse_data (GKeyFile *key_file,
838 g_return_if_fail (key_file != NULL);
842 for (i = 0; i < length; i++)
846 /* When a newline is encountered flush the parse buffer so that the
847 * line can be parsed. Note that completely blank lines won't show
848 * up in the parse buffer, so they get parsed directly.
850 if (key_file->parse_buffer->len > 0)
851 g_key_file_flush_parse_buffer (key_file, &parse_error);
853 g_key_file_parse_comment (key_file, "", 1, &parse_error);
857 g_propagate_error (error, parse_error);
862 g_string_append_c (key_file->parse_buffer, data[i]);
865 key_file->approximate_size += length;
869 g_key_file_flush_parse_buffer (GKeyFile *key_file,
872 GError *file_error = NULL;
874 g_return_if_fail (key_file != NULL);
878 if (key_file->parse_buffer->len > 0)
880 g_key_file_parse_line (key_file, key_file->parse_buffer->str,
881 key_file->parse_buffer->len,
883 g_string_erase (key_file->parse_buffer, 0, -1);
887 g_propagate_error (error, file_error);
894 * g_key_file_to_data:
895 * @key_file: a #GKeyFile
896 * @length: return location for the length of the
897 * returned string, or %NULL
898 * @error: return location for a #GError, or %NULL
900 * This function outputs @key_file as a string.
902 * Return value: a newly allocated string holding
903 * the contents of the #GKeyFile
908 g_key_file_to_data (GKeyFile *key_file,
912 GString *data_string;
914 GList *group_node, *key_file_node;
916 g_return_val_if_fail (key_file != NULL, NULL);
918 data_string = g_string_sized_new (2 * key_file->approximate_size);
920 for (group_node = g_list_last (key_file->groups);
922 group_node = group_node->prev)
924 GKeyFileGroup *group;
926 group = (GKeyFileGroup *) group_node->data;
928 if (group->comment != NULL)
929 g_string_append_printf (data_string, "%s\n", group->comment->value);
930 if (group->name != NULL)
931 g_string_append_printf (data_string, "[%s]\n", group->name);
933 for (key_file_node = g_list_last (group->key_value_pairs);
934 key_file_node != NULL;
935 key_file_node = key_file_node->prev)
937 GKeyFileKeyValuePair *pair;
939 pair = (GKeyFileKeyValuePair *) key_file_node->data;
941 if (pair->key != NULL)
942 g_string_append_printf (data_string, "%s=%s\n", pair->key, pair->value);
944 g_string_append_printf (data_string, "%s\n", pair->value);
949 *length = data_string->len;
951 data = data_string->str;
953 g_string_free (data_string, FALSE);
959 * g_key_file_get_keys:
960 * @key_file: a #GKeyFile
961 * @group_name: a group name, or %NULL
962 * @length: return location for the number of keys returned, or %NULL
963 * @error: return location for a #GError, or %NULL
965 * Returns all keys for the group name @group_name. If @group_name is
966 * %NULL, the start group is used. The array of returned keys will be
967 * %NULL-terminated, so @length may optionally be %NULL.
969 * Return value: a newly-allocated %NULL-terminated array of
970 * strings. Use g_strfreev() to free it.
975 g_key_file_get_keys (GKeyFile *key_file,
976 const gchar *group_name,
980 GKeyFileGroup *group;
985 g_return_val_if_fail (key_file != NULL, NULL);
986 g_return_val_if_fail (group_name != NULL, NULL);
988 group = g_key_file_lookup_group (key_file, group_name);
992 g_set_error (error, G_KEY_FILE_ERROR,
993 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
994 _("Key file does not have group '%s'"),
999 num_keys = g_list_length (group->key_value_pairs);
1001 keys = (gchar **) g_new0 (gchar **, num_keys + 1);
1003 tmp = group->key_value_pairs;
1004 for (i = 0; i < num_keys; i++)
1006 GKeyFileKeyValuePair *pair;
1008 pair = (GKeyFileKeyValuePair *) tmp->data;
1009 keys[i] = g_strdup (pair->key);
1022 * g_key_file_get_start_group:
1023 * @key_file: a #GKeyFile
1025 * Returns the name of the start group of the file.
1027 * Return value: The start group of the key file.
1032 g_key_file_get_start_group (GKeyFile *key_file)
1034 g_return_val_if_fail (key_file != NULL, NULL);
1036 return g_strdup (key_file->start_group_name);
1040 * g_key_file_get_groups:
1041 * @key_file: a #GKeyFile
1042 * @length: return location for the number of returned groups, or %NULL
1044 * Returns all groups in the key file loaded with @key_file. The
1045 * array of returned groups will be %NULL-terminated, so @length may
1046 * optionally be %NULL.
1048 * Return value: a newly-allocated %NULL-terminated array of strings.
1049 * Use g_strfreev() to free it.
1053 g_key_file_get_groups (GKeyFile *key_file,
1058 gsize i, num_groups;
1060 g_return_val_if_fail (key_file != NULL, NULL);
1062 num_groups = g_list_length (key_file->groups);
1064 g_assert (num_groups > 0);
1066 /* Only need num_groups instead of num_groups + 1
1067 * because the first group of the file (last in the
1068 * list) is always the comment group at the top,
1071 groups = (gchar **) g_new0 (gchar **, num_groups);
1073 group_node = g_list_last (key_file->groups);
1075 g_assert (((GKeyFileGroup *) group_node->data)->name == NULL);
1078 for (group_node = group_node->prev;
1080 group_node = group_node->prev)
1082 GKeyFileGroup *group;
1084 group = (GKeyFileGroup *) group_node->data;
1086 g_assert (group->name != NULL);
1088 groups[i++] = g_strdup (group->name);
1099 * g_key_file_get_value:
1100 * @key_file: a #GKeyFile
1101 * @group_name: a group name
1103 * @error: return location for a #GError, or #NULL
1105 * Returns the value associated with @key under @group_name.
1106 * In the event the key cannot be found, %NULL is returned and
1107 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1108 * event that the @group_name cannot be found, %NULL is returned
1109 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1111 * Return value: a string or %NULL if the specified key cannot be
1117 g_key_file_get_value (GKeyFile *key_file,
1118 const gchar *group_name,
1122 GKeyFileGroup *group;
1123 GKeyFileKeyValuePair *pair;
1124 gchar *value = NULL;
1126 g_return_val_if_fail (key_file != NULL, NULL);
1127 g_return_val_if_fail (group_name != NULL, NULL);
1129 group = g_key_file_lookup_group (key_file, group_name);
1133 g_set_error (error, G_KEY_FILE_ERROR,
1134 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1135 _("Key file does not have group '%s'"),
1140 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1143 value = g_strdup (pair->value);
1145 g_set_error (error, G_KEY_FILE_ERROR,
1146 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
1147 _("Key file does not have key '%s'"), key);
1153 * g_key_file_set_value:
1154 * @key_file: a #GKeyFile
1155 * @group_name: a group name
1159 * Associates a new value with @key under @group_name.
1160 * If @key cannot be found then it is created. If @group_name
1161 * cannot be found then it is created as well.
1166 g_key_file_set_value (GKeyFile *key_file,
1167 const gchar *group_name,
1171 GKeyFileGroup *group;
1172 GKeyFileKeyValuePair *pair;
1174 g_return_if_fail (key_file != NULL);
1175 g_return_if_fail (key != NULL);
1176 g_return_if_fail (value != NULL);
1178 if (!g_key_file_has_key (key_file, group_name, key, NULL))
1179 g_key_file_add_key (key_file, group_name, key, value);
1182 group = g_key_file_lookup_group (key_file, group_name);
1183 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
1184 g_free (pair->value);
1185 pair->value = g_strdup (value);
1190 * g_key_file_get_string:
1191 * @key_file: a #GKeyFile
1192 * @group_name: a group name
1194 * @error: return location for a #GError, or #NULL
1196 * Returns the value associated with @key under @group_name.
1197 * In the event the key cannot be found, %NULL is returned and
1198 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1199 * event that the @group_name cannot be found, %NULL is returned
1200 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1202 * Return value: a string or %NULL if the specified key cannot be
1208 g_key_file_get_string (GKeyFile *key_file,
1209 const gchar *group_name,
1213 gchar *value, *string_value;
1214 GError *key_file_error;
1216 g_return_val_if_fail (key_file != NULL, NULL);
1217 g_return_val_if_fail (key != NULL, NULL);
1219 key_file_error = NULL;
1221 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1225 g_propagate_error (error, key_file_error);
1229 if (!g_utf8_validate (value, -1, NULL))
1231 g_set_error (error, G_KEY_FILE_ERROR,
1232 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1233 _("Key file contains key '%s' with value '%s' "
1234 "which is not UTF-8"), key, value);
1239 string_value = g_key_file_parse_value_as_string (key_file, value, NULL,
1245 if (g_error_matches (key_file_error,
1247 G_KEY_FILE_ERROR_INVALID_VALUE))
1249 g_set_error (error, G_KEY_FILE_ERROR,
1250 G_KEY_FILE_ERROR_INVALID_VALUE,
1251 _("Key file contains key '%s' "
1252 "which has value that cannot be interpreted."),
1254 g_error_free (key_file_error);
1257 g_propagate_error (error, key_file_error);
1260 return string_value;
1264 * g_key_file_set_string:
1265 * @key_file: a #GKeyFile
1266 * @group_name: a group name
1270 * Associates a new string value with @key under @group_name.
1271 * If @key cannot be found then it is created. If @group_name
1272 * cannot be found then it is created as well.
1277 g_key_file_set_string (GKeyFile *key_file,
1278 const gchar *group_name,
1280 const gchar *string)
1284 g_return_if_fail (key_file != NULL);
1285 g_return_if_fail (key != NULL);
1287 value = g_key_file_parse_string_as_value (key_file, string, FALSE);
1288 g_key_file_set_value (key_file, group_name, key, value);
1293 * g_key_file_get_string_list:
1294 * @key_file: a #GKeyFile
1295 * @group_name: a group name
1297 * @length: return location for the number of returned strings, or %NULL
1298 * @error: return location for a #GError, or %NULL
1300 * Returns the values associated with @key under @group_name.
1301 * In the event the key cannot be found, %NULL is returned and
1302 * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the
1303 * event that the @group_name cannot be found, %NULL is returned
1304 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1306 * Return value: a %NULL-terminated string array or %NULL if the specified
1307 * key cannot be found. The array should be freed with g_strfreev().
1312 g_key_file_get_string_list (GKeyFile *key_file,
1313 const gchar *group_name,
1318 GError *key_file_error = NULL;
1319 gchar *value, *string_value, **values;
1321 GSList *p, *pieces = NULL;
1323 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1327 g_propagate_error (error, key_file_error);
1331 if (!g_utf8_validate (value, -1, NULL))
1333 g_set_error (error, G_KEY_FILE_ERROR,
1334 G_KEY_FILE_ERROR_UNKNOWN_ENCODING,
1335 _("Key file contains key '%s' with value '%s' "
1336 "which is not UTF-8"), key, value);
1341 string_value = g_key_file_parse_value_as_string (key_file, value, &pieces, &key_file_error);
1343 g_free (string_value);
1347 if (g_error_matches (key_file_error,
1349 G_KEY_FILE_ERROR_INVALID_VALUE))
1351 g_set_error (error, G_KEY_FILE_ERROR,
1352 G_KEY_FILE_ERROR_INVALID_VALUE,
1353 _("Key file contains key '%s' "
1354 "which has value that cannot be interpreted."),
1356 g_error_free (key_file_error);
1359 g_propagate_error (error, key_file_error);
1362 len = g_slist_length (pieces);
1363 values = g_new0 (gchar *, len + 1);
1364 for (p = pieces, i = 0; p; p = p->next)
1365 values[i++] = p->data;
1368 g_slist_free (pieces);
1377 * g_key_file_set_string_list:
1378 * @key_file: a #GKeyFile
1379 * @group_name: a group name
1381 * @list: an array of locale string values
1382 * @length: number of locale string values in @list
1384 * Associates a list of string values for @key under @group_name.
1385 * If the @key cannot be found then it is created.
1390 g_key_file_set_string_list (GKeyFile *key_file,
1391 const gchar *group_name,
1393 const gchar * const list[],
1396 GString *value_list;
1399 g_return_if_fail (key_file != NULL);
1400 g_return_if_fail (key != NULL);
1402 value_list = g_string_sized_new (length * 128);
1403 for (i = 0; list[i] != NULL && i < length; i++)
1407 value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
1408 g_string_append (value_list, value);
1409 g_string_append_c (value_list, key_file->list_separator);
1414 g_key_file_set_value (key_file, group_name, key, value_list->str);
1415 g_string_free (value_list, TRUE);
1419 * g_key_file_set_locale_string:
1420 * @key_file: a #GKeyFile
1421 * @group_name: a group name
1426 * Associates a string value for @key and @locale under
1427 * @group_name. If the translation for @key cannot be found
1428 * then it is created.
1433 g_key_file_set_locale_string (GKeyFile *key_file,
1434 const gchar *group_name,
1436 const gchar *locale,
1437 const gchar *string)
1439 gchar *full_key, *value;
1441 g_return_if_fail (key_file != NULL);
1442 g_return_if_fail (key != NULL);
1444 value = g_key_file_parse_string_as_value (key_file, string, FALSE);
1445 full_key = g_strdup_printf ("%s[%s]", key, locale);
1446 g_key_file_set_value (key_file, group_name, full_key, value);
1451 extern GSList *_g_compute_locale_variants (const gchar *locale);
1454 * g_key_file_get_locale_string:
1455 * @key_file: a #GKeyFile
1456 * @group_name: a group name
1458 * @locale: a locale or %NULL
1459 * @error: return location for a #GError, or %NULL
1461 * Returns the value associated with @key under @group_name
1462 * translated in the given @locale if available. If @locale is
1463 * %NULL then the current locale is assumed. If @key cannot be
1464 * found then %NULL is returned and @error is set to
1465 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
1466 * with @key cannot be interpreted or no suitable translation can
1467 * be found then the untranslated value is returned and @error is
1468 * set to #G_KEY_FILE_ERROR_INVALID_VALUE and
1469 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND, respectively. In the
1470 * event that the @group_name cannot be found, %NULL is returned
1471 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1473 * Return value: a string or %NULL if the specified key cannot be
1478 g_key_file_get_locale_string (GKeyFile *key_file,
1479 const gchar *group_name,
1481 const gchar *locale,
1484 gchar *candidate_key, *translated_value;
1485 GError *key_file_error;
1487 gboolean free_languages = FALSE;
1490 candidate_key = NULL;
1491 translated_value = NULL;
1492 key_file_error = NULL;
1494 if (!g_key_file_has_group (key_file, group_name))
1496 g_set_error (error, G_KEY_FILE_ERROR,
1497 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
1498 _("Key file does not have group '%s'"),
1507 list = _g_compute_locale_variants (locale);
1509 languages = g_new0 (gchar *, g_slist_length (list) + 1);
1510 for (l = list, i = 0; l; l = l->next, i++)
1511 languages[i] = l->data;
1512 languages[i] = NULL;
1514 g_slist_free (list);
1515 free_languages = TRUE;
1519 languages = (gchar **) g_get_language_names ();
1520 free_languages = FALSE;
1523 for (i = 0; languages[i]; i++)
1525 candidate_key = g_strdup_printf ("%s[%s]", key, languages[i]);
1527 translated_value = g_key_file_get_string (key_file,
1529 candidate_key, NULL);
1530 g_free (candidate_key);
1532 if (translated_value)
1536 if (translated_value && !g_utf8_validate (translated_value, -1, NULL))
1538 g_set_error (error, G_KEY_FILE_ERROR,
1539 G_KEY_FILE_ERROR_INVALID_VALUE,
1540 _("Key file contains key '%s' "
1541 "which has value that cannot be interpreted."),
1543 g_free (translated_value);
1544 translated_value = NULL;
1547 /* Fallback to untranslated key
1549 if (!translated_value)
1551 translated_value = g_key_file_get_string (key_file, group_name, key,
1554 if (!translated_value)
1555 g_propagate_error (error, key_file_error);
1557 g_set_error (error, G_KEY_FILE_ERROR,
1558 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
1559 _("Key file contains no translated value "
1560 "for key '%s' with locale '%s'."),
1565 g_strfreev (languages);
1567 return translated_value;
1571 * g_key_file_get_locale_string_list:
1572 * @key_file: a #GKeyFile
1573 * @group_name: a group name
1576 * @length: return location for the number of returned strings or %NULL
1577 * @error: return location for a #GError or %NULL
1579 * Returns the values associated with @key under @group_name
1580 * translated in the given @locale if available. If @locale is
1581 * %NULL then the current locale is assumed. If @key cannot be
1582 * found then %NULL is returned and @error is set to
1583 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
1584 * with @key cannot be interpreted or no suitable translations
1585 * can be found then the untranslated values are returned and
1586 * @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE and
1587 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND, respectively. In the
1588 * event that the @group_name cannot be found, %NULL is returned
1589 * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
1590 * The returned array is %NULL-terminated, so @length may optionally be %NULL.
1592 * Return value: a newly allocated %NULL-terminated string array
1593 * or %NULL if the key isn't found. The string array should be freed
1594 * with g_strfreev().
1599 g_key_file_get_locale_string_list (GKeyFile *key_file,
1600 const gchar *group_name,
1602 const gchar *locale,
1606 GError *key_file_error;
1607 gchar **values, *value;
1609 key_file_error = NULL;
1611 value = g_key_file_get_locale_string (key_file, group_name,
1616 g_propagate_error (error, key_file_error);
1621 if (value[strlen (value) - 1] == ';')
1622 value[strlen (value) - 1] = '\0';
1624 values = g_strsplit (value, ";", 0);
1629 *length = g_strv_length (values);
1635 * g_key_file_set_locale_string_list:
1636 * @key_file: a #GKeyFile
1637 * @group_name: a group name
1640 * @list: a %NULL-terminated array of locale string values
1641 * @length: the length of @list
1643 * Associates a list of string values for @key and @locale under
1644 * @group_name. If the translation for @key cannot be found then
1650 g_key_file_set_locale_string_list (GKeyFile *key_file,
1651 const gchar *group_name,
1653 const gchar *locale,
1654 const gchar * const list[],
1657 GString *value_list;
1661 g_return_if_fail (key_file != NULL);
1662 g_return_if_fail (key != NULL);
1664 value_list = g_string_sized_new (length * 128);
1665 for (i = 0; list[i] != NULL && i < length; i++)
1669 value = g_key_file_parse_string_as_value (key_file, list[i], TRUE);
1671 g_string_append (value_list, value);
1672 g_string_append_c (value_list, ';');
1677 full_key = g_strdup_printf ("%s[%s]", key, locale);
1678 g_key_file_set_value (key_file, group_name, full_key, value_list->str);
1680 g_string_free (value_list, TRUE);
1684 * g_key_file_get_boolean:
1685 * @key_file: a #GKeyFile
1686 * @group_name: a group name
1688 * @error: return location for a #GError
1690 * Returns the value associated with @key under @group_name as a
1691 * boolean. If @key cannot be found then the return value is
1692 * undefined and @error is set to
1693 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
1694 * associated with @key cannot be interpreted as a boolean then
1695 * the return value is also undefined and @error is set to
1696 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1698 * Return value: the value associated with the key as a boolean
1702 g_key_file_get_boolean (GKeyFile *key_file,
1703 const gchar *group_name,
1707 GError *key_file_error = NULL;
1709 gboolean bool_value;
1711 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1715 g_propagate_error (error, key_file_error);
1719 bool_value = g_key_file_parse_value_as_boolean (key_file, value,
1725 if (g_error_matches (key_file_error,
1727 G_KEY_FILE_ERROR_INVALID_VALUE))
1729 g_set_error (error, G_KEY_FILE_ERROR,
1730 G_KEY_FILE_ERROR_INVALID_VALUE,
1731 _("Key file contains key '%s' "
1732 "which has value that cannot be interpreted."),
1734 g_error_free (key_file_error);
1737 g_propagate_error (error, key_file_error);
1744 * g_key_file_set_boolean:
1745 * @key_file: a #GKeyFile
1746 * @group_name: a group name
1748 * @value: %TRUE or %FALSE
1750 * Associates a new boolean value with @key under @group_name.
1751 * If @key cannot be found then it is created.
1756 g_key_file_set_boolean (GKeyFile *key_file,
1757 const gchar *group_name,
1763 g_return_if_fail (key_file != NULL);
1764 g_return_if_fail (key != NULL);
1766 result = g_key_file_parse_boolean_as_value (key_file, value);
1767 g_key_file_set_value (key_file, group_name, key, result);
1772 * g_key_file_get_boolean_list:
1773 * @key_file: a #GKeyFile
1774 * @group_name: a group name
1776 * @length: the number of booleans returned
1777 * @error: return location for a #GError
1779 * Returns the values associated with @key under @group_name as
1780 * booleans. If @key cannot be found then the return value is
1781 * undefined and @error is set to
1782 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values
1783 * associated with @key cannot be interpreted as booleans then
1784 * the return value is also undefined and @error is set to
1785 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1787 * Return value: the values associated with the key as a boolean
1790 g_key_file_get_boolean_list (GKeyFile *key_file,
1791 const gchar *group_name,
1796 GError *key_file_error;
1798 gboolean *bool_values;
1801 key_file_error = NULL;
1803 values = g_key_file_get_string_list (key_file, group_name, key,
1804 &num_bools, &key_file_error);
1807 g_propagate_error (error, key_file_error);
1812 bool_values = g_new0 (gboolean, num_bools);
1814 for (i = 0; i < num_bools; i++)
1816 bool_values[i] = g_key_file_parse_value_as_boolean (key_file,
1822 g_propagate_error (error, key_file_error);
1823 g_strfreev (values);
1824 g_free (bool_values);
1829 g_strfreev (values);
1832 *length = num_bools;
1838 * g_key_file_set_boolean_list:
1839 * @key_file: a #GKeyFile
1840 * @group_name: a group name
1842 * @list: an array of boolean values
1843 * @length: length of @list
1845 * Associates a list of boolean values with @key under
1846 * @group_name. If @key cannot be found then it is created.
1851 g_key_file_set_boolean_list (GKeyFile *key_file,
1852 const gchar *group_name,
1857 GString *value_list;
1860 g_return_if_fail (key_file != NULL);
1861 g_return_if_fail (key != NULL);
1863 value_list = g_string_sized_new (length * 8);
1864 for (i = 0; i < length; i++)
1868 value = g_key_file_parse_boolean_as_value (key_file, list[i]);
1870 g_string_append (value_list, value);
1871 g_string_append_c (value_list, key_file->list_separator);
1876 g_key_file_set_value (key_file, group_name, key, value_list->str);
1877 g_string_free (value_list, TRUE);
1881 * g_key_file_get_integer:
1882 * @key_file: a #GKeyFile
1883 * @group_name: a group name
1885 * @error: return location for a #GError
1887 * Returns the value associated with @key under @group_name as an
1888 * integer. If @key cannot be found then the return value is
1889 * undefined and @error is set to
1890 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value
1891 * associated with @key cannot be interpreted as an integer then
1892 * the return value is also undefined and @error is set to
1893 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1895 * Return value: the value associated with the key as an integer.
1899 g_key_file_get_integer (GKeyFile *key_file,
1900 const gchar *group_name,
1904 GError *key_file_error;
1908 key_file_error = NULL;
1910 value = g_key_file_get_value (key_file, group_name, key, &key_file_error);
1914 g_propagate_error (error, key_file_error);
1918 int_value = g_key_file_parse_value_as_integer (key_file, value,
1924 if (g_error_matches (key_file_error,
1926 G_KEY_FILE_ERROR_INVALID_VALUE))
1928 g_set_error (error, G_KEY_FILE_ERROR,
1929 G_KEY_FILE_ERROR_INVALID_VALUE,
1930 _("Key file contains key '%s' in group '%s' "
1931 "which has value that cannot be interpreted."), key,
1933 g_error_free (key_file_error);
1936 g_propagate_error (error, key_file_error);
1943 * g_key_file_set_integer:
1944 * @key_file: a #GKeyFile
1945 * @group_name: a group name
1947 * @value: an integer value
1949 * Associates a new integer value with @key under @group_name.
1950 * If @key cannot be found then it is created.
1955 g_key_file_set_integer (GKeyFile *key_file,
1956 const gchar *group_name,
1962 g_return_if_fail (key_file != NULL);
1963 g_return_if_fail (key != NULL);
1965 result = g_key_file_parse_integer_as_value (key_file, value);
1966 g_key_file_set_value (key_file, group_name, key, result);
1971 * g_key_file_get_integer_list:
1972 * @key_file: a #GKeyFile
1973 * @group_name: a group name
1975 * @length: the number of integers returned
1976 * @error: return location for a #GError
1978 * Returns the values associated with @key under @group_name as
1979 * integers. If @key cannot be found then the return value is
1980 * undefined and @error is set to
1981 * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values
1982 * associated with @key cannot be interpreted as integers then
1983 * the return value is also undefined and @error is set to
1984 * #G_KEY_FILE_ERROR_INVALID_VALUE.
1986 * Return value: the values associated with the key as a integer
1990 g_key_file_get_integer_list (GKeyFile *key_file,
1991 const gchar *group_name,
1996 GError *key_file_error = NULL;
2001 values = g_key_file_get_string_list (key_file, group_name, key,
2002 &num_ints, &key_file_error);
2005 g_propagate_error (error, key_file_error);
2010 int_values = g_new0 (gint, num_ints);
2012 for (i = 0; i < num_ints; i++)
2014 int_values[i] = g_key_file_parse_value_as_integer (key_file,
2020 g_propagate_error (error, key_file_error);
2021 g_strfreev (values);
2022 g_free (int_values);
2027 g_strfreev (values);
2036 * g_key_file_set_integer_list:
2037 * @key_file: a #GKeyFile
2038 * @group_name: a group name
2040 * @list: an array of integer values
2041 * @length: number of integer values in @list
2043 * Associates a list of integer values with @key under
2044 * @group_name. If @key cannot be found then it is created.
2049 g_key_file_set_integer_list (GKeyFile *key_file,
2050 const gchar *group_name,
2058 g_return_if_fail (key_file != NULL);
2059 g_return_if_fail (key != NULL);
2061 values = g_string_sized_new (length * 16);
2062 for (i = 0; i < length; i++)
2066 value = g_key_file_parse_integer_as_value (key_file, list[i]);
2068 g_string_append (values, value);
2069 g_string_append_c (values, ';');
2074 g_key_file_set_value (key_file, group_name, key, values->str);
2075 g_string_free (values, TRUE);
2079 g_key_file_set_key_comment (GKeyFile *key_file,
2080 const gchar *group_name,
2082 const gchar *comment,
2085 GKeyFileGroup *group;
2086 GKeyFileKeyValuePair *pair;
2087 GList *key_node, *comment_node, *tmp;
2089 group = g_key_file_lookup_group (key_file, group_name);
2092 g_set_error (error, G_KEY_FILE_ERROR,
2093 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2094 _("Key file does not have group '%s'"),
2100 /* First find the key the comments are supposed to be
2103 key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
2105 if (key_node == NULL)
2107 g_set_error (error, G_KEY_FILE_ERROR,
2108 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2109 _("Key file does not have key '%s' in group '%s'"),
2114 /* Then find all the comments already associated with the
2117 tmp = key_node->next;
2120 GKeyFileKeyValuePair *pair;
2122 pair = (GKeyFileKeyValuePair *) tmp->data;
2124 if (pair->key != NULL)
2129 g_key_file_remove_key_value_pair_node (key_file, group,
2133 if (comment == NULL)
2136 /* Now we can add our new comment
2138 pair = g_new0 (GKeyFileKeyValuePair, 1);
2141 pair->value = g_key_file_parse_comment_as_value (key_file, comment);
2143 key_node = g_list_insert (key_node, pair, 1);
2147 g_key_file_set_group_comment (GKeyFile *key_file,
2148 const gchar *group_name,
2149 const gchar *comment,
2152 GKeyFileGroup *group;
2154 group = g_key_file_lookup_group (key_file, group_name);
2157 g_set_error (error, G_KEY_FILE_ERROR,
2158 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2159 _("Key file does not have group '%s'"),
2165 /* First remove any existing comment
2169 g_key_file_key_value_pair_free (group->comment);
2170 group->comment = NULL;
2173 if (comment == NULL)
2176 /* Now we can add our new comment
2178 group->comment = g_new0 (GKeyFileKeyValuePair, 1);
2180 group->comment->key = NULL;
2181 group->comment->value = g_key_file_parse_comment_as_value (key_file, comment);
2185 g_key_file_set_top_comment (GKeyFile *key_file,
2186 const gchar *comment,
2190 GKeyFileGroup *group;
2191 GKeyFileKeyValuePair *pair;
2193 /* The last group in the list should be the top (comments only)
2196 g_assert (key_file->groups != NULL);
2197 group_node = g_list_last (key_file->groups);
2198 group = (GKeyFileGroup *) group_node->data;
2199 g_assert (group->name == NULL);
2201 /* Note all keys must be comments at the top of
2202 * the file, so we can just free it all.
2204 if (group->key_value_pairs != NULL)
2206 g_list_foreach (group->key_value_pairs,
2207 (GFunc) g_key_file_key_value_pair_free,
2209 g_list_free (group->key_value_pairs);
2210 group->key_value_pairs = NULL;
2213 if (comment == NULL)
2216 pair = g_new0 (GKeyFileKeyValuePair, 1);
2219 pair->value = g_key_file_parse_comment_as_value (key_file, comment);
2221 group->key_value_pairs =
2222 g_list_prepend (group->key_value_pairs, pair);
2226 * g_key_file_set_comment:
2227 * @key_file: a #GKeyFile
2228 * @group_name: a group name
2230 * @comment: a comment
2231 * @error: return location for a #GError
2233 * Places a comment above @key from @group_name.
2234 * @group_name. If @key is %NULL then @comment will
2235 * be written above @group_name. If both @key
2236 * and @group_name are NULL, then @comment will
2237 * be written above the first group in the file.
2242 g_key_file_set_comment (GKeyFile *key_file,
2243 const gchar *group_name,
2245 const gchar *comment,
2248 g_return_if_fail (key_file != NULL);
2250 if (group_name != NULL && key != NULL)
2251 g_key_file_set_key_comment (key_file, group_name, key, comment, error);
2252 else if (group_name != NULL)
2253 g_key_file_set_group_comment (key_file, group_name, comment, error);
2255 g_key_file_set_top_comment (key_file, comment, error);
2257 if (comment != NULL)
2258 key_file->approximate_size += strlen (comment);
2262 g_key_file_get_key_comment (GKeyFile *key_file,
2263 const gchar *group_name,
2267 GKeyFileGroup *group;
2268 GList *key_node, *tmp;
2272 group = g_key_file_lookup_group (key_file, group_name);
2275 g_set_error (error, G_KEY_FILE_ERROR,
2276 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2277 _("Key file does not have group '%s'"),
2283 /* First find the key the comments are supposed to be
2286 key_node = g_key_file_lookup_key_value_pair_node (key_file, group, key);
2288 if (key_node == NULL)
2290 g_set_error (error, G_KEY_FILE_ERROR,
2291 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2292 _("Key file does not have key '%s' in group '%s'"),
2299 /* Then find all the comments already associated with the
2300 * key and concatentate them.
2302 tmp = key_node->next;
2305 GKeyFileKeyValuePair *pair;
2307 pair = (GKeyFileKeyValuePair *) tmp->data;
2309 if (pair->key != NULL)
2313 string = g_string_sized_new (512);
2315 comment = g_key_file_parse_value_as_comment (key_file, pair->value);
2316 g_string_append (string, comment);
2324 comment = string->str;
2325 g_string_free (string, FALSE);
2334 g_key_file_get_group_comment (GKeyFile *key_file,
2335 const gchar *group_name,
2338 GKeyFileGroup *group;
2340 group = g_key_file_lookup_group (key_file, group_name);
2343 g_set_error (error, G_KEY_FILE_ERROR,
2344 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2345 _("Key file does not have group '%s'"),
2352 return g_strdup (group->comment->value);
2358 g_key_file_get_top_comment (GKeyFile *key_file,
2361 GList *group_node, *tmp;
2362 GKeyFileGroup *group;
2366 /* The last group in the list should be the top (comments only)
2369 g_assert (key_file->groups != NULL);
2370 group_node = g_list_last (key_file->groups);
2371 group = (GKeyFileGroup *) group_node->data;
2372 g_assert (group->name == NULL);
2376 /* Then find all the comments already associated with the
2377 * key and concatentate them.
2379 tmp = group->key_value_pairs;
2382 GKeyFileKeyValuePair *pair;
2384 pair = (GKeyFileKeyValuePair *) tmp->data;
2386 if (pair->key != NULL)
2390 string = g_string_sized_new (512);
2392 comment = g_key_file_parse_value_as_comment (key_file, pair->value);
2393 g_string_append (string, comment);
2401 comment = string->str;
2402 g_string_free (string, FALSE);
2411 * g_key_file_get_comment:
2412 * @key_file: a #GKeyFile
2413 * @group_name: a group name
2415 * @error: return location for a #GError
2417 * Retreives a comment above @key from @group_name.
2418 * @group_name. If @key is %NULL then @comment will
2419 * be read from above @group_name. If both @key
2420 * and @group_name are NULL, then @comment will
2421 * be read from above the first group in the file.
2424 * Returns: a comment that should be freed with g_free()
2427 g_key_file_get_comment (GKeyFile *key_file,
2428 const gchar *group_name,
2432 g_return_val_if_fail (key_file != NULL, NULL);
2434 if (group_name != NULL && key != NULL)
2435 return g_key_file_get_key_comment (key_file, group_name, key, error);
2436 else if (group_name != NULL)
2437 return g_key_file_get_group_comment (key_file, group_name, error);
2439 return g_key_file_get_top_comment (key_file, error);
2443 * g_key_file_remove_comment:
2444 * @key_file: a #GKeyFile
2445 * @group_name: a group name
2447 * @error: return location for a #GError
2449 * Removes a comment above @key from @group_name.
2450 * @group_name. If @key is %NULL then @comment will
2451 * be written above @group_name. If both @key
2452 * and @group_name are NULL, then @comment will
2453 * be written above the first group in the file.
2459 g_key_file_remove_comment (GKeyFile *key_file,
2460 const gchar *group_name,
2464 g_return_if_fail (key_file != NULL);
2466 if (group_name != NULL && key != NULL)
2467 g_key_file_set_key_comment (key_file, group_name, key, NULL, error);
2468 else if (group_name != NULL)
2469 g_key_file_set_group_comment (key_file, group_name, NULL, error);
2471 g_key_file_set_top_comment (key_file, NULL, error);
2475 * g_key_file_has_group:
2476 * @key_file: a #GKeyFile
2477 * @group_name: a group name
2479 * Looks whether the key file has the group @group_name.
2481 * Return value: %TRUE if @group_name is a part of @key_file, %FALSE
2486 g_key_file_has_group (GKeyFile *key_file,
2487 const gchar *group_name)
2490 GKeyFileGroup *group;
2492 g_return_val_if_fail (key_file != NULL, FALSE);
2493 g_return_val_if_fail (group_name != NULL, FALSE);
2495 for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
2497 group = (GKeyFileGroup *) tmp->data;
2498 if (group && group->name && (strcmp (group->name, group_name) == 0))
2506 * g_key_file_has_key:
2507 * @key_file: a #GKeyFile
2508 * @group_name: a group name
2510 * @error: return location for a #GError
2512 * Looks whether the key file has the key @key in the group
2515 * Return value: %TRUE if @key is a part of @group_name, %FALSE
2520 g_key_file_has_key (GKeyFile *key_file,
2521 const gchar *group_name,
2525 GKeyFileKeyValuePair *pair;
2526 GKeyFileGroup *group;
2528 g_return_val_if_fail (key_file != NULL, FALSE);
2529 g_return_val_if_fail (key != NULL, FALSE);
2530 g_return_val_if_fail (group_name != NULL, FALSE);
2532 group = g_key_file_lookup_group (key_file, group_name);
2536 g_set_error (error, G_KEY_FILE_ERROR,
2537 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2538 _("Key file does not have group '%s'"),
2544 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
2546 return pair != NULL;
2550 g_key_file_add_group (GKeyFile *key_file,
2551 const gchar *group_name)
2553 GKeyFileGroup *group;
2555 g_return_if_fail (key_file != NULL);
2556 g_return_if_fail (group_name != NULL);
2557 g_return_if_fail (g_key_file_lookup_group (key_file, group_name) == NULL);
2559 group = g_new0 (GKeyFileGroup, 1);
2560 group->name = g_strdup (group_name);
2561 group->lookup_map = g_hash_table_new (g_str_hash, g_str_equal);
2562 key_file->groups = g_list_prepend (key_file->groups, group);
2563 key_file->approximate_size += strlen (group_name) + 3;
2564 key_file->current_group = group;
2566 if (key_file->start_group_name == NULL)
2567 key_file->start_group_name = g_strdup (group_name);
2571 g_key_file_key_value_pair_free (GKeyFileKeyValuePair *pair)
2576 g_free (pair->value);
2581 /* Be careful not to call this function on a node with data in the
2582 * lookup map without removing it from the lookup map, first.
2584 * Some current cases where this warning is not a concern are
2586 * - the node being removed is a comment node
2587 * - the entire lookup map is getting destroyed soon after
2591 g_key_file_remove_key_value_pair_node (GKeyFile *key_file,
2592 GKeyFileGroup *group,
2596 GKeyFileKeyValuePair *pair;
2598 pair = (GKeyFileKeyValuePair *) pair_node->data;
2600 group->key_value_pairs = g_list_remove_link (group->key_value_pairs, pair_node);
2602 if (pair->key != NULL)
2603 key_file->approximate_size -= strlen (pair->key) + 1;
2605 g_assert (pair->value != NULL);
2606 key_file->approximate_size -= strlen (pair->value);
2608 g_key_file_key_value_pair_free (pair);
2610 g_list_free_1 (pair_node);
2614 g_key_file_remove_group_node (GKeyFile *key_file,
2617 GKeyFileGroup *group;
2620 group = (GKeyFileGroup *) group_node->data;
2622 /* If the current group gets deleted make the current group the first
2625 if (key_file->current_group == group)
2627 /* groups should always contain at least the top comment group,
2628 * unless g_key_file_clear has been called
2630 if (key_file->groups)
2631 key_file->current_group = (GKeyFileGroup *) key_file->groups->data;
2633 key_file->current_group = NULL;
2636 key_file->groups = g_list_remove_link (key_file->groups, group_node);
2638 if (group->name != NULL)
2639 key_file->approximate_size -= strlen (group->name) + 3;
2641 tmp = group->key_value_pairs;
2648 g_key_file_remove_key_value_pair_node (key_file, group, pair_node);
2651 g_assert (group->key_value_pairs == NULL);
2653 if (group->lookup_map)
2655 g_hash_table_destroy (group->lookup_map);
2656 group->lookup_map = NULL;
2659 g_free ((gchar *) group->name);
2661 g_list_free_1 (group_node);
2665 * g_key_file_remove_group:
2666 * @key_file: a #GKeyFile
2667 * @group_name: a group name
2668 * @error: return location for a #GError or %NULL
2670 * Removes the specified group, @group_name,
2671 * from the key file.
2676 g_key_file_remove_group (GKeyFile *key_file,
2677 const gchar *group_name,
2682 g_return_if_fail (key_file != NULL);
2683 g_return_if_fail (group_name != NULL);
2685 group_node = g_key_file_lookup_group_node (key_file, group_name);
2688 g_set_error (error, G_KEY_FILE_ERROR,
2689 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2690 _("Key file does not have group '%s'"),
2693 g_key_file_remove_group_node (key_file, group_node);
2697 g_key_file_add_key (GKeyFile *key_file,
2698 const gchar *group_name,
2702 GKeyFileGroup *group;
2703 GKeyFileKeyValuePair *pair;
2705 group = g_key_file_lookup_group (key_file, group_name);
2709 g_key_file_add_group (key_file, group_name);
2710 group = (GKeyFileGroup *) key_file->groups->data;
2713 pair = g_new0 (GKeyFileKeyValuePair, 1);
2715 pair->key = g_strdup (key);
2716 pair->value = g_strdup (value);
2718 g_hash_table_replace (group->lookup_map, pair->key, pair);
2719 group->key_value_pairs = g_list_prepend (group->key_value_pairs, pair);
2720 key_file->approximate_size += strlen (key) + strlen (value) + 2;
2724 * g_key_file_remove_key:
2725 * @key_file: a #GKeyFile
2726 * @group_name: a group name
2727 * @key: a key name to remove
2728 * @error: return location for a #GError or %NULL
2730 * Removes @key in @group_name from the key file.
2735 g_key_file_remove_key (GKeyFile *key_file,
2736 const gchar *group_name,
2740 GKeyFileGroup *group;
2741 GKeyFileKeyValuePair *pair;
2745 if (group_name == NULL)
2746 group = key_file->current_group;
2748 group = g_key_file_lookup_group (key_file, group_name);
2752 g_set_error (error, G_KEY_FILE_ERROR,
2753 G_KEY_FILE_ERROR_GROUP_NOT_FOUND,
2754 _("Key file does not have group '%s'"),
2759 group->key_value_pairs = g_list_remove (group->key_value_pairs, key_file);
2760 pair = g_key_file_lookup_key_value_pair (key_file, group, key);
2764 g_set_error (error, G_KEY_FILE_ERROR,
2765 G_KEY_FILE_ERROR_KEY_NOT_FOUND,
2766 _("Key file does not have key '%s' in group '%s'"), key, group_name);
2770 g_hash_table_remove (group->lookup_map, pair->key);
2772 key_file->approximate_size -= strlen (pair->key) + strlen (pair->value) + 2;
2773 g_key_file_key_value_pair_free (pair);
2777 g_key_file_lookup_group_node (GKeyFile *key_file,
2778 const gchar *group_name)
2780 GKeyFileGroup *group;
2784 for (tmp = key_file->groups; tmp != NULL; tmp = tmp->next)
2786 group = (GKeyFileGroup *) tmp->data;
2788 if (group && group->name && strcmp (group->name, group_name) == 0)
2797 static GKeyFileGroup *
2798 g_key_file_lookup_group (GKeyFile *key_file,
2799 const gchar *group_name)
2803 group_node = g_key_file_lookup_group_node (key_file, group_name);
2805 if (group_node != NULL)
2806 return (GKeyFileGroup *) group_node->data;
2812 g_key_file_lookup_key_value_pair_node (GKeyFile *key_file,
2813 GKeyFileGroup *group,
2818 for (key_node = group->key_value_pairs;
2820 key_node = key_node->next)
2822 GKeyFileKeyValuePair *pair;
2824 pair = (GKeyFileKeyValuePair *) key_node->data;
2826 if (pair->key && strcmp (pair->key, key) == 0)
2833 static GKeyFileKeyValuePair *
2834 g_key_file_lookup_key_value_pair (GKeyFile *key_file,
2835 GKeyFileGroup *group,
2838 return (GKeyFileKeyValuePair *) g_hash_table_lookup (group->lookup_map, key);
2841 /* Lines starting with # or consisting entirely of whitespace are merely
2842 * recorded, not parsed. This function assumes all leading whitespace
2843 * has been stripped.
2846 g_key_file_line_is_comment (const gchar *line)
2848 return (*line == '#' || *line == '\0' || *line == '\n');
2851 /* A group in a key file is made up of a starting '[' followed by one
2852 * or more letters making up the group name followed by ']'.
2855 g_key_file_line_is_group (const gchar *line)
2863 p = g_utf8_next_char (p);
2868 p = g_utf8_next_char (p);
2870 /* Group name must be non-empty
2875 while (*p && *p != ']')
2876 p = g_utf8_next_char (p);
2885 g_key_file_line_is_key_value_pair (const gchar *line)
2889 p = (gchar *) g_utf8_strchr (line, -1, '=');
2894 /* Key must be non-empty
2903 g_key_file_parse_value_as_string (GKeyFile *key_file,
2908 GError *parse_error = NULL;
2909 gchar *string_value, *p, *q0, *q;
2911 string_value = g_new0 (gchar, strlen (value) + 1);
2913 p = (gchar *) value;
2914 q0 = q = string_value;
2944 if (pieces && *p == key_file->list_separator)
2945 *q = key_file->list_separator;
2951 if (parse_error == NULL)
2959 g_set_error (error, G_KEY_FILE_ERROR,
2960 G_KEY_FILE_ERROR_INVALID_VALUE,
2961 _("Key file contains invalid escape "
2962 "sequence '%s'"), sequence);
2971 if (pieces && (*p == key_file->list_separator))
2973 *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
2982 if (p[-1] == '\\' && error == NULL)
2983 g_set_error (error, G_KEY_FILE_ERROR,
2984 G_KEY_FILE_ERROR_INVALID_VALUE,
2985 _("Key file contains escape character at end of line"));
2991 *pieces = g_slist_prepend (*pieces, g_strndup (q0, q - q0));
2992 *pieces = g_slist_reverse (*pieces);
2995 return string_value;
2999 g_key_file_parse_string_as_value (GKeyFile *key_file,
3000 const gchar *string,
3001 gboolean escape_separator)
3003 gchar *value, *p, *q;
3006 length = strlen (string) + 1;
3008 /* Worst case would be that every character needs to be escaped.
3009 * In other words every character turns to two characters
3011 value = g_new0 (gchar, 2 * length);
3013 p = (gchar *) string;
3015 while (p < (string + length - 1))
3017 gchar escaped_character[3] = { '\\', 0, 0 };
3022 escaped_character[1] = 's';
3023 strcpy (q, escaped_character);
3027 escaped_character[1] = 'n';
3028 strcpy (q, escaped_character);
3032 escaped_character[1] = 't';
3033 strcpy (q, escaped_character);
3037 escaped_character[1] = 'r';
3038 strcpy (q, escaped_character);
3042 escaped_character[1] = '\\';
3043 strcpy (q, escaped_character);
3047 if (escape_separator && *p == key_file->list_separator)
3049 escaped_character[1] = key_file->list_separator;
3050 strcpy (q, escaped_character);
3068 g_key_file_parse_value_as_integer (GKeyFile *key_file,
3072 gchar *end_of_valid_int;
3075 int_value = strtol (value, &end_of_valid_int, 0);
3077 if (*end_of_valid_int != '\0')
3078 g_set_error (error, G_KEY_FILE_ERROR,
3079 G_KEY_FILE_ERROR_INVALID_VALUE,
3080 _("Value '%s' cannot be interpreted as a number."), value);
3086 g_key_file_parse_integer_as_value (GKeyFile *key_file,
3090 return g_strdup_printf ("%d", value);
3094 g_key_file_parse_value_as_boolean (GKeyFile *key_file,
3100 if (strcmp (value, "true") == 0 || strcmp (value, "1") == 0)
3102 else if (strcmp (value, "false") == 0 || strcmp (value, "0") == 0)
3106 g_set_error (error, G_KEY_FILE_ERROR,
3107 G_KEY_FILE_ERROR_INVALID_VALUE,
3108 _("Value '%s' cannot be interpreted as a boolean."), value);
3114 g_key_file_parse_boolean_as_value (GKeyFile *key_file,
3118 return g_strdup ("true");
3120 return g_strdup ("false");
3124 g_key_file_parse_value_as_comment (GKeyFile *key_file,
3128 gchar **lines, *comment;
3131 string = g_string_sized_new (512);
3133 lines = g_strsplit (value, "\n", 0);
3135 for (i = 0; lines[i] != NULL; i++)
3137 if (lines[i][0] != "#")
3138 g_string_append_printf (string, "%s\n", lines[i]);
3140 g_string_append_printf (string, "%s\n", lines[i] + 1);
3144 comment = string->str;
3146 g_string_free (string, FALSE);
3152 g_key_file_parse_comment_as_value (GKeyFile *key_file,
3153 const gchar *comment)
3156 gchar **lines, *value;
3159 string = g_string_sized_new (512);
3161 lines = g_strsplit (comment, "\n", 0);
3163 for (i = 0; lines[i] != NULL; i++)
3164 g_string_append_printf (string, "#%s%s", lines[i],
3165 lines[i + 1] == NULL? "" : "\n");
3168 value = string->str;
3170 g_string_free (string, FALSE);