formatx 0.3.0

A macro for formatting non literal strings at runtime in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83

//! The [`Renderer`] builder - collects arguments and produces formatted output.

use crate::{error::Error, format, template::Template, value::FormatValue};
use std::fmt::{Debug, Display};

/// A builder for rendering a [`Template`] with arguments.
///
/// # Examples
///
/// ```
/// use formatx::Template;
///
/// let template = Template::new("{} + {} = {}").unwrap();
/// let result = template.render()
///     .arg(&1)
///     .arg(&2)
///     .arg(&3)
///     .finish()
///     .unwrap();
/// assert_eq!(result, "1 + 2 = 3");
/// ```
pub struct Renderer<'a> {
    template: &'a Template,
    args: Vec<&'a dyn FormatValue>,
    named: Vec<(&'a str, usize)>,
}

impl<'a> Renderer<'a> {
    /// Create a new renderer for the given template.
    pub(crate) fn new(template: &'a Template) -> Self {
        Self {
            template,
            args: Vec::new(),
            named: Vec::new(),
        }
    }

    /// Add a positional argument.
    #[inline]
    pub fn arg(&mut self, value: &'a (impl Display + Debug)) -> &mut Self {
        self.args.push(value as &dyn FormatValue);
        self
    }

    /// Add a named argument.
    #[inline]
    pub fn named(&mut self, name: &'a str, value: &'a (impl Display + Debug)) -> &mut Self {
        let index = self.args.len();
        self.args.push(value as &dyn FormatValue);
        self.named.push((name, index));
        self
    }

    /// **Strict**: produce the formatted output.
    ///
    /// Returns `Err(Error::MissingArgument)` if any placeholder references an
    /// argument that was not provided.
    pub fn finish(&self) -> Result<String, Error> {
        self.render_inner(true)
    }

    /// **Lenient**: produce the formatted output.
    ///
    /// Missing arguments are replaced with an empty string `""` instead of
    /// producing an error.
    pub fn finish_lenient(&self) -> Result<String, Error> {
        self.render_inner(false)
    }

    fn render_inner(&self, strict: bool) -> Result<String, Error> {
        let source = self.template.source();
        let mut output = String::with_capacity(source.len());
        format::render(
            &mut output,
            source,
            self.template.parsed(),
            &self.args,
            &self.named,
            strict,
        )?;
        Ok(output)
    }
}