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 @store_int64:
 218 @padding_dummy:
 219
 220 <!-- ##### FUNCTION g_scanner_input_file ##### -->
 221 <para>
 222 Prepares to scan a file.
 223 </para>
 224
 225 @scanner: a #GScanner.
 226 @input_fd: a file descriptor.
 227
 228
 229 <!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
 230 <para>
 231 Rewinds the filedescriptor to the current buffer position and blows
 232 the file read ahead buffer. This is useful for third party uses of
 233 the scanners filedescriptor, which hooks onto the current scanning
 234 position.
 235 </para>
 236
 237 @scanner: a #GScanner.
 238
 239
 240 <!-- ##### FUNCTION g_scanner_input_text ##### -->
 241 <para>
 242 Prepares to scan a text buffer.
 243 </para>
 244
 245 @scanner: a #GScanner.
 246 @text: the text buffer to scan.
 247 @text_len: the length of the text buffer.
 248
 249
 250 <!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
 251 <para>
 252 Gets the next token, without removing it from the input stream.
 253 The token data is placed in the
 254 <structfield>next_token</structfield>,
 255 <structfield>next_value</structfield>,
 256 <structfield>next_line</structfield>, and
 257 <structfield>next_position</structfield> fields of the #GScanner structure.
 258 </para>
 259
 260 @scanner: a #GScanner.
 261 @Returns: the type of the token.
 262
 263
 264 <!-- ##### FUNCTION g_scanner_get_next_token ##### -->
 265 <para>
 266 Gets the next token, removing it from the input stream.
 267 The token data is placed in the
 268 <structfield>token</structfield>,
 269 <structfield>value</structfield>,
 270 <structfield>line</structfield>, and
 271 <structfield>position</structfield> fields of the #GScanner structure.
 272 </para>
 273
 274 @scanner: a #GScanner.
 275 @Returns: the type of the token.
 276
 277
 278 <!-- ##### FUNCTION g_scanner_cur_line ##### -->
 279 <para>
 280 Gets the current line in the input stream (counting from 1).
 281 </para>
 282
 283 @scanner: a #GScanner.
 284 @Returns: the current line.
 285
 286
 287 <!-- ##### FUNCTION g_scanner_cur_position ##### -->
 288 <para>
 289 Gets the current position in the current line (counting from 0).
 290 </para>
 291
 292 @scanner: a #GScanner.
 293 @Returns: the current position on the line.
 294
 295
 296 <!-- ##### FUNCTION g_scanner_cur_token ##### -->
 297 <para>
 298 Gets the current token type.
 299 This is simply the <structfield>token</structfield> field in the #GScanner
 300 structure.
 301 </para>
 302
 303 @scanner: a #GScanner.
 304 @Returns: the current token type.
 305
 306
 307 <!-- ##### FUNCTION g_scanner_cur_value ##### -->
 308 <para>
 309 Gets the current token value.
 310 This is simply the <structfield>value</structfield> field in the #GScanner
 311 structure.
 312 </para>
 313
 314 @scanner: a #GScanner.
 315 @Returns: the current token value.
 316
 317
 318 <!-- ##### FUNCTION g_scanner_eof ##### -->
 319 <para>
 320 Returns %TRUE if the scanner has reached the end of the file or text buffer.
 321 </para>
 322
 323 @scanner: a #GScanner.
 324 @Returns: %TRUE if the scanner has reached the end of the file or text buffer.
 325
 326
 327 <!-- ##### FUNCTION g_scanner_set_scope ##### -->
 328 <para>
 329 Sets the current scope.
 330 </para>
 331
 332 @scanner: a #GScanner.
 333 @scope_id: the new scope id.
 334 @Returns: the old scope id.
 335
 336
 337 <!-- ##### FUNCTION g_scanner_scope_add_symbol ##### -->
 338 <para>
 339 Adds a symbol to the given scope.
 340 </para>
 341
 342 @scanner: a #GScanner.
 343 @scope_id: the scope id.
 344 @symbol: the symbol to add.
 345 @value: the value of the symbol.
 346
 347
 348 <!-- ##### FUNCTION g_scanner_scope_foreach_symbol ##### -->
 349 <para>
 350 Calls the given function for each of the symbol/value pairs in the
 351 given scope of the #GScanner. The function is passed the symbol and
 352 value of each pair, and the given @user_data parameter.
 353 </para>
 354
 355 @scanner: a #GScanner.
 356 @scope_id: the scope id.
 357 @func: the function to call for each symbol/value pair.
 358 @user_data: user data to pass to the function.
 359
 360
 361 <!-- ##### FUNCTION g_scanner_scope_lookup_symbol ##### -->
 362 <para>
 363 Looks up a symbol in a scope and return its value. If the
 364 symbol is not bound in the scope, %NULL is returned.
 365 </para>
 366
 367 @scanner: a #GScanner.
 368 @scope_id: the scope id.
 369 @symbol: the symbol to look up.
 370 @Returns: the value of @symbol in the given scope, or %NULL
 371 if @symbol is not bound in the given scope.
 372
 373
 374 <!-- ##### FUNCTION g_scanner_scope_remove_symbol ##### -->
 375 <para>
 376 Removes a symbol from a scope.
 377 </para>
 378
 379 @scanner: a #GScanner.
 380 @scope_id: the scope id.
 381 @symbol: the symbol to remove.
 382
 383
 384 <!-- ##### MACRO g_scanner_freeze_symbol_table ##### -->
 385 <para>
 386 This function is deprecated and will be removed in the next major
 387 release of GLib. It does nothing.
 388 </para>
 389
 390 @scanner: a #GScanner.
 391
 392
 393 <!-- ##### MACRO g_scanner_thaw_symbol_table ##### -->
 394 <para>
 395 This function is deprecated and will be removed in the next major
 396 release of GLib. It does nothing.
 397 </para>
 398
 399 @scanner: a #GScanner.
 400
 401
 402 <!-- ##### FUNCTION g_scanner_lookup_symbol ##### -->
 403 <para>
 404 Looks up a symbol in the current scope and return its value. If the
 405 symbol is not bound in the current scope, %NULL is returned.
 406 </para>
 407
 408 @scanner: a #GScanner.
 409 @symbol: the symbol to look up.
 410 @Returns: the value of @symbol in the current scope, or %NULL
 411 if @symbol is not bound in the current scope.
 412
 413
 414 <!-- ##### FUNCTION g_scanner_warn ##### -->
 415 <para>
 416 Outputs a warning message, via the #GScanner message handler.
 417 </para>
 418
 419 @scanner: a #GScanner.
 420 @format: the message format. See the <function>printf()</function>
 421 documentation.
 422 @Varargs: the parameters to insert into the format string.
 423
 424
 425 <!-- ##### FUNCTION g_scanner_error ##### -->
 426 <para>
 427 Outputs an error message, via the #GScanner message handler.
 428 </para>
 429
 430 @scanner: a #GScanner.
 431 @format: the message format. See the <function>printf()</function>
 432 documentation.
 433 @Varargs: the parameters to insert into the format string.
 434
 435
 436 <!-- ##### FUNCTION g_scanner_unexp_token ##### -->
 437 <para>
 438 Outputs a message through the scanner's msg_handler, resulting from an
 439 unexpected token in the input stream.
 440 Note that you should not call g_scanner_peek_next_token() followed by
 441 g_scanner_unexp_token() without an intermediate call to
 442 g_scanner_get_next_token(), as g_scanner_unexp_token() evaluates the
 443 scanner's current token (not the peeked token) to construct part
 444 of the message.
 445 </para>
 446
 447 @scanner: a #GScanner.
 448 @expected_token: the expected token.
 449 @identifier_spec: a string describing how the scanner's user refers to
 450                   identifiers (%NULL defaults to "identifier").
 451                   This is used if @expected_token is #G_TOKEN_IDENTIFIER
 452                   or #G_TOKEN_IDENTIFIER_NULL.
 453 @symbol_spec: a string describing how the scanner's user refers to
 454               symbols (%NULL defaults to "symbol").
 455               This is used if @expected_token is #G_TOKEN_SYMBOL or
 456               any token value greater than #G_TOKEN_LAST.
 457 @symbol_name: the name of the symbol, if the scanner's current token
 458               is a symbol.
 459 @message: a message string to output at the end of the warning/error, or %NULL.
 460 @is_error: if %TRUE it is output as an error. If %FALSE it is output as a
 461            warning.
 462
 463
 464 <!-- ##### USER_FUNCTION GScannerMsgFunc ##### -->
 465 <para>
 466 Specifies the type of the message handler function.
 467 </para>
 468
 469 @scanner: a #GScanner.
 470 @message: the message.
 471 @error: %TRUE if the message signals an error, %FALSE if it
 472   signals a warning.
 473
 474
 475 <!-- ##### FUNCTION g_scanner_destroy ##### -->
 476 <para>
 477 Frees all memory used by the #GScanner.
 478 </para>
 479
 480 @scanner: a #GScanner.
 481
 482
 483 <!-- ##### ENUM GTokenType ##### -->
 484 <para>
 485 The possible types of token returned from each g_scanner_get_next_token() call.
 486 </para>
 487
 488 @G_TOKEN_EOF: the end of the file.
 489 @G_TOKEN_LEFT_PAREN: a '(' character.
 490 @G_TOKEN_LEFT_CURLY: a '{' character.
 491 @G_TOKEN_RIGHT_CURLY: a '}' character.
 492
 493 <!-- ##### UNION GTokenValue ##### -->
 494 <para>
 495 A union holding the value of the token.
 496 </para>
 497
 498
 499 <!-- ##### ENUM GErrorType ##### -->
 500 <para>
 501 The possible errors, used in the <structfield>v_error</structfield> field
 502 of #GTokenValue, when the token is a #G_TOKEN_ERROR.
 503 </para>
 504
 505 @G_ERR_UNKNOWN: unknown error.
 506 @G_ERR_UNEXP_EOF: unexpected end of file.
 507 @G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant.
 508 @G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment.
 509 @G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number.
 510 @G_ERR_DIGIT_RADIX: digit beyond radix in a number.
 511 @G_ERR_FLOAT_RADIX: non-decimal floating point number.
 512 @G_ERR_FLOAT_MALFORMED: malformed floating point number.
 513
 514 <!-- ##### MACRO G_CSET_a_2_z ##### -->
 515 <para>
 516 The set of lowercase ASCII alphabet characters.
 517 Used for specifying valid identifier characters in #GScannerConfig.
 518 </para>
 519
 520
 521
 522 <!-- ##### MACRO G_CSET_A_2_Z ##### -->
 523 <para>
 524 The set of uppercase ASCII alphabet characters.
 525 Used for specifying valid identifier characters in #GScannerConfig.
 526 </para>
 527
 528
 529
 530 <!-- ##### MACRO G_CSET_DIGITS ##### -->
 531 <para>
 532 The set of digits.
 533 Used for specifying valid identifier characters in #GScannerConfig.
 534 </para>
 535
 536
 537
 538 <!-- ##### MACRO G_CSET_LATINC ##### -->
 539 <para>
 540 The set of uppercase ISO 8859-1 alphabet characters which are
 541 not ASCII characters.
 542 Used for specifying valid identifier characters in #GScannerConfig.
 543 </para>
 544
 545
 546
 547 <!-- ##### MACRO G_CSET_LATINS ##### -->
 548 <para>
 549 The set of lowercase ISO 8859-1 alphabet characters which are
 550 not ASCII characters.
 551 Used for specifying valid identifier characters in #GScannerConfig.
 552 </para>
 553
 554
 555
 556 <!-- ##### MACRO g_scanner_add_symbol ##### -->
 557 <para>
 558 Adds a symbol to the default scope.
 559 Deprecated in favour of g_scanner_scope_add_symbol().
 560 </para>
 561
 562 @scanner: a #GScanner.
 563 @symbol: the symbol to add.
 564 @value: the value of the symbol.
 565
 566
 567 <!-- ##### MACRO g_scanner_remove_symbol ##### -->
 568 <para>
 569 Removes a symbol from the default scope.
 570 Deprecated in favour of g_scanner_scope_remove_symbol().
 571 </para>
 572
 573 @scanner: a #GScanner.
 574 @symbol: the symbol to remove.
 575
 576
 577 <!-- ##### MACRO g_scanner_foreach_symbol ##### -->
 578 <para>
 579 Calls a function for each symbol in the default scope.
 580 Deprecated in favour of g_scanner_scope_foreach_symbol().
 581 </para>
 582
 583 @scanner: a #GScanner.
 584 @func: the function to call with each symbol.
 585 @data: data to pass to the function.
 586
 587