<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 <glib.h> 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>; <link linkend="void">void</link> <link linkend="g-scanner-input-file">g_scanner_input_file</link> (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="gint">gint</link> input_fd); <link linkend="void">void</link> <link linkend="g-scanner-sync-file-offset">g_scanner_sync_file_offset</link> (<link linkend="GScanner">GScanner</link> *scanner); <link linkend="void">void</link> <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); <link linkend="void">void</link> <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); <link linkend="void">void</link> <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); <link linkend="void">void</link> <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); <link linkend="void">void</link> <link linkend="g-scanner-warn">g_scanner_warn</link> (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *format, ...); <link linkend="void">void</link> <link linkend="g-scanner-error">g_scanner_error</link> (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *format, ...); <link linkend="void">void</link> <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); <link linkend="void">void</link> (<link linkend="GScannerMsgFunc">*GScannerMsgFunc</link>) (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="gchar">gchar</link> *message, <link linkend="gboolean">gboolean</link> error); <link linkend="void">void</link> <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"><type>GScanner</type></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> <indexterm><primary>GScanner</primary></indexterm><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>max_parse_errors</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"><type>GScannerMsgFunc</type></link>. </para></refsect2> <refsect2> <title><anchor id="g-scanner-new"/>g_scanner_new ()</title> <indexterm><primary>g_scanner_new</primary></indexterm><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"><type>GScanner</type></link>. The <parameter>config_templ</parameter> structure specifies the initial settings of the scanner, which are copied into the <link linkend="GScanner"><type>GScanner</type></link> <structfield>config</structfield> field. If you pass <literal>NULL</literal> then the default settings are used. </para><variablelist role="params"> <varlistentry><term><parameter>config_templ</parameter> :</term> <listitem><simpara>the initial scanner settings. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the new <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="GScannerConfig"/>struct GScannerConfig</title> <indexterm><primary>GScannerConfig</primary></indexterm><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 => int */ guint int_2_float : 1; /* int => 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 store_int64 : 1; /* use value.v_int64 rather than v_int */ guint padding_dummy; }; </programlisting> <para> Specifies the <link linkend="GScanner"><type>GScanner</type></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"><type>G_CSET_a_2_z</type></link>, "_", and <link linkend="G-CSET-A-2-Z-CAPS"><type>G_CSET_A_2_Z</type></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"><type>G_CSET_a_2_z</type></link>, "_0123456789", <link linkend="G-CSET-A-2-Z-CAPS"><type>G_CSET_A_2_Z</type></link>, <link linkend="G-CSET-LATINS-CAPS"><type>G_CSET_LATINS</type></link>, <link linkend="G-CSET-LATINC-CAPS"><type>G_CSET_LATINC</type></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"><type>G_TOKEN_IDENTIFIER_NULL</type></link>. (the default is <literal>FALSE</literal>). </para> <para> <structfield>scan_symbols</structfield> specifies if symbols are recognized (the default is <literal>TRUE</literal>). </para> <para> <structfield>scan_binary</structfield> specifies if binary numbers are recognized (the default is <literal>FALSE</literal>). </para> <para> <structfield>scan_octal</structfield> specifies if octal numbers are recognized (the default is <literal>TRUE</literal>). </para> <para> <structfield>scan_float</structfield> specifies if floating point numbers are recognized (the default is <literal>TRUE</literal>). </para> <para> <structfield>scan_hex</structfield> specifies if hexadecimal numbers are recognized (the default is <literal>TRUE</literal>). </para> <para> <structfield>scan_hex_dollar</structfield> specifies if '$' is recognized as a prefix for hexadecimal numbers (the default is <literal>FALSE</literal>). </para> <para> <structfield>scan_string_sq</structfield> specifies if strings can be enclosed in single quotes (the default is <literal>TRUE</literal>). </para> <para> <structfield>scan_string_dq</structfield> specifies if strings can be enclosed in double quotes (the default is <literal>TRUE</literal>). </para> <para> <structfield>numbers_2_int</structfield> specifies if binary, octal and hexadecimal numbers are reported as <link linkend="G-TOKEN-INT-CAPS"><type>G_TOKEN_INT</type></link> (the default is <literal>TRUE</literal>). </para> <para> <structfield>int_2_float</structfield> specifies if all numbers are reported as <link linkend="G-TOKEN-FLOAT-CAPS"><type>G_TOKEN_FLOAT</type></link> (the default is <literal>FALSE</literal>). </para> <para> <structfield>identifier_2_string</structfield> specifies if identifiers are reported as strings (the default is <literal>FALSE</literal>). </para> <para> <structfield>char_2_token</structfield> specifies if characters are reported by setting <literal>token = ch</literal> or as <link linkend="G-TOKEN-CHAR-CAPS"><type>G_TOKEN_CHAR</type></link> (the default is <literal>TRUE</literal>). </para> <para> <structfield>symbol_2_token</structfield> specifies if symbols are reported by setting <literal>token = v_symbol</literal> or as <link linkend="G-TOKEN-SYMBOL-CAPS"><type>G_TOKEN_SYMBOL</type></link> (the default is <literal>FALSE</literal>). </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 <literal>FALSE</literal>). </para></refsect2> <refsect2> <title><anchor id="g-scanner-input-file"/>g_scanner_input_file ()</title> <indexterm><primary>g_scanner_input_file</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_input_file (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="gint">gint</link> input_fd);</programlisting> <para> Prepares to scan a file. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>input_fd</parameter> :</term> <listitem><simpara>a file descriptor. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-sync-file-offset"/>g_scanner_sync_file_offset ()</title> <indexterm><primary>g_scanner_sync_file_offset</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_sync_file_offset (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <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><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-input-text"/>g_scanner_input_text ()</title> <indexterm><primary>g_scanner_input_text</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_input_text (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *text, <link linkend="guint">guint</link> text_len);</programlisting> <para> Prepares to scan a text buffer. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>text</parameter> :</term> <listitem><simpara>the text buffer to scan. </simpara></listitem></varlistentry> <varlistentry><term><parameter>text_len</parameter> :</term> <listitem><simpara>the length of the text buffer. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-peek-next-token"/>g_scanner_peek_next_token ()</title> <indexterm><primary>g_scanner_peek_next_token</primary></indexterm><programlisting><link linkend="GTokenType">GTokenType</link> g_scanner_peek_next_token (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <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 <link linkend="GScanner"><type>GScanner</type></link> structure. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the type of the token. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-get-next-token"/>g_scanner_get_next_token ()</title> <indexterm><primary>g_scanner_get_next_token</primary></indexterm><programlisting><link linkend="GTokenType">GTokenType</link> g_scanner_get_next_token (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <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 <link linkend="GScanner"><type>GScanner</type></link> structure. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the type of the token. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-cur-line"/>g_scanner_cur_line ()</title> <indexterm><primary>g_scanner_cur_line</primary></indexterm><programlisting><link linkend="guint">guint</link> g_scanner_cur_line (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Gets the current line in the input stream (counting from 1). </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the current line. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-cur-position"/>g_scanner_cur_position ()</title> <indexterm><primary>g_scanner_cur_position</primary></indexterm><programlisting><link linkend="guint">guint</link> g_scanner_cur_position (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Gets the current position in the current line (counting from 0). </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the current position on the line. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-cur-token"/>g_scanner_cur_token ()</title> <indexterm><primary>g_scanner_cur_token</primary></indexterm><programlisting><link linkend="GTokenType">GTokenType</link> g_scanner_cur_token (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Gets the current token type. This is simply the <structfield>token</structfield> field in the <link linkend="GScanner"><type>GScanner</type></link> structure. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the current token type. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-cur-value"/>g_scanner_cur_value ()</title> <indexterm><primary>g_scanner_cur_value</primary></indexterm><programlisting><link linkend="GTokenValue">GTokenValue</link> g_scanner_cur_value (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Gets the current token value. This is simply the <structfield>value</structfield> field in the <link linkend="GScanner"><type>GScanner</type></link> structure. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the current token value. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-eof"/>g_scanner_eof ()</title> <indexterm><primary>g_scanner_eof</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_scanner_eof (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Returns <literal>TRUE</literal> if the scanner has reached the end of the file or text buffer. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><literal>TRUE</literal> if the scanner has reached the end of the file or text buffer. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-set-scope"/>g_scanner_set_scope ()</title> <indexterm><primary>g_scanner_set_scope</primary></indexterm><programlisting><link linkend="guint">guint</link> g_scanner_set_scope (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="guint">guint</link> scope_id);</programlisting> <para> Sets the current scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>scope_id</parameter> :</term> <listitem><simpara>the new scope id. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the old scope id. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-scope-add-symbol"/>g_scanner_scope_add_symbol ()</title> <indexterm><primary>g_scanner_scope_add_symbol</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_scope_add_symbol (<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);</programlisting> <para> Adds a symbol to the given scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>scope_id</parameter> :</term> <listitem><simpara>the scope id. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to add. </simpara></listitem></varlistentry> <varlistentry><term><parameter>value</parameter> :</term> <listitem><simpara>the value of the symbol. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-scope-foreach-symbol"/>g_scanner_scope_foreach_symbol ()</title> <indexterm><primary>g_scanner_scope_foreach_symbol</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_scope_foreach_symbol (<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);</programlisting> <para> Calls the given function for each of the symbol/value pairs in the given scope of the <link linkend="GScanner"><type>GScanner</type></link>. The function is passed the symbol and value of each pair, and the given <parameter>user_data</parameter> parameter. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>scope_id</parameter> :</term> <listitem><simpara>the scope id. </simpara></listitem></varlistentry> <varlistentry><term><parameter>func</parameter> :</term> <listitem><simpara>the function to call for each symbol/value pair. </simpara></listitem></varlistentry> <varlistentry><term><parameter>user_data</parameter> :</term> <listitem><simpara>user data to pass to the function. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-scope-lookup-symbol"/>g_scanner_scope_lookup_symbol ()</title> <indexterm><primary>g_scanner_scope_lookup_symbol</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_scanner_scope_lookup_symbol (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="guint">guint</link> scope_id, const <link linkend="gchar">gchar</link> *symbol);</programlisting> <para> Looks up a symbol in a scope and return its value. If the symbol is not bound in the scope, <literal>NULL</literal> is returned. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>scope_id</parameter> :</term> <listitem><simpara>the scope id. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to look up. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the value of <parameter>symbol</parameter> in the given scope, or <literal>NULL</literal> if <parameter>symbol</parameter> is not bound in the given scope. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-scope-remove-symbol"/>g_scanner_scope_remove_symbol ()</title> <indexterm><primary>g_scanner_scope_remove_symbol</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_scope_remove_symbol (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="guint">guint</link> scope_id, const <link linkend="gchar">gchar</link> *symbol);</programlisting> <para> Removes a symbol from a scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>scope_id</parameter> :</term> <listitem><simpara>the scope id. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to remove. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-freeze-symbol-table"/>g_scanner_freeze_symbol_table()</title> <indexterm role="deprecated"><primary>g_scanner_freeze_symbol_table</primary></indexterm><programlisting>#define g_scanner_freeze_symbol_table(scanner)</programlisting> <warning><para><literal>g_scanner_freeze_symbol_table</literal> is deprecated and should not be used in newly-written code.</para></warning> <para> This function is deprecated and will be removed in the next major release of GLib. It does nothing. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-thaw-symbol-table"/>g_scanner_thaw_symbol_table()</title> <indexterm role="deprecated"><primary>g_scanner_thaw_symbol_table</primary></indexterm><programlisting>#define g_scanner_thaw_symbol_table(scanner)</programlisting> <warning><para><literal>g_scanner_thaw_symbol_table</literal> is deprecated and should not be used in newly-written code.</para></warning> <para> This function is deprecated and will be removed in the next major release of GLib. It does nothing. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-lookup-symbol"/>g_scanner_lookup_symbol ()</title> <indexterm><primary>g_scanner_lookup_symbol</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link> g_scanner_lookup_symbol (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *symbol);</programlisting> <para> Looks up a symbol in the current scope and return its value. If the symbol is not bound in the current scope, <literal>NULL</literal> is returned. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to look up. </simpara></listitem></varlistentry> <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the value of <parameter>symbol</parameter> in the current scope, or <literal>NULL</literal> if <parameter>symbol</parameter> is not bound in the current scope. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-warn"/>g_scanner_warn ()</title> <indexterm><primary>g_scanner_warn</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_warn (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *format, ...);</programlisting> <para> Outputs a warning message, via the <link linkend="GScanner"><type>GScanner</type></link> message handler. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>format</parameter> :</term> <listitem><simpara>the message format. See the <function><link linkend="printf"><function>printf()</function></link></function> documentation. </simpara></listitem></varlistentry> <varlistentry><term><parameter>...</parameter> :</term> <listitem><simpara>the parameters to insert into the format string. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-error"/>g_scanner_error ()</title> <indexterm><primary>g_scanner_error</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_error (<link linkend="GScanner">GScanner</link> *scanner, const <link linkend="gchar">gchar</link> *format, ...);</programlisting> <para> Outputs an error message, via the <link linkend="GScanner"><type>GScanner</type></link> message handler. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>format</parameter> :</term> <listitem><simpara>the message format. See the <function><link linkend="printf"><function>printf()</function></link></function> documentation. </simpara></listitem></varlistentry> <varlistentry><term><parameter>...</parameter> :</term> <listitem><simpara>the parameters to insert into the format string. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-unexp-token"/>g_scanner_unexp_token ()</title> <indexterm><primary>g_scanner_unexp_token</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_unexp_token (<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);</programlisting> <para> Outputs a message through the scanner's msg_handler, resulting from an unexpected token in the input stream. Note that you should not call <link linkend="g-scanner-peek-next-token"><function>g_scanner_peek_next_token()</function></link> followed by <link linkend="g-scanner-unexp-token"><function>g_scanner_unexp_token()</function></link> without an intermediate call to <link linkend="g-scanner-get-next-token"><function>g_scanner_get_next_token()</function></link>, as <link linkend="g-scanner-unexp-token"><function>g_scanner_unexp_token()</function></link> evaluates the scanner's current token (not the peeked token) to construct part of the message. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>expected_token</parameter> :</term> <listitem><simpara>the expected token. </simpara></listitem></varlistentry> <varlistentry><term><parameter>identifier_spec</parameter> :</term> <listitem><simpara>a string describing how the scanner's user refers to identifiers (<literal>NULL</literal> defaults to "identifier"). This is used if <parameter>expected_token</parameter> is <link linkend="G-TOKEN-IDENTIFIER-CAPS"><type>G_TOKEN_IDENTIFIER</type></link> or <link linkend="G-TOKEN-IDENTIFIER-NULL-CAPS"><type>G_TOKEN_IDENTIFIER_NULL</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol_spec</parameter> :</term> <listitem><simpara>a string describing how the scanner's user refers to symbols (<literal>NULL</literal> defaults to "symbol"). This is used if <parameter>expected_token</parameter> is <link linkend="G-TOKEN-SYMBOL-CAPS"><type>G_TOKEN_SYMBOL</type></link> or any token value greater than <link linkend="G-TOKEN-LAST-CAPS"><type>G_TOKEN_LAST</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol_name</parameter> :</term> <listitem><simpara>the name of the symbol, if the scanner's current token is a symbol. </simpara></listitem></varlistentry> <varlistentry><term><parameter>message</parameter> :</term> <listitem><simpara>a message string to output at the end of the warning/error, or <literal>NULL</literal>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>is_error</parameter> :</term> <listitem><simpara>if <literal>TRUE</literal> it is output as an error. If <literal>FALSE</literal> it is output as a warning. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="GScannerMsgFunc"/>GScannerMsgFunc ()</title> <indexterm><primary>GScannerMsgFunc</primary></indexterm><programlisting><link linkend="void">void</link> (*GScannerMsgFunc) (<link linkend="GScanner">GScanner</link> *scanner, <link linkend="gchar">gchar</link> *message, <link linkend="gboolean">gboolean</link> error);</programlisting> <para> Specifies the type of the message handler function. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>message</parameter> :</term> <listitem><simpara>the message. </simpara></listitem></varlistentry> <varlistentry><term><parameter>error</parameter> :</term> <listitem><simpara><literal>TRUE</literal> if the message signals an error, <literal>FALSE</literal> if it signals a warning. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-destroy"/>g_scanner_destroy ()</title> <indexterm><primary>g_scanner_destroy</primary></indexterm><programlisting><link linkend="void">void</link> g_scanner_destroy (<link linkend="GScanner">GScanner</link> *scanner);</programlisting> <para> Frees all memory used by the <link linkend="GScanner"><type>GScanner</type></link>. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="GTokenType"/>enum GTokenType</title> <indexterm><primary>GTokenType</primary></indexterm><programlisting>typedef enum { G_TOKEN_EOF = 0, G_TOKEN_LEFT_PAREN = '(', G_TOKEN_RIGHT_PAREN = ')', G_TOKEN_LEFT_CURLY = '{', G_TOKEN_RIGHT_CURLY = '}', G_TOKEN_LEFT_BRACE = '[', G_TOKEN_RIGHT_BRACE = ']', G_TOKEN_EQUAL_SIGN = '=', G_TOKEN_COMMA = ',', G_TOKEN_NONE = 256, G_TOKEN_ERROR, G_TOKEN_CHAR, G_TOKEN_BINARY, G_TOKEN_OCTAL, G_TOKEN_INT, G_TOKEN_HEX, G_TOKEN_FLOAT, G_TOKEN_STRING, G_TOKEN_SYMBOL, G_TOKEN_IDENTIFIER, G_TOKEN_IDENTIFIER_NULL, G_TOKEN_COMMENT_SINGLE, G_TOKEN_COMMENT_MULTI, G_TOKEN_LAST } GTokenType; </programlisting> <para> The possible types of token returned from each <link linkend="g-scanner-get-next-token"><function>g_scanner_get_next_token()</function></link> call. </para><variablelist role="enum"> <varlistentry> <term><literal>G_TOKEN_EOF</literal></term> <listitem><simpara>the end of the file. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_TOKEN_LEFT_PAREN</literal></term> <listitem><simpara>a '(' character. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_TOKEN_LEFT_CURLY</literal></term> <listitem><simpara>a '{' character. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_TOKEN_RIGHT_CURLY</literal></term> <listitem><simpara>a '}' character. </simpara></listitem> </varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="GTokenValue"/>union GTokenValue</title> <indexterm><primary>GTokenValue</primary></indexterm><programlisting>union GTokenValue { gpointer v_symbol; gchar *v_identifier; gulong v_binary; gulong v_octal; gulong v_int; guint64 v_int64; gdouble v_float; gulong v_hex; gchar *v_string; gchar *v_comment; guchar v_char; guint v_error; }; </programlisting> <para> A union holding the value of the token. </para></refsect2> <refsect2> <title><anchor id="GErrorType"/>enum GErrorType</title> <indexterm><primary>GErrorType</primary></indexterm><programlisting>typedef enum { G_ERR_UNKNOWN, G_ERR_UNEXP_EOF, G_ERR_UNEXP_EOF_IN_STRING, G_ERR_UNEXP_EOF_IN_COMMENT, G_ERR_NON_DIGIT_IN_CONST, G_ERR_DIGIT_RADIX, G_ERR_FLOAT_RADIX, G_ERR_FLOAT_MALFORMED } GErrorType; </programlisting> <para> The possible errors, used in the <structfield>v_error</structfield> field of <link linkend="GTokenValue"><type>GTokenValue</type></link>, when the token is a <link linkend="G-TOKEN-ERROR-CAPS"><type>G_TOKEN_ERROR</type></link>. </para><variablelist role="enum"> <varlistentry> <term><literal>G_ERR_UNKNOWN</literal></term> <listitem><simpara>unknown error. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_UNEXP_EOF</literal></term> <listitem><simpara>unexpected end of file. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_UNEXP_EOF_IN_STRING</literal></term> <listitem><simpara>unterminated string constant. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_UNEXP_EOF_IN_COMMENT</literal></term> <listitem><simpara>unterminated comment. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_NON_DIGIT_IN_CONST</literal></term> <listitem><simpara>non-digit character in a number. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_DIGIT_RADIX</literal></term> <listitem><simpara>digit beyond radix in a number. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_FLOAT_RADIX</literal></term> <listitem><simpara>non-decimal floating point number. </simpara></listitem> </varlistentry> <varlistentry> <term><literal>G_ERR_FLOAT_MALFORMED</literal></term> <listitem><simpara>malformed floating point number. </simpara></listitem> </varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="G-CSET-a-2-z"/>G_CSET_a_2_z</title> <indexterm><primary>G_CSET_a_2_z</primary></indexterm><programlisting>#define G_CSET_a_2_z "abcdefghijklmnopqrstuvwxyz" </programlisting> <para> The set of lowercase ASCII alphabet characters. Used for specifying valid identifier characters in <link linkend="GScannerConfig"><type>GScannerConfig</type></link>. </para></refsect2> <refsect2> <title><anchor id="G-CSET-A-2-Z-CAPS"/>G_CSET_A_2_Z</title> <indexterm><primary>G_CSET_A_2_Z</primary></indexterm><programlisting>#define G_CSET_A_2_Z "ABCDEFGHIJKLMNOPQRSTUVWXYZ" </programlisting> <para> The set of uppercase ASCII alphabet characters. Used for specifying valid identifier characters in <link linkend="GScannerConfig"><type>GScannerConfig</type></link>. </para></refsect2> <refsect2> <title><anchor id="G-CSET-DIGITS-CAPS"/>G_CSET_DIGITS</title> <indexterm><primary>G_CSET_DIGITS</primary></indexterm><programlisting>#define G_CSET_DIGITS "0123456789" </programlisting> <para> The set of digits. Used for specifying valid identifier characters in <link linkend="GScannerConfig"><type>GScannerConfig</type></link>. </para></refsect2> <refsect2> <title><anchor id="G-CSET-LATINC-CAPS"/>G_CSET_LATINC</title> <indexterm><primary>G_CSET_LATINC</primary></indexterm><programlisting>#define G_CSET_LATINC</programlisting> <para> The set of uppercase ISO 8859-1 alphabet characters which are not ASCII characters. Used for specifying valid identifier characters in <link linkend="GScannerConfig"><type>GScannerConfig</type></link>. </para></refsect2> <refsect2> <title><anchor id="G-CSET-LATINS-CAPS"/>G_CSET_LATINS</title> <indexterm><primary>G_CSET_LATINS</primary></indexterm><programlisting>#define G_CSET_LATINS</programlisting> <para> The set of lowercase ISO 8859-1 alphabet characters which are not ASCII characters. Used for specifying valid identifier characters in <link linkend="GScannerConfig"><type>GScannerConfig</type></link>. </para></refsect2> <refsect2> <title><anchor id="g-scanner-add-symbol"/>g_scanner_add_symbol()</title> <indexterm role="deprecated"><primary>g_scanner_add_symbol</primary></indexterm><programlisting>#define g_scanner_add_symbol( scanner, symbol, value )</programlisting> <warning><para><literal>g_scanner_add_symbol</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-scanner-scope-add-symbol"><function>g_scanner_scope_add_symbol()</function></link> instead.</para></warning> <para> Adds a symbol to the default scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to add. </simpara></listitem></varlistentry> <varlistentry><term><parameter>value</parameter> :</term> <listitem><simpara>the value of the symbol. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-remove-symbol"/>g_scanner_remove_symbol()</title> <indexterm role="deprecated"><primary>g_scanner_remove_symbol</primary></indexterm><programlisting>#define g_scanner_remove_symbol( scanner, symbol )</programlisting> <warning><para><literal>g_scanner_remove_symbol</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-scanner-scope-remove-symbol"><function>g_scanner_scope_remove_symbol()</function></link> instead.</para></warning> <para> Removes a symbol from the default scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>symbol</parameter> :</term> <listitem><simpara>the symbol to remove. </simpara></listitem></varlistentry> </variablelist></refsect2> <refsect2> <title><anchor id="g-scanner-foreach-symbol"/>g_scanner_foreach_symbol()</title> <indexterm role="deprecated"><primary>g_scanner_foreach_symbol</primary></indexterm><programlisting>#define g_scanner_foreach_symbol( scanner, func, data )</programlisting> <warning><para><literal>g_scanner_foreach_symbol</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-scanner-scope-foreach-symbol"><function>g_scanner_scope_foreach_symbol()</function></link> instead.</para></warning> <para> Calls a function for each symbol in the default scope. </para><variablelist role="params"> <varlistentry><term><parameter>scanner</parameter> :</term> <listitem><simpara>a <link linkend="GScanner"><type>GScanner</type></link>. </simpara></listitem></varlistentry> <varlistentry><term><parameter>func</parameter> :</term> <listitem><simpara>the function to call with each symbol. </simpara></listitem></varlistentry> <varlistentry><term><parameter>data</parameter> :</term> <listitem><simpara>data to pass to the function. </simpara></listitem></varlistentry> </variablelist></refsect2> </refsect1> </refentry>