Lexical Scanner

Lexical Scanner — универсальный лексический сканер.

Краткое описание



#include <glib.h>


            GScanner;
GScanner*   g_scanner_new                   (const GScannerConfig *config_templ);
            GScannerConfig;

void        g_scanner_input_file            (GScanner *scanner,
                                             gint input_fd);
void        g_scanner_sync_file_offset      (GScanner *scanner);
void        g_scanner_input_text            (GScanner *scanner,
                                             const gchar *text,
                                             guint text_len);
GTokenType  g_scanner_peek_next_token       (GScanner *scanner);
GTokenType  g_scanner_get_next_token        (GScanner *scanner);

guint       g_scanner_cur_line              (GScanner *scanner);
guint       g_scanner_cur_position          (GScanner *scanner);
GTokenType  g_scanner_cur_token             (GScanner *scanner);
GTokenValue g_scanner_cur_value             (GScanner *scanner);
gboolean    g_scanner_eof                   (GScanner *scanner);

guint       g_scanner_set_scope             (GScanner *scanner,
                                             guint scope_id);
void        g_scanner_scope_add_symbol      (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol,
                                             gpointer value);
void        g_scanner_scope_foreach_symbol  (GScanner *scanner,
                                             guint scope_id,
                                             GHFunc func,
                                             gpointer user_data);
gpointer    g_scanner_scope_lookup_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);
void        g_scanner_scope_remove_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

#define     g_scanner_freeze_symbol_table   (scanner)
#define     g_scanner_thaw_symbol_table     (scanner)
gpointer    g_scanner_lookup_symbol         (GScanner *scanner,
                                             const gchar *symbol);

void        g_scanner_warn                  (GScanner *scanner,
                                             const gchar *format,
                                             ...);
void        g_scanner_error                 (GScanner *scanner,
                                             const gchar *format,
                                             ...);
void        g_scanner_unexp_token           (GScanner *scanner,
                                             GTokenType expected_token,
                                             const gchar *identifier_spec,
                                             const gchar *symbol_spec,
                                             const gchar *symbol_name,
                                             const gchar *message,
                                             gint is_error);
void        (*GScannerMsgFunc)              (GScanner *scanner,
                                             gchar *message,
                                             gboolean error);

void        g_scanner_destroy               (GScanner *scanner);

enum        GTokenType;
union       GTokenValue;
enum        GErrorType;
#define     G_CSET_a_2_z
#define     G_CSET_A_2_Z
#define     G_CSET_DIGITS
#define     G_CSET_LATINC
#define     G_CSET_LATINS

#define     g_scanner_add_symbol            ( scanner, symbol, value )
#define     g_scanner_remove_symbol         ( scanner, symbol )
#define     g_scanner_foreach_symbol        ( scanner, func, data )

Описание

GScanner и связанные с ней функции обеспечивают универсальный лексический сканер.

Детали

GScanner

typedef struct {
  /* неиспользуемые поля */
  gpointer		user_data;
  guint			max_parse_errors;
  
  /* g_scanner_error() инкрементирует это поле */
  guint			parse_errors;
  
  /* имя входного потока, показываемое обработчиком сообщения по умолчанию */
  const gchar		*input_name;
  
  /* quarked data */
  GData			*qdata;
  
  /* ссылка на конфигурацию сканера */
  GScannerConfig	*config;
  
  /* поля заполняемые после g_scanner_get_next_token() */
  GTokenType		token;
  GTokenValue		value;
  guint			line;
  guint			position;
  
  /* поля заполняемые после g_scanner_peek_next_token() */
  GTokenType		next_token;
  GTokenValue		next_value;
  guint			next_line;
  guint			next_position;
  
  /* рассматриваются как закрытые */
  GHashTable		*symbol_table;
  gint			input_fd;
  const gchar		*text;
  const gchar		*text_end;
  gchar			*buffer;
  guint			scope_id;
  
  /* функция обработчик для _warn и _error */
  GScannerMsgFunc	msg_handler;
} GScanner;

Структура данных представляющая лексический сканер.

Вы должны установить input_name после создания сканера, та как оно используется обработчиком сообщений по умолчанию когда отображаются предупреждения и ошибки Если вы сканируете файл, имя файла будет хорошим выбором для этого.

Поля user_data и max_parse_errors неиспользуются. Если вам нужно связать дополнительные данные со сканером вы можете поместить их сюда.

Если вам нужно использовать собственный обработчик сообщений вы можете установить его в поле msg_handler. Тип функции обработки сообщений определяет GScannerMsgFunc.

g_scanner_new ()

GScanner* g_scanner_new (const GScannerConfig *config_templ);

Создаёт новую GScanner. Структура config_templ определяет начальные установки сканера, которые копируются в структуру GScanner поле config. Для использования настроек по умолчанию вы можете поместить NULL.

`config_templ` :	начальные настройки сканера.
Возвращает :	новая GScanner.

GScannerConfig

typedef struct {
  /* Наборы символов
   */
  gchar		*cset_skip_characters;		/* по умолчанию: " \t\n" */
  gchar		*cset_identifier_first;
  gchar		*cset_identifier_nth;
  gchar		*cpair_comment_single;		/* по умолчанию: "#\n" */
  
  /* Чувствителен ли поиск символа к регистру?
   */
  guint		case_sensitive : 1;
  
  /* Логическое значение для настройки "на лету"
   * конфигурации правил сканирования.
   */
  guint		skip_comment_multi : 1;		/* C подобный комментарий */
  guint		skip_comment_single : 1;	/* единственная строка комментария */
  guint		scan_comment_multi : 1;		/* сканировать множество строк коментария? */
  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;		/* возвращать G_TOKEN_CHAR? */
  guint		symbol_2_token : 1;
  guint		scope_0_fallback : 1;		/* позволить 0 контекст поиска? */
  guint		store_int64 : 1; 		/* использовать значение.v_int64 вместо v_int */
  guint		padding_dummy;
} GScannerConfig;

Определяет настройки GScanner.

cset_skip_characters определяет символы которые сканер должен пропускать (по умолчанию символы пробелов: пробел, табуляцию, перевод каретки и перевод строки).

cset_identifier_first определяет символы которые могут начинать идентификаторы (по умолчанию это G_CSET_a_2_z, "_", и G_CSET_A_2_Z).

cset_identifier_nth определяет символы которые могут использоваться в идентификаторах после первого символа (по умолчанию это G_CSET_a_2_z, "_0123456789", G_CSET_A_2_Z, G_CSET_LATINS, G_CSET_LATINC).

cpair_comment_single определяет символы начала и конца единственной строки коментария. По умолчанию это "#\n" который означает что единственная строка комментария начинается с '#' и продолжается до '\n' (конец строки).

case_sensitive определяет чувствительность символов к регистру (по умолчанию FALSE).

skip_comment_multi определяет пропускать ли многострочные комментарии и не возвращать как лексемы (по умолчанию TRUE).

skip_comment_single определяет пропускать ли однострочные комментарии и не возвращать как лексемы (по умолчанию TRUE).

scan_comment_multi определяет распознавать ли многострочные комментарии (по умолчанию TRUE).

scan_identifier определяет распознавать ли идентификатор (по умолчанию TRUE).

scan_identifier_1char определяет распознавать ли единственный символ идентификатора (по умолчанию FALSE).

scan_identifier_NULL определяет возвращать ли NULL как G_TOKEN_IDENTIFIER_NULL. (по умолчанию FALSE).

scan_symbols определяет распознавать ли символы (по умолчанию TRUE).

scan_binary определяет распознавать ли двоичные числа (по умолчанию FALSE).

scan_octal определяет распознавать ли восьмеричные числа (по умолчанию TRUE).

scan_float определяет распознавать ли числа с плавающей точкой (по умолчанию TRUE).

scan_hex определяет распознавать ли шестнадцатеричные числа (по умолчанию TRUE).

scan_hex_dollar определяет распознавать ли '$' как префикс для шестнадцатеричных чисел (по умолчанию FALSE).

scan_string_sq определяет заключена ли строка в одиночные кавычки (по умолчанию TRUE).

scan_string_dq определяет заключена ли строка в двойные кавычки (по умолчанию TRUE).

numbers_2_int определяет должны ли двоичные, восьмеричные и шестнадцатеричные числа передаваться как G_TOKEN_INT (по умолчанию TRUE).

int_2_float определяет передаются ли все числа как G_TOKEN_FLOAT (по умолчанию FALSE).

identifier_2_string определяет передаётся ли идентификатор как строка (по умолчанию FALSE).

char_2_token определяет передаются символы устанавливая token = ch или как G_TOKEN_CHAR (по умолчанию TRUE).

symbol_2_token определяет передаются ли символы установленными как token = v_symbol или как G_TOKEN_SYMBOL (по умолчанию FALSE).

scope_0_fallback определяет разыскивается ли символ для контекста по умолчанию в дополнение к текущему контексту (по умолчанию FALSE).

g_scanner_input_file ()

void        g_scanner_input_file            (GScanner *scanner,
                                             gint input_fd);

Подготавливает файл для сканирования.

`scanner` :	GScanner.
`input_fd` :	дискриптор файла.

g_scanner_sync_file_offset ()

void g_scanner_sync_file_offset (GScanner *scanner);

Перематывает файловый дескриптор в текущую позицию буфера и позволяет читать файл с начала буфера. Это полезно когда используется третичный сканер файлового дескриптора, который прикрепляется к текущей позиции сканера.

scanner : GScanner.

g_scanner_input_text ()

void        g_scanner_input_text            (GScanner *scanner,
                                             const gchar *text,
                                             guint text_len);

Подготавливает для сканирования текстовый буфер.

`scanner` :	GScanner.
`text` :	текстовый буфер для сканирования.
`text_len` :	длина текстового буфера.

g_scanner_peek_next_token ()

GTokenType g_scanner_peek_next_token (GScanner *scanner);

Получает следующую лексему, не удаляя её из потока ввода. Символьные данные помещаются в next_token, next_value, next_line, и next_position поля структуры GScanner.

Помните что пока лексема не удалена из входного потока (то есть следующий вызов g_scanner_get_next_token() будет возвращать туже лексему), она не будет переоценена. Это может привести к удивительным результатам когда изменяется контекст заглядывания за следующую лексему. Получение следующей лексемы после переключения контекста вернёт то что рассматривалось ранее, независимо от любых символов которые могут быть добавлены или удалены в новом контексте.

`scanner` :	GScanner.
Возвращает :	тип лексемы.

g_scanner_get_next_token ()

GTokenType g_scanner_get_next_token (GScanner *scanner);

Получает следующую лексему удаляя её из входного потока. Символьные данные помещаются в token, value, line, и position поля структуры GScanner.

`scanner` :	GScanner.
Возвращает :	тип лексемы.

g_scanner_cur_line ()

guint g_scanner_cur_line (GScanner *scanner);

Получает текущую строку во входном потоке (подсчёт начинается с 1).

`scanner` :	GScanner.
Возвращает :	текущая строка.

g_scanner_cur_position ()

guint g_scanner_cur_position (GScanner *scanner);

Получает текущую позицию в текущей строке (подсчёт начинается с 0).

`scanner` :	GScanner.
Возвращает :	текущая позиция в строке.

g_scanner_cur_token ()

GTokenType g_scanner_cur_token (GScanner *scanner);

Получает текущий тип лексемы. Это просто поле token в структуре GScanner.

`scanner` :	GScanner.
Возвращает :	текущий тип лексемы.

g_scanner_cur_value ()

GTokenValue g_scanner_cur_value (GScanner *scanner);

Получает текущее значение лексемы. Это просто поле value в структуре GScanner.

`scanner` :	GScanner.
Возвращает :	текущее значение лексемы.

g_scanner_eof ()

gboolean g_scanner_eof (GScanner *scanner);

Возвращает TRUE если сканер достиг конца файла или текстового буфера.

`scanner` :	GScanner.
Возвращает :	`TRUE` если сканер достиг конца файла или текстового буфера.

g_scanner_set_scope ()

guint       g_scanner_set_scope             (GScanner *scanner,
                                             guint scope_id);

Устанавливает текущий контекст.

`scanner` :	GScanner.
`scope_id` :	новый id контекста.
Возвращает :	старый id контекста.

g_scanner_scope_add_symbol ()

void        g_scanner_scope_add_symbol      (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol,
                                             gpointer value);

Добавляет символ в полученный контекст.

`scanner` :	GScanner.
`scope_id` :	id контектса.
`symbol` :	добавляемый символ.
`value` :	значение символа.

g_scanner_scope_foreach_symbol ()

void        g_scanner_scope_foreach_symbol  (GScanner *scanner,
                                             guint scope_id,
                                             GHFunc func,
                                             gpointer user_data);

Вызывает полученную функцию для каждой пары символ/значение в полученном контексте GScanner. Функция помещает символ и значение каждой пары и полученный параметр user_data.

`scanner` :	GScanner.
`scope_id` :	id контекста.
`func` :	функция вызываемая для каждой пары символ/значение.
`user_data` :	пользовательские данные помещаемые в функцию.

g_scanner_scope_lookup_symbol ()

gpointer    g_scanner_scope_lookup_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

Находит символ в контексте и возвращает его значение. Если символа нет в контексте, возвращает NULL.

`scanner` :	GScanner.
`scope_id` :	id контекста.
`symbol` :	разыскиваемый символ.
Возвращает :	значение `symbol` в полученном контексте, или `NULL` если `symbol` не находится в полученном контексте.

g_scanner_scope_remove_symbol ()

void        g_scanner_scope_remove_symbol   (GScanner *scanner,
                                             guint scope_id,
                                             const gchar *symbol);

Удаляет символ из контекста.

`scanner` :	GScanner.
`scope_id` :	id контекста.
`symbol` :	символ для удаления.

g_scanner_freeze_symbol_table()

#define g_scanner_freeze_symbol_table(scanner)

Внимание

g_scanner_freeze_symbol_table устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.

scanner : GScanner.

g_scanner_thaw_symbol_table()

#define g_scanner_thaw_symbol_table(scanner)

Внимание

g_scanner_thaw_symbol_table устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.

scanner : GScanner.

g_scanner_lookup_symbol ()

gpointer    g_scanner_lookup_symbol         (GScanner *scanner,
                                             const gchar *symbol);

Находит символ в текущем контексте и возвращает его значение. Если символ не находится в текущем контексте, то возвращает NULL.

`scanner` :	GScanner.
`symbol` :	символ для поиска.
Возвращает :	значение `symbol` в текущем контексте, или `NULL` если `symbol` не находится в текущем контексте.

g_scanner_warn ()

void        g_scanner_warn                  (GScanner *scanner,
                                             const gchar *format,
                                             ...);

Выводит предупреждающее сообщение через обработчик сообщений GScanner.

`scanner` :	GScanner.
`format` :	формат сообщения. Смотрите документацию для `printf()`.
`...` :	параметры вставляемые в строку формата.

g_scanner_error ()

void        g_scanner_error                 (GScanner *scanner,
                                             const gchar *format,
                                             ...);

Выводит сообщение об ошибке через обработчик сообщений GScanner.

`scanner` :	GScanner.
`format` :	формат сообщения. Смотрите документацию для `printf()`.
`...` :	параметры вставляемые в строку формата.

g_scanner_unexp_token ()

void        g_scanner_unexp_token           (GScanner *scanner,
                                             GTokenType expected_token,
                                             const gchar *identifier_spec,
                                             const gchar *symbol_spec,
                                             const gchar *symbol_name,
                                             const gchar *message,
                                             gint is_error);

Выводит сообщение через msg_handler сканера, реагируя на неожиданную лексему во входном потоке. Помните что вы не должны вызывать g_scanner_peek_next_token() сопровождаемый g_scanner_unexp_token() без промежуточного вызова g_scanner_get_next_token(), поскольку g_scanner_unexp_token() оценивает текущую лексему (не просматриваемую лексему) для создания части сообщения.

`scanner` :	GScanner.
`expected_token` :	ожидаемая лексема.
`identifier_spec` :	строка описывающая как пользователю сканера обращаться к идентификаторам (`NULL` для идентификатора по умолчанию). Это используется если `expected_token` равен G_TOKEN_IDENTIFIER или G_TOKEN_IDENTIFIER_NULL.
`symbol_spec` :	строка описывающая как пользователь сканера обращается к символам (`NULL` по умолчанию к "symbol"). Это используется если `expected_token` равен G_TOKEN_SYMBOL или какому нибудь символьному значению больше чем G_TOKEN_LAST.
`symbol_name` :	имя символа, если текущая сканируемая лексема является символом.
`message` :	строка сообщения выводимая в конце предупреждения/ошибки, или `NULL`.
`is_error` :	если `TRUE` выводится как ошибка. Если `FALSE` выводится как предупреждение.

GScannerMsgFunc ()

void        (*GScannerMsgFunc)              (GScanner *scanner,
                                             gchar *message,
                                             gboolean error);

Определяет тип функции обработчика сообщений.

`scanner` :	GScanner.
`message` :	сообщение.
`error` :	`TRUE` если сообщение означает ошибку, `FALSE` если оно обозначает предупреждение.

g_scanner_destroy ()

void g_scanner_destroy (GScanner *scanner);

Освобождает всю память используемую GScanner.

scanner : GScanner.

enum GTokenType

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;

Возможные типы лексем возвращаемые из каждого вызова g_scanner_get_next_token().

`G_TOKEN_EOF`	конец файла.
`G_TOKEN_LEFT_PAREN`	символ '('.
`G_TOKEN_LEFT_CURLY`	символ '{'.
`G_TOKEN_RIGHT_CURLY`	символ '}'.

union GTokenValue

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;
};

Объединение содержащее значения лексем.

enum GErrorType

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;

Возможные ошибки, используются в поле v_error GTokenValue, когда лексема равна G_TOKEN_ERROR.

`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`	некорректное число с плавающей точкой.

G_CSET_a_2_z

#define G_CSET_a_2_z	"abcdefghijklmnopqrstuvwxyz"

Набор алфавитных символов ASCII в нижнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.

G_CSET_A_2_Z

#define G_CSET_A_2_Z	"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Набор алфавитных символов ASCII в верхнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.

G_CSET_DIGITS

#define G_CSET_DIGITS	"0123456789"

Набор цифр. Используется для определения допустимых идентификаторов символов в GScannerConfig.

G_CSET_LATINC

#define G_CSET_LATINC

Набор алфавитных символов ISO 8859-1 в верхнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.

G_CSET_LATINS

#define G_CSET_LATINS

Набор алфавитных символов ISO 8859-1 в нижнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.

g_scanner_add_symbol()

#define g_scanner_add_symbol( scanner, symbol, value )

Внимание

g_scanner_add_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_add_symbol().

Добавляет символ к контексту по умолчанию.

`scanner` :	GScanner.
`symbol` :	добавляемый символ.
`value` :	значение символа.

g_scanner_remove_symbol()

#define g_scanner_remove_symbol( scanner, symbol )

Внимание

g_scanner_remove_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_remove_symbol().

Удаляет символ из контекста по умолчанию.

`scanner` :	GScanner.
`symbol` :	удаляемый символ.

g_scanner_foreach_symbol()

#define g_scanner_foreach_symbol( scanner, func, data )

Внимание

g_scanner_foreach_symbol устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_foreach_symbol().

Вызываемая функция для каждого символа в контексте по умолчанию.

`scanner` :	GScanner.
`func` :	функция вызываемая для каждого символа.
`data` :	данные помещаемые в функцию.

			Справочное описание GLib
Начало \| Описание