xrust/
lib.rs

1/*!
2A Rust implementation of the [XQuery and XPath Data Model 3.1](https://www.w3.org/TR/xpath-datamodel-31/) and [XSLT 3.0](http://www.w3.org/TR/xslt-30/). The idea is to separate the syntax from the semantics. A [Transform] performs the semantics; an XPath expression or XSL Stylesheet is the syntax that is mapped to a [Transform].
3
4## Transformation
5
6A [Transform] is used to create a [Sequence], starting with a [Context].
7
8A [Sequence] is the basic data type in XPath. It is an ordered collection of zero or more [Item]s, implemented as a Rust vector, i.e. ```Vec<Rc<Item>>```. An [Item] is a [Node], Function, or atomic [Value].
9
10Once a [Context] is configured, it can be used to execute a [Transform] using the evaluate method. The return result is a new [Sequence].
11
12## Trees
13
14The [Transform] engine reads a tree structure as its source document and produces a tree structure as its result document. The tree needs to be both navigable and mutable. Tree nodes are defined by the [Item] module's [Node] trait.
15
16The module trees::intmuttree is an implementation of the [Node] trait.
17
18## Parsing XML
19
20Parsing XML documents is done using the built-in parser combinator: [parser]. The parser supports XML Namespaces, and DTDs (entities, but not validation).
21
22## XPath
23
24Support for XPath involves mapping the XPath syntax to a [Transform]. The XPath parser maps an expression to a [Transform].
25
26### Patterns
27
28XPath [Pattern]s are also supported. These are used to match nodes, mainly when template processing.
29
30### Security
31
32The [Security](crate::security) module provides a mechanism to prevent exfiltration of data or denial-of-service attacks.
33A module may define a security [Feature](crate::security::Feature) that are then combined into a security [Policy](crate::security::Policy).
34A security policy may permit or deny access to a feature. If it is permitted then the policy may further restrict access to some limit.
35
36### Status
37
38Most of functionality for v1.0 is present, with some v2.0 and v3.1 features.
39
40## XSLT
41
42Support for XSLT involves mapping an XSL Stylesheet to a [Context]. The [xslt] module provides the ```from_document``` function that returns a [Context] populated with [Template]s, given an XSL Stylesheet document.
43
44### Status
45
46The XSLT implementation is functionally equivalent to XSLT 1.0, but is not compliant to v1.0. This is because Xrust implements the v3.0 data model. All the elements and functions in XPath 1.0 and XSLT 1.0 are implemented.
47
48It supports basic templating, literal result elements, element, text, attribute, comment and processing instruction creation, sequence, and messages. Also, conditionals (if, choose), repetition (for-each, for-each-group), copying (copy, copy-of), and inclusion/importing.
49
50NB, the library has not been extensively tested.
51
52### External Resources
53
54One aim of the library is to be usable in a WASM environment. To allow that, the library must not have dependencies on file and network I/O, since that is provided by the host browser environment. Where external resources, i.e. URLs, are required the application must provide a closure. In particular, closures must be provided for stylesheet inclusion and importing, as well as for messages.
55
56## Plan
57
581. Complete the XPath 1.0 implementation. (Done!)
592. Implement all v1.0 XSLT functionality. (Done!)
603. Implement all XPath 3.1 data model, data types, and functions.
614. Complete the v3.1 XSLT engine.
62
63## Contributions
64
65We need your help!
66
67- Download the crate and try it out. Tell us what you like or don't like. How can it be improved?
68- There are definitely gaps and missing parts in the v1.0 XPath and XSLT implementation. Let us know if you need them fixed. [Submit a bug report.](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/issues)
69- Let us know what doesn't work. [Submit a bug report.](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/issues)
70- Do you need more documentation? There can never be enough! [Submit an RFE.](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/issues)
71- Add some tests.
72- Write some code. The χrust Wiki has a [list of desired features](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/wikis/home).
73- Donate resources (i.e. $$$)
74
75*/
76
77pub mod xdmerror;
78pub use xdmerror::{Error, ErrorKind};
79
80pub mod externals;
81pub mod output;
82pub mod xmldecl;
83
84pub mod value;
85pub use value::Value;
86pub mod item;
87pub use item::{Item, Node, Sequence, SequenceTrait};
88
89pub mod pattern;
90pub use pattern::Pattern;
91
92#[cfg(feature = "xslt")]
93pub mod xslt;
94
95pub mod parser;
96
97pub mod transform;
98pub use transform::Transform;
99pub use transform::context::Context;
100pub use transform::template::Template;
101
102pub mod trees;
103
104pub mod security;
105
106pub mod testutils;
107pub mod validators;
xrust/lib.rs

xrust/
lib.rs
