|
| 1 | +# masterror-template |
| 2 | + |
| 3 | +`masterror-template` packages the template parser shared by the [`masterror`][masterror] runtime crate and the [`masterror-derive`][derive] procedural macros. It understands the `#[error("...")]` formatting language popularised by `thiserror` v2, producing a structured representation that downstream code can inspect or render. |
| 4 | + |
| 5 | +The crate is intentionally small: it exposes just enough API for advanced applications that want to inspect derived error displays, implement custom derive helpers, or perform static analysis over formatting placeholders. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +Add the crate alongside `masterror` if you need direct access to the parser: |
| 10 | + |
| 11 | +```toml |
| 12 | +[dependencies] |
| 13 | +masterror-template = { version = "0.3.6" } |
| 14 | +``` |
| 15 | + |
| 16 | +`masterror-template` targets Rust 1.90 and builds on stable and nightly toolchains alike. |
| 17 | + |
| 18 | +## Parsing templates |
| 19 | + |
| 20 | +Call [`ErrorTemplate::parse`](https://docs.rs/masterror-template/latest/masterror_template/template/struct.ErrorTemplate.html#method.parse) to turn an `&str` into a structured template: |
| 21 | + |
| 22 | +```rust |
| 23 | +use masterror_template::template::{ErrorTemplate, TemplateIdentifier}; |
| 24 | + |
| 25 | +fn inspect(template: &str) { |
| 26 | + let parsed = ErrorTemplate::parse(template).expect("valid template"); |
| 27 | + |
| 28 | + for placeholder in parsed.placeholders() { |
| 29 | + match placeholder.identifier() { |
| 30 | + TemplateIdentifier::Named(name) => println!("named placeholder: {name}"), |
| 31 | + TemplateIdentifier::Positional(index) => println!("positional placeholder: {index}"), |
| 32 | + TemplateIdentifier::Implicit(index) => println!("implicit placeholder: {index}"), |
| 33 | + } |
| 34 | + } |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +The parser preserves literal text and exposes every placeholder with span metadata, making it straightforward to surface diagnostics or transform templates programmatically. |
| 39 | + |
| 40 | +## Formatter metadata |
| 41 | + |
| 42 | +Each [`TemplatePlaceholder`](https://docs.rs/masterror-template/latest/masterror_template/template/struct.TemplatePlaceholder.html) advertises the requested formatter through [`TemplateFormatter`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateFormatter.html) and [`TemplateFormatterKind`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateFormatterKind.html): |
| 43 | + |
| 44 | +```rust |
| 45 | +use masterror_template::template::{ErrorTemplate, TemplateFormatterKind}; |
| 46 | + |
| 47 | +let template = ErrorTemplate::parse("{value:#x}").expect("parse"); |
| 48 | +let placeholder = template.placeholders().next().expect("placeholder"); |
| 49 | +let formatter = placeholder.formatter(); |
| 50 | +assert_eq!(formatter.kind(), TemplateFormatterKind::LowerHex); |
| 51 | +assert!(formatter.is_alternate()); |
| 52 | +``` |
| 53 | + |
| 54 | +This mirrors the formatting traits accepted by `core::fmt`, enabling consumers to route values through `Display`, `Debug`, hexadecimal, binary, pointer, or exponential renderers. |
| 55 | + |
| 56 | +## Error reporting |
| 57 | + |
| 58 | +Parsing failures produce [`TemplateError`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateError.html) variants with precise byte ranges. The metadata simplifies IDE integrations and procedural macros that need to point at the offending part of the template. |
| 59 | + |
| 60 | +```rust |
| 61 | +use masterror_template::template::ErrorTemplate; |
| 62 | + |
| 63 | +let err = ErrorTemplate::parse("{foo").unwrap_err(); |
| 64 | +assert!(matches!(err, masterror_template::template::TemplateError::UnterminatedPlaceholder { .. })); |
| 65 | +``` |
| 66 | + |
| 67 | +## License |
| 68 | + |
| 69 | +Dual licensed under either of |
| 70 | + |
| 71 | +- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>) |
| 72 | +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or <http://opensource.org/licenses/MIT>) |
| 73 | + |
| 74 | +at your option. |
| 75 | + |
| 76 | +### Contribution |
| 77 | + |
| 78 | +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. |
| 79 | + |
| 80 | +[masterror]: https://crates.io/crates/masterror |
| 81 | +[derive]: https://crates.io/crates/masterror-derive |
0 commit comments