Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::G::MarkupParseContext Class Reference

A GMarkupParseContext C++ wrapper interface. More...

`#include <xfc/glib/markup.hh>`

Inheritance diagram for Xfc::G::MarkupParseContext:

List of all members.

## Public Member Functions

Constructors

- MarkupParseContext (MarkupParser &parser)
    Constructs a new parse context.
- MarkupParseContext (GMarkupParseContext *context, bool can_free)
    Constructs a new parse context from an existing GMarkupParseContext.
- ~MarkupParseContext ()
    Destructor.

Accessors

- GMarkupParseContext * g_markup_parse_context () const
    Get a pointer to the GMarkupParseContext object.
- operator GMarkupParseContext * () const
    Conversion operator; Safely converts a G::MarkupParseContext object into a GMarkupParseContext pointer.
- String get_element () const
    Retrieves the name of the currently open element.
- void get_position (int *line_number, int *char_number) const
    Retrieves the current line number and the number of the character on that line.

Methods

- bool parse (const char *text, int length, G::Error *error)
    Feed some data to the MarkupParseContext.
- bool parse (const String &text, G::Error *error)
    Feed some data to the MarkupParseContext.
- bool end_parse (G::Error *error)
    Signals to the MarkupParseContext that all data has been fed into the parse context with parse().

## Static Public Member Functions

- String escape_text (const char *text, int length)
    Escapes text so that the markup parser will parse it verbatim.
- String escape_text (const String &text)
    Escapes text so that the markup parser will parse it verbatim.

## Detailed Description

A GMarkupParseContext C++ wrapper interface.

The markup parser is intended to parse a simple markup format that's a subset of XML. This is a small, efficient, easy-to-use parser. It should not be used if you expect to interoperate with other applications generating full-scale XML. However, it's very useful for application data files, config files, etc. where you know your application will be the only one writing the file. Full-scale XML parsers should be able to parse the subset used by MarkupParseContext, so you can easily migrate to full-scale XML at a later time if the need arises.

The markup parser is not guaranteed to signal an error on all invalid XML; the parser may accept documents that an XML parser would not. However, invalid XML documents are not considered valid markup documents.

Simplifications to XML include:

- Only UTF-8 encoding is allowed.
- No user-defined entities.
- Processing instructions, comments and the doctype declaration are "passed through" but are not interpreted in any way.
- No DTD or validation.

The markup format does support:

- Elements.
- Attributes.
- 5 standard entities: & < > " '
- Character references.
- Sections marked as CDATA.

## Constructor & Destructor Documentation

Xfc::G::MarkupParseContext::MarkupParseContext | ( | MarkupParser & | parser | ) |

Constructs a new parse context.

Parameters:

  | parser | A MarkupParser.

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 delete the parse context and construct a new one. The easiest way to do this is to use a smart pointer. If an error occurs construct a new parse context and assign it to the existing smart pointer. The smart pointer will delete the previous parse context first and then take over the new one.

Xfc::G::MarkupParseContext::MarkupParseContext | ( | GMarkupParseContext * | context,
|  | bool | can_free
| ) |

Constructs a new parse context from an existing GMarkupParseContext.

Parameters:

  | context | A pointer to a GMarkupParseContext.
  | can_free | Set true if context should be freed.

## Member Function Documentation

bool Xfc::G::MarkupParseContext::end_parse | ( | G::Error * | error | ) |

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

Parameters:

  | error | The return location for a G::Error.

Returns:
  true on success, false if an error was set.

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

String Xfc::G::MarkupParseContext::escape_text | ( | const String & | text | ) | `[static]`

Escapes text so that the markup parser will parse it verbatim.

Parameters:

  | text | Some valid UTF-8 text.

Returns:
  A String holding the escaped text.

Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This method would typically be used when writing out a file to be parsed with the markup parser.

String Xfc::G::MarkupParseContext::escape_text | ( | const char * | text,
|  | int | length
| ) | `[static]`

Escapes text so that the markup parser will parse it verbatim.

Parameters:

  | text | Some valid UTF-8 text.
  | length | The length of text in bytes.

Returns:
  A String holding the escaped text.

Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This method would typically be used when writing out a file to be parsed with the markup parser.

String Xfc::G::MarkupParseContext::get_element | ( |  | ) | const

Retrieves the name of the currently open element.

Returns:
  The name of the currently open element, or null.

void Xfc::G::MarkupParseContext::get_position | ( | int * | line_number,
|  | int * | char_number
| ) | const

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

Parameters:

  | line_number | The return location for a line number, or null;
  | char_number | The return location for a char-on-line number, or null;

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

bool Xfc::G::MarkupParseContext::parse | ( | const String & | text,
|  | G::Error * | error
| ) |

Feed some data to the MarkupParseContext.

Parameters:

  | text | The chunk of text to parse.
  | error | The return location for a G::Error.

Returns:
  false if an error occurred, true on success.

See parse(const char*, int, G::Error*) for details.

bool Xfc::G::MarkupParseContext::parse | ( | const char * | text,
|  | int | length,
|  | G::Error * | error
| ) |

Feed some data to the MarkupParseContext.

Parameters:

  | text | The chunk of text to parse.
  | length | The length of text in bytes.
  | error | The return location for a G::Error.

Returns:
  false if an error occurred, true on success.

The data need not be valid UTF-8; an error will be signaled 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 MarkupParseContext; all errors are fatal.

The documentation for this class was generated from the following file:

- markup.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3