docs/reference/glib/tmpl/scanner.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Lexical Scanner
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 a general purpose lexical scanner.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GScanner and its associated functions provide a general purpose
  10 lexical scanner.
  11 </para>
  12 <para>
  13 FIXME: really needs an example and more detail, but I don't completely
  14 understand it myself. Look at gtkrc.c for some code using the scanner.
  15 </para>
  16
  17 <!-- ##### SECTION See_Also ##### -->
  18 <para>
  19
  20 </para>
  21
  22 <!-- ##### STRUCT GScanner ##### -->
  23 <para>
  24 The data structure representing a lexical scanner.
  25 </para>
  26 <para>
  27 You should set input_name after creating the scanner, since it is used
  28 by the default message handler when displaying warnings and errors.
  29 If you are scanning a file, the file name would be a good choice.
  30 </para>
  31 <para>
  32 The <structfield>user_data</structfield> and
  33 <structfield>derived_data</structfield> fields are not used.
  34 If you need to associate extra data with the scanner you can place them here.
  35 </para>
  36 <para>
  37 If you want to use your own message handler you can set the
  38 <structfield>msg_handler</structfield> field. The type of the message
  39 handler function is declared by #GScannerMsgFunc.
  40 </para>
  41
  42 @user_data:
  43 @max_parse_errors:
  44 @parse_errors:
  45 @input_name:
  46 @derived_data:
  47 @config:
  48 @token:
  49 @value:
  50 @line:
  51 @position:
  52 @next_token:
  53 @next_value:
  54 @next_line:
  55 @next_position:
  56 @symbol_table:
  57 @input_fd:
  58 @text:
  59 @text_end:
  60 @buffer:
  61 @scope_id:
  62 @msg_handler:
  63
  64 <!-- ##### FUNCTION g_scanner_new ##### -->
  65 <para>
  66 Creates a new #GScanner.
  67 The @config_templ structure specifies the initial settings of the scanner,
  68 which are copied into the #GScanner <structfield>config</structfield> field.
  69 If you pass NULL then the default settings are used.
  70 (See g_scanner_config_template in gscanner.c for the defaults.)
  71 </para>
  72
  73 @config_templ: the initial scanner settings.
  74 @Returns: the new #GScanner.
  75
  76
  77 <!-- ##### STRUCT GScannerConfig ##### -->
  78 <para>
  79 Specifies the #GScanner settings.
  80 </para>
  81 <para>
  82 <structfield>cset_skip_characters</structfield> specifies which characters
  83 should be skipped by the scanner (the default is the whitespace characters:
  84 space, tab, carriage-return and line-feed).
  85 </para>
  86 <para>
  87 <structfield>cset_identifier_first</structfield> specifies the characters
  88 which can start identifiers.
  89 (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z).
  90 </para>
  91 <para>
  92 <structfield>cset_identifier_nth</structfield> specifies the characters
  93 which can be used in identifiers, after the first character.
  94 The default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
  95 #G_CSET_LATINC.
  96 </para>
  97 <para>
  98 <structfield>cpair_comment_single</structfield> specifies the characters
  99 at the start and end of single-line comments. The default is "#\n" which
 100 means that single-line comments start with a '#' and continue until a '\n'
 101 (end of line).
 102 </para>
 103 <para>
 104 <structfield>case_sensitive</structfield> specifies if symbols are
 105 case sensitive.
 106 </para>
 107 <para>
 108 The rest of the fields are flags which turn features on or off.
 109 FIXME: should describe these.
 110 </para>
 111
 112 @cset_skip_characters:
 113 @cset_identifier_first:
 114 @cset_identifier_nth:
 115 @cpair_comment_single:
 116 @case_sensitive:
 117 @skip_comment_multi:
 118 @skip_comment_single:
 119 @scan_comment_multi:
 120 @scan_identifier:
 121 @scan_identifier_1char:
 122 @scan_identifier_NULL:
 123 @scan_symbols:
 124 @scan_binary:
 125 @scan_octal:
 126 @scan_float:
 127 @scan_hex:
 128 @scan_hex_dollar:
 129 @scan_string_sq:
 130 @scan_string_dq:
 131 @numbers_2_int:
 132 @int_2_float:
 133 @identifier_2_string:
 134 @char_2_token:
 135 @symbol_2_token:
 136 @scope_0_fallback:
 137
 138 <!-- ##### FUNCTION g_scanner_input_file ##### -->
 139 <para>
 140 Prepares to scan a file.
 141 </para>
 142
 143 @scanner: a #GScanner.
 144 @input_fd: a file descriptor.
 145
 146
 147 <!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @scanner:
 153
 154
 155 <!-- ##### FUNCTION g_scanner_stat_mode ##### -->
 156 <para>
 157 Gets the file attributes.
 158 This is the <structfield>st_mode</structfield> field from the
 159 <structname>stat</structname> structure. See the <function>stat()</function>
 160 documentation.
 161 </para>
 162
 163 @filename: the file name.
 164 @Returns: the file attributes.
 165
 166
 167 <!-- ##### FUNCTION g_scanner_input_text ##### -->
 168 <para>
 169 Prepares to scan a text buffer.
 170 </para>
 171
 172 @scanner: a #GScanner.
 173 @text: the text buffer to scan.
 174 @text_len: the length of the text buffer.
 175
 176
 177 <!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
 178 <para>
 179 Gets the next token, without removing it from the input stream.
 180 The token data is placed in the
 181 <structfield>next_token</structfield>,
 182 <structfield>next_value</structfield>,
 183 <structfield>next_line</structfield>, and
 184 <structfield>next_position</structfield> fields of the #GScanner structure.
 185 </para>
 186
 187 @scanner: a #GScanner.
 188 @Returns: the type of the token.
 189
 190
 191 <!-- ##### FUNCTION g_scanner_get_next_token ##### -->
 192 <para>
 193 Gets the next token, removing it from the input stream.
 194 The token data is placed in the
 195 <structfield>token</structfield>,
 196 <structfield>value</structfield>,
 197 <structfield>line</structfield>, and
 198 <structfield>position</structfield> fields of the #GScanner structure.
 199 </para>
 200
 201 @scanner: a #GScanner.
 202 @Returns: the type of the token.
 203
 204
 205 <!-- ##### FUNCTION g_scanner_cur_line ##### -->
 206 <para>
 207 Gets the current line in the input stream (counting from 1).
 208 </para>
 209
 210 @scanner: a #GScanner.
 211 @Returns: the current line.
 212
 213
 214 <!-- ##### FUNCTION g_scanner_cur_position ##### -->
 215 <para>
 216 Gets the current position in the current line (counting from 0).
 217 </para>
 218
 219 @scanner: a #GScanner.
 220 @Returns: the current position on the line.
 221
 222
 223 <!-- ##### FUNCTION g_scanner_cur_token ##### -->
 224 <para>
 225 Gets the current token type.
 226 This is simply the <structfield>token</structfield> field in the #GScanner
 227 structure.
 228 </para>
 229
 230 @scanner: a #GScanner.
 231 @Returns: the current token type.
 232
 233
 234 <!-- ##### FUNCTION g_scanner_cur_value ##### -->
 235 <para>
 236 Gets the current token value.
 237 This is simply the <structfield>value</structfield> field in the #GScanner
 238 structure.
 239 </para>
 240
 241 @scanner: a #GScanner.
 242 @Returns: the current token value.
 243
 244
 245 <!-- ##### FUNCTION g_scanner_eof ##### -->
 246 <para>
 247 Returns TRUE if the scanner has reached the end of the file or text buffer.
 248 </para>
 249
 250 @scanner: a #GScanner.
 251 @Returns: TRUE if the scanner has reached the end of the file or text buffer.
 252
 253
 254 <!-- ##### FUNCTION g_scanner_set_scope ##### -->
 255 <para>
 256 Sets the current scope.
 257 </para>
 258
 259 @scanner: a #GScanner.
 260 @scope_id: the new scope id.
 261 @Returns: the old scope id.
 262
 263
 264 <!-- ##### FUNCTION g_scanner_scope_add_symbol ##### -->
 265 <para>
 266 Adds a symbol to the given scope.
 267 </para>
 268
 269 @scanner: a #GScanner.
 270 @scope_id: the scope id.
 271 @symbol: the symbol to add.
 272 @value: the value of the symbol.
 273
 274
 275 <!-- ##### FUNCTION g_scanner_scope_foreach_symbol ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @scanner:
 281 @scope_id:
 282 @func:
 283 @user_data:
 284
 285
 286 <!-- ##### FUNCTION g_scanner_scope_lookup_symbol ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @scanner:
 292 @scope_id:
 293 @symbol:
 294 @Returns:
 295
 296
 297 <!-- ##### FUNCTION g_scanner_scope_remove_symbol ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @scanner:
 303 @scope_id:
 304 @symbol:
 305
 306
 307 <!-- ##### FUNCTION g_scanner_freeze_symbol_table ##### -->
 308 <para>
 309 This function is deprecated and will be removed in the next major
 310 release of GLib. It does nothing.
 311 </para>
 312
 313 @scanner:
 314
 315
 316 <!-- ##### FUNCTION g_scanner_thaw_symbol_table ##### -->
 317 <para>
 318 This function is deprecated and will be removed in the next major
 319 release of GLib. It does nothing.
 320 </para>
 321
 322 @scanner:
 323
 324
 325 <!-- ##### FUNCTION g_scanner_lookup_symbol ##### -->
 326 <para>
 327
 328 </para>
 329
 330 @scanner:
 331 @symbol:
 332 @Returns:
 333
 334
 335 <!-- ##### FUNCTION g_scanner_warn ##### -->
 336 <para>
 337 Outputs a warning message, via the #GScanner message handler.
 338 </para>
 339
 340 @scanner: a #GScanner.
 341 @format: the message format. See the <function>printf()</function>
 342 documentation.
 343 @Varargs: the parameters to insert into the format string.
 344
 345
 346 <!-- ##### FUNCTION g_scanner_error ##### -->
 347 <para>
 348 Outputs an error message, via the #GScanner message handler.
 349 </para>
 350
 351 @scanner: a #GScanner.
 352 @format: the message format. See the <function>printf()</function>
 353 documentation.
 354 @Varargs: the parameters to insert into the format string.
 355
 356
 357 <!-- ##### FUNCTION g_scanner_unexp_token ##### -->
 358 <para>
 359 Outputs a message resulting from an unexpected token in the input stream.
 360 FIXME: I don't understand the arguments here.
 361 </para>
 362
 363 @scanner: a #GScanner.
 364 @expected_token: the expected token.
 365 @identifier_spec: a string describing the expected type of identifier,
 366 or NULL to use the default "identifier" string.
 367 @symbol_spec: a string describing the expected type of identifier,
 368 or NULL to use the default "symbol" string.
 369 @symbol_name:
 370 @message: a message string to output at the end of the warning/error, or NULL.
 371 @is_error: if TRUE it is output as an error. If False it is output as a
 372 warning.
 373
 374
 375 <!-- ##### USER_FUNCTION GScannerMsgFunc ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @scanner:
 381 @message:
 382 @error:
 383
 384
 385 <!-- ##### FUNCTION g_scanner_destroy ##### -->
 386 <para>
 387 Frees all memory used by the #GScanner.
 388 </para>
 389
 390 @scanner: a #GScanner.
 391
 392
 393 <!-- ##### ENUM GTokenType ##### -->
 394 <para>
 395 The possible types of token returned from each g_scanner_get_next_token() call.
 396 </para>
 397
 398 @G_TOKEN_EOF:
 399 @G_TOKEN_LEFT_PAREN:
 400 @G_TOKEN_LEFT_CURLY:
 401 @G_TOKEN_RIGHT_CURLY:
 402
 403 <!-- ##### UNION GTokenValue ##### -->
 404 <para>
 405 A union holding the value of the token.
 406 </para>
 407
 408
 409 <!-- ##### ENUM GErrorType ##### -->
 410 <para>
 411 The possible errors, used in the <structfield>v_error</structfield> field
 412 of #GTokenValue, when the token is a G_TOKEN_ERROR.
 413 </para>
 414
 415 @G_ERR_UNKNOWN:
 416 @G_ERR_UNEXP_EOF:
 417 @G_ERR_UNEXP_EOF_IN_STRING:
 418 @G_ERR_UNEXP_EOF_IN_COMMENT:
 419 @G_ERR_NON_DIGIT_IN_CONST:
 420 @G_ERR_DIGIT_RADIX:
 421 @G_ERR_FLOAT_RADIX:
 422 @G_ERR_FLOAT_MALFORMED:
 423
 424 <!-- ##### MACRO G_CSET_a_2_z ##### -->
 425 <para>
 426 The set of lower-case ASCII alphabet characters.
 427 Used for specifying valid identifier characters in #GScannerConfig.
 428 </para>
 429
 430
 431
 432 <!-- ##### MACRO G_CSET_A_2_Z ##### -->
 433 <para>
 434 The set of upper-case ASCII alphabet characters.
 435 Used for specifying valid identifier characters in #GScannerConfig.
 436 </para>
 437
 438
 439
 440 <!-- ##### MACRO G_CSET_DIGITS ##### -->
 441 <para>
 442
 443 </para>
 444
 445
 446
 447 <!-- ##### MACRO G_CSET_LATINC ##### -->
 448 <para>
 449 Part of the set of extended characters in the Latin character sets.
 450 FIXME: lower case?
 451 Used for specifying valid identifier characters in #GScannerConfig.
 452 </para>
 453
 454
 455
 456 <!-- ##### MACRO G_CSET_LATINS ##### -->
 457 <para>
 458 Part of the set of extended characters in the Latin character sets.
 459 FIXME: upper case?
 460 Used for specifying valid identifier characters in #GScannerConfig.
 461 </para>
 462
 463
 464
 465 <!-- ##### MACRO g_scanner_add_symbol ##### -->
 466 <para>
 467 Adds a symbol to the default scope.
 468 Deprecated in favour of g_scanner_scope_add_symbol().
 469 </para>
 470
 471 @scanner: a #GScanner.
 472 @symbol: the symbol to add.
 473 @value: the value of the symbol.
 474
 475
 476 <!-- ##### MACRO g_scanner_remove_symbol ##### -->
 477 <para>
 478 Removes a symbol from the default scope.
 479 Deprecated in favour of g_scanner_scope_remove_symbol().
 480 </para>
 481
 482 @scanner: a #GScanner.
 483 @symbol: the symbol to remove.
 484
 485
 486 <!-- ##### MACRO g_scanner_foreach_symbol ##### -->
 487 <para>
 488 Calls a function for each symbol in the default scope.
 489 Deprecated in favour of g_scanner_scope_foreach_symbol().
 490 </para>
 491
 492 @scanner: a #GScanner.
 493 @func: the function to call with each symbol.
 494 @data: data to pass to the function.
 495
 496