iri_string/template/

string.rs

//! Template string types.

use core::fmt;

#[cfg(feature = "alloc")]
use alloc::borrow::Cow;
#[cfg(all(feature = "alloc", not(feature = "std")))]
use alloc::boxed::Box;
#[cfg(feature = "alloc")]
use alloc::rc::Rc;
#[cfg(feature = "alloc")]
use alloc::string::String;
#[cfg(feature = "alloc")]
use alloc::sync::Arc;

use crate::spec::Spec;
use crate::template::components::{VarListIter, VarName};
use crate::template::context::{Context, DynamicContext};
use crate::template::error::{Error, ErrorKind};
use crate::template::expand::{expand_whole_dynamic, Chunk, Chunks, Expanded};
use crate::template::parser::validate_template_str;

#[cfg(feature = "alloc")]
pub use self::owned::UriTemplateString;

/// Implements `PartialEq` and `PartialOrd`.
macro_rules! impl_cmp {
    ($ty_common:ty, $ty_lhs:ty, $ty_rhs:ty) => {
        impl PartialEq<$ty_rhs> for $ty_lhs {
            #[inline]
            fn eq(&self, o: &$ty_rhs) -> bool {
                <$ty_common as PartialEq<$ty_common>>::eq(self.as_ref(), o.as_ref())
            }
        }
        impl PartialEq<$ty_lhs> for $ty_rhs {
            #[inline]
            fn eq(&self, o: &$ty_lhs) -> bool {
                <$ty_common as PartialEq<$ty_common>>::eq(self.as_ref(), o.as_ref())
            }
        }
        impl PartialOrd<$ty_rhs> for $ty_lhs {
            #[inline]
            fn partial_cmp(&self, o: &$ty_rhs) -> Option<core::cmp::Ordering> {
                <$ty_common as PartialOrd<$ty_common>>::partial_cmp(self.as_ref(), o.as_ref())
            }
        }
        impl PartialOrd<$ty_lhs> for $ty_rhs {
            #[inline]
            fn partial_cmp(&self, o: &$ty_lhs) -> Option<core::cmp::Ordering> {
                <$ty_common as PartialOrd<$ty_common>>::partial_cmp(self.as_ref(), o.as_ref())
            }
        }
    };
}

#[cfg(feature = "alloc")]
mod owned;

/// A borrowed slice of a URI template.
///
/// URI Template is defined by [RFC 6570].
///
/// Note that "URI Template" can also be used for IRI.
///
/// [RFC 6570]: https://www.rfc-editor.org/rfc/rfc6570.html
///
/// # Valid values
///
/// This type can have a URI template string.
///
/// # Applied errata
///
/// [Errata ID 6937](https://www.rfc-editor.org/errata/eid6937) is applied, so
/// single quotes are allowed to appear in an URI template.
///
/// ```
/// # use iri_string::template::Error;
/// use iri_string::template::UriTemplateStr;
///
/// let template = UriTemplateStr::new("'quoted'")?;
/// # Ok::<_, Error>(())
/// ```
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
#[repr(transparent)]
#[derive(PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct UriTemplateStr {
    /// The raw string.
    inner: str,
}

impl UriTemplateStr {
    /// Creates a new string.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// use iri_string::template::UriTemplateStr;
    ///
    /// let template = UriTemplateStr::new("/users/{username}")?;
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    pub fn new(s: &str) -> Result<&Self, Error> {
        TryFrom::try_from(s)
    }

    /// Creates a new string without validation.
    ///
    /// This does not validate the given string, so it is caller's
    /// responsibility to ensure the given string is valid.
    ///
    /// # Safety
    ///
    /// The given string must be syntactically valid as `Self` type.
    /// If not, any use of the returned value or the call of this
    /// function itself may result in undefined behavior.
    #[inline]
    #[must_use]
    pub unsafe fn new_unchecked(s: &str) -> &Self {
        // SAFETY: `new_always_unchecked` requires the same precondition
        // as `new_always_unchecked`.
        unsafe { Self::new_always_unchecked(s) }
    }

    /// Creates a new string without any validation.
    ///
    /// This does not validate the given string at any time.
    ///
    /// Intended for internal use.
    ///
    /// # Safety
    ///
    /// The given string must be valid.
    #[inline]
    #[must_use]
    unsafe fn new_always_unchecked(s: &str) -> &Self {
        // SAFETY: the cast is safe since `Self` type has `repr(transparent)`
        // attribute and the content is guaranteed as valid by the
        // precondition of the function.
        unsafe { &*(s as *const str as *const Self) }
    }

    /// Returns the template as a plain `&str`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// use iri_string::template::UriTemplateStr;
    ///
    /// let template = UriTemplateStr::new("/users/{username}")?;
    /// assert_eq!(template.as_str(), "/users/{username}");
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn as_str(&self) -> &str {
        self.as_ref()
    }

    /// Returns the template string length.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// use iri_string::template::UriTemplateStr;
    ///
    /// let template = UriTemplateStr::new("/users/{username}")?;
    /// assert_eq!(template.len(), "/users/{username}".len());
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn len(&self) -> usize {
        self.as_str().len()
    }

    /// Returns whether the string is empty.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// use iri_string::template::UriTemplateStr;
    ///
    /// let template = UriTemplateStr::new("/users/{username}")?;
    /// assert!(!template.is_empty());
    ///
    /// let empty = UriTemplateStr::new("")?;
    /// assert!(empty.is_empty());
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.as_str().is_empty()
    }
}

impl UriTemplateStr {
    /// Expands the template with the given context.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// # #[cfg(feature = "alloc")] {
    /// use iri_string::spec::UriSpec;
    /// use iri_string::template::UriTemplateStr;
    /// use iri_string::template::simple_context::SimpleContext;
    ///
    /// let mut context = SimpleContext::new();
    /// context.insert("username", "foo");
    ///
    /// let template = UriTemplateStr::new("/users/{username}")?;
    /// let expanded = template.expand::<UriSpec, _>(&context)?;
    ///
    /// assert_eq!(
    ///     expanded.to_string(),
    ///     "/users/foo"
    /// );
    /// # }
    /// # Ok::<_, Error>(())
    /// ```
    ///
    /// You can control allowed characters in the output by changing spec type.
    ///
    /// ```
    /// # 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("alpha", "\u{03B1}");
    ///
    /// let template = UriTemplateStr::new("{?alpha}")?;
    ///
    /// assert_eq!(
    ///     template.expand::<UriSpec, _>(&context)?.to_string(),
    ///     "?alpha=%CE%B1",
    ///     "a URI cannot contain Unicode alpha (U+03B1), so it should be escaped"
    /// );
    /// assert_eq!(
    ///     template.expand::<IriSpec, _>(&context)?.to_string(),
    ///     "?alpha=\u{03B1}",
    ///     "an IRI can contain Unicode alpha (U+03B1), so it written as is"
    /// );
    /// # }
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    pub fn expand<'a, S: Spec, C: Context>(
        &'a self,
        context: &'a C,
    ) -> Result<Expanded<'a, S, C>, Error> {
        Expanded::new(self, context)
    }

    /// Expands the template with the given dynamic context.
    ///
    #[cfg_attr(
        feature = "alloc",
        doc = concat!(
            "If you need the allocated [`String`], use",
            "[`expand_dynamic_to_string`][`Self::expand_dynamic_to_string`]."
        )
    )]
    ///
    /// See the documentation for [`DynamicContext`] for usage.
    pub fn expand_dynamic<S: Spec, W: fmt::Write, C: DynamicContext>(
        &self,
        writer: &mut W,
        context: &mut C,
    ) -> Result<(), Error> {
        expand_whole_dynamic::<S, _, _>(self, writer, context)
    }

    /// Expands the template into a string, with the given dynamic context.
    ///
    /// This is basically [`expand_dynamic`][`Self::expand_dynamic`] method
    /// that returns an owned string instead of writing to the given writer.
    ///
    /// See the documentation for [`DynamicContext`] for usage.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[cfg(feature = "alloc")]
    /// # extern crate alloc;
    /// # use iri_string::template::Error;
    /// # #[cfg(feature = "alloc")] {
    /// # use alloc::string::String;
    /// use iri_string::template::UriTemplateStr;
    /// # use iri_string::template::context::{DynamicContext, Visitor, VisitPurpose};
    /// use iri_string::spec::UriSpec;
    ///
    /// struct MyContext<'a> {
    ///     // See the documentation for `DynamicContext`.
    /// #     /// Target path.
    /// #     target: &'a str,
    /// #     /// Username.
    /// #     username: Option<&'a str>,
    /// #     /// A flag to remember whether the URI template
    /// #     /// attempted to use `username` variable.
    /// #     username_visited: bool,
    /// }
    /// #
    /// # impl DynamicContext for MyContext<'_> {
    /// #     fn on_expansion_start(&mut self) {
    /// #         // Reset the state.
    /// #         self.username_visited = false;
    /// #     }
    /// #     fn visit_dynamic<V: Visitor>(&mut self, visitor: V) -> V::Result {
    /// #         match visitor.var_name().as_str() {
    /// #             "target" => visitor.visit_string(self.target),
    /// #             "username" => {
    /// #                 if visitor.purpose() == VisitPurpose::Expand {
    /// #                     // The variable `username` is being used
    /// #                     // on the template expansion.
    /// #                     // Don't care whether `username` is defined or not.
    /// #                     self.username_visited = true;
    /// #                 }
    /// #                 if let Some(username) = &self.username {
    /// #                     visitor.visit_string(username)
    /// #                 } else {
    /// #                     visitor.visit_undefined()
    /// #                 }
    /// #             }
    /// #             _ => visitor.visit_undefined(),
    /// #         }
    /// #     }
    /// # }
    ///
    /// let mut context = MyContext {
    ///     target: "/posts/1",
    ///     username: Some("the_admin"),
    ///     username_visited: false,
    /// };
    ///
    /// // No access to the variable `username`.
    /// let template = UriTemplateStr::new("{+target}{?username}")?;
    /// let s = template.expand_dynamic_to_string::<UriSpec, _>(&mut context)?;
    /// assert_eq!(s, "/posts/1?username=the_admin");
    /// assert!(context.username_visited);
    /// # }
    /// # Ok::<_, Error>(())
    /// ```
    #[cfg(feature = "alloc")]
    pub fn expand_dynamic_to_string<S: Spec, C: DynamicContext>(
        &self,
        context: &mut C,
    ) -> Result<String, Error> {
        let mut buf = String::new();
        expand_whole_dynamic::<S, _, _>(self, &mut buf, context)?;
        Ok(buf)
    }

    /// Returns an iterator of variables in the template.
    ///
    /// # Examples
    ///
    /// ```
    /// # use iri_string::template::Error;
    /// use iri_string::template::UriTemplateStr;
    ///
    /// let template = UriTemplateStr::new("foo{/bar*,baz:4}{?qux}{&bar*}")?;
    /// let mut vars = template.variables();
    /// assert_eq!(vars.next().map(|var| var.as_str()), Some("bar"));
    /// assert_eq!(vars.next().map(|var| var.as_str()), Some("baz"));
    /// assert_eq!(vars.next().map(|var| var.as_str()), Some("qux"));
    /// assert_eq!(vars.next().map(|var| var.as_str()), Some("bar"));
    /// # Ok::<_, Error>(())
    /// ```
    #[inline]
    #[must_use]
    pub fn variables(&self) -> UriTemplateVariables<'_> {
        UriTemplateVariables::new(self)
    }
}

impl fmt::Debug for UriTemplateStr {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_tuple("UriTemplateStr").field(&&self.inner).finish()
    }
}

impl AsRef<str> for UriTemplateStr {
    #[inline]
    fn as_ref(&self) -> &str {
        &self.inner
    }
}

impl AsRef<UriTemplateStr> for UriTemplateStr {
    #[inline]
    fn as_ref(&self) -> &UriTemplateStr {
        self
    }
}

#[cfg(feature = "alloc")]
impl<'a> From<&'a UriTemplateStr> for Cow<'a, UriTemplateStr> {
    #[inline]
    fn from(s: &'a UriTemplateStr) -> Self {
        Cow::Borrowed(s)
    }
}

#[cfg(feature = "alloc")]
impl From<&UriTemplateStr> for Arc<UriTemplateStr> {
    fn from(s: &UriTemplateStr) -> Self {
        let inner: &str = s.as_str();
        let buf = Arc::<str>::from(inner);
        // SAFETY: `UriTemplateStr` has `repr(transparent)` attribute, so
        // the memory layouts of `Arc<str>` and `Arc<UriTemplateStr>` are
        // compatible.
        unsafe {
            let raw: *const str = Arc::into_raw(buf);
            Self::from_raw(raw as *const UriTemplateStr)
        }
    }
}

#[cfg(feature = "alloc")]
impl From<&UriTemplateStr> for Box<UriTemplateStr> {
    fn from(s: &UriTemplateStr) -> Self {
        let inner: &str = s.as_str();
        let buf = Box::<str>::from(inner);
        // SAFETY: `UriTemplateStr` has `repr(transparent)` attribute, so
        // the memory layouts of `Box<str>` and `Box<UriTemplateStr>` are
        // compatible.
        unsafe {
            let raw: *mut str = Box::into_raw(buf);
            Self::from_raw(raw as *mut UriTemplateStr)
        }
    }
}

#[cfg(feature = "alloc")]
impl From<&UriTemplateStr> for Rc<UriTemplateStr> {
    fn from(s: &UriTemplateStr) -> Self {
        let inner: &str = s.as_str();
        let buf = Rc::<str>::from(inner);
        // SAFETY: `UriTemplateStr` has `repr(transparent)` attribute, so
        // the memory layouts of `Rc<str>` and `Rc<UriTemplateStr>` are
        // compatible.
        unsafe {
            let raw: *const str = Rc::into_raw(buf);
            Self::from_raw(raw as *const UriTemplateStr)
        }
    }
}

impl<'a> From<&'a UriTemplateStr> for &'a str {
    #[inline]
    fn from(s: &'a UriTemplateStr) -> &'a str {
        s.as_ref()
    }
}

impl<'a> TryFrom<&'a str> for &'a UriTemplateStr {
    type Error = Error;

    #[inline]
    fn try_from(s: &'a str) -> Result<Self, Self::Error> {
        match validate_template_str(s) {
            // SAFETY: just checked the string is valid.
            Ok(()) => Ok(unsafe { UriTemplateStr::new_always_unchecked(s) }),
            Err(e) => Err(e),
        }
    }
}

impl<'a> TryFrom<&'a [u8]> for &'a UriTemplateStr {
    type Error = Error;

    #[inline]
    fn try_from(bytes: &'a [u8]) -> Result<Self, Self::Error> {
        let s = core::str::from_utf8(bytes)
            .map_err(|e| Error::new(ErrorKind::InvalidUtf8, e.valid_up_to()))?;
        match validate_template_str(s) {
            // SAFETY: just checked the string is valid.
            Ok(()) => Ok(unsafe { UriTemplateStr::new_always_unchecked(s) }),
            Err(e) => Err(e),
        }
    }
}

impl_cmp!(str, str, UriTemplateStr);
impl_cmp!(str, &str, UriTemplateStr);
impl_cmp!(str, str, &UriTemplateStr);

impl fmt::Display for UriTemplateStr {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.as_str())
    }
}

/// Serde deserializer implementation.
#[cfg(feature = "serde")]
mod __serde_slice {
    use super::UriTemplateStr;

    use core::fmt;

    use serde::{
        de::{self, Visitor},
        Deserialize, Deserializer,
    };

    /// Custom borrowed string visitor.
    #[derive(Debug, Clone, Copy)]
    struct CustomStrVisitor;

    impl<'de> Visitor<'de> for CustomStrVisitor {
        type Value = &'de UriTemplateStr;

        #[inline]
        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("URI template string")
        }

        #[inline]
        fn visit_borrowed_str<E>(self, v: &'de str) -> Result<Self::Value, E>
        where
            E: de::Error,
        {
            <&'de UriTemplateStr as TryFrom<&'de str>>::try_from(v).map_err(E::custom)
        }
    }

    // About `'de` and `'a`, see
    // <https://serde.rs/lifetimes.html#the-deserializede-lifetime>.
    impl<'a, 'de: 'a> Deserialize<'de> for &'a UriTemplateStr {
        #[inline]
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserializer.deserialize_string(CustomStrVisitor)
        }
    }
}

/// An iterator of variables in a URI template.
#[derive(Debug, Clone)]
pub struct UriTemplateVariables<'a> {
    /// Chunks iterator.
    chunks: Chunks<'a>,
    /// Variables in the last chunk.
    vars_in_chunk: Option<VarListIter<'a>>,
}

impl<'a> UriTemplateVariables<'a> {
    /// Creates a variables iterator from the URI template.
    #[inline]
    #[must_use]
    fn new(template: &'a UriTemplateStr) -> Self {
        Self {
            chunks: Chunks::new(template),
            vars_in_chunk: None,
        }
    }
}

impl<'a> Iterator for UriTemplateVariables<'a> {
    type Item = VarName<'a>;

    fn next(&mut self) -> Option<Self::Item> {
        loop {
            if let Some(vars) = &mut self.vars_in_chunk {
                match vars.next() {
                    Some((_len, spec)) => return Some(spec.name()),
                    None => self.vars_in_chunk = None,
                }
            }
            let expr = self.chunks.find_map(|chunk| match chunk {
                Chunk::Literal(_) => None,
                Chunk::Expr(v) => Some(v),
            });
            self.vars_in_chunk = match expr {
                Some(expr) => Some(expr.decompose().1.into_iter()),
                None => return None,
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    use crate::spec::IriSpec;
    use crate::template::context::{AssocVisitor, ListVisitor, Visitor};

    struct TestContext;
    impl Context for TestContext {
        fn visit<V: Visitor>(&self, visitor: V) -> V::Result {
            match visitor.var_name().as_str() {
                "str" => visitor.visit_string("string"),
                "list" => visitor
                    .visit_list()
                    .visit_items_and_finish(["item0", "item1", "item2"]),
                "assoc" => visitor
                    .visit_assoc()
                    .visit_entries_and_finish([("key0", "value0"), ("key1", "value1")]),
                _ => visitor.visit_undefined(),
            }
        }
    }

    #[test]
    fn expand_error_pos() {
        {
            let e = UriTemplateStr::new("foo{list:4}")
                .unwrap()
                .expand::<IriSpec, _>(&TestContext)
                .err()
                .map(|e| e.location());
            assert_eq!(e, Some("foo{".len()));
        }

        {
            let e = UriTemplateStr::new("foo{/list*,list:4}")
                .unwrap()
                .expand::<IriSpec, _>(&TestContext)
                .err()
                .map(|e| e.location());
            assert_eq!(e, Some("foo{/list*,".len()));
        }

        {
            let e = UriTemplateStr::new("foo{/str:3,list*,assoc:4}")
                .unwrap()
                .expand::<IriSpec, _>(&TestContext)
                .err()
                .map(|e| e.location());
            assert_eq!(e, Some("foo{/str:3,list*,".len()));
        }
    }
}