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 <!-- ##### STRUCT GKeyFile ##### -->
 101 <para>
 102 The <structname>GKeyFile</structname> struct contains only private fields
 103 and should not be used directly.
 104 </para>
 105
 106
 107 <!-- ##### MACRO G_KEY_FILE_ERROR ##### -->
 108 <para>
 109 Error domain for key file parsing. Errors in this domain will
 110 be from the #GKeyFileError enumeration. See #GError for information on
 111 error domains.
 112 </para>
 113
 114
 115
 116 <!-- ##### ENUM GKeyFileError ##### -->
 117 <para>
 118 Error codes returned by key file parsing.
 119 </para>
 120
 121 @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding
 122 @G_KEY_FILE_ERROR_PARSE: document was ill-formed
 123 @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
 124 @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
 125 @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found
 126 @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed
 127
 128 <!-- ##### ENUM GKeyFileFlags ##### -->
 129 <para>
 130 Flags which influence the parsing.
 131 </para>
 132
 133 @G_KEY_FILE_NONE: No flags, default behaviour
 134 @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified)
 135   contents of the key file back to a file; otherwise all comments will be lost when
 136   the key file is written back.
 137 @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified)
 138   contents of the key file back to a file; otherwise only the translations for the current
 139   language will be written back.
 140
 141 <!-- ##### FUNCTION g_key_file_new ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @Returns:
 147
 148
 149 <!-- ##### FUNCTION g_key_file_free ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @key_file:
 155
 156
 157 <!-- ##### FUNCTION g_key_file_set_list_separator ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @key_file:
 163 @separator:
 164
 165
 166 <!-- ##### FUNCTION g_key_file_load_from_file ##### -->
 167 <para>
 168
 169 </para>
 170
 171 @key_file:
 172 @file:
 173 @flags:
 174 @error:
 175 @Returns:
 176
 177
 178 <!-- ##### FUNCTION g_key_file_load_from_data ##### -->
 179 <para>
 180
 181 </para>
 182
 183 @key_file:
 184 @data:
 185 @length:
 186 @flags:
 187 @error:
 188 @Returns:
 189
 190
 191 <!-- ##### FUNCTION g_key_file_load_from_data_dirs ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @key_file:
 197 @file:
 198 @full_path:
 199 @flags:
 200 @error:
 201 @Returns:
 202
 203
 204 <!-- ##### FUNCTION g_key_file_to_data ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @key_file:
 210 @length:
 211 @error:
 212 @Returns:
 213
 214
 215 <!-- ##### FUNCTION g_key_file_get_start_group ##### -->
 216 <para>
 217
 218 </para>
 219
 220 @key_file:
 221 @Returns:
 222
 223
 224 <!-- ##### FUNCTION g_key_file_get_groups ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @key_file:
 230 @length:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION g_key_file_get_keys ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @key_file:
 240 @group_name:
 241 @length:
 242 @error:
 243 @Returns:
 244
 245
 246 <!-- ##### FUNCTION g_key_file_has_group ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @key_file:
 252 @group_name:
 253 @Returns:
 254
 255
 256 <!-- ##### FUNCTION g_key_file_has_key ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @key_file:
 262 @group_name:
 263 @key:
 264 @error:
 265 @Returns:
 266
 267
 268 <!-- ##### FUNCTION g_key_file_get_value ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @key_file:
 274 @group_name:
 275 @key:
 276 @error:
 277 @Returns:
 278
 279
 280 <!-- ##### FUNCTION g_key_file_get_string ##### -->
 281 <para>
 282
 283 </para>
 284
 285 @key_file:
 286 @group_name:
 287 @key:
 288 @error:
 289 @Returns:
 290
 291
 292 <!-- ##### FUNCTION g_key_file_get_locale_string ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @key_file:
 298 @group_name:
 299 @key:
 300 @locale:
 301 @error:
 302 @Returns:
 303
 304
 305 <!-- ##### FUNCTION g_key_file_get_boolean ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @key_file:
 311 @group_name:
 312 @key:
 313 @error:
 314 @Returns:
 315
 316
 317 <!-- ##### FUNCTION g_key_file_get_integer ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @key_file:
 323 @group_name:
 324 @key:
 325 @error:
 326 @Returns:
 327
 328
 329 <!-- ##### FUNCTION g_key_file_get_string_list ##### -->
 330 <para>
 331
 332 </para>
 333
 334 @key_file:
 335 @group_name:
 336 @key:
 337 @length:
 338 @error:
 339 @Returns:
 340
 341
 342 <!-- ##### FUNCTION g_key_file_get_locale_string_list ##### -->
 343 <para>
 344
 345 </para>
 346
 347 @key_file:
 348 @group_name:
 349 @key:
 350 @locale:
 351 @length:
 352 @error:
 353 @Returns:
 354
 355
 356 <!-- ##### FUNCTION g_key_file_get_boolean_list ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @key_file:
 362 @group_name:
 363 @key:
 364 @length:
 365 @error:
 366 @Returns:
 367
 368
 369 <!-- ##### FUNCTION g_key_file_get_integer_list ##### -->
 370 <para>
 371
 372 </para>
 373
 374 @key_file:
 375 @group_name:
 376 @key:
 377 @length:
 378 @error:
 379 @Returns:
 380
 381
 382 <!-- ##### FUNCTION g_key_file_get_comment ##### -->
 383 <para>
 384
 385 </para>
 386
 387 @key_file:
 388 @group_name:
 389 @key:
 390 @error:
 391 @Returns:
 392
 393
 394 <!-- ##### FUNCTION g_key_file_set_value ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @key_file:
 400 @group_name:
 401 @key:
 402 @value:
 403
 404
 405 <!-- ##### FUNCTION g_key_file_set_string ##### -->
 406 <para>
 407
 408 </para>
 409
 410 @key_file:
 411 @group_name:
 412 @key:
 413 @string:
 414
 415
 416 <!-- ##### FUNCTION g_key_file_set_locale_string ##### -->
 417 <para>
 418
 419 </para>
 420
 421 @key_file:
 422 @group_name:
 423 @key:
 424 @locale:
 425 @string:
 426
 427
 428 <!-- ##### FUNCTION g_key_file_set_boolean ##### -->
 429 <para>
 430
 431 </para>
 432
 433 @key_file:
 434 @group_name:
 435 @key:
 436 @value:
 437 <!-- # Unused Parameters # -->
 438 @boolean:
 439
 440
 441 <!-- ##### FUNCTION g_key_file_set_integer ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @key_file:
 447 @group_name:
 448 @key:
 449 @value:
 450 <!-- # Unused Parameters # -->
 451 @integer:
 452
 453
 454 <!-- ##### FUNCTION g_key_file_set_string_list ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @key_file:
 460 @group_name:
 461 @key:
 462 @list:
 463 @length:
 464
 465
 466 <!-- ##### FUNCTION g_key_file_set_locale_string_list ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @key_file:
 472 @group_name:
 473 @key:
 474 @locale:
 475 @list:
 476 @length:
 477
 478
 479 <!-- ##### FUNCTION g_key_file_set_boolean_list ##### -->
 480 <para>
 481
 482 </para>
 483
 484 @key_file:
 485 @group_name:
 486 @key:
 487 @list:
 488 @length:
 489
 490
 491 <!-- ##### FUNCTION g_key_file_set_integer_list ##### -->
 492 <para>
 493
 494 </para>
 495
 496 @key_file:
 497 @group_name:
 498 @key:
 499 @list:
 500 @length:
 501
 502
 503 <!-- ##### FUNCTION g_key_file_set_comment ##### -->
 504 <para>
 505
 506 </para>
 507
 508 @key_file:
 509 @group_name:
 510 @key:
 511 @comment:
 512 @error:
 513
 514
 515 <!-- ##### FUNCTION g_key_file_remove_group ##### -->
 516 <para>
 517
 518 </para>
 519
 520 @key_file:
 521 @group_name:
 522 @error:
 523
 524
 525 <!-- ##### FUNCTION g_key_file_remove_key ##### -->
 526 <para>
 527
 528 </para>
 529
 530 @key_file:
 531 @group_name:
 532 @key:
 533 @error:
 534
 535
 536 <!-- ##### FUNCTION g_key_file_remove_comment ##### -->
 537 <para>
 538
 539 </para>
 540
 541 @key_file:
 542 @group_name:
 543 @key:
 544 @error:
 545
 546