1 /* markup.h -- simple XML-like string parser
2 Copyright (C) 2015 Free Software Foundation, Inc.
3
4 This file is not part of the GNU gettext program, but is used with
5 GNU gettext.
6
7 This is a stripped down version of GLib's gmarkup.h. The original
8 copyright notice is as follows:
9 */
10
11 /* gmarkup.h - Simple XML-like string parser/writer
12 *
13 * Copyright 2000 Red Hat, Inc.
14 *
15 * GLib is free software; you can redistribute it and/or modify it
16 * under the terms of the GNU General Public License as
17 * published by the Free Software Foundation; either version 3 of the
18 * License, or (at your option) any later version.
19 *
20 * GLib is distributed in the hope that it will be useful,
21 * but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 * General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public
26 * License along with GLib; see the file COPYING.LIB. If not,
27 * see <https://www.gnu.org/licenses/>.
28 */
29
30 #ifndef __MARKUP_H__
31 #define __MARKUP_H__ 1
32
33 #ifdef __cplusplus
34 extern "C" {
35 #endif
36
37 #include <stdbool.h>
38 #include <stddef.h>
39 #include <sys/types.h>
40
41 /**
42 * markup_parse_flags_ty:
43 * @MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use
44 * @MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked
45 * sections are not passed literally to the @passthrough function of
46 * the parser. Instead, the content of the section (without the
47 * `<![CDATA[` and `]]>`) is
48 * passed to the @text function. This flag was added in GLib 2.12
49 * @MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup
50 * itself have line/column information prefixed to them to let the
51 * caller know the location of the error. When this flag is set the
52 * location information is also prefixed to errors generated by the
53 * #GMarkupParser implementation functions
54 * @MARKUP_IGNORE_QUALIFIED: Ignore (don't report) qualified
55 * attributes and tags, along with their contents. A qualified
56 * attribute or tag is one that contains ':' in its name (ie: is in
57 * another namespace). Since: 2.40.
58 *
59 * Flags that affect the behaviour of the parser.
60 */
61 typedef enum
62 {
63 MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0,
64 MARKUP_TREAT_CDATA_AS_TEXT = 1 << 1,
65 MARKUP_PREFIX_ERROR_POSITION = 1 << 2,
66 MARKUP_IGNORE_QUALIFIED = 1 << 3
67 } markup_parse_flags_ty;
68
69 /**
70 * markup_parse_context_ty:
71 *
72 * A parse context is used to parse a stream of bytes that
73 * you expect to contain marked-up text.
74 *
75 * See markup_parse_context_new(), #markup_parser_ty, and so
76 * on for more details.
77 */
78 typedef struct _markup_parse_context_ty markup_parse_context_ty;
79 typedef struct _markup_parser_ty markup_parser_ty;
80
81 /**
82 * markup_parser_ty:
83 * @start_element: Callback to invoke when the opening tag of an element
84 * is seen. The callback's @attribute_names and @attribute_values parameters
85 * are %NULL-terminated.
86 * @end_element: Callback to invoke when the closing tag of an element
87 * is seen. Note that this is also called for empty tags like
88 * `<empty/>`.
89 * @text: Callback to invoke when some text is seen (text is always
90 * inside an element). Note that the text of an element may be spread
91 * over multiple calls of this function. If the
92 * %MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also
93 * called for the content of CDATA marked sections.
94 * @passthrough: Callback to invoke for comments, processing instructions
95 * and doctype declarations; if you're re-writing the parsed document,
96 * write the passthrough text back out in the same position. If the
97 * %MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also
98 * called for CDATA marked sections.
99 * @error: Callback to invoke when an error occurs.
100 *
101 * Any of the fields in #markup_parser_ty can be %NULL, in which case they
102 * will be ignored. Except for the @error function, any of these callbacks
103 * can set an error; in particular the %MARKUP_ERROR_UNKNOWN_ELEMENT,
104 * %MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %MARKUP_ERROR_INVALID_CONTENT
105 * errors are intended to be set from these callbacks. If you set an error
106 * from a callback, markup_parse_context_parse() will report that error
107 * back to its caller.
108 */
109 struct _markup_parser_ty
110 {
111 /* Called for open tags <foo bar="baz"> */
112 bool (*start_element) (markup_parse_context_ty *context,
113 const char *element_name,
114 const char **attribute_names,
115 const char **attribute_values,
116 void *user_data);
117
118 /* Called for close tags </foo> */
119 bool (*end_element) (markup_parse_context_ty *context,
120 const char *element_name,
121 void *user_data);
122
123 /* Called for character data */
124 /* text is not nul-terminated */
125 bool (*text) (markup_parse_context_ty *context,
126 const char *text,
127 size_t text_len,
128 void *user_data);
129
130 /* Called for strings that should be re-saved verbatim in this same
131 * position, but are not otherwise interpretable. At the moment
132 * this includes comments and processing instructions.
133 */
134 /* text is not nul-terminated. */
135 bool (*passthrough) (markup_parse_context_ty *context,
136 const char *passthrough_text,
137 size_t text_len,
138 void *user_data);
139
140 /* Called on error, including one set by other
141 * methods in the vtable. The GError should not be freed.
142 */
143 void (*error) (markup_parse_context_ty *context,
144 const char *error_text,
145 void *user_data);
146 };
147
148 extern markup_parse_context_ty *
149 markup_parse_context_new (const markup_parser_ty *parser,
150 markup_parse_flags_ty flags,
151 void *user_data);
152 extern void markup_parse_context_free (markup_parse_context_ty *context);
153 extern bool markup_parse_context_parse (markup_parse_context_ty *context,
154 const char *text,
155 ssize_t text_len);
156 extern bool markup_parse_context_end_parse (markup_parse_context_ty *context);
157 extern const char *
158 markup_parse_context_get_error (markup_parse_context_ty *context);
159
160 #ifdef __cplusplus
161 }
162 #endif
163
164 #endif /* __MARKUP_H__ */