| |
![]() |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#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
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; кое-что неправильно в содержимом документе, например недопустимое значение атрибута |
#define G_MARKUP_ERROR g_markup_error_quark ()
Домен ошибки для анализатора разметки. Ошибки в этом домене будут из перечисления GMarkupError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0, G_MARKUP_TREAT_CDATA_AS_TEXT = 1 << 1 } GMarkupParseFlags;
Флаги которые влияют на поведение анализатора.
typedef struct _GMarkupParseContext GMarkupParseContext;
Контекст анализатора используемый для анализа потока байт которые вы ожидаете в содержимом размеченного текста.
Смотрите g_markup_parse_context_new()
,
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-функция вызываемая когда происходит ошибка. |
gchar* g_markup_escape_text (const gchar *text, gssize length);
Ограничивает текст так чтобы анализатор разметки анализировал его дословно. Меньше чем, больше чем, амперсанд и т.д. заменяются соответствующими объектами. Эта функция обычно используется когда записываемый вывод файла должен быть проанализирован анализатором разметки.
Помните что эта функция не защищает пробелы и конец строк от обработки согласно правилам XML для нормализации концов строк и значений атрибутов.
text : |
некоторый текст в UTF-8 |
length : |
длина text в байтах, или -1 если текст nul-завершённый
|
Возвращает : | вновь распределённая строка с ограниченным текстом (escaped text) |
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
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
gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, GError **error);
Сигнализирует GMarkupParseContext
что все данные были предоставлены в анализируемый контекст с помощью
g_markup_parse_context_parse()
.
Эта функция сообщает об ошибке если документ неполон, например если есть открытые элементы.
context : |
GMarkupParseContext |
error : |
расположение возвращаемой GError |
Возвращает : | TRUE при успешном выполнении,
FALSE если была установлена ошибка
|
void g_markup_parse_context_free (GMarkupParseContext *context);
Освобождает GMarkupParseContext. Может быть вызвана из функций GMarkupParser.
context : |
GMarkupParseContext |
void g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number);
Находит текущий номер строки и количество символов в этой строке. Предназначена для использования с сообщениями об ошибках; нет определённой семантики составляющей "текущий" номер строки, кроме "лучший номер который мы смогли придумать для сообщения об ошибке".
context : |
GMarkupParseContext |
line_number : |
расположение для возвращаемого номера строки,
или NULL
|
char_number : |
расположение для возвращаемого количества символов в строке,
или NULL
|
const gchar* g_markup_parse_context_get_element (GMarkupParseContext *context);
Находит имя текущего открытого элемента.
context : |
GMarkupParseContext |
Возвращает : | имя текущего открытого элемента, или NULL
|
Начиная с версии 2.2
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 |
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 при успешном выполнении
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |