parseEvents function

Iterable<XmlEvent> parseEvents(String input, { XmlEntityMapping? entityMapping, bool validateNesting = false, bool validateDocument = false, bool withBuffer = false, bool withLocation = false, bool withParent = false, })

Returns an Iterable of XmlEvent instances over the provided String.

Iteration can throw an XmlException, if the input is malformed and cannot be properly parsed. In case of an error iteration can be resumed and the parsing is retried at the next possible input position.

If validateNesting is true, the parser validates the nesting of tags and throws an XmlTagException if there is a mismatch or tags are not closed. Again, in case of an error iteration can be resumed with the next event.

If validateDocument is true, the parser validates that the root elements of the input follow the requirements of an XML document. This means the document consists of an optional declaration, an optional doctype, and a single root element.

Furthermore, the following annotations can be enabled if needed:

• If withBuffer is true, each event is annotated with the input buffer. Note that this can come at a high memory cost, if the events are retained.
• If withLocation is true, each event is annotated with the starting and stopping position (exclusive) of the event in the input buffer.
• If withParent is true, each event is annotated with its logical parent event; this enables lookup of namespace URIs and other traversals.

Iteration is lazy, meaning that none of the input is parsed and none of the events are created unless requested. This technique is also called pull-parsing.

The iterator terminates when the complete input is consumed.

For example, to print all trimmed non-empty text elements one would write:

parseEvents(bookstoreXml) .whereType

Implementation

Iterable<XmlEvent> parseEvents(
  String input, {
  XmlEntityMapping? entityMapping,
  bool validateNesting = false,
  bool validateDocument = false,
  bool withBuffer = false,
  bool withLocation = false,
  bool withParent = false,
}) =>
    XmlEventIterable(
      input,
      entityMapping: entityMapping ?? defaultEntityMapping,
      validateNesting: validateNesting,
      validateDocument: validateDocument,
      withBuffer: withBuffer,
      withLocation: withLocation,
      withParent: withParent,
    );