| | | BLib Reference Manual | |
|---|
BParser — an XML parser that offers a simplified SAX API
struct BParser; enum BParserState; BParserState (*BParserStartFunc) (BParserState state, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error); BParserState (*BParserEndFunc) (BParserState state, const gchar *element_name, const gchar *cdata, gsize cdata_len, gpointer user_data, GError **error); BParser* b_parser_new (BParserStartFunc start_element, BParserEndFunc end_element, gpointer user_data); void b_parser_free (BParser *parser); gboolean b_parser_parse (BParser *parser, const gchar *text, gssize text_len, GError **error); gboolean b_parser_end_parse (BParser *parser, GError **error); gboolean b_parser_parse_io_channel (BParser *parser, GIOChannel *io, gboolean recode, GError **error); BParserState b_parser_get_state (BParser *parser); gchar* b_parse_encoding (const gchar *text, gint text_len);
typedef enum
{
B_PARSER_STATE_UNKNOWN,
B_PARSER_STATE_TOPLEVEL,
B_PARSER_STATE_USER = 0x10 /* first user state, use as many as you need */
} BParserState;
An enumeration used to indicate the state of a BParser. Users of BParser will want to add their own states; they may use any values equal or greater than B_PARSER_STATE_USER.
BParserState (*BParserStartFunc) (BParserState state, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error);
The function that is called when the parser hits the start of an element. Return B_PARSER_STATE_UNKNOWN from this function to indicate an error which should cause the parser to abort.
| state : | the current state of the parser |
| element_name : | the name of the element |
| attribute_names : | a NULL-terminated list of attribute names |
| attribute_values : | a NULL-terminated list of attribute values |
| user_data : | the data that was passed to b_parser_new() |
| error : | the error pointer that was passed to b_parser_new() |
| Returns : | the new state of the parser |
BParserState (*BParserEndFunc) (BParserState state, const gchar *element_name, const gchar *cdata, gsize cdata_len, gpointer user_data, GError **error);
The function that is called when the parser hits the end of an element. Return B_PARSER_STATE_UNKNOWN from this function to indicate an error which should cause the parser to abort.
| state : | the current state of the parser |
| element_name : | the name of the element |
| cdata : | pointer to character data that occured between the opening and closing tags |
| cdata_len : | the length of cdata in bytes |
| user_data : | the data that was passed to b_parser_new() |
| error : | the error pointer that was passed to b_parser_new() |
| Returns : | the new state of the parser |
BParser* b_parser_new (BParserStartFunc start_element, BParserEndFunc end_element, gpointer user_data);
Creates a new BParser suited to parse XML files. The BParser should later be freed using b_parser_free().
| start_element : | the function to call when an element is started |
| end_element : | the function to call when an element is closed |
| user_data : | data to pass to the functions above |
| Returns : | a newly allocated BParser |
void b_parser_free (BParser *parser);
Frees the resources allocated for parser. You must not access parser after calling this function.
| parser : | a BParser |
gboolean b_parser_parse (BParser *parser, const gchar *text, gssize text_len, GError **error);
Let the parser process a chunk of text. You need to call b_parser_end_parse() after you passed the last chunk to the parser.
| parser : | a BParser |
| text : | pointer to a text buffer to parse |
| text_len : | the number of bytes to parse from text |
| error : | location to store the error occuring, or NULL to ignore errors |
| Returns : | TRUE if parsing was successful, FALSE if an error occured |
gboolean b_parser_end_parse (BParser *parser, GError **error);
Finishes the parser. After calling this function, you must not call b_parser_parse() on the parser again.
| parser : | a BParser |
| error : | location to store the error occuring, or NULL to ignore errors |
| Returns : | TRUE if parser was successfully finished, FALSE otherwise |
gboolean b_parser_parse_io_channel (BParser *parser, GIOChannel *io, gboolean recode, GError **error);
Reads data from the GIOChannel io and passes it to parser. If recode is TRUE, the data should start with an XML header so this function can determine the encoding of the XML data and convert it to UTF-8 for you.
| parser : | a BParser |
| io : | a GIOChannel to read the text to parse from |
| recode : | TRUE if you want the parser to do automatic encoding conversion |
| error : | location to store the error occuring, or NULL to ignore errors |
| Returns : | TRUE if parsing was successful, FALSE otherwise |
BParserState b_parser_get_state (BParser *parser);
Retrieves the current state of parser.
| parser : | a BParser |
| Returns : | the state of parser |
gchar* b_parse_encoding (const gchar *text,
gint text_len);Scans the text for an XML header with encoding specification.
| text : | a string to parse, must be at least 20 bytes |
| text_len : | the maximum number of bytes to parse from text |
| Returns : | a copy of the encoding string or NULL if none was found |
| << BUtils | BWriter >> |