Simple XML Subset Parser

Simple XML Subset Parser — Синтаксический анализатор подмножества XML.

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

#include <glib.h> enum GMarkupError; #define G_MARKUP_ERROR enum GMarkupParseFlags; GMarkupParseContext; GMarkupParser; gchar* g_markup_escape_text (const gchar *text, gssize length); gchar* g_markup_printf_escaped (const char *format, ...); gchar* g_markup_vprintf_escaped (const char *format, va_list args); gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, GError **error); void g_markup_parse_context_free (GMarkupParseContext *context); void g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number); const gchar* g_markup_parse_context_get_element (GMarkupParseContext *context); GMarkupParseContext* g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify); gboolean g_markup_parse_context_parse (GMarkupParseContext *context, const gchar *text, gssize text_len, GError **error);

Описание

Анализатор "GMarkup" предназначен для анализа простого формата разметки подмножества XML. Это небольшой, эффективный, лёгкий в использовании анализатор. Он не должен использоваться если вы хотите интегрироваться с другими приложениями генерирующими полномасштабный XML. Однако, он очень полезен для файлов данных программы, конфигурационных файлов и т.д. где вы знаете что ваше приложение будет единственным пишущим в файл. Полномасштабные анализаторы XML должны быть в состоянии анализировать подмножество используемое GMarkup, поэтому вы сможете легко перейти к полномасштабному анализатору позже, если возникнет необходимость.

GMarkup не гарантирует сигнал об ошибке на любом недопустимом XML; анализатор может принять документ XML который не будет проанализирован. Однако, XML документы которые не в формате[4] рассматриваются как недопустимые документы GMarkup.

Упращение XML включает:

  • Допускается только кодировка UTF-8.

  • Нет объектов определяемых пользователем.

  • Инструкции выполнения, комментарии и doctype объявления "проходят" но никогда не интерпретируются.

  • Нет DTD или проверки правильности.

Форматированная разметка поддерживает:

  • Элементы

  • Атрибуты

  • 5 стандартных объектов: &amp; &lt; &gt; &quot; &apos;

  • Символьные ссылки

  • Разделы помеченные как CDATA

Детали

enum GMarkupError

typedef enum { G_MARKUP_ERROR_BAD_UTF8, G_MARKUP_ERROR_EMPTY, G_MARKUP_ERROR_PARSE, /* These three are primarily intended for specific GMarkupParser * implementations to set. */ G_MARKUP_ERROR_UNKNOWN_ELEMENT, G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, G_MARKUP_ERROR_INVALID_CONTENT } GMarkupError;

Коды ошибок возвращаемые анализатором разметки.

G_MARKUP_ERROR_BAD_UTF8 анализируемый текст не был в допустимой UTF-8
G_MARKUP_ERROR_EMPTY документ пустой, или содержит только пробелы
G_MARKUP_ERROR_PARSE документ был плохо сформирован
G_MARKUP_ERROR_UNKNOWN_ELEMENT ошибка устанавливается функциями GMarkupParser; неизвестный элемент
G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE ошибка устанавливаться функциями GMarkupParser; неизвестный атрибут
G_MARKUP_ERROR_INVALID_CONTENT ошибка устанавливается функциями GMarkupParser; кое-что неправильно в содержимом документе, например недопустимое значение атрибута

G_MARKUP_ERROR

#define G_MARKUP_ERROR g_markup_error_quark ()

Домен ошибки для анализатора разметки. Ошибки в этом домене будут из перечисления GMarkupError. Смотрите GError для информации о доменах ошибки.


enum GMarkupParseFlags

typedef enum { G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0, G_MARKUP_TREAT_CDATA_AS_TEXT = 1 << 1 } GMarkupParseFlags;

Флаги которые влияют на поведение анализатора.

G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG вы не должны использовать флаг.
G_MARKUP_TREAT_CDATA_AS_TEXT Когда этот флаг установлен, разделы помеченные как CDATA не помещаются буквально в функцию passthrough анализатора. Вместо этого, содержимое раздела (без <![CDATA[ и ]]>) помещается в функцию text. Этот флаг добавлен в версии GLib 2.12.

GMarkupParseContext

typedef struct _GMarkupParseContext GMarkupParseContext;

Контекст анализатора используемый для анализа потока байт которые вы ожидаете в содержимом размеченного текста. Смотрите g_markup_parse_context_new(), GMarkupParser и так далее, для получения подробностей.


GMarkupParser

typedef struct { /* Вызов для открывающего тега <foo bar="baz"> */ void (*start_element) (GMarkupParseContext *context, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error); /* Вызов для закрывающего тега </foo> */ void (*end_element) (GMarkupParseContext *context, const gchar *element_name, gpointer user_data, GError **error); /* Вызов для символьных данных */ /* текст не nul-завершённый */ void (*text) (GMarkupParseContext *context, const gchar *text, gsize text_len, gpointer user_data, GError **error); /* Вызов для строк которые должны быть повторно сохранены дословно * в том же самом месте, но не являются иначе истолкованными. * В настоящий момент это включает комментарии и исполняемые инструкции. */ /* текст не nul-завершённый. */ void (*passthrough) (GMarkupParseContext *context, const gchar *passthrough_text, gsize text_len, gpointer user_data, GError **error); /* Вызов ошибки, включая один из методов установленный в vtable. * GError не должна освобождаться. */ void (*error) (GMarkupParseContext *context, GError *error, gpointer user_data); } GMarkupParser;

Любые поля в GMarkupParser могут быть NULL, в этом случае они будут игнорироваться. За исключением error функции, любые callback-функции могут установить; особенно ошибки G_MARKUP_ERROR_UNKNOWN_ELEMENT, G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, и G_MARKUP_ERROR_INVALID_CONTENT предназначены для установки из этих callback-функций. Если вы установили ошибку из callback-функции, g_markup_parse_context_parse() сообщит что ошибка вернулась в вызывающую программу.

start_element () Callback-функция вызываемая при обнаружении элемента открывающего тега.
end_element () Callback-функция вызываемая при обнаружении элемента закрывающего тега. Помните что она также вызывается для пустых тегов, например <empty/>.
text () Callback-функция вызываемая при обнаружении некоторого текста (текст всегда находится внутри элементов). Помните что текст элемента может распространяться на множество вызовов этой функции. Если установлен флаг G_MARKUP_TREAT_CDATA_AS_TEXT, эта функция также вызывается для содержимого раздела помеченного как CDATA.
passthrough () Callback-функция вызываемая для комментариев, исполняемых инструкций и doctype деклараций; если вы перезаписываете анализируемый документ, текст записывается в туже самую позицию. Если установлен флаг G_MARKUP_TREAT_CDATA_AS_TEXT, эта функция также вызывается для раздела помеченного как CDATA.
error () Callback-функция вызываемая когда происходит ошибка.

g_markup_escape_text ()

gchar* g_markup_escape_text (const gchar *text, gssize length);

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

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

text : некоторый текст в UTF-8
length : длина text в байтах, или -1 если текст nul-завершённый
Возвращает : вновь распределённая строка с ограниченным текстом (escaped text)

g_markup_printf_escaped ()

gchar* g_markup_printf_escaped (const char *format, ...);

Форматирует аргументы согласно format, ограничивает всю строку и символьные аргументы в стиле g_markup_escape_text(). Это полезно когда вам нужно вставить буквенную строку в вывод в стиле XML, не беспокоясь о том, что строки могут иметь собственную разметку.

const char *store = "Fortnum & Mason"; const char *item = "Tea"; char *output;   output = g_markup_printf_escaped ("<purchase>" "<store>%s</store>" "<item>%s</item>" "</purchase>", store, item);

format : строка формата в стиле printf()
... : аргументы для вставки в строку формата
Возвращает : Вновь распределённый результат операции форматирвания. Освобождается с помощью g_free().

Начиная с версии 2.4


g_markup_vprintf_escaped ()

gchar* g_markup_vprintf_escaped (const char *format, va_list args);

Форматирует данные в args согласно format, ограничивает все строки и символьные аргументы в стиле g_markup_escape_text(). Смотрите g_markup_printf_escaped().

format : строка формата в стиле printf()
args : список аргументов переменных, подобных vprintf()
Возвращает : Вновь распределённый результат операции фоматирования. Освобождается с помощью g_free().

Начиная с версии 2.4


g_markup_parse_context_end_parse ()

gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, GError **error);

Сигнализирует GMarkupParseContext что все данные были предоставлены в анализируемый контекст с помощью g_markup_parse_context_parse(). Эта функция сообщает об ошибке если документ неполон, например если есть открытые элементы.

context : GMarkupParseContext
error : расположение возвращаемой GError
Возвращает : TRUE при успешном выполнении, FALSE если была установлена ошибка

g_markup_parse_context_free ()

void g_markup_parse_context_free (GMarkupParseContext *context);

Освобождает GMarkupParseContext. Может быть вызвана из функций GMarkupParser.

context : GMarkupParseContext

g_markup_parse_context_get_position ()

void g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number);

Находит текущий номер строки и количество символов в этой строке. Предназначена для использования с сообщениями об ошибках; нет определённой семантики составляющей "текущий" номер строки, кроме "лучший номер который мы смогли придумать для сообщения об ошибке".

context : GMarkupParseContext
line_number : расположение для возвращаемого номера строки, или NULL
char_number : расположение для возвращаемого количества символов в строке, или NULL

g_markup_parse_context_get_element ()

const gchar* g_markup_parse_context_get_element (GMarkupParseContext *context);

Находит имя текущего открытого элемента.

context : GMarkupParseContext
Возвращает : имя текущего открытого элемента, или NULL

Начиная с версии 2.2


g_markup_parse_context_new ()

GMarkupParseContext* g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify);

Создаёт новый анализатор контекста. Анализатор контекста используется для анализа размеченных документов. Вы можете направить любое количество документов в контекст, пока не произойдёт ошибка; как только происходит ошибка, анализатор контекста не сможет продолжать анализ текста (вы должны освободить его и создать новый анализатор контекста).

parser : GMarkupParser
flags : один или больше GMarkupParseFlags
user_data : пользовательские данные помещаемые в функции GMarkupParser
user_data_dnotify : пользовательские данные разрушающего уведомления вызываемого когда анализатор контекста освобождён
Возвращает : новый GMarkupParseContext

g_markup_parse_context_parse ()

gboolean g_markup_parse_context_parse (GMarkupParseContext *context, const gchar *text, gssize text_len, GError **error);

Заполняет некоторые данные в GMarkupParseContext. Данные не должны быть в допустимой UTF-8; будет сообщено об ошибке если они будут недопустимы. Данные не должны быть полным документом; вы можете подавать документ в анализатор инкрементно, через множество вызовов этой функции. Обычно, поскольку вы получаете данные через сетевое подключение или файл, вы направляете каждую полученную часть данных в эту функцию, прерывая процесс если происходит ошибка. Как только происходит ошибка, никакие данные больше не могут быть направлены в GMarkupParseContext; все ошибки фатальны.

context : GMarkupParseContext
text : часть анализируемого текста
text_len : длина text в байтах
error : расположение для возвращаемой GError
Возвращает : FALSE если произошла ошибка, TRUE при успешном выполнении


[4] XML спецификация