xrust 1.2.4

Support for XPath and XSLT
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

/*!
A 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].

## Transformation

A [Transform] is used to create a [Sequence], starting with a [Context].

A [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].

Once a [Context] is configured, it can be used to execute a [Transform] using the evaluate method. The return result is a new [Sequence].

## Trees

The [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.

The module trees::intmuttree is an implementation of the [Node] trait.

## Parsing XML

Parsing XML documents is done using the built-in parser combinator: [parser]. The parser supports XML Namespaces, and DTDs (entities, but not validation).

## XPath

Support for XPath involves mapping the XPath syntax to a [Transform]. The XPath parser maps an expression to a [Transform].

### Patterns

XPath [Pattern]s are also supported. These are used to match nodes, mainly when template processing.

### Status

Most of functionality for v1.0 is present, with some v2.0 and v3.1 features.

## XSLT

Support 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.

### Status

The 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.

It 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.

NB, the library has not been extensively tested.

### External Resources

One 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.

## Plan

1. Complete the XPath 1.0 implementation. (Done!)
2. Implement all v1.0 XSLT functionality. (Done!)
3. Implement all XPath 3.1 data model, data types, and functions.
4. Complete the v3.1 XSLT engine.

## Contributions

We need your help!

- Download the crate and try it out. Tell us what you like or don't like. How can it be improved?
- 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://github.com/ballsteve/xrust/issues/new/choose)
- Let us know what doesn't work. [Submit a bug report.](https://github.com/ballsteve/xrust/issues/new/choose)
- Do you need more documentation? There can never be enough! [Submit an RFE.](https://github.com/ballsteve/xrust/issues/new/choose)
- Add some tests.
- Write some code. The χrust Wiki has a [list of desired features](https://github.com/ballsteve/xrust/wiki/Help-Wanted).
- Donate resources (i.e. $$$)

*/

pub mod xdmerror;
pub use xdmerror::{Error, ErrorKind};

pub mod externals;
pub mod output;
pub mod qname;
pub mod xmldecl;

pub mod value;
pub use value::Value;
pub mod item;
pub use item::{Item, Node, Sequence, SequenceTrait};

pub mod pattern;
pub use pattern::Pattern;

#[cfg(feature = "xslt")]
pub mod xslt;

pub mod parser;

pub mod transform;
pub use transform::context::Context;
pub use transform::template::Template;
pub use transform::Transform;

pub mod trees;

pub mod namespace;
pub mod testutils;
pub mod validators;