head 1.4; access; symbols; locks; strict; comment @# @; 1.4 date 2002.09.07.01.50.37; author curt; state Exp; branches; next 1.3; 1.3 date 2002.08.31.19.01.51; author curt; state Exp; branches; next 1.2; 1.2 date 2002.08.31.18.53.59; author curt; state Exp; branches; next 1.1; 1.1 date 2002.02.15.17.21.55; author curt; state Exp; branches; next ; desc @@ 1.4 log @Updated doxygen docs. @ text @
Main Page Class Hierarchy Compound List File List Compound Members File Members

# XMLVisitor Class Reference

Visitor class for an XML document. More...

`#include <easyxml.hxx>`

Inheritance diagram for XMLVisitor:

List of all members.

## Public Methods
virtual | ~XMLVisitor ()
| Virtual destructor.
virtual void | startXML ()
| Callback for the start of an XML document.
virtual void | endXML ()
| Callback for the end of an XML document.
virtual void | startElement (const char *name, const XMLAttributes &atts)
| Callback for the start of an XML element.
virtual void | endElement (const char *name)
| Callback for the end of an XML element.
virtual void | data (const char *s, int length)
| Callback for a chunk of character data.
virtual void | pi (const char *target, const char *data)
| Callback for an XML processing instruction.
virtual void | warning (const char *message, int line, int column)
| Callback for an XML parsing warning.
## Related Functions
(Note that these are not member functions.)
void | readXML (istream &input, XMLVisitor &visitor, const string &path="")
| Read an XML document.
void | readXML (const string &path, XMLVisitor &visitor)
| Read an XML document.

## Detailed Description

Visitor class for an XML document.

This interface uses the Visitor pattern. The XML parser walks through the XML document and invokes the appropriate method in this visitor for each piece of markup it finds. By default, the methods do nothing; the application must subclass the visitor and override the methods for the events it's interested in. All applications are required to provide an implementation for the callback.

Definition at line 241 of file easyxml.hxx.

## Member Function Documentation

virtual void XMLVisitor::data | ( | const char * | s,
|  | int | length
| ) | `[inline, virtual]`

  | Callback for a chunk of character data. The XML parser will invoke this method once for every chunk of character data in the XML document, including whitespace separating elements (as required by the XML recommendation). Note that character data may be chunked arbitrarily: the character data content of an element may be returned in one large chunk or several consecutive smaller chunks. Parameters:
  s | A pointer to the beginning of the character data (not null).
  length | The number of characters in the chunk (may be zero).
Definition at line 327 of file easyxml.hxx. Referenced by pi().

virtual void XMLVisitor::endElement | ( | const char * | name | ) | `[inline, virtual]`

  | Callback for the end of an XML element. The XML parser will invoke this method at the end of every XML element. Parameters:
  name | The name of the element that is ending (not null).
See also: startElement Definition at line 310 of file easyxml.hxx.

virtual void XMLVisitor::endXML | ( |  | ) | `[inline, virtual]`

| Callback for the end of an XML document. The XML parser will invoke this method once, at the end of the XML document, after all other methods are invoked, and only if there have been no parsing errors. The application can use this callback to close or write files, finalize data structures, and so on, but the application will need to be prepared to clean up any resources without this callback in the event of an error. See also: startXML , error Definition at line 278 of file easyxml.hxx.

virtual void XMLVisitor::pi | ( | const char * | target,
|  | const char * | data
| ) | `[inline, virtual]`

  | Callback for an XML processing instruction. The XML parser will invoke this method once for every processing instruction in the XML document. Note that the XML declaration and the Text declaration are NOT PROCESSING INSTRUCTIONS and will not be reported through this callback. Processing instructions are not all that useful, but the XML recommendation requires that they be reported. Most applications can safely ignore this callback and use the empty default implementation. Parameters:
  target | The processing instruction target (not null).
  data | The processing instruction data (not null).
Definition at line 344 of file easyxml.hxx. References data().

virtual void XMLVisitor::startElement | ( | const char * | name,
|  | const XMLAttributes & | atts
| ) | `[inline, virtual]`

  | Callback for the start of an XML element. The XML parser will invoke this method at the beginning of every XML element. Start and end element calls will be balanced and properly nested: every element has both a start and end callback (even if it was specified with an XML empty element tag), there is exactly one root element, and every element must end before its parent does. Elements may not overlap. Note that the attribute list provided is volatile; it's contents are not guaranteed to persist after the end of the callback. If the application needs to keep a copy of the attribute list, it can make the copy with the XMLAttributesDefault class. Parameters:
  name | The name of the element that is starting (not null).
  atts | The element's attributes (not null).
See also: endElement Definition at line 299 of file easyxml.hxx.

virtual void XMLVisitor::startXML | ( |  | ) | `[inline, virtual]`

| Callback for the start of an XML document. The XML parser will invoke this method once, at the beginning of the XML document, before any other methods are invoked. The application can use this callback to set up data structures, open files, etc. See also: endXML Definition at line 261 of file easyxml.hxx. Referenced by readXML().

virtual void XMLVisitor::warning | ( | const char * | message,
|  | int | line,
|  | int | column
| ) | `[inline, virtual]`

  | Callback for an XML parsing warning. The XML parser will use this callback to report any non-fatal warnings during parsing. It is the responsibility of the application to deal with the warning in some appropriate way. Parameters:
  message | The warning message from the parser.
  line | The number of the line that generated the warning.
  column | The character position in the line that generated the warning.
Definition at line 359 of file easyxml.hxx.

## Friends And Related Function Documentation

void readXML | ( | const string & | path,
|  | XMLVisitor & | visitor
| ) | `[related]`

  | Read an XML document. This function reads an XML document from the input stream provided, and invokes the callback methods in the visitor object to pass the parsing events back to the application. When this function returns, the parser will have reported all of the data in the XML document to the application through the visitor callback methods, and XML processing will be complete. Parameters:
  path | The file name of the XML resource.
  visitor | An object that contains callbacks for XML parsing events.
  Exceptions:
  Throws | sg_io_exception or sg_xml_exception if there is a problem reading the file.
See also: XMLVisitor Definition at line 258 of file easyxml.cxx.

void readXML | ( | istream & | input,
|  | XMLVisitor & | visitor,
|  | const string & | path = ""
| ) | `[related]`

  | Read an XML document. This function reads an XML document from the input stream provided, and invokes the callback methods in the visitor object to pass the parsing events back to the application. When this function returns, the parser will have reported all of the data in the XML document to the application through the visitor callback methods, and XML processing will be complete. Parameters:
  input | The byte input stream containing the XML document.
  visitor | An object that contains callbacks for XML parsing events.
  path | A string describing the original path of the resource.
  Exceptions:
  Throws | sg_io_exception or sg_xml_exception if there is a problem reading the file.
See also: XMLVisitor Definition at line 209 of file easyxml.cxx. References startXML().

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

- easyxml.hxx

@ 1.3 log @Oops, try again. @ text @d510 1 a510 1