v_escape_proc_macro/
lib.rs

1#![deny(missing_docs)]
2
3//! Procedural macro crate for v_escape
4//!
5//! This crate provides the `escape!` procedural macro for generating SIMD-optimized
6//! escape functions from character mappings. The macro generates both `escape_string`
7//! and `escape_fmt` functions that can be used for efficient string escaping.
8
9use proc_macro2::TokenStream;
10use quote::quote;
11use v_escape_codegen_base::generate;
12
13/// Generate escape functions from a list of character mappings.
14///
15/// This procedural macro generates SIMD-optimized escape functions for efficiently
16/// replacing specific characters with their corresponding escape sequences. The macro
17/// creates both `escape_string` and `escape_fmt` functions that can be used to escape
18/// strings in various contexts (HTML, JSON, LaTeX, etc.).
19///
20/// # Syntax
21///
22/// ```rust,ignore
23/// escape! {
24///     character -> "escape_sequence",
25///     character -> "escape_sequence",
26///     // ... more mappings
27/// }
28/// ```
29///
30/// # Parameters
31///
32/// - `character`: A character to be escaped, specified as:
33///   - A byte literal: `b'"'`, `b'<'`, `b'&'`
34///   - A char literal: `'"'`, `'<'`, `'&'`
35///   - An integer literal: `34`, `60`, `38` (ASCII values)
36/// - `escape_sequence`: A string literal containing the replacement text
37///
38/// # Generated Functions
39///
40/// The macro generates the following functions in the current module:
41///
42/// - `escape_string(input: &str, buffer: &mut String)`: Escapes the input string and
43///   appends the result to the provided buffer
44/// - `escape_fmt(input: &str) -> impl std::fmt::Display`: Returns a displayable object
45///   that formats the escaped string
46///
47/// # Features
48///
49/// The generated functions require specific features to be enabled:
50/// - `string` feature: Enables `escape_string` function
51/// - `fmt` feature: Enables `escape_fmt` function
52///
53/// # Performance
54///
55/// The generated functions use SIMD vectorization for optimal performance:
56/// - Automatically selects the best available SIMD instructions (AVX2, SSE2, NEON, WASM, etc.)
57/// - Falls back to scalar operations when SIMD is not available
58/// - Uses efficient lookup tables for character matching
59/// - Minimizes memory allocations and copies
60///
61/// # Error Handling
62///
63/// The macro will fail to compile if:
64/// - Character mappings are not properly formatted
65/// - Duplicate characters are specified
66/// - Non-ASCII characters are used (only ASCII characters 0-127 are supported)
67/// - Escape sequences are not valid string literals
68///
69/// # Implementation Details
70///
71/// The macro generates:
72/// - Static lookup tables for efficient character matching
73/// - SIMD-optimized escape implementations for various architectures
74/// - Fallback implementations for compatibility
75/// - Proper trait implementations for the v_escape framework
76#[proc_macro]
77pub fn escape(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
78    let input: TokenStream = input.into();
79    match generate(quote!(new!( #input );), "v_escape") {
80        Ok((code, _)) => code.into(),
81        Err(e) => e.to_compile_error().into(),
82    }
83}
v_escape_proc_macro/lib.rs

v_escape_proc_macro/
lib.rs
