Crate uri_template_system

uri-template-system

URI Templates (RFC6570) are an underrated tool for web programming. They regularise the construction of URIs and related forms, removing the need for ad-hoc string manipulation, and can help provide consistency across complex web applications.

use uri_template_system_core::{ Template, Value, Values };

let template = Template::parse("/hello/{name}/from{/library*}").unwrap();
let values = Values::default()
    .add("name", Value::item("world"))
    .add("library", Value::list(["uri", "template", "system"]));

assert_eq!(
    template.expand(&values).unwrap(),
    "/hello/world/from/uri/template/system"
);

Beyond the scope of the RFC itself, they can also be used (with some judgement) for matching URIs and related forms as well, effectively providing the basis for a routing mechanism which can be driven from the same data as the linking mechanism. No more mismatches between linking and routing.

Scope

This library provides an implementation of URI Templates which complies with the RFC and passes the standard test cases for parsing and expansion.

Future iterations will extend this to provide matching for both single and multiple URI templates, routing based on URI Template matching, and support for strongly-typed template data. See the milestones for the latest progress and for more detailed descriptions of planned features.

Goals

Existing implementations of URI Templates exist for Rust, notably rust-uritemplate and the various forks of that implementation, and an implementation in the broader iri-string library.

This implementation aims to be both more “correct” (the parser is intentionally strict with regards to the RFC, while the existing implementations allow some malformed templates through as valid) and more structured in terms of underlying representation (with the aim of making additional features such as matching more tractable). Performance is also important, and the implementation is roughly on-par with – or slightly quicker than – iri-string (the rust-uritemplate derivations have a slightly different programming model, but even allowing for this, they are generally significantly slower).

Benchmarks and RFC-compliance tests (and test harnesses) can be found in the tests directory - as always, benchmarks are indicative but performance under real-world conditions will always vary.

Structs

• Template
  The Template type is the basis for most simple tasks. Parsing and expansion are both template functions.
• Values
  The Values type is used as the source of content during template expansion, and is a logical map of keys to typed Value (which may or may not be present during expansion).

Enums

• ExpandError
  An Error compatible type which may be the result of a failure of Template::expand (given a valid Template and provided Values).
• ParseError
  An Error compatible type which may be the result of a failure of Template::parse, likely due to an invalid URI Template format (as defined by the grammar given in RFC6570).
• Value
  The Value type is used as the source of content during template expansion, as part of a Values collection. It maps to the three valid shapes of data defined by the RFC (a single item, a list of items, or a list of key/value pairs).