docs/reference/glib/tmpl/keyfile.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Key-value file parser
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 parses <filename>.ini</filename>-like config files
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GKeyFile lets you parse, edit or create files containing groups of
  10 key-value pairs, which we call <firstterm>key files</firstterm> for
  11 lack of a better name. Several freedesktop.org specifications use
  12 key files now, e.g the
  13 <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
  14 Entry Specification</ulink> and the
  15 <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
  16 Theme Specification</ulink>.
  17 </para>
  18
  19 <para>
  20 The syntax of key files is described in detail in the
  21 <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
  22 Entry Specification</ulink>, here is a quick summary: Key files
  23 consists of groups of key-value pairs, interspersed with comments.
  24 </para>
  25
  26 <informalexample><programlisting>
  27 # this is just an example
  28 # there can be comments before the first group
  29
  30 [First Group]
  31
  32 Name=Key File Example\tthis value shows\nescaping
  33
  34 # localized strings are stored in multiple key-value pairs
  35 Welcome=Hello
  36 Welcome[de]=Hallo
  37 Welcome[fr]=Bonjour
  38 Welcome[it]=Ciao
  39
  40 [Another Group]
  41
  42 Numbers=2;20;-200;0
  43
  44 Booleans=true;false;true;true
  45
  46 </programlisting></informalexample>
  47
  48 <para>
  49 Lines beginning with a '#' and blank lines are considered comments.
  50 </para>
  51
  52 <para>
  53 Groups are started by a header line containing the group name enclosed
  54 in '[' and ']', and ended implicitly by the start of the next group or
  55 the end of the file. Each key-value pair must be contained in a group.
  56 </para>
  57
  58 <para>
  59 Key-value pairs generally have the form <literal>key=value</literal>,
  60 with the exception of localized strings, which have the form
  61 <literal>key[locale]=value</literal>. Space before and after the
  62 '=' character are ignored. Newline, tab, carriage return and backslash
  63 characters are escaped as \n, \t, \r, and \\, respectively. To preserve
  64 initial and final spaces, these can also be escaped as \s.
  65 </para>
  66
  67 <para>
  68 Key files can store strings (possibly with localized variants), integers,
  69 booleans and lists of these. Lists are separated by a separator character,
  70 typically ';' or ','. To use the list separator character in a value in
  71 a list, it has to be escaped by prefixing it with a backslash.
  72 </para>
  73
  74 <para>
  75 This syntax is obviously inspired by the <filename>.ini</filename>
  76 files commonly met on Windows, but there are some important differences:
  77 <itemizedlist>
  78 <listitem><para>
  79 <filename>.ini</filename> files use the ';' character to begin comments,
  80  key files use the '#' character.
  81 </para></listitem>
  82 <listitem><para>
  83 Key files allow only comments before the first group.
  84 </para></listitem>
  85 <listitem><para>
  86 Key files are always encoded in UTF-8.
  87 </para></listitem>
  88 <listitem><para>
  89 Key and Group names are case-sensitive, for example a group called
  90 <literal>[GROUP]</literal> is a different group from <literal>[group]</literal>.
  91 </para></listitem>
  92 </itemizedlist>
  93 </para>
  94
  95 <!-- ##### SECTION See_Also ##### -->
  96 <para>
  97
  98 </para>
  99
 100 <!-- ##### SECTION Stability_Level ##### -->
 101
 102
 103 <!-- ##### STRUCT GKeyFile ##### -->
 104 <para>
 105 The <structname>GKeyFile</structname> struct contains only private fields
 106 and should not be used directly.
 107 </para>
 108
 109
 110 <!-- ##### MACRO G_KEY_FILE_ERROR ##### -->
 111 <para>
 112 Error domain for key file parsing. Errors in this domain will
 113 be from the #GKeyFileError enumeration. See #GError for information on
 114 error domains.
 115 </para>
 116
 117
 118
 119 <!-- ##### ENUM GKeyFileError ##### -->
 120 <para>
 121 Error codes returned by key file parsing.
 122 </para>
 123
 124 @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding
 125 @G_KEY_FILE_ERROR_PARSE: document was ill-formed
 126 @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
 127 @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
 128 @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found
 129 @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed
 130
 131 <!-- ##### ENUM GKeyFileFlags ##### -->
 132 <para>
 133 Flags which influence the parsing.
 134 </para>
 135
 136 @G_KEY_FILE_NONE: No flags, default behaviour
 137 @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified)
 138   contents of the key file back to a file; otherwise all comments will be lost when
 139   the key file is written back.
 140 @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified)
 141   contents of the key file back to a file; otherwise only the translations for the current
 142   language will be written back.
 143
 144 <!-- ##### FUNCTION g_key_file_new ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @Returns:
 150
 151
 152 <!-- ##### FUNCTION g_key_file_free ##### -->
 153 <para>
 154
 155 </para>
 156
 157 @key_file:
 158
 159
 160 <!-- ##### FUNCTION g_key_file_set_list_separator ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @key_file:
 166 @separator:
 167
 168
 169 <!-- ##### FUNCTION g_key_file_load_from_file ##### -->
 170 <para>
 171
 172 </para>
 173
 174 @key_file:
 175 @file:
 176 @flags:
 177 @error:
 178 @Returns:
 179
 180
 181 <!-- ##### FUNCTION g_key_file_load_from_data ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @key_file:
 187 @data:
 188 @length:
 189 @flags:
 190 @error:
 191 @Returns:
 192
 193
 194 <!-- ##### FUNCTION g_key_file_load_from_data_dirs ##### -->
 195 <para>
 196
 197 </para>
 198
 199 @key_file:
 200 @file:
 201 @full_path:
 202 @flags:
 203 @error:
 204 @Returns:
 205
 206
 207 <!-- ##### FUNCTION g_key_file_to_data ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @key_file:
 213 @length:
 214 @error:
 215 @Returns:
 216
 217
 218 <!-- ##### FUNCTION g_key_file_get_start_group ##### -->
 219 <para>
 220
 221 </para>
 222
 223 @key_file:
 224 @Returns:
 225
 226
 227 <!-- ##### FUNCTION g_key_file_get_groups ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @key_file:
 233 @length:
 234 @Returns:
 235
 236
 237 <!-- ##### FUNCTION g_key_file_get_keys ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @key_file:
 243 @group_name:
 244 @length:
 245 @error:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION g_key_file_has_group ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @key_file:
 255 @group_name:
 256 @Returns:
 257
 258
 259 <!-- ##### FUNCTION g_key_file_has_key ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @key_file:
 265 @group_name:
 266 @key:
 267 @error:
 268 @Returns:
 269
 270
 271 <!-- ##### FUNCTION g_key_file_get_value ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @key_file:
 277 @group_name:
 278 @key:
 279 @error:
 280 @Returns:
 281
 282
 283 <!-- ##### FUNCTION g_key_file_get_string ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @key_file:
 289 @group_name:
 290 @key:
 291 @error:
 292 @Returns:
 293
 294
 295 <!-- ##### FUNCTION g_key_file_get_locale_string ##### -->
 296 <para>
 297
 298 </para>
 299
 300 @key_file:
 301 @group_name:
 302 @key:
 303 @locale:
 304 @error:
 305 @Returns:
 306
 307
 308 <!-- ##### FUNCTION g_key_file_get_boolean ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @key_file:
 314 @group_name:
 315 @key:
 316 @error:
 317 @Returns:
 318
 319
 320 <!-- ##### FUNCTION g_key_file_get_integer ##### -->
 321 <para>
 322
 323 </para>
 324
 325 @key_file:
 326 @group_name:
 327 @key:
 328 @error:
 329 @Returns:
 330
 331
 332 <!-- ##### FUNCTION g_key_file_get_string_list ##### -->
 333 <para>
 334
 335 </para>
 336
 337 @key_file:
 338 @group_name:
 339 @key:
 340 @length:
 341 @error:
 342 @Returns:
 343
 344
 345 <!-- ##### FUNCTION g_key_file_get_locale_string_list ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @key_file:
 351 @group_name:
 352 @key:
 353 @locale:
 354 @length:
 355 @error:
 356 @Returns:
 357
 358
 359 <!-- ##### FUNCTION g_key_file_get_boolean_list ##### -->
 360 <para>
 361
 362 </para>
 363
 364 @key_file:
 365 @group_name:
 366 @key:
 367 @length:
 368 @error:
 369 @Returns:
 370
 371
 372 <!-- ##### FUNCTION g_key_file_get_integer_list ##### -->
 373 <para>
 374
 375 </para>
 376
 377 @key_file:
 378 @group_name:
 379 @key:
 380 @length:
 381 @error:
 382 @Returns:
 383
 384
 385 <!-- ##### FUNCTION g_key_file_get_comment ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @key_file:
 391 @group_name:
 392 @key:
 393 @error:
 394 @Returns:
 395
 396
 397 <!-- ##### FUNCTION g_key_file_set_value ##### -->
 398 <para>
 399
 400 </para>
 401
 402 @key_file:
 403 @group_name:
 404 @key:
 405 @value:
 406
 407
 408 <!-- ##### FUNCTION g_key_file_set_string ##### -->
 409 <para>
 410
 411 </para>
 412
 413 @key_file:
 414 @group_name:
 415 @key:
 416 @string:
 417
 418
 419 <!-- ##### FUNCTION g_key_file_set_locale_string ##### -->
 420 <para>
 421
 422 </para>
 423
 424 @key_file:
 425 @group_name:
 426 @key:
 427 @locale:
 428 @string:
 429
 430
 431 <!-- ##### FUNCTION g_key_file_set_boolean ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @key_file:
 437 @group_name:
 438 @key:
 439 @value:
 440 <!-- # Unused Parameters # -->
 441 @boolean:
 442
 443
 444 <!-- ##### FUNCTION g_key_file_set_integer ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @key_file:
 450 @group_name:
 451 @key:
 452 @value:
 453 <!-- # Unused Parameters # -->
 454 @integer:
 455
 456
 457 <!-- ##### FUNCTION g_key_file_set_string_list ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @key_file:
 463 @group_name:
 464 @key:
 465 @list:
 466 @length:
 467
 468
 469 <!-- ##### FUNCTION g_key_file_set_locale_string_list ##### -->
 470 <para>
 471
 472 </para>
 473
 474 @key_file:
 475 @group_name:
 476 @key:
 477 @locale:
 478 @list:
 479 @length:
 480
 481
 482 <!-- ##### FUNCTION g_key_file_set_boolean_list ##### -->
 483 <para>
 484
 485 </para>
 486
 487 @key_file:
 488 @group_name:
 489 @key:
 490 @list:
 491 @length:
 492
 493
 494 <!-- ##### FUNCTION g_key_file_set_integer_list ##### -->
 495 <para>
 496
 497 </para>
 498
 499 @key_file:
 500 @group_name:
 501 @key:
 502 @list:
 503 @length:
 504
 505
 506 <!-- ##### FUNCTION g_key_file_set_comment ##### -->
 507 <para>
 508
 509 </para>
 510
 511 @key_file:
 512 @group_name:
 513 @key:
 514 @comment:
 515 @error:
 516
 517
 518 <!-- ##### FUNCTION g_key_file_remove_group ##### -->
 519 <para>
 520
 521 </para>
 522
 523 @key_file:
 524 @group_name:
 525 @error:
 526
 527
 528 <!-- ##### FUNCTION g_key_file_remove_key ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @key_file:
 534 @group_name:
 535 @key:
 536 @error:
 537
 538
 539 <!-- ##### FUNCTION g_key_file_remove_comment ##### -->
 540 <para>
 541
 542 </para>
 543
 544 @key_file:
 545 @group_name:
 546 @key:
 547 @error:
 548
 549