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 стандартных объектов: & < > " '
Символьные ссылки
Разделы помеченные как 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 спецификация

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