scanner.sgml

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

<refentry id="glib-Lexical-Scanner">
<refmeta>
<refentrytitle>Lexical Scanner</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Lexical Scanner</refname><refpurpose>a general purpose lexical scanner.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


struct      <link linkend="GScanner">GScanner</link>;
<link linkend="GScanner">GScanner</link>*   <link linkend="g-scanner-new">g_scanner_new</link>                   (const <link linkend="GScannerConfig">GScannerConfig</link> *config_templ);
struct      <link linkend="GScannerConfig">GScannerConfig</link>;

void        <link linkend="g-scanner-input-file">g_scanner_input_file</link>            (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="gint">gint</link> input_fd);
void        <link linkend="g-scanner-sync-file-offset">g_scanner_sync_file_offset</link>      (<link linkend="GScanner">GScanner</link> *scanner);
void        <link linkend="g-scanner-input-text">g_scanner_input_text</link>            (<link linkend="GScanner">GScanner</link> *scanner,
                                             const	<link linkend="gchar">gchar</link> *text,
                                             <link linkend="guint">guint</link> text_len);
<link linkend="GTokenType">GTokenType</link>  <link linkend="g-scanner-peek-next-token">g_scanner_peek_next_token</link>       (<link linkend="GScanner">GScanner</link> *scanner);
<link linkend="GTokenType">GTokenType</link>  <link linkend="g-scanner-get-next-token">g_scanner_get_next_token</link>        (<link linkend="GScanner">GScanner</link> *scanner);

<link linkend="guint">guint</link>       <link linkend="g-scanner-cur-line">g_scanner_cur_line</link>              (<link linkend="GScanner">GScanner</link> *scanner);
<link linkend="guint">guint</link>       <link linkend="g-scanner-cur-position">g_scanner_cur_position</link>          (<link linkend="GScanner">GScanner</link> *scanner);
<link linkend="GTokenType">GTokenType</link>  <link linkend="g-scanner-cur-token">g_scanner_cur_token</link>             (<link linkend="GScanner">GScanner</link> *scanner);
<link linkend="GTokenValue">GTokenValue</link> <link linkend="g-scanner-cur-value">g_scanner_cur_value</link>             (<link linkend="GScanner">GScanner</link> *scanner);
<link linkend="gboolean">gboolean</link>    <link linkend="g-scanner-eof">g_scanner_eof</link>                   (<link linkend="GScanner">GScanner</link> *scanner);

<link linkend="guint">guint</link>       <link linkend="g-scanner-set-scope">g_scanner_set_scope</link>             (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="guint">guint</link> scope_id);
void        <link linkend="g-scanner-scope-add-symbol">g_scanner_scope_add_symbol</link>      (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="guint">guint</link> scope_id,
                                             const <link linkend="gchar">gchar</link> *symbol,
                                             <link linkend="gpointer">gpointer</link> value);
void        <link linkend="g-scanner-scope-foreach-symbol">g_scanner_scope_foreach_symbol</link>  (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="guint">guint</link> scope_id,
                                             <link linkend="GHFunc">GHFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gpointer">gpointer</link>    <link linkend="g-scanner-scope-lookup-symbol">g_scanner_scope_lookup_symbol</link>   (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="guint">guint</link> scope_id,
                                             const <link linkend="gchar">gchar</link> *symbol);
void        <link linkend="g-scanner-scope-remove-symbol">g_scanner_scope_remove_symbol</link>   (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="guint">guint</link> scope_id,
                                             const <link linkend="gchar">gchar</link> *symbol);

#define     <link linkend="g-scanner-freeze-symbol-table">g_scanner_freeze_symbol_table</link>   (scanner)
#define     <link linkend="g-scanner-thaw-symbol-table">g_scanner_thaw_symbol_table</link>     (scanner)
<link linkend="gpointer">gpointer</link>    <link linkend="g-scanner-lookup-symbol">g_scanner_lookup_symbol</link>         (<link linkend="GScanner">GScanner</link> *scanner,
                                             const <link linkend="gchar">gchar</link> *symbol);

void        <link linkend="g-scanner-warn">g_scanner_warn</link>                  (<link linkend="GScanner">GScanner</link> *scanner,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
void        <link linkend="g-scanner-error">g_scanner_error</link>                 (<link linkend="GScanner">GScanner</link> *scanner,
                                             const <link linkend="gchar">gchar</link> *format,
                                             ...);
void        <link linkend="g-scanner-unexp-token">g_scanner_unexp_token</link>           (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="GTokenType">GTokenType</link> expected_token,
                                             const <link linkend="gchar">gchar</link> *identifier_spec,
                                             const <link linkend="gchar">gchar</link> *symbol_spec,
                                             const <link linkend="gchar">gchar</link> *symbol_name,
                                             const <link linkend="gchar">gchar</link> *message,
                                             <link linkend="gint">gint</link> is_error);
void        (<link linkend="GScannerMsgFunc">*GScannerMsgFunc</link>)              (<link linkend="GScanner">GScanner</link> *scanner,
                                             <link linkend="gchar">gchar</link> *message,
                                             <link linkend="gboolean">gboolean</link> error);

void        <link linkend="g-scanner-destroy">g_scanner_destroy</link>               (<link linkend="GScanner">GScanner</link> *scanner);

enum        <link linkend="GTokenType">GTokenType</link>;
union       <link linkend="GTokenValue">GTokenValue</link>;
enum        <link linkend="GErrorType">GErrorType</link>;
#define     <link linkend="G-CSET-a-2-z">G_CSET_a_2_z</link>
#define     <link linkend="G-CSET-A-2-Z-CAPS">G_CSET_A_2_Z</link>
#define     <link linkend="G-CSET-DIGITS-CAPS">G_CSET_DIGITS</link>
#define     <link linkend="G-CSET-LATINC-CAPS">G_CSET_LATINC</link>
#define     <link linkend="G-CSET-LATINS-CAPS">G_CSET_LATINS</link>

#define     <link linkend="g-scanner-add-symbol">g_scanner_add_symbol</link>            ( scanner, symbol, value )
#define     <link linkend="g-scanner-remove-symbol">g_scanner_remove_symbol</link>         ( scanner, symbol )
#define     <link linkend="g-scanner-foreach-symbol">g_scanner_foreach_symbol</link>        ( scanner, func, data )
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GScanner">GScanner</link> 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>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GScanner">struct GScanner</title>
<programlisting>struct GScanner
{
  /* unused fields */
  gpointer		user_data;
  guint			max_parse_errors;
  
  /* g_scanner_error() increments this field */
  guint			parse_errors;
  
  /* name of input stream, featured by the default message handler */
  const gchar		*input_name;
  
  /* quarked data */
  GData			*qdata;
  
  /* link into the scanner configuration */
  GScannerConfig	*config;
  
  /* fields filled in after g_scanner_get_next_token() */
  GTokenType		token;
  GTokenValue		value;
  guint			line;
  guint			position;
  
  /* fields filled in after g_scanner_peek_next_token() */
  GTokenType		next_token;
  GTokenValue		next_value;
  guint			next_line;
  guint			next_position;
  
  /* to be considered private */
  GHashTable		*symbol_table;
  gint			input_fd;
  const gchar		*text;
  const gchar		*text_end;
  gchar			*buffer;
  guint			scope_id;
  
  /* handler function for _warn and _error */
  GScannerMsgFunc	msg_handler;
};
</programlisting>
<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 <link linkend="GScannerMsgFunc">GScannerMsgFunc</link>.
</para></refsect2>
<refsect2>
<title><anchor id="g-scanner-new">g_scanner_new ()</title>
<programlisting><link linkend="GScanner">GScanner</link>*   g_scanner_new                   (const <link linkend="GScannerConfig">GScannerConfig</link> *config_templ);</programlisting>
<para>
Creates a new <link linkend="GScanner">GScanner</link>.
The <parameter>config_templ</parameter> structure specifies the initial settings of the scanner,
which are copied into the <link linkend="GScanner">GScanner</link> <structfield>config</structfield> field.
If you pass <literal>NULL</literal> then the default settings are used.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>config_templ</parameter>&nbsp;:</entry>
<entry>the initial scanner settings.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the new <link linkend="GScanner">GScanner</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GScannerConfig">struct GScannerConfig</title>
<programlisting>struct GScannerConfig
{
  /* Character sets
   */
  gchar		*cset_skip_characters;		/* default: " \t\n" */
  gchar		*cset_identifier_first;
  gchar		*cset_identifier_nth;
  gchar		*cpair_comment_single;		/* default: "#\n" */
  
  /* Should symbol lookup work case sensitive?
   */
  guint		case_sensitive : 1;
  
  /* Boolean values to be adjusted "on the fly"
   * to configure scanning behaviour.
   */
  guint		skip_comment_multi : 1;		/* C like comment */
  guint		skip_comment_single : 1;	/* single line comment */
  guint		scan_comment_multi : 1;		/* scan multi line comments? */
  guint		scan_identifier : 1;
  guint		scan_identifier_1char : 1;
  guint		scan_identifier_NULL : 1;
  guint		scan_symbols : 1;
  guint		scan_binary : 1;
  guint		scan_octal : 1;
  guint		scan_float : 1;
  guint		scan_hex : 1;			/* `0x0ff0' */
  guint		scan_hex_dollar : 1;		/* `$0ff0' */
  guint		scan_string_sq : 1;		/* string: 'anything' */
  guint		scan_string_dq : 1;		/* string: "\\-escapes!\n" */
  guint		numbers_2_int : 1;		/* bin, octal, hex =&gt; int */
  guint		int_2_float : 1;		/* int =&gt; G_TOKEN_FLOAT? */
  guint		identifier_2_string : 1;
  guint		char_2_token : 1;		/* return G_TOKEN_CHAR? */
  guint		symbol_2_token : 1;
  guint		scope_0_fallback : 1;		/* try scope 0 on lookups? */
  guint		padding_dummy;
};
</programlisting>
<para>
Specifies the <link linkend="GScanner">GScanner</link> 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 <link linkend="G-CSET-a-2-z">G_CSET_a_2_z</link>, "_", and 
<link linkend="G-CSET-A-2-Z-CAPS">G_CSET_A_2_Z</link>).
</para>
<para>
<structfield>cset_identifier_nth</structfield> specifies the characters
which can be used in identifiers, after the first character (the default 
is <link linkend="G-CSET-a-2-z">G_CSET_a_2_z</link>, "_0123456789", <link linkend="G-CSET-A-2-Z-CAPS">G_CSET_A_2_Z</link>, <link linkend="G-CSET-LATINS-CAPS">G_CSET_LATINS</link>,
<link linkend="G-CSET-LATINC-CAPS">G_CSET_LATINC</link>).
</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 <literal>FALSE</literal>).
</para>
<para>
<structfield>skip_comment_multi</structfield> specifies if multi-line
comments are skipped and not returned as tokens (the default is <literal>TRUE</literal>).
</para>
<para>
<structfield>skip_comment_single</structfield> specifies if single-line
comments are skipped and not returned as tokens (the default is <literal>TRUE</literal>).
</para>
<para>
<structfield>scan_comment_multi</structfield> specifies if multi-line
comments are recognized (the default is <literal>TRUE</literal>).
</para>
<para>
<structfield>scan_identifier</structfield> specifies if identifiers
are recognized (the default is <literal>TRUE</literal>).
</para>
<para>
<structfield>scan_identifier_1char</structfield> specifies if single-character
identifiers are recognized (the default is <literal>FALSE</literal>).
</para>
<para>
<structfield>scan_identifier_NULL</structfield> specifies if 
<literal>NULL</literal> is reported as <link linkend="G-TOKEN-IDENTIFIER-NULL-CAPS">G_TOKEN_IDENTIFIER_NULL</link>.
(the default is <literal>FALSE</literal>).
</para>
<para>
<structfield>scan_symbols</structfield> specifies if symbols are
recognized (the default is <literal>TRUE</literal>).