The OpenNET Project / Index page

[ новости /+++ | форум | wiki | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

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 спецификация



Спонсоры:
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2021 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру