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### Status
31
32Most of functionality for v1.0 is present, with some v2.0 and v3.1 features.
33
34## XSLT
35
36Support 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.
37
38### Status
39
40The 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.
41
42It 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.
43
44NB, the library has not been extensively tested.
45
46### External Resources
47
48One 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.
49
50## Plan
51
521. Complete the XPath 1.0 implementation. (Done!)
532. Implement all v1.0 XSLT functionality. (Done!)
543. Implement all XPath 3.1 data model, data types, and functions.
554. Complete the v3.1 XSLT engine.
56
57## Contributions
58
59We need your help!
60
61- Download the crate and try it out. Tell us what you like or don't like. How can it be improved?
62- 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)
63- Let us know what doesn't work. [Submit a bug report.](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/issues)
64- Do you need more documentation? There can never be enough! [Submit an RFE.](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/issues)
65- Add some tests.
66- Write some code. The χrust Wiki has a [list of desired features](https://gitlab.gnome.org/World/Rust/markup-rs/xrust/-/wikis/home).
67- Donate resources (i.e. $$$)
68
69*/
70
71pub mod xdmerror;
72pub use xdmerror::{Error, ErrorKind};
73
74pub mod externals;
75pub mod output;
76pub mod xmldecl;
77
78pub mod value;
79pub use value::Value;
80pub mod item;
81pub use item::{Item, Node, Sequence, SequenceTrait};
82
83pub mod pattern;
84pub use pattern::Pattern;
85
86#[cfg(feature = "xslt")]
87pub mod xslt;
88
89pub mod parser;
90
91pub mod transform;
92pub use transform::Transform;
93pub use transform::context::Context;
94pub use transform::template::Template;
95
96pub mod trees;
97
98pub mod testutils;
99pub mod validators;
xrust/lib.rs

xrust/
lib.rs
