//! Processor for [RFC 6570] URI Template.
//!
//! [RFC 6570]: https://www.rfc-editor.org/rfc/rfc6570.html
//!
//! # Usage
//!
//! 1. Prepare a template.
//! * You can create a template as [`UriTemplateStr`]
#![cfg_attr(
feature = "alloc",
doc = " type (borrowed) or [`UriTemplateString`] type (owned)."
)]
#![cfg_attr(not(feature = "alloc"), doc = " type.")]
//! 2. Prepare a context.
//! * Create a value of type that implements [`Context`] trait.
#![cfg_attr(
feature = "alloc",
doc = " * Or, if you use [`SimpleContext`], insert key-value pairs into it."
)]
//! 3. Expand.
//! * Pass the context to [`UriTemplateStr::expand`] method of the template.
//! 4. Use the result.
//! * Returned [`Expanded`] object can be directly printed since it
//! implements [`Display`][`core::fmt::Display`] trait. Or, you can call
//! `.to_string()` method of the `alloc::string::ToString` trait to
//! convert it to a `String`.
//!
//! # Examples
//!
//! ## Custom context type
//!
//! For details, see [the documentation of `context` module][`context`].
//!
//! ```
//! # use iri_string::template::Error;
//! use core::fmt;
//! use iri_string::spec::{IriSpec, Spec, UriSpec};
//! use iri_string::template::UriTemplateStr;
//! use iri_string::template::context::{Context, VarName, Visitor};
//!
//! struct UserInfo {
//! username: &'static str,
//! utf8_available: bool,
//! }
//!
//! impl Context for UserInfo {
//! fn visit<V: Visitor>(
//! &self,
//! visitor: V,
//! ) -> V::Result {
//! match visitor.var_name().as_str() {
//! "username" => visitor.visit_string(self.username),
//! "utf8" => {
//! if self.utf8_available {
//! // U+2713 CHECK MARK
//! visitor.visit_string("\u{2713}")
//! } else {
//! visitor.visit_undefined()
//! }
//! }
//! _ => visitor.visit_undefined()
//! }
//! }
//! }
//!
//! let context = UserInfo {
//! username: "foo",
//! utf8_available: true,
//! };
//!
//! let template = UriTemplateStr::new("/users/{username}{?utf8}")?;
//!
//! # #[cfg(feature = "alloc")] {
//! assert_eq!(
//! template.expand::<UriSpec, _>(&context)?.to_string(),
//! "/users/foo?utf8=%E2%9C%93"
//! );
//! assert_eq!(
//! template.expand::<IriSpec, _>(&context)?.to_string(),
//! "/users/foo?utf8=\u{2713}"
//! );
//! # }
//! # Ok::<_, Error>(())
//! ```
//!
//! ## `SimpleContext` type (enabled by `alloc` feature flag)
//!
//! ```
//! # use iri_string::template::Error;
//! # #[cfg(feature = "alloc")] {
//! use iri_string::spec::{IriSpec, UriSpec};
//! use iri_string::template::UriTemplateStr;
//! use iri_string::template::simple_context::SimpleContext;
//!
//! let mut context = SimpleContext::new();
//! context.insert("username", "foo");
//! // U+2713 CHECK MARK
//! context.insert("utf8", "\u{2713}");
//!
//! let template = UriTemplateStr::new("/users/{username}{?utf8}")?;
//!
//! assert_eq!(
//! template.expand::<UriSpec, _>(&context)?.to_string(),
//! "/users/foo?utf8=%E2%9C%93"
//! );
//! assert_eq!(
//! template.expand::<IriSpec, _>(&context)?.to_string(),
//! "/users/foo?utf8=\u{2713}"
//! );
//! # }
//! # Ok::<_, Error>(())
//! ```
//!
#![cfg_attr(
feature = "alloc",
doc = "[`SimpleContext`]: `simple_context::SimpleContext`"
)]
mod components;
pub mod context;
mod error;
mod expand;
mod parser;
#[cfg(feature = "alloc")]
pub mod simple_context;
mod string;
pub use self::context::{Context, DynamicContext};
#[cfg(feature = "alloc")]
pub use self::error::CreationError;
pub use self::error::Error;
pub use self::expand::Expanded;
#[cfg(feature = "alloc")]
pub use self::string::UriTemplateString;
pub use self::string::{UriTemplateStr, UriTemplateVariables};
/// Deprecated old name of [`template::context::VarName`].
///
/// [`template::context::VarName`]: `components::VarName`
#[deprecated(
since = "0.7.1",
note = "renamed (moved) to `template::context::VarName`"
)]
pub type VarName<'a> = self::components::VarName<'a>;
/// Variable value type.
#[derive(Debug, Clone, Copy)]
enum ValueType {
/// Undefined (i.e. null).
Undefined,
/// String value.
String,
/// List.
List,
/// Associative array.
Assoc,
}
impl ValueType {
/// Returns the value type for an undefined variable.
#[inline]
#[must_use]
pub const fn undefined() -> Self {
ValueType::Undefined
}
/// Returns the value type for a string variable.
#[inline]
#[must_use]
pub const fn string() -> Self {
ValueType::String
}
/// Returns the value type for an empty list variable.
#[inline]
#[must_use]
pub const fn empty_list() -> Self {
ValueType::Undefined
}
/// Returns the value type for a nonempty list variable.
#[inline]
#[must_use]
pub const fn nonempty_list() -> Self {
ValueType::List
}
/// Returns the value type for an empty associative array variable.
#[inline]
#[must_use]
pub const fn empty_assoc() -> Self {
ValueType::Undefined
}
/// Returns the value type for a nonempty associative array variable.
#[inline]
#[must_use]
pub const fn nonempty_assoc() -> Self {
ValueType::Assoc
}
}
