figura 3.0.0

A flexible string template formatting crate
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
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! Error types for template directive execution.
//!
//! This module defines the errors that can occur during template rendering,
//! particularly when resolving arguments and executing directives.

use thiserror::Error;

/// Errors that can occur during directive execution.
///
/// These errors represent runtime failures when rendering a compiled template,
/// such as missing variables, type mismatches, or parse failures. All errors
/// include detailed context to help diagnose issues.
///
/// # Examples
///
/// ```rust
/// use figura::{Template, DefaultParser, Context, Value, DirectiveError};
/// use std::collections::HashMap;
///
/// let tmpl = Template::<'{', '}'>::compile::<DefaultParser>("{missing}").unwrap();
/// let ctx = HashMap::new();
///
/// match tmpl.format(&ctx) {
///     Err(DirectiveError::NotFound { name, .. }) => {
///         println!("Variable '{}' not found", name);
///     }
///     _ => {}
/// }
/// ```
#[derive(Debug)]
#[derive(Error)]
pub enum DirectiveError {
    /// A variable was not found in the template context.
    ///
    /// This error occurs when a template references a variable that doesn't
    /// exist in the context hashmap. The error includes both the variable name
    /// and the type it was expected to be used as.
    ///
    /// # Fields
    ///
    /// * `name` - The name of the missing variable
    /// * `type_name` - The type the variable was expected to be (e.g., "string", "i64")
    ///
    /// # Examples
    ///
    /// ```text
    /// Template: "{username}"
    /// Context: (empty)
    /// Error: Variable 'username' was not found in the context while being used as 'string'
    /// ```
    #[error("Variable '{name}' was not found in the context while being used as '{type_name}'")]
    NotFound {
        name: String,
        type_name: &'static str,
    },

    /// A variable was found but has an incompatible type.
    ///
    /// This error occurs when a variable exists in the context but cannot be
    /// converted to the required type for the operation. For example, trying
    /// to use a string value where an integer is required.
    ///
    /// # Fields
    ///
    /// * `name` - The name of the variable with the wrong type
    /// * `expected` - The type that was expected (e.g., "i64")
    /// * `found` - The actual type of the variable (e.g., "string")
    ///
    /// # Examples
    ///
    /// ```text
    /// Template: "{value:count}"  (requires count to be an integer)
    /// Context: count = "not a number"
    /// Error: Variable 'count' has type 'string' but was expected to have type 'i64'
    /// ```
    #[error("Variable '{name}' has type '{found}' but was expected to have type '{expected}'")]
    TypeError {
        name: String,
        expected: &'static str,
        found: String,
    },

    /// A literal value could not be parsed as the required type.
    ///
    /// This error occurs when a literal value embedded in the template cannot
    /// be parsed into the type required by the directive. For example, trying
    /// to parse "abc" as an integer.
    ///
    /// # Fields
    ///
    /// * `value` - The literal value that failed to parse
    /// * `type_name` - The type it was being parsed as
    /// * `message` - The detailed parse error message
    ///
    /// # Examples
    ///
    /// ```text
    /// Template: "{'hello':3}"  (tries to parse "hello" as i64 for repeat count)
    /// Error: Failed to parse 'hello' as a literal of type 'i64': invalid digit found in string
    /// ```
    #[error("Failed to parse '{value}' as a literal of type '{type_name}': {message}")]
    ParseError {
        value: String,
        type_name: &'static str,
        message: String,
    },
}

#[derive(Debug, Error)]
pub enum TemplateError {
    #[error("Unclosed delimiter '{0}'")]
    MissingDelimiter(char),

    #[error("Failed to parse directive: {0}")]
    DirectiveParsing(String),
}