glibmm: Glib::Markup::ParseContext Class Reference

glibmm 2.89.0

Public Member Functions | List of all members
Glib::Markup::ParseContext Class Reference
Simple XML Subset Parser

A parse context is used to parse marked-up documents. More...

`#include <glibmm/markup.h>`

Inheritance diagram for Glib::Markup::ParseContext:
[legend]

## Public Member Functions
| ParseContext (Parser & parser, ParseFlags flags=ParseFlags(0))
| Creates a new parse context.
| ParseContext (const ParseContext &)=delete
ParseContext & | operator= (const ParseContext &)=delete
| ParseContext (ParseContext && other) noexcept
ParseContext & | operator= (ParseContext && other) noexcept
virtual | ~ParseContext ()
void | parse (const Glib::ustring & text)
| Feed some data to the ParseContext.
void | parse (const char * text_begin, const char * text_end)
| Feed some data to the ParseContext.
void | end_parse ()
| Signals to the ParseContext that all data has been fed into the parse context with parse().
Glib::ustring | get_element () const
| Retrieves the name of the currently open element.
int | get_line_number () const
| Retrieves the current line number.
int | get_char_number () const
| Retrieves the number of the current character on the current line.
gsize | get_offset () const
| Retrieves the current offset from the beginning of the document, in bytes.
void | get_tag_start (gsize & line_number, gsize & char_number, gsize & offset) const
| Retrieves the start position of the current start or end tag.
std::array< size_t, 6 > | get_attribute_position (unsigned int attr) const
| Retrieves the start and end positions of an attribute assignment in a start tag.
Parser * | get_parser ()
const Parser * | get_parser () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src) noexcept
| ~trackable ()
void | add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src) noexcept
void | remove_destroy_notify_callback (notifiable *data) const

## Additional Inherited Members
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify
Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify | func_destroy_notify

## Detailed Description

A parse context is used to parse marked-up documents.

You can feed any number of documents into a context, as long as no errors occur; once an error occurs, the parse context can't continue to parse text (you have to destroy it and create a new parse context).

## Constructor & Destructor Documentation

## ◆ ParseContext() [1/3]

Glib::Markup::ParseContext::ParseContext | ( | Parser & | parser,
|  | ParseFlags | flags = ParseFlags(0) )
| explicit

Creates a new parse context.

Parameters

  parser | A Markup::Parser instance.
  flags | Bitwise combination of Markup::ParseFlags.

## ◆ ParseContext() [2/3]

Glib::Markup::ParseContext::ParseContext | ( | const ParseContext & |  | ) |
| delete

## ◆ ParseContext() [3/3]

Glib::Markup::ParseContext::ParseContext | ( | ParseContext && | other | ) |
| noexcept

## ◆ ~ParseContext()

virtual Glib::Markup::ParseContext::~ParseContext | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ end_parse()

void Glib::Markup::ParseContext::end_parse | ( |  | ) |

Signals to the ParseContext that all data has been fed into the parse context with parse().

This method reports an error if the document isn't complete, for example if elements are still open.

Exceptions

  Glib::MarkupError |

## ◆ get_attribute_position()

std::array< size_t, 6 > Glib::Markup::ParseContext::get_attribute_position | ( | unsigned int | attr | ) | const

Retrieves the start and end positions of an attribute assignment in a start tag.

This function can be used in the start_element callback to obtain location information for error reporting.

Calling it outside of the start_element callback has undefined results.

Note that line_number and char_number are intended for human readable error messages and are therefore 1-based and in Unicode characters. offset on the other hand is meant for programmatic use, and thus is 0-based and in bytes.

The information is meant to accompany the values returned by get_line_number() and get_char_number(), and comes with the same accuracy guarantees.

Parameters

  attr | The index of the attribute to query.

Returns
  A 6-element array.
  - Element 0: start_line: The line number of the attribute assignment start.
  - Element 1: start_char: The character number of the attribute assignment start.
  - Element 2: start_offset: Offset of the attribute assignment start.
  - Element 3: end_line: The line number of the attribute assignment end.
  - Element 4: end_char: The character number of the attribute assignment end.
  - Element 5: end_offset: Offset of the attribute assignment end.

Since glibmm 2.90

## ◆ get_char_number()

int Glib::Markup::ParseContext::get_char_number | ( |  | ) | const

Retrieves the number of the current character on the current line.

Intended for use in error messages; there are no strict semantics for what constitutes the "current" character number other than "the best number we could come up with for error messages."

## ◆ get_element()

Glib::ustring Glib::Markup::ParseContext::get_element | ( |  | ) | const

Retrieves the name of the currently open element.

Returns
  The name of the currently open element, or "".

## ◆ get_line_number()

int Glib::Markup::ParseContext::get_line_number | ( |  | ) | const

Retrieves the current line number.

Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages."

## ◆ get_offset()

gsize Glib::Markup::ParseContext::get_offset | ( |  | ) | const

Retrieves the current offset from the beginning of the document, in bytes.

The information is meant to accompany the values returned by get_line_number() and get_char_number(), and comes with the same accuracy guarantees.

Since glibmm 2.88

## ◆ get_parser() [1/2]

Parser * Glib::Markup::ParseContext::get_parser | ( |  | ) |
| inline

## ◆ get_parser() [2/2]

const Parser * Glib::Markup::ParseContext::get_parser | ( |  | ) | const
| inline

## ◆ get_tag_start()

void Glib::Markup::ParseContext::get_tag_start | ( | gsize & | line_number,
|  | gsize & | char_number,
|  | gsize & | offset ) const

Retrieves the start position of the current start or end tag.

This function can be used in the start_element or end_element callbacks to obtain location information for error reporting.

Note that line_number and char_number are intended for human readable error messages and are therefore 1-based and in Unicode characters. offset on the other hand is meant for programmatic use, and thus is 0-based and in bytes.

The information is meant to accompany the values returned by get_line_number() and get_char_number(), and comes with the same accuracy guarantees.

Parameters

  [out] | line_number | The line number.
  [out] | char_number | The character number.
  [out] | offset | Offset from the beginning of the document.

Since glibmm 2.88

## ◆ operator=() [1/2]

ParseContext & Glib::Markup::ParseContext::operator= | ( | const ParseContext & |  | ) |
| delete

## ◆ operator=() [2/2]

ParseContext & Glib::Markup::ParseContext::operator= | ( | ParseContext && | other | ) |
| noexcept

## ◆ parse() [1/2]

void Glib::Markup::ParseContext::parse | ( | const char * | text_begin,
|  | const char * | text_end )

Feed some data to the ParseContext.

The data need not be valid UTF-8; an error will be signalled if it's invalid. The data need not be an entire document; you can feed a document into the parser incrementally, via multiple calls to this function. Typically, as you receive data from a network connection or file, you feed each received chunk of data into this function, aborting the process if an error occurs. Once an error is reported, no further data may be fed to the ParseContext; all errors are fatal.

Parameters

  text_begin | Begin of chunk of text to parse.
  text_end | End of chunk of text to parse.

Exceptions

  Glib::MarkupError |

## ◆ parse() [2/2]

void Glib::Markup::ParseContext::parse | ( | const Glib::ustring & | text | ) |

Feed some data to the ParseContext.

The data need not be valid UTF-8; an error will be signalled if it's invalid. The data need not be an entire document; you can feed a document into the parser incrementally, via multiple calls to this function. Typically, as you receive data from a network connection or file, you feed each received chunk of data into this function, aborting the process if an error occurs. Once an error is reported, no further data may be fed to the ParseContext; all errors are fatal.

Parameters

  text | Chunk of text to parse.

Exceptions

  Glib::MarkupError |