scanner.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<!-- ##### SECTION Title ##### -->
Lexical Scanner

<!-- ##### SECTION Short_Description ##### -->
a general purpose lexical scanner.

<!-- ##### SECTION Long_Description ##### -->
<para>
The #GScanner and its associated functions provide a general purpose
lexical scanner.
</para>
<para>
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.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### STRUCT GScanner ##### -->
<para>
The data structure representing a lexical scanner.
</para>
<para>
You should set <structfield>input_name</structfield> 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.
</para>
<para>
The <structfield>user_data</structfield> and
<structfield>derived_data</structfield> fields are not used.
If you need to associate extra data with the scanner you can place them here.
</para>
<para>
If you want to use your own message handler you can set the
<structfield>msg_handler</structfield> field. The type of the message
handler function is declared by #GScannerMsgFunc.
</para>

@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: 

<!-- ##### FUNCTION g_scanner_new ##### -->
<para>
Creates a new #GScanner.
The @config_templ structure specifies the initial settings of the scanner,
which are copied into the #GScanner <structfield>config</structfield> field.
If you pass %NULL then the default settings are used.
</para>

@config_templ: the initial scanner settings.
@Returns: the new #GScanner.


<!-- ##### STRUCT GScannerConfig ##### -->
<para>
Specifies the #GScanner settings.
</para>
<para>
<structfield>cset_skip_characters</structfield> specifies which characters
should be skipped by the scanner (the default is the whitespace characters:
space, tab, carriage-return and line-feed).
</para>
<para>
<structfield>cset_identifier_first</structfield> specifies the characters
which can start identifiers (the default is #G_CSET_a_2_z, "_", and 
#G_CSET_A_2_Z).
</para>
<para>
<structfield>cset_identifier_nth</structfield> 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).
</para>
<para>
<structfield>cpair_comment_single</structfield> 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).
</para>
<para>
<structfield>case_sensitive</structfield> specifies if symbols are
case sensitive (the default is %FALSE).
</para>
<para>
<structfield>skip_comment_multi</structfield> specifies if multi-line
comments are skipped and not returned as tokens (the default is %TRUE).
</para>
<para>
<structfield>skip_comment_single</structfield> specifies if single-line
comments are skipped and not returned as tokens (the default is %TRUE).
</para>
<para>
<structfield>scan_comment_multi</structfield> specifies if multi-line
comments are recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_identifier</structfield> specifies if identifiers
are recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_identifier_1char</structfield> specifies if single-character
identifiers are recognized (the default is %FALSE).
</para>
<para>
<structfield>scan_identifier_NULL</structfield> specifies if 
<literal>NULL</literal> is reported as #G_TOKEN_IDENTIFIER_NULL.
(the default is %FALSE).
</para>
<para>
<structfield>scan_symbols</structfield> specifies if symbols are
recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_binary</structfield> specifies if binary numbers
are recognized (the default is %FALSE).
</para>
<para>
<structfield>scan_octal</structfield> specifies if octal numbers
are recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_float</structfield> specifies if floating point numbers
are recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_hex</structfield> specifies if hexadecimal numbers
are recognized (the default is %TRUE).
</para>
<para>
<structfield>scan_hex_dollar</structfield> specifies if '$' is recognized
as a prefix for hexadecimal numbers (the default is %FALSE).
</para>
<para>
<structfield>scan_string_sq</structfield> specifies if strings can be
enclosed in single quotes (the default is %TRUE).
</para>
<para>
<structfield>scan_string_dq</structfield> specifies if strings can be
enclosed in double quotes (the default is %TRUE).
</para>
<para>
<structfield>numbers_2_int</structfield> specifies if binary, octal and
hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE).
</para>
<para>
<structfield>int_2_float</structfield> specifies if all numbers are 
reported as #G_TOKEN_FLOAT (the default is %FALSE).
</para>
<para>
<structfield>identifier_2_string</structfield> specifies if identifiers
are reported as strings (the default is %FALSE).
</para>
<para>
<structfield>char_2_token</structfield> specifies if characters
are reported by setting <literal>token = ch</literal> or as #G_TOKEN_CHAR 
(the default is %TRUE).
</para>
<para>
<structfield>symbol_2_token</structfield> specifies if symbols 
are reported by setting <literal>token = v_symbol</literal> or as
#G_TOKEN_SYMBOL (the default is %FALSE).
</para>
<para>
<structfield>scope_0_fallback</structfield> specifies if a symbol 
is searched for in the default scope in addition to the current scope
(the default is %FALSE).
</para>

@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: 
@padding_dummy: 

<!-- ##### FUNCTION g_scanner_input_file ##### -->
<para>
Prepares to scan a file.
</para>

@scanner: a #GScanner.
@input_fd: a file descriptor.


<!-- ##### FUNCTION g_scanner_sync_file_offset ##### -->
<para>
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.
</para>

@scanner: a #GScanner.


<!-- ##### FUNCTION g_scanner_input_text ##### -->
<para>
Prepares to scan a text buffer.
</para>

@scanner: a #GScanner.
@text: the text buffer to scan.
@text_len: the length of the text buffer.


<!-- ##### FUNCTION g_scanner_peek_next_token ##### -->
<para>
Gets the next token, without removing it from the input stream.
The token data is placed in the
<structfield>next_token</structfield>,
<structfield>next_value</structfield>,
<structfield>next_line</structfield>, and
<structfield>next_position</structfield> fields of the #GScanner structure.
</para>

@scanner: a #GScanner.
@Returns: the type of the token.


<!-- ##### FUNCTION g_scanner_get_next_token ##### -->
<para>
Gets the next token, removing it from the input stream.
The token data is placed in the
<structfield>token</structfield>,
<structfield>value</structfield>,
<structfield>line</structfield>, and
<structfield>position</structfield> fields of the #GScanner structure.
</para>

@scanner: a #GScanner.
@Returns: the type of the token.


<!-- ##### FUNCTION g_scanner_cur_line ##### -->
<para>
Gets the current line in the input stream (counting from 1).
</para>

@scanner: a #GScanner.
@Returns: the current line.


<!-- ##### FUNCTION g_scanner_cur_position ##### -->
<para>
Gets the current position in the current line (counting from 0).
</para>