:right-sidebar: True Scanner =================================================================== .. currentmodule:: gi.repository.GLib .. class:: Scanner(*args, **kwargs) :no-contents-entry: ``GScanner`` provides a general-purpose 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 filename 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 :obj:`~gi.repository.GLib.ScannerMsgFunc`\. Methods ------- .. rst-class:: interim-class .. class:: Scanner :no-index: .. method:: cur_line() -> int Returns the current line in the input stream (counting from 1). This is the line of the last token parsed via :func:`~gi.repository.GLib.Scanner.get_next_token`. .. method:: cur_position() -> int Returns the current position in the current line (counting from 0). This is the position of the last token parsed via :func:`~gi.repository.GLib.Scanner.get_next_token`. .. method:: cur_token() -> ~gi.repository.GLib.TokenType Gets the current token type. This is simply the ``token`` field in the :obj:`~gi.repository.GLib.Scanner` structure. .. method:: destroy() -> None Frees all memory used by the :obj:`~gi.repository.GLib.Scanner`\. .. method:: eof() -> bool Returns :const:`True` if the scanner has reached the end of the file or text buffer. .. method:: get_next_token() -> ~gi.repository.GLib.TokenType Parses the next token just like :func:`~gi.repository.GLib.Scanner.peek_next_token` and also removes it from the input stream. The token data is placed in the ``token``\, ``value``\, ``line``\, and ``position`` fields of the :obj:`~gi.repository.GLib.Scanner` structure. .. method:: input_file(input_fd: int) -> None Prepares to scan a file. :param input_fd: a file descriptor .. method:: input_text(text: str, text_len: int) -> None Prepares to scan a text buffer. :param text: the text buffer to scan :param text_len: the length of the text buffer .. method:: lookup_symbol(symbol: str) -> ~typing.Any | None Looks up a symbol in the current scope and return its value. If the symbol is not bound in the current scope, :const:`None` is returned. :param symbol: the symbol to look up .. method:: peek_next_token() -> ~gi.repository.GLib.TokenType Parses 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 :obj:`~gi.repository.GLib.Scanner` structure. Note that, while the token is not removed from the input stream (i.e. the next call to :func:`~gi.repository.GLib.Scanner.get_next_token` will return the same token), it will not be reevaluated. This can lead to surprising results when changing scope or the scanner configuration after peeking the next token. Getting the next token after switching the scope or configuration will return whatever was peeked before, regardless of any symbols that may have been added or removed in the new scope. .. method:: scope_add_symbol(scope_id: int, symbol: str, value: ~typing.Any = None) -> None Adds a symbol to the given scope. :param scope_id: the scope id :param symbol: the symbol to add :param value: the value of the symbol .. method:: scope_foreach_symbol(scope_id: int, func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], None], user_data: ~typing.Any = None) -> None Calls the given function for each of the symbol/value pairs in the given scope of the :obj:`~gi.repository.GLib.Scanner`\. The function is passed the symbol and value of each pair, and the given ``user_data`` parameter. :param scope_id: the scope id :param func: the function to call for each symbol/value pair :param user_data: user data to pass to the function .. method:: scope_lookup_symbol(scope_id: int, symbol: str) -> ~typing.Any | None Looks up a symbol in a scope and return its value. If the symbol is not bound in the scope, :const:`None` is returned. :param scope_id: the scope id :param symbol: the symbol to look up .. method:: scope_remove_symbol(scope_id: int, symbol: str) -> None Removes a symbol from a scope. :param scope_id: the scope id :param symbol: the symbol to remove .. method:: set_scope(scope_id: int) -> int Sets the current scope. :param scope_id: the new scope id .. method:: sync_file_offset() -> None 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. .. method:: unexp_token(expected_token: ~gi.repository.GLib.TokenType, identifier_spec: str, symbol_spec: str, symbol_name: str, message: str, is_error: int) -> None Outputs a message through the scanner's msg_handler, resulting from an unexpected token in the input stream. Note that you should not call :func:`~gi.repository.GLib.Scanner.peek_next_token` followed by :func:`~gi.repository.GLib.Scanner.unexp_token` without an intermediate call to :func:`~gi.repository.GLib.Scanner.get_next_token`, as :func:`~gi.repository.GLib.Scanner.unexp_token` evaluates the scanner's current token (not the peeked token) to construct part of the message. :param expected_token: the expected token :param identifier_spec: a string describing how the scanner's user refers to identifiers (:const:`None` defaults to "identifier"). This is used if ``expected_token`` is :const:`~gi.repository.GLib.TokenType.IDENTIFIER` or :const:`~gi.repository.GLib.TokenType.IDENTIFIER_NULL`. :param symbol_spec: a string describing how the scanner's user refers to symbols (:const:`None` defaults to "symbol"). This is used if ``expected_token`` is :const:`~gi.repository.GLib.TokenType.SYMBOL` or any token value greater than %G_TOKEN_LAST. :param symbol_name: the name of the symbol, if the scanner's current token is a symbol. :param message: a message string to output at the end of the warning/error, or :const:`None`. :param is_error: if :const:`True` it is output as an error. If :const:`False` it is output as a warning. Fields ------ .. rst-class:: interim-class .. class:: Scanner :no-index: .. attribute:: buffer .. attribute:: config Link into the scanner configuration .. attribute:: input_fd .. attribute:: input_name Name of input stream, featured by the default message handler .. attribute:: line Line number of the last token from :func:`~gi.repository.GLib.Scanner.get_next_token` .. attribute:: max_parse_errors Unused .. attribute:: msg_handler Handler function for _warn and _error .. attribute:: next_line Line number of the last token from :func:`~gi.repository.GLib.Scanner.peek_next_token` .. attribute:: next_position Char number of the last token from :func:`~gi.repository.GLib.Scanner.peek_next_token` .. attribute:: next_token Token parsed by the last :func:`~gi.repository.GLib.Scanner.peek_next_token` .. attribute:: next_value Value of the last token from :func:`~gi.repository.GLib.Scanner.peek_next_token` .. attribute:: parse_errors :func:`~gi.repository.GLib.Scanner.error` increments this field .. attribute:: position Char number of the last token from :func:`~gi.repository.GLib.Scanner.get_next_token` .. attribute:: qdata Quarked data .. attribute:: scope_id .. attribute:: symbol_table .. attribute:: text .. attribute:: text_end .. attribute:: token Token parsed by the last :func:`~gi.repository.GLib.Scanner.get_next_token` .. attribute:: user_data Unused .. attribute:: value Value of the last token from :func:`~gi.repository.GLib.Scanner.get_next_token`