## BParser

BParser — an XML parser that offers a simplified SAX API

## Synopsis

    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);

## Description

## Details

### struct BParser

    struct BParser;

The BParser struct is private.

### enum BParserState

    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`.

### BParserStartFunc ()

    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

### BParserEndFunc ()

    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

### b_parser_new ()

    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

### b_parser_free ()

    void        b_parser_free                   (BParser *parser);

Frees the resources allocated for `parser`. You must not access `parser` after calling this function.

`parser` : | a BParser

### b_parser_parse ()

    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

### b_parser_end_parse ()

    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

### b_parser_parse_io_channel ()

    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

### b_parser_get_state ()

    BParserState b_parser_get_state             (BParser *parser);

Retrieves the current state of `parser`.

`parser` : | a BParser
Returns : | the state of `parser`

### b_parse_encoding ()

    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

## See Also

GMarkupParser