Lexical Scanner
a general purpose lexical scanner.
The #GScanner and its associated functions provide a general purpose
lexical scanner.
FIXME: really needs an example and more detail, but I don't completely
understand it myself. Look at gtkrc.c for some code using the scanner.
The data structure representing a lexical scanner.
You should set input_name after creating
the scanner, since it is used by the default message handler when
displaying warnings and errors. If you are scanning a file, the file
name would be a good choice.
The user_data and
max_parse_errors fields are not used.
If you need to associate extra data with the scanner you can place them here.
If you want to use your own message handler you can set the
msg_handler field. The type of the message
handler function is declared by #GScannerMsgFunc.
@user_data:
@max_parse_errors:
@parse_errors:
@input_name:
@qdata:
@config:
@token:
@value:
@line:
@position:
@next_token:
@next_value:
@next_line:
@next_position:
@symbol_table:
@input_fd:
@text:
@text_end:
@buffer:
@scope_id:
@msg_handler:
Creates a new #GScanner.
The @config_templ structure specifies the initial settings of the scanner,
which are copied into the #GScanner config field.
If you pass %NULL then the default settings are used.
@config_templ: the initial scanner settings.
@Returns: the new #GScanner.
Specifies the #GScanner settings.
cset_skip_characters specifies which characters
should be skipped by the scanner (the default is the whitespace characters:
space, tab, carriage-return and line-feed).
cset_identifier_first specifies the characters
which can start identifiers (the default is #G_CSET_a_2_z, "_", and
#G_CSET_A_2_Z).
cset_identifier_nth specifies the characters
which can be used in identifiers, after the first character (the default
is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS,
#G_CSET_LATINC).
cpair_comment_single specifies the characters
at the start and end of single-line comments. The default is "#\n" which
means that single-line comments start with a '#' and continue until a '\n'
(end of line).
case_sensitive specifies if symbols are
case sensitive (the default is %FALSE).
skip_comment_multi specifies if multi-line
comments are skipped and not returned as tokens (the default is %TRUE).
skip_comment_single specifies if single-line
comments are skipped and not returned as tokens (the default is %TRUE).
scan_comment_multi specifies if multi-line
comments are recognized (the default is %TRUE).
scan_identifier specifies if identifiers
are recognized (the default is %TRUE).
scan_identifier_1char specifies if single-character
identifiers are recognized (the default is %FALSE).
scan_identifier_NULL specifies if
NULL is reported as #G_TOKEN_IDENTIFIER_NULL.
(the default is %FALSE).
scan_symbols specifies if symbols are
recognized (the default is %TRUE).
scan_binary specifies if binary numbers
are recognized (the default is %FALSE).
scan_octal specifies if octal numbers
are recognized (the default is %TRUE).
scan_float specifies if floating point numbers
are recognized (the default is %TRUE).
scan_hex specifies if hexadecimal numbers
are recognized (the default is %TRUE).
scan_hex_dollar specifies if '$' is recognized
as a prefix for hexadecimal numbers (the default is %FALSE).
scan_string_sq specifies if strings can be
enclosed in single quotes (the default is %TRUE).
scan_string_dq specifies if strings can be
enclosed in double quotes (the default is %TRUE).
numbers_2_int specifies if binary, octal and
hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE).
int_2_float specifies if all numbers are
reported as #G_TOKEN_FLOAT (the default is %FALSE).
identifier_2_string specifies if identifiers
are reported as strings (the default is %FALSE).
char_2_token specifies if characters
are reported by setting token = ch or as #G_TOKEN_CHAR
(the default is %TRUE).
symbol_2_token specifies if symbols
are reported by setting token = v_symbol or as
#G_TOKEN_SYMBOL (the default is %FALSE).
scope_0_fallback specifies if a symbol
is searched for in the default scope in addition to the current scope
(the default is %FALSE).
@cset_skip_characters:
@cset_identifier_first:
@cset_identifier_nth:
@cpair_comment_single:
@case_sensitive:
@skip_comment_multi:
@skip_comment_single:
@scan_comment_multi:
@scan_identifier:
@scan_identifier_1char:
@scan_identifier_NULL:
@scan_symbols:
@scan_binary:
@scan_octal:
@scan_float:
@scan_hex:
@scan_hex_dollar:
@scan_string_sq:
@scan_string_dq:
@numbers_2_int:
@int_2_float:
@identifier_2_string:
@char_2_token:
@symbol_2_token:
@scope_0_fallback:
@store_int64:
@padding_dummy:
Prepares to scan a file.
@scanner: a #GScanner.
@input_fd: a file descriptor.
Rewinds the filedescriptor to the current buffer position and blows
the file read ahead buffer. This is useful for third party uses of
the scanners filedescriptor, which hooks onto the current scanning
position.
@scanner: a #GScanner.
Prepares to scan a text buffer.
@scanner: a #GScanner.
@text: the text buffer to scan.
@text_len: the length of the text buffer.
Gets the next token, without removing it from the input stream.
The token data is placed in the
next_token,
next_value,
next_line, and
next_position fields of the #GScanner structure.
@scanner: a #GScanner.
@Returns: the type of the token.
Gets the next token, removing it from the input stream.
The token data is placed in the
token,
value,
line, and
position fields of the #GScanner structure.
@scanner: a #GScanner.
@Returns: the type of the token.
Gets the current line in the input stream (counting from 1).
@scanner: a #GScanner.
@Returns: the current line.
Gets the current position in the current line (counting from 0).
@scanner: a #GScanner.
@Returns: the current position on the line.
Gets the current token type.
This is simply the token field in the #GScanner
structure.
@scanner: a #GScanner.
@Returns: the current token type.
Gets the current token value.
This is simply the value field in the #GScanner
structure.
@scanner: a #GScanner.
@Returns: the current token value.
Returns %TRUE if the scanner has reached the end of the file or text buffer.
@scanner: a #GScanner.
@Returns: %TRUE if the scanner has reached the end of the file or text buffer.
Sets the current scope.
@scanner: a #GScanner.
@scope_id: the new scope id.
@Returns: the old scope id.
Adds a symbol to the given scope.
@scanner: a #GScanner.
@scope_id: the scope id.
@symbol: the symbol to add.
@value: the value of the symbol.
Calls the given function for each of the symbol/value pairs in the
given scope of the #GScanner. The function is passed the symbol and
value of each pair, and the given @user_data parameter.
@scanner: a #GScanner.
@scope_id: the scope id.
@func: the function to call for each symbol/value pair.
@user_data: user data to pass to the function.
Looks up a symbol in a scope and return its value. If the
symbol is not bound in the scope, %NULL is returned.
@scanner: a #GScanner.
@scope_id: the scope id.
@symbol: the symbol to look up.
@Returns: the value of @symbol in the given scope, or %NULL
if @symbol is not bound in the given scope.
Removes a symbol from a scope.
@scanner: a #GScanner.
@scope_id: the scope id.
@symbol: the symbol to remove.
This function is deprecated and will be removed in the next major
release of GLib. It does nothing.
@scanner: a #GScanner.
This function is deprecated and will be removed in the next major
release of GLib. It does nothing.
@scanner: a #GScanner.
Looks up a symbol in the current scope and return its value. If the
symbol is not bound in the current scope, %NULL is returned.
@scanner: a #GScanner.
@symbol: the symbol to look up.
@Returns: the value of @symbol in the current scope, or %NULL
if @symbol is not bound in the current scope.
Outputs a warning message, via the #GScanner message handler.
@scanner: a #GScanner.
@format: the message format. See the printf()
documentation.
@Varargs: the parameters to insert into the format string.
Outputs an error message, via the #GScanner message handler.
@scanner: a #GScanner.
@format: the message format. See the printf()
documentation.
@Varargs: the parameters to insert into the format string.
Outputs a message through the scanner's msg_handler, resulting from an
unexpected token in the input stream.
Note that you should not call g_scanner_peek_next_token() followed by
g_scanner_unexp_token() without an intermediate call to
g_scanner_get_next_token(), as g_scanner_unexp_token() evaluates the
scanner's current token (not the peeked token) to construct part
of the message.
@scanner: a #GScanner.
@expected_token: the expected token.
@identifier_spec: a string describing how the scanner's user refers to
identifiers (%NULL defaults to "identifier").
This is used if @expected_token is #G_TOKEN_IDENTIFIER
or #G_TOKEN_IDENTIFIER_NULL.
@symbol_spec: a string describing how the scanner's user refers to
symbols (%NULL defaults to "symbol").
This is used if @expected_token is #G_TOKEN_SYMBOL or
any token value greater than #G_TOKEN_LAST.
@symbol_name: the name of the symbol, if the scanner's current token
is a symbol.
@message: a message string to output at the end of the warning/error, or %NULL.
@is_error: if %TRUE it is output as an error. If %FALSE it is output as a
warning.
Specifies the type of the message handler function.
@scanner: a #GScanner.
@message: the message.
@error: %TRUE if the message signals an error, %FALSE if it
signals a warning.
Frees all memory used by the #GScanner.
@scanner: a #GScanner.
The possible types of token returned from each g_scanner_get_next_token() call.
@G_TOKEN_EOF: the end of the file.
@G_TOKEN_LEFT_PAREN: a '(' character.
@G_TOKEN_LEFT_CURLY: a '{' character.
@G_TOKEN_RIGHT_CURLY: a '}' character.
A union holding the value of the token.
The possible errors, used in the v_error field
of #GTokenValue, when the token is a #G_TOKEN_ERROR.
@G_ERR_UNKNOWN: unknown error.
@G_ERR_UNEXP_EOF: unexpected end of file.
@G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant.
@G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment.
@G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number.
@G_ERR_DIGIT_RADIX: digit beyond radix in a number.
@G_ERR_FLOAT_RADIX: non-decimal floating point number.
@G_ERR_FLOAT_MALFORMED: malformed floating point number.
The set of lowercase ASCII alphabet characters.
Used for specifying valid identifier characters in #GScannerConfig.
The set of uppercase ASCII alphabet characters.
Used for specifying valid identifier characters in #GScannerConfig.
The set of digits.
Used for specifying valid identifier characters in #GScannerConfig.
The set of uppercase ISO 8859-1 alphabet characters which are
not ASCII characters.
Used for specifying valid identifier characters in #GScannerConfig.
The set of lowercase ISO 8859-1 alphabet characters which are
not ASCII characters.
Used for specifying valid identifier characters in #GScannerConfig.
Adds a symbol to the default scope.
@scanner: a #GScanner.
@symbol: the symbol to add.
@value: the value of the symbol.
@Deprecated: Use g_scanner_scope_add_symbol() instead.
Removes a symbol from the default scope.
@scanner: a #GScanner.
@symbol: the symbol to remove.
@Deprecated: Use g_scanner_scope_remove_symbol() instead.
Calls a function for each symbol in the default scope.
@scanner: a #GScanner.
@func: the function to call with each symbol.
@data: data to pass to the function.
@Deprecated: Use g_scanner_scope_foreach_symbol() instead.