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 <structfield>input_name</structfield> after creating
  28 the scanner, since it is used by the default message handler when
  29 displaying warnings and errors. If you are scanning a file, the file
  30 name would be a good choice.
  31 </para>
  32 <para>
  33 The <structfield>user_data</structfield> and
  34 <structfield>max_parse_errors</structfield> fields are not used.
  35 If you need to associate extra data with the scanner you can place them here.
  36 </para>
  37 <para>
  38 If you want to use your own message handler you can set the
  39 <structfield>msg_handler</structfield> field. The type of the message
  40 handler function is declared by #GScannerMsgFunc.
  41 </para>
  42
  43 @user_data:
  44 @max_parse_errors:
  45 @parse_errors:
  46 @input_name:
  47 @qdata:
  48 @config:
  49 @token:
  50 @value:
  51 @line:
  52 @position:
  53 @next_token:
  54 @next_value:
  55 @next_line:
  56 @next_position:
  57 @symbol_table:
  58 @input_fd:
  59 @text:
  60 @text_end:
  61 @buffer:
  62 @scope_id:
  63 @msg_handler:
  64
  65 <!-- ##### FUNCTION g_scanner_new ##### -->
  66 <para>
  67 Creates a new #GScanner.
  68 The @config_templ structure specifies the initial settings of the scanner,
  69 which are copied into the #GScanner <structfield>config</structfield> field.
  70 If you pass %NULL then the default settings are used.
  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 (the default is #G_CSET_a_2_z, "_", and
  89 #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 (the default
  94 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 (the default is %FALSE).
 106 </para>
 107 <para>
 108 <structfield>skip_comment_multi</structfield> specifies if multi-line
 109 comments are skipped and not returned as tokens (the default is %TRUE).
 110 </para>
 111 <para>
 112 <structfield>skip_comment_single</structfield> specifies if single-line
 113 comments are skipped and not returned as tokens (the default is %TRUE).
 114 </para>
 115 <para>
 116 <structfield>scan_comment_multi</structfield> specifies if multi-line
 117 comments are recognized (the default is %TRUE).
 118 </para>
 119 <para>
 120 <structfield>scan_identifier</structfield> specifies if identifiers
 121 are recognized (the default is %TRUE).
 122 </para>
 123 <para>
 124 <structfield>scan_identifier_1char</structfield> specifies if single-character
 125 identifiers are recognized (the default is %FALSE).
 126 </para>
 127 <para>
 128 <structfield>scan_identifier_NULL</structfield> specifies if
 129 <literal>NULL</literal> is reported as #G_TOKEN_IDENTIFIER_NULL.
 130 (the default is %FALSE).
 131 </para>
 132 <para>
 133 <structfield>scan_symbols</structfield> specifies if symbols are
 134 recognized (the default is %TRUE).
 135 </para>
 136 <para>
 137 <structfield>scan_binary</structfield> specifies if binary numbers
 138 are recognized (the default is %FALSE).
 139 </para>
 140 <para>
 141 <structfield>scan_octal</structfield> specifies if octal numbers
 142 are recognized (the default is %TRUE).
 143 </para>
 144 <para>
 145 <structfield>scan_float</structfield> specifies if floating point numbers
 146 are recognized (the default is %TRUE).
 147 </para>
 148 <para>
 149 <structfield>scan_hex</structfield> specifies if hexadecimal numbers
 150 are recognized (the default is %TRUE).
 151 </para>
 152 <para>
 153 <structfield>scan_hex_dollar</structfield> specifies if '$' is recognized
 154 as a prefix for hexadecimal numbers (the default is %FALSE).
 155 </para>
 156 <para>
 157 <structfield>scan_string_sq</structfield> specifies if strings can be
 158 enclosed in single quotes (the default is %TRUE).
 159 </para>
 160 <para>
 161 <structfield>scan_string_dq</structfield> specifies if strings can be
 162 enclosed in double quotes (the default is %TRUE).
 163 </para>
 164 <para>
 165 <structfield>numbers_2_int</structfield> specifies if binary, octal and
 166 hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE).
 167 </para>
 168 <para>
 169 <structfield>int_2_float</structfield> specifies if all numbers are
 170 reported as #G_TOKEN_FLOAT (the default is %FALSE).
 171 </para>
 172 <para>
 173 <structfield>identifier_2_string</structfield> specifies if identifiers
 174 are reported as strings (the default is %FALSE).
 175 </para>
 176 <para>
 177 <structfield>char_2_token</structfield> specifies if characters
 178 are reported by setting <literal>token = ch</literal> or as #G_TOKEN_CHAR
 179 (the default is %TRUE).
 180 </para>
 181 <para>
 182 <structfield>symbol_2_token</structfield> specifies if symbols
 183 are reported by setting <literal>token = v_symbol</literal> or as
 184 #G_TOKEN_SYMBOL (the default is %FALSE).
 185 </para>
 186 <para>
 187 <structfield>scope_0_fallback</structfield> specifies if a symbol
 188 is searched for in the default scope in addition to the current scope
 189 (the default is %FALSE).
 190 </para>
 191
 192 @cset_skip_characters:
 193 @cset_identifier_first:
 194 @cset_identifier_nth:
 195 @cpair_comment_single:
 196 @case_sensitive:
 197 @skip_comment_multi:
 198 @skip_comment_single:
 199 @scan_comment_multi:
 200 @scan_identifier:
 201 @scan_identifier_1char:
 202 @scan_identifier_NULL:
 203 @scan_symbols:
 204 @scan_binary:
 205 @scan_octal:
 206 @scan_float:
 207 @scan_hex:
 208 @scan_hex_dollar:
 209 @scan_string_sq:
 210 @scan_string_dq:
 211 @numbers_2_int:
 212 @int_2_float:
 213 @identifier_2_string:
 214 @char_2_token:
 215 @symbol_2_token:
 216 @scope_0_fallback:
 217 @padding_dummy:
 218
 219 <!-- ##### FUNCTION g_scanner_input_file ##### -->
 220 <para>
 221 Prepares to scan a file.
 222 </para>
 223
 224 @scanner: a #GScanner.
 225 @input_fd: a file descriptor.
 226
 227
 228 <!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
 229 <para>
 230 Rewinds the filedescriptor to the current buffer position and blows
 231 the file read ahead buffer. This is useful for third party uses of
 232 the scanners filedescriptor, which hooks onto the current scanning
 233 position.
 234 </para>
 235
 236 @scanner: a #GScanner.
 237
 238
 239 <!-- ##### FUNCTION g_scanner_input_text ##### -->
 240 <para>
 241 Prepares to scan a text buffer.
 242 </para>
 243
 244 @scanner: a #GScanner.
 245 @text: the text buffer to scan.
 246 @text_len: the length of the text buffer.
 247
 248
 249 <!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
 250 <para>
 251 Gets the next token, without removing it from the input stream.
 252 The token data is placed in the
 253 <structfield>next_token</structfield>,
 254 <structfield>next_value</structfield>,
 255 <structfield>next_line</structfield>, and
 256 <structfield>next_position</structfield> fields of the #GScanner structure.
 257 </para>
 258
 259 @scanner: a #GScanner.
 260 @Returns: the type of the token.
 261
 262
 263 <!-- ##### FUNCTION g_scanner_get_next_token ##### -->
 264 <para>
 265 Gets the next token, removing it from the input stream.
 266 The token data is placed in the
 267 <structfield>token</structfield>,
 268 <structfield>value</structfield>,
 269 <structfield>line</structfield>, and
 270 <structfield>position</structfield> fields of the #GScanner structure.
 271 </para>
 272
 273 @scanner: a #GScanner.
 274 @Returns: the type of the token.
 275
 276
 277 <!-- ##### FUNCTION g_scanner_cur_line ##### -->
 278 <para>
 279 Gets the current line in the input stream (counting from 1).
 280 </para>
 281
 282 @scanner: a #GScanner.
 283 @Returns: the current line.
 284
 285
 286 <!-- ##### FUNCTION g_scanner_cur_position ##### -->
 287 <para>
 288 Gets the current position in the current line (counting from 0).
 289 </para>
 290
 291 @scanner: a #GScanner.
 292 @Returns: the current position on the line.
 293
 294
 295 <!-- ##### FUNCTION g_scanner_cur_token ##### -->
 296 <para>
 297 Gets the current token type.
 298 This is simply the <structfield>token</structfield> field in the #GScanner
 299 structure.
 300 </para>
 301
 302 @scanner: a #GScanner.
 303 @Returns: the current token type.
 304
 305
 306 <!-- ##### FUNCTION g_scanner_cur_value ##### -->
 307 <para>
 308 Gets the current token value.
 309 This is simply the <structfield>value</structfield> field in the #GScanner
 310 structure.
 311 </para>
 312
 313 @scanner: a #GScanner.
 314 @Returns: the current token value.
 315
 316
 317 <!-- ##### FUNCTION g_scanner_eof ##### -->
 318 <para>
 319 Returns %TRUE if the scanner has reached the end of the file or text buffer.
 320 </para>
 321
 322 @scanner: a #GScanner.
 323 @Returns: %TRUE if the scanner has reached the end of the file or text buffer.
 324
 325
 326 <!-- ##### FUNCTION g_scanner_set_scope ##### -->
 327 <para>
 328 Sets the current scope.
 329 </para>
 330
 331 @scanner: a #GScanner.
 332 @scope_id: the new scope id.
 333 @Returns: the old scope id.
 334
 335
 336 <!-- ##### FUNCTION g_scanner_scope_add_symbol ##### -->
 337 <para>
 338 Adds a symbol to the given scope.
 339 </para>
 340
 341 @scanner: a #GScanner.
 342 @scope_id: the scope id.
 343 @symbol: the symbol to add.
 344 @value: the value of the symbol.
 345
 346
 347 <!-- ##### FUNCTION g_scanner_scope_foreach_symbol ##### -->
 348 <para>
 349 Calls the given function for each of the symbol/value pairs in the
 350 given scope of the #GScanner. The function is passed the symbol and
 351 value of each pair, and the given @user_data parameter.
 352 </para>
 353
 354 @scanner: a #GScanner.
 355 @scope_id: the scope id.
 356 @func: the function to call for each symbol/value pair.
 357 @user_data: user data to pass to the function.
 358
 359
 360 <!-- ##### FUNCTION g_scanner_scope_lookup_symbol ##### -->
 361 <para>
 362 Looks up a symbol in a scope and return its value. If the
 363 symbol is not bound in the scope, %NULL is returned.
 364 </para>
 365
 366 @scanner: a #GScanner.
 367 @scope_id: the scope id.
 368 @symbol: the symbol to look up.
 369 @Returns: the value of @symbol in the given scope, or %NULL
 370 if @symbol is not bound in the given scope.
 371
 372
 373 <!-- ##### FUNCTION g_scanner_scope_remove_symbol ##### -->
 374 <para>
 375 Removes a symbol from a scope.
 376 </para>
 377
 378 @scanner: a #GScanner.
 379 @scope_id: the scope id.
 380 @symbol: the symbol to remove.
 381
 382
 383 <!-- ##### MACRO g_scanner_freeze_symbol_table ##### -->
 384 <para>
 385 This function is deprecated and will be removed in the next major
 386 release of GLib. It does nothing.
 387 </para>
 388
 389 @scanner: a #GScanner.
 390
 391
 392 <!-- ##### MACRO g_scanner_thaw_symbol_table ##### -->
 393 <para>
 394 This function is deprecated and will be removed in the next major
 395 release of GLib. It does nothing.
 396 </para>
 397
 398 @scanner: a #GScanner.
 399
 400
 401 <!-- ##### FUNCTION g_scanner_lookup_symbol ##### -->
 402 <para>
 403 Looks up a symbol in the current scope and return its value. If the
 404 symbol is not bound in the current scope, %NULL is returned.
 405 </para>
 406
 407 @scanner: a #GScanner.
 408 @symbol: the symbol to look up.
 409 @Returns: the value of @symbol in the current scope, or %NULL
 410 if @symbol is not bound in the current scope.
 411
 412
 413 <!-- ##### FUNCTION g_scanner_warn ##### -->
 414 <para>
 415 Outputs a warning message, via the #GScanner message handler.
 416 </para>
 417
 418 @scanner: a #GScanner.
 419 @format: the message format. See the <function>printf()</function>
 420 documentation.
 421 @Varargs: the parameters to insert into the format string.
 422
 423
 424 <!-- ##### FUNCTION g_scanner_error ##### -->
 425 <para>
 426 Outputs an error message, via the #GScanner message handler.
 427 </para>
 428
 429 @scanner: a #GScanner.
 430 @format: the message format. See the <function>printf()</function>
 431 documentation.
 432 @Varargs: the parameters to insert into the format string.
 433
 434
 435 <!-- ##### FUNCTION g_scanner_unexp_token ##### -->
 436 <para>
 437 Outputs a message through the scanner's msg_handler, resulting from an
 438 unexpected token in the input stream.
 439 Note that you should not call g_scanner_peek_next_token() followed by
 440 g_scanner_unexp_token() without an intermediate call to
 441 g_scanner_get_next_token(), as g_scanner_unexp_token() evaluates the
 442 scanner's current token (not the peeked token) to construct part
 443 of the message.
 444 </para>
 445
 446 @scanner: a #GScanner.
 447 @expected_token: the expected token.
 448 @identifier_spec: a string describing how the scanner's user refers to
 449                   identifiers (%NULL defaults to "identifier").
 450                   This is used if @expected_token is #G_TOKEN_IDENTIFIER
 451                   or #G_TOKEN_IDENTIFIER_NULL.
 452 @symbol_spec: a string describing how the scanner's user refers to
 453               symbols (%NULL defaults to "symbol").
 454               This is used if @expected_token is #G_TOKEN_SYMBOL or
 455               any token value greater than #G_TOKEN_LAST.
 456 @symbol_name: the name of the symbol, if the scanner's current token
 457               is a symbol.
 458 @message: a message string to output at the end of the warning/error, or %NULL.
 459 @is_error: if %TRUE it is output as an error. If %FALSE it is output as a
 460            warning.
 461
 462
 463 <!-- ##### USER_FUNCTION GScannerMsgFunc ##### -->
 464 <para>
 465 Specifies the type of the message handler function.
 466 </para>
 467
 468 @scanner: a #GScanner.
 469 @message: the message.
 470 @error: %TRUE if the message signals an error, %FALSE if it
 471   signals a warning.
 472
 473
 474 <!-- ##### FUNCTION g_scanner_destroy ##### -->
 475 <para>
 476 Frees all memory used by the #GScanner.
 477 </para>
 478
 479 @scanner: a #GScanner.
 480
 481
 482 <!-- ##### ENUM GTokenType ##### -->
 483 <para>
 484 The possible types of token returned from each g_scanner_get_next_token() call.
 485 </para>
 486
 487 @G_TOKEN_EOF: the end of the file.
 488 @G_TOKEN_LEFT_PAREN: a '(' character.
 489 @G_TOKEN_LEFT_CURLY: a '{' character.
 490 @G_TOKEN_RIGHT_CURLY: a '}' character.
 491
 492 <!-- ##### UNION GTokenValue ##### -->
 493 <para>
 494 A union holding the value of the token.
 495 </para>
 496
 497
 498 <!-- ##### ENUM GErrorType ##### -->
 499 <para>
 500 The possible errors, used in the <structfield>v_error</structfield> field
 501 of #GTokenValue, when the token is a #G_TOKEN_ERROR.
 502 </para>
 503
 504 @G_ERR_UNKNOWN: unknown error.
 505 @G_ERR_UNEXP_EOF: unexpected end of file.
 506 @G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant.
 507 @G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment.
 508 @G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number.
 509 @G_ERR_DIGIT_RADIX: digit beyond radix in a number.
 510 @G_ERR_FLOAT_RADIX: non-decimal floating point number.
 511 @G_ERR_FLOAT_MALFORMED: malformed floating point number.
 512
 513 <!-- ##### MACRO G_CSET_a_2_z ##### -->
 514 <para>
 515 The set of lowercase ASCII alphabet characters.
 516 Used for specifying valid identifier characters in #GScannerConfig.
 517 </para>
 518
 519
 520
 521 <!-- ##### MACRO G_CSET_A_2_Z ##### -->
 522 <para>
 523 The set of uppercase ASCII alphabet characters.
 524 Used for specifying valid identifier characters in #GScannerConfig.
 525 </para>
 526
 527
 528
 529 <!-- ##### MACRO G_CSET_DIGITS ##### -->
 530 <para>
 531 The set of digits.
 532 Used for specifying valid identifier characters in #GScannerConfig.
 533 </para>
 534
 535
 536
 537 <!-- ##### MACRO G_CSET_LATINC ##### -->
 538 <para>
 539 The set of uppercase ISO 8859-1 alphabet characters which are
 540 not ASCII characters.
 541 Used for specifying valid identifier characters in #GScannerConfig.
 542 </para>
 543
 544
 545
 546 <!-- ##### MACRO G_CSET_LATINS ##### -->
 547 <para>
 548 The set of lowercase ISO 8859-1 alphabet characters which are
 549 not ASCII characters.
 550 Used for specifying valid identifier characters in #GScannerConfig.
 551 </para>
 552
 553
 554
 555 <!-- ##### MACRO g_scanner_add_symbol ##### -->
 556 <para>
 557 Adds a symbol to the default scope.
 558 Deprecated in favour of g_scanner_scope_add_symbol().
 559 </para>
 560
 561 @scanner: a #GScanner.
 562 @symbol: the symbol to add.
 563 @value: the value of the symbol.
 564
 565
 566 <!-- ##### MACRO g_scanner_remove_symbol ##### -->
 567 <para>
 568 Removes a symbol from the default scope.
 569 Deprecated in favour of g_scanner_scope_remove_symbol().
 570 </para>
 571
 572 @scanner: a #GScanner.
 573 @symbol: the symbol to remove.
 574
 575
 576 <!-- ##### MACRO g_scanner_foreach_symbol ##### -->
 577 <para>
 578 Calls a function for each symbol in the default scope.
 579 Deprecated in favour of g_scanner_scope_foreach_symbol().
 580 </para>
 581
 582 @scanner: a #GScanner.
 583 @func: the function to call with each symbol.
 584 @data: data to pass to the function.
 585
 586