xrust

χrust (pronounced "crust") is a Rust library providing implementations for XPath, XQuery, and XSLT. It includes an XML parser based on a parser combinator approach.

Current Capabilities:

• Functional equivalent of XPath 1.0 and XSLT 1.0.
• Implements the XQuery and XPath Data Model (XDM) 3.1.
• Supports advanced features like FLWR expressions, grouping (xsl:for-each-group), and user-defined functions.

Note on Compliance: While it implements the core elements of v1.0, it is not strictly compliant with v1.0 standards because it uses the v3.0 data model.

The "Tree" is the fundamental data object used for transformations in χrust. It is implemented via a library called smite.

Key Characteristics:

• Fully Navigable: From any given node, you can access its children, parent, siblings, or attributes.
• Mutable: It achieves mutability through the interior mutability pattern (the name "smite" is an anagram of "tuple struct enum interior mutability").

The library follows a design that separates parsing from evaluation.

1. Compilation Phase: XPath expressions or XSLT stylesheets are parsed (compiled) into an internal representation called a "transformation".
2. Evaluation Phase: The resulting transformation is then evaluated against data.

This design ensures that different syntaxes that represent the same logic result in the same internal transformation format. For example, an XPath if $a then "a is true" else "" will compile to the same internal form as an XSLT <xsl:if test="$a">a is true</xsl:if>.

Namespace support in χrust is implemented across three layers:

1. Parsing: The XML parser uses a NamespaceMap (a flat mapping of prefix to URI) to track in-scope namespaces during construction.
2. Tree Representation: The smite tree implementation includes a Namespace type node to represent XML Namespace declarations. NamespaceNode objects are Rc-shared for efficiency.
3. Transformations: Transformations can store a NamespaceMap to use during the transformation process.

A convenience routine is provided to build a NamespaceMap from Namespace node declarations.

Because XML documents and XSLT stylesheets can access external resources, χrust implements a "secure by default" security model. By default, access to external resources is restricted (often completely).

Security Components:

• Security Feature: A module defines a feature that determines if resource access is permitted and may impose limits (e.g., limiting the size of an external entity).
• Security Policy: An application creates a policy containing multiple features. When a module attempts to access a resource, it looks up the required feature in the current policy to decide if the action is allowed.

To evaluate an XSL stylesheet, refer to the documentation for the XSLT module.

Note: Detailed API usage examples are located in the official XSLT module documentation.

The module provides two ways to copy items:

1. copy (Shallow Copy): Selects items using a Transform s, performs a shallow copy, and then constructs new content for each copied item using a second Transform c.
2. deep_copy: Selects items using a Transform s and returns a sequence of fully independent deep copies of those items.

To prevent infinite loops during transformation, you can limit the maximum evaluation depth. This is controlled via the max_depth field in Context or by setting a security policy.

In XSLT, this can be controlled via the feature URI: Q{http://gitlab.gnome.org/World/Rust/markup-rs/xrust/transform}maximum-depth

Security results for this feature:

• NotPermitted: Uses the default value.
• Permitted (no value): No limit.
• Permitted (with value): The provided number is the maximum depth.

The security module allows you to define and enforce restrictions to prevent data exfiltration or denial-of-service attacks.

Security is managed through three layers:

1. Feature: A specific capability or access type defined by a module.
2. Policy: A combination of Features that defines what is allowed.
3. Restriction: A policy can permit a feature but further restrict it with specific limits.

To select or filter nodes, use NodeMatch, which combines an Axis with a NodeTest.

NodeTest Types

• Kind(KindTest): Matches based on the node type (e.g., Element, Attribute, Text, Comment, PI, Document).
• Name(NameTest): Matches based on the node's name, supporting:
  • Exact QName matches.
  • Wildcards for namespaces or local names (e.g., *:local-name or prefix:*).

Axis Types

Axis defines the direction of navigation in the tree. Common axes include:

• Child, Descendant, DescendantOrSelf.
• Parent, Ancestor, AncestorOrSelf.
• Following, FollowingSibling, Preceding, PrecedingSibling.
• Attribute, SelfAxis, SelfDocument, SelfNamespace.

The Grouping<N> enum determines how a collection is divided into groups during operations like ForEach.

Supported grouping methods:

• By(Vec<Transform<N>>): Groups items based on the result of a transformation.
• StartingWith(Box<Pattern<N>>): Groups items based on a pattern match at the start.
• EndingWith(Box<Pattern<N>>): Groups items based on a pattern match at the end.
• Adjacent(Vec<Transform<N>>): Groups adjacent items based on a transformation.