komichi 2.2.0

use camino::Utf8Path;
use std::collections::VecDeque;
use unicode_segmentation::UnicodeSegmentation;

use crate::error::{
    ExpandIdentifierError, ExpandTextError, IdentifierKeyError,
};

#[doc(hidden)]
#[derive(Debug, Clone, PartialEq)]
pub enum Token {
    Identifier(String),
    Text(String),
    NewLine,
}

impl Token {
    fn new_text(text: &str) -> Self {
        let text = text.to_string();
        Self::Text(text)
    }
}

enum CapturingState {
    Pre,
    Enabled,
    Post,
}
// | 000 | 001 | 002 | 003 | 004 | 005 | 006 | 007 | 008 | 009 | 010 | 011 | 012 | 013 | 014 | 015
// |  a  |     |  b  |  o  |  t  |     |  $  |  {  |  _  |  a  |  }  |
// |  a  |     |  b  |  o  |  t  |     |  $  |  $  |  {  |  _  |  a  |  }  |

#[doc(hidden)]
pub struct WideChars<'a> {
    wide_chars: Vec<&'a str>,
    started: bool,
    index: usize,
}

impl<'a> WideChars<'a> {
    pub fn new(data: &'a str) -> Self {
        let wide_chars = UnicodeSegmentation::graphemes(data, true)
            .collect::<Vec<&str>>();

        Self {
            wide_chars,
            started: false,
            index: 0_usize,
        }
    }

    pub fn get(
        &self,
        index: usize,
    ) -> Option<&'a str> {
        match self.wide_chars.get(index) {
            Some(out) => Some(*out),
            None => None,
        }
    }

    pub fn bump_index(&mut self) {
        self.index += 1;
    }

    pub fn get_index(&self) -> usize {
        self.index
    }

    pub fn set_index(
        &mut self,
        index: usize,
    ) {
        self.index = index;
    }
}

impl<'a> Iterator for WideChars<'a> {
    type Item = &'a str;

    fn next(&mut self) -> Option<&'a str> {
        if self.started {
            self.index += 1;
        } else {
            self.started = true;
        }
        let out = self.get(self.index);
        if out.is_none() && self.index > 0 {
            self.index -= 1;
        }
        out
    }
}

pub struct TokenIterator<'a> {
    wide_chars: WideChars<'a>,
    token_cache: VecDeque<Token>,
    line_number: usize,
}

impl<'a> TokenIterator<'a> {
    pub fn new(text: &'a str) -> Self {
        let wide_chars = WideChars::new(text);
        let token_cache: VecDeque<Token> =
            VecDeque::with_capacity(2);
        Self {
            wide_chars,
            token_cache,
            line_number: 0_usize,
        }
    }
    fn get_identifier(
        &mut self,
        wide_char: &str,
    ) -> Result<Option<String>, IdentifierKeyError> {
        if wide_char != "$" {
            return Ok(None);
        }
        let mut index = self.wide_chars.get_index();
        let next_wide_char = match self.wide_chars.get(index + 1) {
            Some(nwc) => nwc,
            None => return Ok(None),
        };
        if next_wide_char == "$" {
            self.wide_chars.bump_index();
            return Ok(None);
        }

        if next_wide_char != "{" {
            return Err(IdentifierKeyError::missing_starting_curly(
                index + 1,
            ));
        }
        index += 2;
        let starting_curly_index = index;
        let mut state = CapturingState::Pre;
        let mut out = String::new();
        let mut has_closing_curly = false;
        let mut first_identifier_character_index = 0_usize;
        while let Some(wchar) = self.wide_chars.get(index) {
            if !wchar.is_ascii() {
                return Err(IdentifierKeyError::non_ascii(index));
            }
            if wchar == "}" {
                has_closing_curly = true;
                break;
            }
            match state {
                CapturingState::Pre => {
                    if wchar == " " {
                        index += 1;
                        continue;
                    }
                    if wchar
                        .chars()
                        .all(|x| x.is_alphanumeric() || x == '_')
                    {
                        state = CapturingState::Enabled;
                        out.push_str(wchar);
                        first_identifier_character_index = index;
                        index += 1;
                        continue;
                    } else {
                        return Err(IdentifierKeyError::non_alpha_numeric_underscore(index));
                    }
                },
                CapturingState::Enabled => {
                    if wchar == " " {
                        state = CapturingState::Post;
                        index += 1;
                        continue;
                    }
                    if !wchar
                        .chars()
                        .all(|x| x.is_alphanumeric() || x == '_')
                    {
                        return Err(IdentifierKeyError::non_alpha_numeric_underscore(index));
                    }
                    index += 1;
                    out.push_str(wchar);
                    continue;
                },
                CapturingState::Post => {
                    if wchar == " " {
                        index += 1;
                        continue;
                    } else {
                        return Err(
                            IdentifierKeyError::invalid_name(index),
                        );
                    }
                },
            }
        }

        if !has_closing_curly {
            return Err(IdentifierKeyError::missing_closing_curly(
                starting_curly_index,
            ));
        }
        if out.is_empty() {
            return Err(IdentifierKeyError::empty_identifier_name(
                index - 1,
            ));
        }

        let first_char = out
            .chars()
            .next()
            .expect("Should have at lest one character");
        if first_char.is_numeric() {
            return Err(IdentifierKeyError::starts_with_number(
                first_identifier_character_index,
            ));
        }
        self.wide_chars.set_index(index);
        Ok(Some(out))
    }
}

impl Iterator for TokenIterator<'_> {
    type Item = Result<Token, ExpandIdentifierError>;

    fn next(&mut self) -> Option<Self::Item> {
        #[allow(clippy::never_loop)]
        while let Some(out) = self.token_cache.pop_front() {
            return Some(Ok(out));
        }
        let mut text = String::new();
        while let Some(wide_char) = self.wide_chars.next() {
            let identifier = match self.get_identifier(wide_char) {
                Ok(identifier) => identifier,
                Err(e) => {
                    return Some(Err(
                        ExpandIdentifierError::key_error(
                            self.line_number,
                            e,
                        ),
                    ));
                },
            };

            if let Some(identifier_name) = identifier {
                if !text.is_empty() {
                    self.token_cache
                        .push_back(Token::new_text(&text));
                    text.clear();
                }
                self.token_cache
                    .push_back(Token::Identifier(identifier_name));
                break;
            }
            if wide_char == "\n" {
                if !text.is_empty() {
                    self.token_cache
                        .push_back(Token::new_text(&text));
                    text.clear();
                }
                self.token_cache.push_back(Token::NewLine);
                self.line_number += 1;
                break;
            }
            text.push_str(wide_char);
        }
        if !text.is_empty() {
            self.token_cache.push_back(Token::new_text(&text));
            text.clear();
        }
        #[allow(clippy::never_loop)]
        while let Some(out) = self.token_cache.pop_front() {
            return Some(Ok(out));
        }
        None
    }
}

/// Provide the ability to expand BASH-like-curly-variables in text or in a
/// file.
///
/// This struct will only expand BASH-like-curly-variables (e.g. `${VAR}`).
/// This struct will not expand any non-curly-BASH-variables (e.g. `$VAR`).
///
/// The `$` character can be escaped by using two `$` characters e.g. `$$`.
///
/// # Example
///
/// ```
/// use komichi::ExpandText;
///
/// fn fetcher(key: &str) -> Option<String> {
///     match key {
///         "COLOR" => Some(String::from("brown")),
///         "animal" => Some(String::from("dog")),
///         _ => None
///     }
/// }
///
/// // Expand a simple string
/// let expect = "The quick brown fox jumps over the lazy dog";
/// let arg = "The quick ${COLOR} fox jumps over the lazy ${animal}";
/// let expand = ExpandText::new(fetcher);
///
/// let result = expand.text(arg).unwrap();
///
/// assert_eq!(result, expect);
///
/// // Expand the contents of a file (in this case a temp file)
/// use tempfile::NamedTempFile;
/// use camino::Utf8Path;
/// use std::io::Write;
///
/// let expect = "The playful brown fox runs into the sleeping dog";
/// let text = "The playful ${COLOR} fox runs into the sleeping ${animal}";
///
/// let mut file = NamedTempFile::new().expect("unable to create temp file");
/// file.write_all(text.as_bytes()).unwrap();
/// let path = Utf8Path::from_path(file.path()).unwrap();
///
/// let result = expand.file(&path).unwrap();
/// drop(file);
///
/// assert_eq!(result, expect);
/// ```
pub struct ExpandText {
    fetch_function: fn(&str) -> Option<String>,
}

impl ExpandText {
    pub fn new(fetch_function: fn(&str) -> Option<String>) -> Self {
        Self { fetch_function }
    }

    #[inline]
    fn _text(
        &self,
        text: &str,
    ) -> Result<String, ExpandIdentifierError> {
        let tokens = TokenIterator::new(text);
        let mut out = String::new();
        for token in tokens {
            let token = token?;
            match token {
                Token::Text(text) => out.push_str(&text),
                Token::Identifier(key) => {
                    if let Some(value) = (self.fetch_function)(&key)
                    {
                        out.push_str(&value);
                    } else {
                        out.push_str(format!("${{{key}}}").as_str());
                    }
                },
                Token::NewLine => out.push('\n'),
            }
        }
        Ok(out)
    }
    /// Return the given text, containing bash-like-curly variables that are
    /// expanded with values from this struct's callback function.
    ///
    /// The text can contain BASH-like variables with each variable using
    /// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
    /// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
    /// identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// Any identifier that does not have a value, as given by the callback
    /// function will be skipped. Meaning that the BASH-like variable will be
    /// put back into the output.
    ///
    /// # Arguments
    /// * `text` - A string-slice containing the text-to-be-expanded
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`).
    pub fn text(
        &self,
        text: &str,
    ) -> Result<String, ExpandTextError> {
        Ok(self._text(text)?)
    }

    #[inline]
    fn _text_strict(
        &self,
        text: &str,
    ) -> Result<String, ExpandIdentifierError> {
        let tokens = TokenIterator::new(text);
        let mut out = String::new();
        for token in tokens {
            let token = token?;
            match token {
                Token::Text(text) => out.push_str(&text),
                Token::Identifier(key) => {
                    if let Some(value) = (self.fetch_function)(&key)
                    {
                        out.push_str(&value);
                    } else {
                        return Err(
                            ExpandIdentifierError::ValueError(key),
                        );
                    }
                },
                Token::NewLine => out.push('\n'),
            }
        }
        Ok(out)
    }

    /// Return the given text, containing bash-like-curly variables that are
    /// expanded with values from the given callback-function. And return
    /// an [`ExpandTextError`] when a value cannot be found by the given
    /// callback-function
    ///
    /// The text can contain BASH-like variables with each variable using
    /// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
    /// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
    /// identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// # Arguments
    /// * `text` - A string-slice containing the text-to-be-expanded
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`),
    ///   * if the value for any identifier cannot be returned by the given
    ///     callback-function.
    pub fn text_strict(
        &self,
        text: &str,
    ) -> Result<String, ExpandTextError> {
        Ok(self._text_strict(text)?)
    }

    /// Return the given file's text, containing bash-like-curly variables
    /// that are expanded with values from this struct's callback function.
    ///
    /// The file-contents can contain BASH-like variables with each variable
    /// using the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like
    /// variables that do not contain curly brackets (e.g. `$DOG_NAME`) will
    /// become identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// # Arguments
    /// * path - a string-like reference to a [`str`] containing the path
    ///   that will be expanded.
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any problems opening the given file path
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the
    ///       curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an
    ///       underscore or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`).
    pub fn file<T>(
        &self,
        path: &T,
    ) -> Result<String, ExpandTextError>
    where
        T: AsRef<Utf8Path> + ?Sized,
    {
        let path = path.as_ref();
        let text = std::fs::read_to_string(path).map_err(|e| {
            ExpandTextError::read_file_error(path, e)
        })?;
        self._text(&text).map_err(|e| {
            ExpandTextError::identifier_error_in_file(path, e)
        })
    }

    /// Return the given file's text, containing bash-like-curly variables that
    /// are expanded with values from this struct's callback function and
    /// return an [`ExpandTextError`] if the value cannot be retrieved.
    ///
    /// The file-contents can contain BASH-like variables with each variable
    /// using the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like
    /// variables that do not contain curly brackets (e.g. `$DOG_NAME`) will
    /// become identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// # Arguments
    /// * path - a string-like reference to a [`str`] containing the path
    ///   that will be expanded.
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any problems opening the given file path
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`),
    ///   * if the value for any identifier cannot be returned by the given
    ///     callback-function.
    ///
    pub fn file_strict<T>(
        &self,
        path: &T,
    ) -> Result<String, ExpandTextError>
    where
        T: AsRef<Utf8Path> + ?Sized,
    {
        let path = path.as_ref();
        let text = std::fs::read_to_string(path).map_err(|e| {
            ExpandTextError::read_file_error(path, e)
        })?;
        self._text(&text).map_err(|e| {
            ExpandTextError::identifier_error_in_file(path, e)
        })
    }
}

/// A trait for types that can retrieve string-based data by a given key.
///
/// Implementors of `Fetcher` provide a mechanism to look up and return
/// a `String` value based on a `&str` key. This trait is suitable for
/// abstracting over various data sources, such as caches, configuration stores,
/// environment variables, or simple in-memory key-value maps.
///
/// # Examples
///
/// ## Implementing `Fetcher` on a struct holding values:
/// ```
/// use komichi::{Fetcher, ExpandTextWith};
///
/// struct Data {
///     a: String,
///     b: u16,
/// }
///
/// impl Data {
///     fn new(a: &str, b: u16) -> Self {
///         let a = a.to_string();
///         Self { a, b }
///     }
/// }
///
/// impl Fetcher for Data {
///     fn fetch(&self, key: &str) -> Option<String> {
///         match key {
///             "a" => Some(self.a.to_string()),
///             "b" => Some(self.b.to_string()),
///             _ => None
///         }
///     }
/// }
///
/// // Now interpolate a string using Data::fetch
/// let arg = "Hello ${a} for the ${b}th time";
/// let expect = "Hello World for the 12th time".to_string();
/// let data = Data::new("World", 12u16);
/// let expand = ExpandTextWith::new(&data);
/// let got = expand.text(&arg).unwrap();
/// assert_eq!(expect, got);
/// ```
/// ## Implementing `Fetcher` on a more complicated struct:
/// ```
/// use komichi::{Fetcher, ExpandTextWith};
///
/// struct Data<'a> {
///     a: &'a str,
///     b: u16,
/// }
///
/// impl<'a> Data<'a> {
///     fn new(a: &'a str, b: u16) -> Self {
///         Self { a, b }
///     }
/// }
///
/// impl<'a> Fetcher for Data<'a> {
///     fn fetch(&self, key: &str) -> Option<String> {
///         match key {
///             "a" => Some(self.a.to_string()),
///             "b" => Some(self.b.to_string()),
///             _ => None
///         }
///     }
/// }
///
/// // Now interpolate a string using Data::fetch
/// let arg = "Hello ${a} for the ${b}th time";
/// let expect = "Hello World for the 12th time".to_string();
/// let a = "World";
/// let data = Data::new(a, 12u16);
/// let expand = ExpandTextWith::new(&data);
/// let got = expand.text(&arg).unwrap();
/// assert_eq!(expect, got);
/// ```
/// ## Implementing `Fetcher` for an in-memory map:
/// ```
/// use std::collections::HashMap;
/// use komichi::{Fetcher, ExpandTextWith};
///
/// struct InMemoryCache {
///     data: HashMap<String, String>
/// }
///
/// impl InMemoryCache {
///     fn new() -> Self {
///         let mut data = HashMap::new();
///         data.insert("a".to_string(), "World".to_string());
///         data.insert("b".to_string(), "12".to_string());
///         Self { data }
///     }
/// }
///
/// impl Fetcher for InMemoryCache {
///     fn fetch(&self, key: &str) -> Option<String> {
///         self.data.get(key).cloned()
///     }
/// }
///
/// // Now interpolate a string using InMemoryCache::fetch
/// let arg = "Hello ${a} for the ${b}th time";
/// let expect = "Hello World for the 12th time".to_string();
/// let in_memory_cache = InMemoryCache::new();
/// let expand = ExpandTextWith::new(&in_memory_cache);
/// let got = expand.text(&arg).unwrap();
/// assert_eq!(expect, got);
/// ```
pub trait Fetcher {
    fn fetch(
        &self,
        key: &str,
    ) -> Option<String>;
}

/// Expand any BASH-like-identifiers in text or a file by obtaining values
/// using the [`Fetcher`] trait.
///
/// # Example
///
/// ```
/// use komichi::{Fetcher, ExpandTextWith};
///
/// struct Data<'a> {
///     a: &'a str,
///     b: u16,
/// }
///
/// impl<'a> Data<'a> {
///     fn new(a: &'a str, b: u16) -> Self {
///         Self { a, b }
///     }
/// }
///
/// impl<'a> Fetcher for Data<'a> {
///     fn fetch(&self, key: &str) -> Option<String> {
///         match key {
///             "a" => Some(self.a.to_string()),
///             "b" => Some(self.b.to_string()),
///             _ => None
///         }
///     }
/// }
///
/// // Now interpolate a string using Data::fetch
/// let arg = "Hello ${a} for the ${b}th time";
/// let expect = "Hello World for the 12th time".to_string();
/// let a = "World";
/// let data = Data::new(a, 12u16);
/// let expand = ExpandTextWith::new(&data);
/// let got = expand.text(&arg).unwrap();
/// assert_eq!(expect, got);
/// ```
pub struct ExpandTextWith<'a> {
    pub obj: &'a dyn Fetcher,
}

impl<'a> ExpandTextWith<'a> {
    pub fn new(obj: &'a dyn Fetcher) -> Self {
        Self { obj }
    }

    fn _text(
        &self,
        text: &str,
    ) -> Result<String, ExpandIdentifierError> {
        let tokens = TokenIterator::new(text);
        let mut out = String::new();
        for token in tokens {
            let token = token?;
            match token {
                Token::Text(text) => out.push_str(&text),
                Token::Identifier(key) => {
                    if let Some(value) = self.obj.fetch(&key) {
                        out.push_str(&value);
                    } else {
                        out.push_str(format!("${{{key}}}").as_str());
                    }
                },
                Token::NewLine => out.push('\n'),
            }
        }
        Ok(out)
    }

    /// Return the given text, containing bash-like-curly variables that are
    /// expanded with values from this struct's callback function.
    ///
    /// The text can contain BASH-like variables with each variable using
    /// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
    /// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
    /// identifier errors.
    ///
    /// Any identifier that does not have a value, as given by the callback
    /// function will be skipped. Meaning that the BASH-like variable will be
    /// put back into the output.
    ///
    /// # Arguments
    /// * `text` - A string-slice containing the text-to-be-expanded
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`).
    pub fn text(
        &self,
        text: &str,
    ) -> Result<String, ExpandTextError> {
        Ok(self._text(text)?)
    }

    fn _text_strict(
        &self,
        text: &str,
    ) -> Result<String, ExpandIdentifierError> {
        let tokens = TokenIterator::new(text);
        let mut out = String::new();
        for token in tokens {
            let token = token?;
            match token {
                Token::Text(text) => out.push_str(&text),
                Token::Identifier(key) => {
                    if let Some(value) = self.obj.fetch(&key) {
                        out.push_str(&value);
                    } else {
                        return Err(
                            ExpandIdentifierError::ValueError(key),
                        );
                    }
                },
                Token::NewLine => out.push('\n'),
            }
        }
        Ok(out)
    }

    /// Return the given text, containing bash-like-curly variables that are
    /// expanded with values from the given callback-function. And return
    /// an [`ExpandTextError`] when a value cannot be found by the given
    /// callback-function
    ///
    /// The text can contain BASH-like variables with each variable using
    /// the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like variables
    /// that do not contain curly brackets (e.g. `$DOG_NAME`) will become
    /// identifier errors.
    ///
    /// # Arguments
    /// * `text` - A string-slice containing the text-to-be-expanded
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`),
    ///   * if the value for any identifier cannot be returned by the given
    ///     callback-function.
    pub fn text_strict(
        &self,
        text: &str,
    ) -> Result<String, ExpandTextError> {
        Ok(self._text_strict(text)?)
    }

    /// Return the given file's text, containing bash-like-curly variables
    /// that are expanded with values from this struct's callback function.
    ///
    /// The file-contents can contain BASH-like variables with each variable
    /// using the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like
    /// variables that do not contain curly brackets (e.g. `$DOG_NAME`) will
    /// become identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// # Arguments
    /// * path - a string-like reference to a [`str`] containing the path
    ///   that will be expanded.
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any problems opening the given file path
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the
    ///       curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an
    ///       underscore or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`).
    pub fn file<T>(
        &self,
        path: &T,
    ) -> Result<String, ExpandTextError>
    where
        T: AsRef<Utf8Path> + ?Sized,
    {
        let path = path.as_ref();
        let text = std::fs::read_to_string(path).map_err(|e| {
            ExpandTextError::read_file_error(path, e)
        })?;
        self._text(&text).map_err(|e| {
            ExpandTextError::identifier_error_in_file(path, e)
        })
    }

    /// Return the given file's text, containing bash-like-curly variables that
    /// are expanded with values from this struct's callback function and
    /// return an [`ExpandTextError`] if the value cannot be retrieved.
    ///
    /// The file-contents can contain BASH-like variables with each variable
    /// using the curly syntax (e.g. `A dog named ${DOG_NAME}`). BASH-like
    /// variables that do not contain curly brackets (e.g. `$DOG_NAME`) will
    /// become identifier errors.
    ///
    /// The `$` character can be escaped by using two `$` characters e.g. `$$`.
    ///
    /// # Arguments
    /// * path - a string-like reference to a [`str`] containing the path
    ///   that will be expanded.
    ///
    /// # Errors
    /// A [`ExpandTextError`] - will be returned if:
    ///   * there are any problems opening the given file path
    ///   * there are any syntactical errors with any BASH-like variables:
    ///     * Non-ASCII characters between the curly-brackets,
    ///     * Non-alpha-numeric-underscore characters between the curly-brackets,
    ///     * No characters/empty between the curly-brackets,
    ///     * Missing an opening curly-bracket, after the `$`,
    ///     * Missing a closing curly-bracket, after the identifier,
    ///     * Identifier starts with a number. Can only start with an underscore
    ///       or an ASCII-letter,
    ///     * Invalid identifier name when the identifier name contains spaces
    ///       between parts of the identifier name (e.g. `${dog name}`),
    ///   * if the value for any identifier cannot be returned by the given
    ///     callback-function.
    ///
    pub fn file_strict<T>(
        &self,
        path: &T,
    ) -> Result<String, ExpandTextError>
    where
        T: AsRef<Utf8Path> + ?Sized,
    {
        let path = path.as_ref();
        let text = std::fs::read_to_string(path).map_err(|e| {
            ExpandTextError::read_file_error(path, e)
        })?;
        self._text(&text).map_err(|e| {
            ExpandTextError::identifier_error_in_file(path, e)
        })
    }
}