luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GKeyFile SECTION

Browse Source 
Move the contents to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 08:16:50 -04:00 committed by Philip Withnall
parent f27af99233
commit f2b1e4d936
1 changed files with 23 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
glib/gkeyfile.c
View File

@ -74,23 +74,22 @@
/**
* SECTION:gkeyfile
* @title: Key-value file parser
* @short_description: parses .ini-like config files
* GKeyFile:
*
* #GKeyFile lets you parse, edit or create files containing groups of
* `GKeyFile` parses .ini-like config files.
*
* `GKeyFile` lets you parse, edit or create files containing groups of
* key-value pairs, which we call "key files" for lack of a better name.
* Several freedesktop.org specifications use key files now, e.g the
* [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
* and the
* [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
* and the [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
*
* The syntax of key files is described in detail in the
* [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
* here is a quick summary: Key files
* consists of groups of key-value pairs, interspersed with comments.
* here is a quick summary: Key files consists of groups of key-value pairs, interspersed
* with comments.
*
* |[
* ```txt
* # this is just an example
* # there can be comments before the first group
*
@ -110,7 +109,7 @@
* Numbers=2;20;-200;0
*
* Booleans=true;false;true;true
* ]|
* ```
*
* Lines beginning with a '#' and blank lines are considered comments.
*
@ -118,15 +117,13 @@
* in '[' and ']', and ended implicitly by the start of the next group or
* the end of the file. Each key-value pair must be contained in a group.
*
* Key-value pairs generally have the form `key=value`, with the
* exception of localized strings, which have the form
* `key[locale]=value`, with a locale identifier of the
* form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER`
* are optional.
* Space before and after the '=' character are ignored. Newline, tab,
* carriage return and backslash characters in value are escaped as \n,
* \t, \r, and \\\\, respectively. To preserve leading spaces in values,
* these can also be escaped as \s.
* Key-value pairs generally have the form `key=value`, with the exception
* of localized strings, which have the form `key[locale]=value`, with a
* locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY`
* and `MODIFIER` are optional. Space before and after the '=' character
* are ignored. Newline, tab, carriage return and backslash characters in
* value are escaped as `\n`, `\t`, `\r`, and `\\\\`, respectively. To preserve
* leading spaces in values, these can also be escaped as `\s`.
*
* Key files can store strings (possibly with localized variants), integers,
* booleans and lists of these. Lists are separated by a separator character,
@ -153,15 +150,14 @@
*
* Note that in contrast to the
* [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
* groups in key files may contain the same
* key multiple times; the last entry wins. Key files may also contain
* multiple groups with the same name; they are merged together.
* Another difference is that keys and group names in key files are not
* groups in key files may contain the same key multiple times; the last entry wins.
* Key files may also contain multiple groups with the same name; they are merged
* together. Another difference is that keys and group names in key files are not
* restricted to ASCII characters.
*
* Here is an example of loading a key file and reading a value:
*
* |[<!-- language="C" -->
* ```c
* g_autoptr(GError) error = NULL;
* g_autoptr(GKeyFile) key_file = g_key_file_new ();
*
@ -184,11 +180,11 @@
* // Fall back to a default value.
* val = g_strdup ("default-value");
* }
* ]|
* ```
*
* Here is an example of creating and saving a key file:
*
* |[<!-- language="C" -->
* ```c
* g_autoptr(GKeyFile) key_file = g_key_file_new ();
* const gchar *val = …;
* g_autoptr(GError) error = NULL;
@ -211,7 +207,7 @@
* return;
* }
* g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
* ]|
* ```
*/
/**
@ -499,12 +495,6 @@
typedef struct _GKeyFileGroup GKeyFileGroup;
/**
* GKeyFile:
*
* The GKeyFile struct contains only private data
* and should not be accessed directly.
*/
struct _GKeyFile
{
GList *groups;