silk.xml.document.

When to use#

Use XmlDocument.parse to read a complete XML document, such as an SVG image, a feed, or a configuration file, from bytes. Use XmlDocument.parseWithLimits to lower the resource limits for input that you do not trust. Walk the tree from XmlDocument.root with XmlDocument.firstChild and XmlDocument.nextSibling, read names with XmlDocument.localName and XmlDocument.namespaceUri, and read attributes with XmlDocument.attribute. Use XmlPseudoAttributes.parse to read the pseudo-attributes of an xml-stylesheet processing instruction.

Details#

The parser follows XML 1.0 (Fifth Edition) and Namespaces in XML 1.0, and does not validate. It accepts UTF-8 and UTF-16 input, with or without a byte order mark, and checks the encoding declaration. It reads the internal DTD subset: general and parameter entities, attribute defaults, and ID attributes. It never fetches an external subset or an external entity. It skips their content, and XmlDocument.skippedExternalContent reports that it did. XmlDocument.skippedEntities identifies unread references. XmlDocument.notations and XmlDocument.unparsedEntities expose DTD metadata without fetching external resources.

All nodes live in one arena in the document and are addressed by XmlNodeId. The document stores names, namespace URIs, text, and attribute values as normalized UTF-8, and the accessors return string views that borrow the document. Line ends are normalized to \n, character and entity references are replaced, and attribute values are normalized as XML requires. CDATA sections become text nodes. Comments, processing instructions, namespace declarations, and attributes in foreign namespaces are kept.

Errors#

• XmlError if the input is not well-formed, breaks a namespace rule, or exceeds an XmlLimits bound. reason names the problem and offset gives its position. No partial document is returned.

• OutOfMemoryError if the Allocator cannot supply the document.

Gotchas#

An XmlError offset counts bytes of the decoded UTF-8 text with normalized line ends, not bytes of the input, except for an encoding error, whose offset counts input bytes. For UTF-16 input or input with \r\n line ends, the two differ.

Examples#

Count the children of the root that have an id attribute#

import silk.core.effect { Effect }
import silk.core.option { Option }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.xml.document { XmlDocument, XmlError, XmlNodeId, XmlNodeKind }

pub effect fn main() -> i32
  ! XmlError | OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let source = b"<list><item id='a'/><item/><item id='c'>text</item></list>"
  let document = run XmlDocument.parse(source) |> Effect.provideMut<Allocator>(&mut allocator)
  let mut count = 0
  let mut child = document.firstChild(document.root())
  while let Option<XmlNodeId>.Some { value } = child {
    if document.kind(value) == XmlNodeKind.Element && document.attribute(value, "", "id").isSome() {
      count = count + 1
    }
    child = document.nextSibling(value)
  }
  if count != 2 || document.localName(document.root()) != "list" {
    return 1
  }
  return 0
}

Read a namespaced attribute#

import silk.core.effect { Effect }
import silk.core.option { Option }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.xml.document { XmlDocument, XmlError }

pub effect fn main() -> i32
  ! XmlError | OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let source = b"<svg xmlns='http://www.w3.org/2000/svg' xmlns:x='http://www.w3.org/1999/xlink' x:href='#a'/>"
  let document = run XmlDocument.parse(source) |> Effect.provideMut<Allocator>(&mut allocator)
  let root = document.root()
  let href = document.attribute(root, "http://www.w3.org/1999/xlink", "href")
    |> Option<string>.unwrapOr("")
  if href != "#a" || document.namespaceUri(root) != "http://www.w3.org/2000/svg" {
    return 1
  }
  return 0
}

See also#

Use silk.json.value for JSON and silk.toml.value for TOML.

Import as XmlDocument with import silk.xml.document { XmlDocument }.

Public declarations: 15.

XmlReason#

pub enum XmlReason

The reason that XML input was rejected, carried by XmlError.

Encoding#

Encoding

The input is not valid UTF-8 or UTF-16, or the encoding declaration names an encoding that the input does not use.

InvalidCharacter#

InvalidCharacter

A character that XML does not allow, such as a control character, appears in the document or is produced by a character reference.

InvalidName#

InvalidName

A name, such as an element, attribute, entity, or target name, does not match the XML Name production, or a namespace-aware name has more than one colon.

UnexpectedEnd#

UnexpectedEnd

The input ends inside markup, such as an unclosed tag, comment, or quoted value.

Syntax#

Syntax

Markup does not match the XML grammar, such as a missing = or quote, or a < in an attribute value.

Declaration#

Declaration

The XML declaration or a markup declaration in the DTD is malformed.

Structure#

Structure

The document has content after the root element that is not a comment, a processing instruction, or white space.

MismatchedTag#

MismatchedTag

An end tag does not have the name of the element that it closes.

DuplicateAttribute#

DuplicateAttribute

An element has two attributes with the same qualified name or the same namespace URI and local name, or a pseudo-attribute appears two times.

Namespace#

Namespace

A prefix is not declared, or a declaration binds the reserved xml or xmlns prefix or namespace URI incorrectly.

UndeclaredEntity#

UndeclaredEntity

A reference names an entity that is not declared, in a document where XML requires the declaration.

RecursiveEntity#

RecursiveEntity

An entity refers to itself, directly or through other entities.

ExternalEntityInAttribute#

ExternalEntityInAttribute

An attribute value refers to an external entity.

UnparsedEntity#

UnparsedEntity

Content refers to an unparsed entity, which is declared with NDATA.

EntityBoundary#

EntityBoundary

The replacement text of an entity starts or ends an element or other markup that the entity does not also close or open.

Limit#

Limit

The input exceeds a bound of the XmlLimits that the parse used.

Implementation Debug for XmlReason#

impl Debug for XmlReason

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes the name of the variant, such as MismatchedTag.

XmlError#

pub struct XmlError

The failure of an XML parse: what was wrong, and where.

Details#

offset counts bytes of the decoded UTF-8 text with normalized line ends, except for an XmlReason.Encoding failure, where it counts bytes of the input. An error that is found in the replacement text of an entity gives the offset of the reference or the declaration that contains it.

Field reason#

pub reason: XmlReason

The reason that the input was rejected.

Field offset#

pub offset: usize

The byte position of the problem.

Implementation Copy for XmlError#

impl Copy for XmlError

Implementation Debug for XmlError#

impl Debug for XmlError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes the fields, as XmlError { reason: ..., offset: ... }.

XmlLimits#

pub struct XmlLimits

The resource bounds of one XML parse.

When to use#

Use XmlLimits.make for the defaults, which suit untrusted input, and lower a field before you pass the limits to XmlDocument.parseWithLimits or XmlPseudoAttributes.parse.

Details#

When the input exceeds a bound, the parse fails with XmlReason.Limit and returns no document.

Gotchas#

maxDepth and maxEntityDepth can only lower the hard ceilings of 256 and 32. A larger value has no effect.

Field maxInputBytes#

pub maxInputBytes: usize

The largest input, in bytes. The default is 16 MiB.

Field maxStorageBytes#

pub maxStorageBytes: usize

The largest total of retained UTF-8 for names, namespace URIs, text, and values. The default is 64 MiB.

Field maxExpandedBytes#

pub maxExpandedBytes: usize

The largest total of bytes that entity references and character references can add, which bounds entity expansion attacks. The default is 8 MiB.

Field maxNodes#

pub maxNodes: usize

The largest number of nodes in the document. The default is one million.

Field maxAttributes#

pub maxAttributes: usize

The largest number of attributes in the document, and of attribute defaults in the DTD. The default is one million.

Field maxDeclarations#

pub maxDeclarations: usize

The largest number of markup declarations in the DTD. The default is one million.

Field maxDepth#

pub maxDepth: usize

The deepest element nesting. The default is 256, which is also the ceiling.

Field maxEntityDepth#

pub maxEntityDepth: usize

The deepest nesting of entity references. The default is 32, which is also the ceiling.

Implementation Copy for XmlLimits#

impl Copy for XmlLimits

Implementation XmlLimits#

impl XmlLimits

Associated function make#

pub fn make() -> XmlLimits

Returns the default limits: 16 MiB of input, 64 MiB of retained text, 8 MiB of entity expansion, one million nodes, attributes, and declarations, element depth 256, and entity depth 32.

When to use#

Use the result as it is for XmlDocument.parseWithLimits, or lower one field first to tighten one bound.

XmlNodeId#

pub struct XmlNodeId

The position of one node in the arena of an XmlDocument.

Gotchas#

An id is meaningful only for the document that produced it. The accessors of XmlDocument return empty or absent results for an id that is out of range.

Field index#

pub index: usize

The index of the node in XmlDocument.nodes.

Implementation Copy for XmlNodeId#

impl Copy for XmlNodeId

XmlNodeKind#

pub enum XmlNodeKind

The kind of one node of an XmlDocument.

Element#

Element

An element, with a name, attributes, and children.

Text#

Text

Character data, from text or a CDATA section, with references replaced.

Comment#

Comment

A comment. Its text is the content between ``.

ProcessingInstruction#

ProcessingInstruction

A processing instruction. Its local name is the target and its text is the content after the target.

XmlAttribute#

pub struct XmlAttribute

One attribute of an element of an XmlDocument, read with the attribute functions of the document.

Details#

The value is a handle into the document that produced it. Pass it to XmlDocument.attributeLocalName, XmlDocument.attributeNamespaceUri, XmlDocument.attributeValue, or XmlDocument.attributeIsId of that document.

Implementation Copy for XmlAttribute#

impl Copy for XmlAttribute

XmlNode#

pub struct XmlNode

One node in the arena of an XmlDocument: its kind, its parent, and private links to its name, value, attributes, and children.

Field kind#

pub kind: XmlNodeKind

The kind of the node.

Field parent#

pub parent: Option<XmlNodeId>

The element that contains the node, or None for the root element and for comments and processing instructions outside it.

Implementation Copy for XmlNode#

impl Copy for XmlNode

XmlEncoding#

pub enum XmlEncoding

The byte encoding of the input of an XmlDocument.

Utf8#

Utf8

UTF-8, with or without a byte order mark.

Utf16Le#

Utf16Le

UTF-16 little-endian.

Utf16Be#

Utf16Be

UTF-16 big-endian.

XmlSkippedEntity#

pub struct XmlSkippedEntity

An entity reference whose replacement text was not read.

Field name#

pub name: String

The referenced name, without delimiters.

Field parameter#

pub parameter: bool

Whether this is a parameter entity from the DTD.

Field offset#

pub offset: usize

The reference position in normalized UTF-8 text, or its enclosing entity reference position.

XmlExternalId#

pub struct XmlExternalId

External identifiers from an XML declaration. No external resource is fetched.

Field publicId#

pub publicId: Option<String>

The public identifier with whitespace collapsed, or None if absent.

Field systemId#

pub systemId: Option<String>

The system identifier as written after line-end normalization, or None if absent.

XmlNotation#

pub struct XmlNotation

A notation read from the DTD. Identifiers describe the format of unparsed data.

Field name#

pub name: String

The notation name.

Field externalId#

pub externalId: XmlExternalId

The declared public and system identifiers.

XmlUnparsedEntity#

pub struct XmlUnparsedEntity

An unparsed entity read from the DTD. Its contents are not read by the parser.

Field name#

pub name: String

The entity name, without the reference delimiters.

Field externalId#

pub externalId: XmlExternalId

The external identifiers of the entity.

Field notation#

pub notation: String

The notation that describes the entity's format.

XmlDocument#

pub struct XmlDocument

A parsed XML document: an arena of nodes and the UTF-8 text of their names and values.

When to use#

Use XmlDocument.parse or XmlDocument.parseWithLimits to make one. Walk it from XmlDocument.root with XmlDocument.firstChild and XmlDocument.nextSibling, or visit every node in document order with XmlDocument.nodes.

Details#

Every name, namespace URI, text, and attribute value is a string view that borrows the document, so none of them can outlive it. Namespace prefixes are resolved: every element and attribute has a local name and a namespace URI, which is empty for no namespace. Nodes are stored in document order.

Implementation XmlDocument#

impl XmlDocument

Method skippedEntities#

pub fn skippedEntities(self: &XmlDocument) -> &[XmlSkippedEntity]

Borrows notifications for unread entity references in declarations, attributes, and content. Each entry gives the entity name and the normalized byte offset. A skipped reference supplies no replacement text. External subset declarations are reported by skippedExternalContent.

Method notations#

pub fn notations(self: &XmlDocument) -> &[XmlNotation]

Borrows notation declarations read from the internal DTD, in declaration order. Public identifiers have collapsed whitespace. System identifiers retain their spelling. Declarations in unread external content are absent.

Method unparsedEntities#

pub fn unparsedEntities(self: &XmlDocument) -> &[XmlUnparsedEntity]

Borrows unparsed entity declarations read from the internal DTD, in declaration order. The first declaration of each entity binds. No external content is fetched.

Associated function parse#

pub effect fn parse(data: &[u8]) -> XmlDocument
    ! XmlError | OutOfMemoryError
    ? &mut Allocator

Parses data as a complete XML document with the default XmlLimits.

When to use#

Use this function for input of ordinary size. Use XmlDocument.parseWithLimits to set tighter bounds.

Details#

data is UTF-8 or UTF-16. A byte order mark, or the first character <, selects the encoding. The parse reads the internal DTD subset and never fetches external content. The defaults allow 16 MiB of input, 64 MiB of retained text, 8 MiB of entity expansion, one million nodes, attributes, and declarations, element depth 256, and entity depth 32.

Errors#

• XmlError if data is not a well-formed, namespace-well-formed XML 1.0 document or exceeds a default limit. reason gives the cause and offset the position. No document is returned.

• OutOfMemoryError if the Allocator cannot supply the document.

Associated function parseWithLimits#

pub effect fn parseWithLimits(data: &[u8], limits: &XmlLimits) -> XmlDocument
    ! XmlError | OutOfMemoryError
    ? &mut Allocator

Parses data as a complete XML document, within the bounds of limits.

When to use#

Use this function for untrusted input where the default bounds of XmlDocument.parse are too large, such as an upload size limit.

Details#

data is UTF-8 or UTF-16. A byte order mark, or the first character <, selects the encoding. The parse reads the internal DTD subset and never fetches external content.

Errors#

• XmlError with XmlReason.Limit if the input exceeds a bound of limits.

• XmlError with another kind if data is not a well-formed, namespace-well-formed XML 1.0 document. offset gives the position. No document is returned.

• OutOfMemoryError if the Allocator cannot supply the document.

Gotchas#

maxDepth and maxEntityDepth can only lower the hard ceilings of 256 and 32.

Method encoding#

pub fn encoding(self: &XmlDocument) -> XmlEncoding

Returns the byte encoding of the input: UTF-8 or UTF-16 with its byte order.

Details#

The text that the document returns is always UTF-8. The encoding only describes the input.

Method root#

pub fn root(self: &XmlDocument) -> XmlNodeId

Returns the id of the root element.

Method nodes#

pub fn nodes(self: &XmlDocument) -> &[XmlNode]

Returns every node of the document in document order, indexed by XmlNodeId.

When to use#

Use this function to visit every node without walking the tree, or to read the XmlNodeKind and parent of a node.

Details#

The node at index id.index is the node with that id. A node comes after its parent and before its next sibling. The slice includes comments and processing instructions outside the root element.

Method kind#

pub fn kind(self: &XmlDocument, id: XmlNodeId) -> XmlNodeKind

Returns the kind of node id, or XmlNodeKind.Text if id is out of range.

Method parent#

pub fn parent(self: &XmlDocument, id: XmlNodeId) -> Option<XmlNodeId>

Returns the parent element of node id, or None for the root element, for a node outside it, and for an id that is out of range.

Method skippedExternalContent#

pub fn skippedExternalContent(self: &XmlDocument) -> bool

Returns true if the document declares an external DTD subset or an external entity whose content the parse skipped.

When to use#

Use this function to tell if the document can depend on declarations that the parse did not read, such as an entity or an attribute default in an external subset.

Details#

The parser never fetches external content. A skipped entity reference produces no replacement text or node. skippedEntities identifies unread references, including references in attributes. Attribute values can therefore be incomplete when this function returns true.

Method firstChild#

pub fn firstChild(self: &XmlDocument, id: XmlNodeId) -> Option<XmlNodeId>

Returns the first child of node id, or None if it has no children or id is out of range.

Details#

Only elements have children. The children are elements, text, comments, and processing instructions, in document order.

Method nextSibling#

pub fn nextSibling(self: &XmlDocument, id: XmlNodeId) -> Option<XmlNodeId>

Returns the node after id that has the same parent, or None if id is the last child or out of range.

Gotchas#

The root element and the comments and processing instructions outside it have no parent and are not linked as siblings. Read them with XmlDocument.nodes.

Method localName#

pub fn localName<'a>(self: &'a XmlDocument, id: XmlNodeId) -> string<'a>

Returns the local name of element id, without its prefix, or the target of processing instruction id.

Details#

The result is empty for text, for comments, and for an id that is out of range. It borrows the document.

Method qualifiedName#

pub fn qualifiedName<'a>(self: &'a XmlDocument, id: XmlNodeId) -> string<'a>

Returns the name of element id as it is written in the source, with its prefix, or the target of processing instruction id.

When to use#

Use this function to report a name to a person. Compare names with XmlDocument.localName and XmlDocument.namespaceUri, because the prefix of a namespace can change between documents.

Details#

The result is empty for text, for comments, and for an id that is out of range. It borrows the document.

Method namespaceUri#

pub fn namespaceUri<'a>(self: &'a XmlDocument, id: XmlNodeId) -> string<'a>

Returns the namespace URI of element id, or an empty string if the element is in no namespace.

Details#

The URI comes from the prefix of the element, or from the default namespace in scope for an unprefixed element. The result is empty for other node kinds and for an id that is out of range. It borrows the document.

Method text#

pub fn text<'a>(self: &'a XmlDocument, id: XmlNodeId) -> string<'a>

Returns the text of a text, comment, or processing instruction node.

Details#

For a text node, the result has references replaced and line ends normalized to \n. For a processing instruction, it is the content after the target and its white space. The result is empty for an element and for an id that is out of range. It borrows the document.

Gotchas#

The text of an element is in its child text nodes. Adjacent text, CDATA sections, and references can form more than one text node.

Method byteLength#

pub fn byteLength(self: &XmlDocument) -> usize

Returns the number of bytes of UTF-8 that the document holds for names, namespace URIs, text, and attribute values.

Details#

The count includes values that XmlDocument.setAttribute replaced, until XmlDocument.restore drops them.

Method attributeCount#

pub fn attributeCount(self: &XmlDocument) -> usize

Returns the number of attributes on all elements of the document, including attributes that come from DTD defaults.

Method attributes#

pub fn attributes(self: &XmlDocument, id: XmlNodeId) -> &[XmlAttribute]

Returns the attributes of element id in source order, followed by the attributes that come from DTD defaults.

Details#

The result includes namespace declarations, such as xmlns and xmlns:x, whose namespace URI is http://www.w3.org/2000/xmlns/. It is empty for other node kinds and for an id that is out of range.

Method attributeLocalName#

pub fn attributeLocalName<'a>(self: &'a XmlDocument, attr: XmlAttribute) -> string<'a>

Returns the local name of attr, without its prefix.

Details#

attr must come from XmlDocument.attributes of this document. The result is empty for an attribute of another document that is out of range. It borrows the document.

Method attributeNamespaceUri#

pub fn attributeNamespaceUri<'a>(self: &'a XmlDocument, attr: XmlAttribute) -> string<'a>

Returns the namespace URI of attr, or an empty string if it has no prefix.

Details#

An unprefixed attribute is in no namespace, even when a default namespace is in scope. attr must come from XmlDocument.attributes of this document. The result borrows the document.

Method attributeQualifiedName#

pub fn attributeQualifiedName<'a>(self: &'a XmlDocument, attr: XmlAttribute) -> string<'a>

Returns the name of attr as it is written in the source, with its prefix.

Details#

attr must come from XmlDocument.attributes of this document. The result borrows the document.

Method attributeValue#

pub fn attributeValue<'a>(self: &'a XmlDocument, attr: XmlAttribute) -> string<'a>

Returns the normalized value of attr.

Details#

References are replaced and white space is normalized as XML requires, including the extra collapsing for attributes that the DTD declares with a type other than CDATA. attr must come from XmlDocument.attributes of this document. The result borrows the document. An unread entity contributes no replacement text; skippedEntities reports the omitted reference.

Method attributeIsId#

pub fn attributeIsId(self: &XmlDocument, attr: XmlAttribute) -> bool

Returns true if the DTD declares attr with type ID.

Details#

The xml:id attribute is an ID only when the DTD declares it. attr must come from XmlDocument.attributes of this document.

Method attribute#

pub fn attribute<'a>(
    self: &'a XmlDocument,
    id: XmlNodeId,
    namespaceUri: string,
    localName: string,
  ) -> Option<string<'a>>

Returns the value of the attribute of element id with local name localName in namespace namespaceUri, or None if the element does not have it.

Details#

Pass an empty namespaceUri for an unprefixed attribute. The match uses the resolved namespace URI, not the prefix in the source. The result borrows the document.

Implementation XmlDocument#

impl XmlDocument

Method setAttribute#

pub effect fn setAttribute(
    self: &mut XmlDocument,
    id: XmlNodeId,
    namespaceUri: string,
    localName: string,
    value: string,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the attribute of element id with local name localName in namespace namespaceUri to value, and adds the attribute if the element does not have it.

When to use#

Use this function to apply computed values, such as animated attributes, to a parsed document. Take an XmlSnapshot with XmlDocument.snapshot first and put it back with XmlDocument.restore to undo the changes.

Details#

A new attribute has no prefix, so its qualified name is localName, and it is not an ID. Changing an attribute does not change which attributes are IDs. Nothing happens if id is not an element.

Errors#

• OutOfMemoryError if the Allocator cannot store the value. The attributes of the element can be unchanged or already changed.

Gotchas#

The replaced value stays in the storage of the document, so repeated calls make the document grow. XmlDocument.restore drops the replaced values.

XmlSnapshot#

pub struct XmlSnapshot

The attribute state of an XmlDocument at one moment, taken with XmlDocument.snapshot and put back with XmlDocument.restore.

When to use#

Use a snapshot when you apply values with XmlDocument.setAttribute many times, such as once for each frame of an animation. Restore the snapshot before each round, so that rounds do not see each other's values and the document does not grow with the number of rounds.

Details#

A snapshot owns a copy of the attribute list of the document. It does not borrow the document.

Implementation XmlDocument#

impl XmlDocument

Method snapshot#

pub effect fn snapshot(self: &XmlDocument) -> XmlSnapshot
    ! OutOfMemoryError
    ? &mut Allocator

Returns an XmlSnapshot of the current attributes of every element.

Details#

The snapshot copies the attribute list, so it costs memory proportional to the number of attributes and nodes. Pass it to XmlDocument.restore to undo later calls to XmlDocument.setAttribute.

Errors#

• OutOfMemoryError if the Allocator cannot supply the copy. The document does not change.

Method restore#

pub effect fn restore(self: &mut XmlDocument, snapshot: &XmlSnapshot) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Puts back the attributes recorded in snapshot, and drops every attribute value and name that XmlDocument.setAttribute stored since. Returns false, with no change, if snapshot cannot come from this document.

Details#

The storage of the document shrinks back to its size when the snapshot was taken. A snapshot can be restored any number of times.

Errors#

• OutOfMemoryError if the Allocator cannot supply the restored lists. The document can be partly restored. Restore the snapshot again to finish.

Gotchas#

The check compares sizes only. A snapshot of another document with the same number of nodes and no more storage passes the check and gives that document's attributes to this one.

XmlPseudoAttributes#

pub struct XmlPseudoAttributes

The pseudo-attributes of an xml-stylesheet processing instruction, such as href and type, read with XmlPseudoAttributes.parse.

Details#

The set owns the decoded names and values. Look one up with XmlPseudoAttributes.get.

Implementation XmlPseudoAttributes#

impl XmlPseudoAttributes

Method get#

pub fn get<'a>(self: &'a XmlPseudoAttributes, name: string) -> Option<string<'a>>

Returns the decoded value of pseudo-attribute name, or None if the set does not have it.

Details#

Names are compared exactly, with case. The result borrows the set.

Associated function parse#

pub effect fn parse(data: string, limits: &XmlLimits) -> XmlPseudoAttributes
    ! XmlError | OutOfMemoryError
    ? &mut Allocator

Parses data, the text of an xml-stylesheet processing instruction, as pseudo-attributes.

When to use#

Use this function on the result of XmlDocument.text for a processing instruction whose target is xml-stylesheet, to read the href, type, media, and other values that link a style sheet to the document.

Details#

The grammar is that of Associating Style Sheets with XML documents, Second Edition. Each pseudo-attribute is an XML name, =, and a quoted value. Only character references and the five predefined entity references are replaced, and white space in values is not normalized. limits bounds the length of data (maxInputBytes), the stored names and values (maxStorageBytes), the number of pseudo-attributes (maxAttributes), and the bytes that references add (maxExpandedBytes).

Errors#

• XmlError with XmlReason.DuplicateAttribute if a name appears two times.

• XmlError with XmlReason.UndeclaredEntity for a reference to another entity.

• XmlError with XmlReason.Limit if data exceeds a bound of limits.

• XmlError with another kind if data does not match the grammar. offset counts bytes of data.

• OutOfMemoryError if the Allocator cannot supply the set.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.