litext 1.0.0

Just what you need for extracting string literal contents at compile time
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

use proc_macro2::Span;

/// A span-aware string literal container.
///
/// `LitStr` bundles the extracted text of a string literal with its original source
/// location. This is essential for procedural macro authors who need to emit
/// compiler diagnostics (errors or warnings) that point precisely to the string
/// provided in the macro input.
///
/// # Type Details
///
/// Unlike `String`, `LitStr` preserves the source location (`Span`) of the original
/// literal. This allows you to emit error messages that highlight exactly where in
/// the user's code the problematic literal appears.
///
/// # What Gets Extracted
///
/// The `value` field contains the unescaped string content:
///
/// | Input Literal | Extracted Value |
/// |---------------|-----------------|
/// | `"hello"` | `hello` |
/// | `"hello\nworld"` | `hello` + newline + `world` |
/// | `r#"hello\nworld"#` | `hello\nworld` (verbatim, no unescaping) |
/// | `"\x41"` | `A` |
/// | `"\u{1F600}"` | The emoji character |
///
/// # Why Not Just Use `String`?
///
/// Use `LitStr` when you need the span for error reporting. If you only need the
/// string content, using `String` directly is simpler.
///
/// # Examples
///
/// ```ignore
/// use litext::{litext, TokenStream};
/// use litext::literal::LitStr;
///
/// pub fn my_macro(input: TokenStream) -> TokenStream {
///     let lit = litext!(input as LitStr);
///
///     if lit.value().is_empty() {
///         // Use the span for precise error reporting
///         return comperr::error(lit.span(), "string cannot be empty");
///     }
///
///     // Access the string content
///     let text = lit.value();
///
///     // ... proceed with expansion
/// }
/// ```
///
/// # See Also
///
/// - [`FromLit`](super::FromLit) for the extraction trait
pub struct LitStr {
    /// The inner text of the string literal, with quotes and escape sequences removed.
    ///
    /// For a literal like `"hello\nworld"` this will be `hello` + newline + `world`.
    /// For a raw literal like `r#"hello\nworld"#` this will be `hello\nworld` verbatim,
    /// since raw strings do not process escape sequences.
    pub value: String,

    /// The source location of the string literal in the macro input.
    ///
    /// Useful for emitting compiler diagnostics that point at the exact position
    /// of the literal, for example via `Diagnostic::spanned` on nightly, or by
    /// constructing a new token with this span attached.
    pub span: Span,
}

impl LitStr {
    /// Creates a new `LitStr` from an unescaped value and its source span.
    ///
    /// This is typically called by the internal parsing logic after
    /// resolving escapes and identifying the literal's location.
    #[must_use] 
    pub fn new(value: String, span: Span) -> Self {
        Self { value, span }
    }

    /// Returns a reference to the unescaped string content.
    #[must_use] 
    pub fn value(&self) -> &str {
        &self.value
    }

    /// Returns the source span of the literal.
    ///
    /// This span can be used with crates like `proc_macro2` or `syn` to
    /// anchor error messages to the specific string in the user's code.
    #[must_use] 
    pub fn span(&self) -> Span {
        self.span
    }
}