Class xrx.stream
Defined in: stream.js.
Constructor Attributes | Constructor Name and Description |
---|---|
xrx.stream(xml)
A class to stream over XML documents or XML fragments.
|
Field Attributes | Field Name and Description |
---|---|
Event, thrown whenever a namespace declaration is found.
|
|
Event, thrown whenever a empty-tag row is found.
|
|
Event, thrown whenever a end-tag row is found.
|
|
Event, thrown whenever a start-tag row is found.
|
Method Attributes | Method Name and Description |
---|---|
attribute(xml, pos, opt_offset)
Streams over a start-tag or a empty tag and returns the location
of the n'th attribute, or null if the attribute does not exist.
|
|
attributes(xml)
Streams over a start-tag or a empty tag and returns an array of
locations of all attributes found in the tag or null if no
attributes were found.
|
|
attrName(xml, pos)
Streams over a start-tag or empty tag and returns the location
of the name of the n'th attribute.
|
|
attrValue(xml, pos)
Streams over a start-tag or empty tag and returns the location
of the value of the n'th attribute.
|
|
backward(opt_offset)
Streams over a XML document or XML fragment in backward direction
and fires start-row, end-row, empty row and namespace events.
|
|
cdata(xml)
Streams over some XML content and returns the location of
one or more character data (CDATA) sections.
|
|
comment(xml)
Streams over some XML content and returns the location of
one or more comments.
|
|
doctypedecl(xml)
Streams over some XML content and returns the location of
one or more document type declarations.
|
|
forward(opt_offset)
Streams over a XML document or XML fragment in forward direction
and fires start-row, end-row, empty row and namespace events.
|
|
pi(xml)
Streams over some XML content and returns the location of
one or more processing instructions (PI).
|
|
pos(opt_pos)
Returns or sets the position of the stream reader.
|
|
stop()
Can be called to stop streaming.
|
|
tagName(xml, opt_reader)
Streams over a start-tag, a empty tag or an end-tag and
returns the location of the name of the tag.
|
|
update(offset, length, xml)
Updates the XML stream at a given location.
|
|
xml(opt_xml)
Returns or sets the content of the current stream reader.
|
Class Detail
xrx.stream(xml)
A class to stream over XML documents or XML fragments.
IMPORTANT NOTE: This class represents a XML streamer and not a XML parser! The streamer is different from a XML parser in the following respects:
the XML input document or fragment must be well-formed before
streaming starts. The streamer itself does not do any well-formed
checks
the streamer expects the XML document or fragment serialized
as a string
the string must be encoded in UTF-8
whitespace must already be normalized and collapsed before
streaming starts
the streamer expects the XML document without any indentation
These restrictions are intended by design, finally to reach optimal performance and to reach full XML support in browsers. For more background about parsing see e.g.:
XML Document Parsing: Operational and Performance Characteristics
String conversion, encoding conversion, whitespace normalization as well as indentation can best be prepared with the XQuery and XPath 3.0 serialization feature. Example XQuery script:
See also:
XSLT and XQuery Serialization 3.0
XRX++ XQuery Agent
XRX++ XSLT Agent (For
development only, only runs in modern browsers with full XML
support)
IMPORTANT NOTE: This class represents a XML streamer and not a XML parser! The streamer is different from a XML parser in the following respects:
These restrictions are intended by design, finally to reach optimal performance and to reach full XML support in browsers. For more background about parsing see e.g.:
String conversion, encoding conversion, whitespace normalization as well as indentation can best be prepared with the XQuery and XPath 3.0 serialization feature. Example XQuery script:
--- xquery version "3.0"; declare option output:method "xml"; declare option output:encoding "UTF-8"; declare option output:indent "no"; declare variable $xml := <someXml/>; fn:serialize($xml) ---The output of this XQuery script is exactly what the streamer expects.
See also:
- Parameters:
- {!string} xml
- A well-formed, normalized XML document or XML fragment serialized as UTF-8 string.
Field Detail
namespace
Event, thrown whenever a namespace declaration is found.
rowEmptyTag
Event, thrown whenever a empty-tag row is found.
rowEndTag
Event, thrown whenever a end-tag row is found.
rowStartTag
Event, thrown whenever a start-tag row is found.
Method Detail
{string|null}
attribute(xml, pos, opt_offset)
Streams over a start-tag or a empty tag and returns the location
of the n'th attribute, or null if the attribute does not exist.
- Parameters:
- {!string} xml
- The start-tag or empty tag.
- {!number} pos
- The attribute position.
- opt_offset
- Returns:
- {string|null} The attribute at position n or null.
{Array.|null}
attributes(xml)
Streams over a start-tag or a empty tag and returns an array of
locations of all attributes found in the tag or null if no
attributes were found.
- Parameters:
- {!string} xml
- The start-tag or empty tag.
- Returns:
- {Array.
|null} The attribute array.
{!string}
attrName(xml, pos)
Streams over a start-tag or empty tag and returns the location
of the name of the n'th attribute.
- Parameters:
- {!string} xml
- The tag.
- {!number} pos
- The attribute position.
- Returns:
- {!string} The attribute name.
{!xrx.location}
attrValue(xml, pos)
Streams over a start-tag or empty tag and returns the location
of the value of the n'th attribute.
- Parameters:
- {!string} xml
- The attribute.
- {!number} pos
- The attribute position.
- Returns:
- {!xrx.location} The attribute value location.
backward(opt_offset)
Streams over a XML document or XML fragment in backward direction
and fires start-row, end-row, empty row and namespace events. The
streaming starts at the end of the XML document / fragment by
default or optionally at an offset.
TODO(jochen): do we need lenght2 in backward streaming events?
- Parameters:
- {?number} opt_offset
- The offset.
cdata(xml)
Streams over some XML content and returns the location of
one or more character data (CDATA) sections.
- Parameters:
- xml
- XML string.
comment(xml)
Streams over some XML content and returns the location of
one or more comments.
- Parameters:
- xml
doctypedecl(xml)
Streams over some XML content and returns the location of
one or more document type declarations.
- Parameters:
- xml
- XML string.
forward(opt_offset)
Streams over a XML document or XML fragment in forward direction
and fires start-row, end-row, empty row and namespace events.
The streaming starts at the beginning of the XML document /
fragment by default or optionally at an offset.
- Parameters:
- {?number} opt_offset
- The offset.
pi(xml)
Streams over some XML content and returns the location of
one or more processing instructions (PI).
- Parameters:
- xml
- XML string.
{!number}
pos(opt_pos)
Returns or sets the position of the stream reader.
- Parameters:
- opt_pos
- The position.
- Returns:
- {!number} The position or the new position.
stop()
Can be called to stop streaming.
{!string}
tagName(xml, opt_reader)
Streams over a start-tag, a empty tag or an end-tag and
returns the location of the name of the tag.
- Parameters:
- {!string} xml
- The tag.
- {?xrx.reader} opt_reader
- Optional reader object.
- Returns:
- {!string} The tag-name.
update(offset, length, xml)
Updates the XML stream at a given location.
- Parameters:
- {!number} offset
- The offset.
- {!number} length
- Number of characters to replace.
- {!string} xml
- The new string.
xml(opt_xml)
Returns or sets the content of the current stream reader.
- Parameters:
- opt_xml
- Well-formed, normalized UTF-8 XML string.
- Returns:
- The content of the stream reader.