iri_string/

template.rs

//! 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
    }
}