displaydoc

https://docs.rs/displaydoc
Admin
displaydoc is a Rust crate that provides a convenient derive macro for implementing the standard...
Tokens:9,668
Snippets:73
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Derive Display for Struct with Interpolated Field

Source: https://docs.rs/displaydoc/latest/displaydoc/index.html

Shows how to derive `Display` for a struct, using doc comments to define the display format with interpolated fields. This example uses a generic struct.

```rust
/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

let error: Error<&str> = Error("muahaha i am an error");
assert!("oh no, an error: muahaha i am an error" == &format!("{}", error));
```

--------------------------------

### Derive Display for Generic Struct

Source: https://docs.rs/displaydoc/latest/src/displaydoc/lib.rs.html

This example shows how to derive the `Display` trait for a generic struct. It utilizes a simple string interpolation for the generic type parameter, demonstrating basic usage for structs.

```rust
# use displaydoc::Display;
/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

let error: Error<&str> = Error("muahaha i am an error");
assert!("oh no, an error: muahaha i am an error" == &format!("{}", error));
```

--------------------------------

### Derive Display and Error for Enum with Source

Source: https://docs.rs/displaydoc/latest/displaydoc/index.html

Demonstrates deriving `Display` and `Error` for an enum, propagating source locations from `io::Error` using the `#[source]` attribute. This example shows how to define custom error messages with interpolated fields.

```rust
use std::io;
use displaydoc::Display;
use thiserror::Error;

#[derive(Display, Error, Debug)]
pub enum DataStoreError {
    /// data store disconnected
    Disconnect(#[source] io::Error),
    /// the data for key `{0}` is not available
    Redaction(String),
    /// invalid header (expected {expected:?}, found {found:?})
    InvalidHeader {
        expected: String,
        found: String,
    },
    /// unknown data store error
    Unknown,
}

let error = DataStoreError::Redaction("CLASSIFIED CONTENT".to_string());
assert!("the data for key `CLASSIFIED CONTENT` is not available" == &format!("{}", error));
```

--------------------------------

### Add displaydoc to dependencies

Source: https://docs.rs/displaydoc/latest/displaydoc/index.html

Add this to your Cargo.toml file to include the displaydoc crate in your project. Requires rustc 1.56 or newer.

```toml
[dependencies]
displaydoc = "0.2"
```

--------------------------------

### Display Derive Macro

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

This section details the `#[derive(Display)]` macro provided by the displaydoc crate. It explains how to use doc comment attributes to define the display format and covers the available attributes for customization.

```APIDOC
## Derive Macro Display

### Description
Custom `#[derive(...)]` macro for implementing `fmt::Display` via doc comment attributes.

### Attributes
- `#[ignore_extra_doc_attributes]`
- `#[prefix_enum_doc_attributes]`
- `#[displaydoc]`

### Request Example
```rust
#[derive(Display)]
{
    // Attributes available to this derive:
    #[ignore_extra_doc_attributes]
    #[prefix_enum_doc_attributes]
    #[displaydoc]
}
```
```

--------------------------------

### Where Clause Utilities

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Helper functions for constructing empty where predicates and clauses for trait bounds.

```rust
fn new_empty_where_type_predicate(ident: Ident) -> PredicateType {
    let mut path_segments = Punctuated::<PathSegment, PathSep>::new();
    path_segments.push_value(PathSegment {
        ident,
        arguments: PathArguments::None,
    });
    PredicateType {
        lifetimes: None,
        bounded_ty: Type::Path(TypePath {
            qself: None,
            path: Path {
                leading_colon: None,
                segments: path_segments,
            },
        }),
        colon_token: Colon {
            spans: [Span::call_site()],
        },
        bounds: Punctuated::<TypeParamBound, Plus>::new(),
    }
}

fn new_empty_where_clause() -> WhereClause {
    WhereClause {

```

--------------------------------

### Create Path with Segments

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Constructs a Path with specified identifier segments and an optional global prefix. Use when building path expressions programmatically.

```rust
fn join_paths(name_segments: &[&str], use_global_prefix: UseGlobalPrefix) -> Path {
    let mut segments = Punctuated::<PathSegment, PathSep>::new();
    assert!(!name_segments.is_empty());
    segments.push_value(PathSegment {
        ident: Ident::new(name_segments[0], Span::call_site()),
        arguments: PathArguments::None,
    });
    for name in name_segments[1..].iter() {
        segments.push_punct(PathSep {
            spans: [Span::call_site(), Span::mixed_site()],
        });
        segments.push_value(PathSegment {
            ident: Ident::new(name, Span::call_site()),
            arguments: PathArguments::None,
        });
    }
    Path {
        leading_colon: match use_global_prefix {
            UseGlobalPrefix::LeadingColon => Some(PathSep {
                spans: [Span::call_site(), Span::mixed_site()],
            }),
            UseGlobalPrefix::NoLeadingColon => None,
        },
        segments,
    }
}
```

--------------------------------

### Derive Display Trait Implementation

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

The primary entry point for the derive macro, dispatching to struct or enum implementation logic and wrapping the result in a constant block.

```rust
pub(crate) fn derive(input: &DeriveInput) -> Result<TokenStream> {
    let impls = match &input.data {
        Data::Struct(data) => impl_struct(input, data),
        Data::Enum(data) => impl_enum(input, data),
        Data::Union(_) => Err(Error::new_spanned(input, "Unions are not supported")),
    }?;

    let helpers = specialization();
    Ok(quote! {
        #[allow(non_upper_case_globals, unused_attributes, unused_qualifications)]
        const _: () = {
            #helpers
            #impls
        };
    })
}
```

--------------------------------

### Tests for Shorthand Formatting Expansion (std enabled)

Source: https://docs.rs/displaydoc/latest/src/displaydoc/fmt.rs.html

Unit tests verifying the `expand_shorthand` functionality when the 'std' feature is enabled. These tests cover various scenarios including simple variables, formatted variables, indexed arguments, and ignored double braces.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    use pretty_assertions::assert_eq;
    use proc_macro2::Span;

    fn assert(input: &str, fmt: &str, args: &str) {
        let mut display = Display {
            fmt: LitStr::new(input, Span::call_site()),
            args: TokenStream::new(),
        };
        display.expand_shorthand();
        assert_eq!(fmt, display.fmt.value());
        assert_eq!(args, display.args.to_string());
    }

    #[test]
    fn test_expand() {
        assert("fn main() {{ }}", "fn main() {{ }}", "");
    }

    #[test]
    #[cfg_attr(not(feature = "std"), ignore)]
    fn test_std_expand() {
        assert(
            "{v} {v:?} {0} {0:?}",
            "{} {:?} {} ?",
            ", v . __displaydoc_display () , v , _0 . __displaydoc_display () , _0",
        );
        assert("error {var}", "error {}", ", var . __displaydoc_display ()");

        assert(
            "error {var1}",
            "error {}",
            ", var1 . __displaydoc_display ()",
        );

        assert(
            "error {var1var}",
            "error {}",
            ", var1var . __displaydoc_display ()",
        );

        assert(
            "The path {0}",
            "The path {}",
            ", _0 . __displaydoc_display ()",
        );
        assert("The path {0:?}", "The path ?", ", _0");
    }

    #[test]
    #[cfg_attr(feature = "std", ignore)]
    fn test_nostd_expand() {
        assert(
            "{v} {v:?} {0} {0:?}",
            "{} {:?} {} ?",
            ", v , v , _0 , _0",
        );
        assert("error {var}", "error {}", ", var");

        assert("The path {0}", "The path {}", ", _0");
        assert("The path {0:?}", "The path ?", ", _0");

        assert("error {var1}", "error {}", ", var1");

        assert("error {var1var}", "error {}", ", var1var");
    }
}
```

--------------------------------

### Generic Type Parameters

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

Explains how generic type parameters are handled when using the `#[derive(Display)]` macro. It clarifies that explicit `Display` constraints are not required on the struct or enum definition site, as the macro implicitly handles this.

```APIDOC
### Generic Type Parameters

Type parameters to an enum or struct using this macro should _not_ need to have an explicit `Display` constraint at the struct or enum definition site. A `Display` implementation for the `derive`d struct or enum is generated assuming each type parameter implements `Display`, but that should be possible without adding the constraint to the struct definition itself:

```rust
use displaydoc::Display;

/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

// No need to require `E: Display`, since `displaydoc::Display` adds that implicitly.
fn generate_error<E>(e: E) -> Error<E> { Error(e) }

assert!("oh no, an error: muahaha" == &format!("{}", generate_error("muahaha")));
```
```

--------------------------------

### Display Generic Type Parameters

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

Demonstrates how `displaydoc::Display` implicitly adds a `Display` constraint to generic type parameters, eliminating the need for explicit constraints in the struct/enum definition.

```rust
use displaydoc::Display;

/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

// No need to require `E: Display`, since `displaydoc::Display` adds that implicitly.
fn generate_error<E>(e: E) -> Error<E> { Error(e) }

assert!("oh no, an error: muahaha" == &format!("{}", generate_error("muahaha")));

```

--------------------------------

### DisplayDoc Proc Macro Implementation

Source: https://docs.rs/displaydoc/latest/src/displaydoc/lib.rs.html

The `derive_error` function is the entry point for the `#[derive(Display)]` proc macro. It parses the input token stream and uses the `expand::derive` function to generate the `Display` implementation, handling potential errors by converting them to compile errors.

```rust
#[proc_macro_derive(
    Display,
    attributes(ignore_extra_doc_attributes, prefix_enum_doc_attributes, displaydoc)
)]
pub fn derive_error(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    expand::derive(&input)
        .unwrap_or_else(|err| err.to_compile_error())
        .into()
}
```

--------------------------------

### Ensure Display for All Unconstrained Members

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Iterates through type parameters and adds a `core::fmt::Display` constraint to the `where_clause` if the type parameter does not already have any type constraints. This prevents breaking existing constraints.

```rust
fn ensure_where_clause_has_display_for_all_unconstrained_members(
    where_clause: &mut WhereClause,
    type_params: &[&TypeParam],
) {
    let param_constraint_mapping = extract_trait_constraints_from_source(where_clause, type_params);

    for (ident, known_bounds) in param_constraint_mapping.into_iter() {
        // If the type parameter has any constraints already, we don't want to touch it, to avoid
        // breaking use cases where a type parameter only needs to impl `Debug`, for example.
        if known_bounds.is_empty() {
            ensure_display_in_where_clause_for_type(where_clause, ident);
        }
    }
}
```

--------------------------------

### Display Derive Macro Attributes

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

Shows the available attributes for the `#[derive(Display)]` macro. Use `#[ignore_extra_doc_attributes]` and `#[prefix_enum_doc_attributes]` to control doc attribute behavior.

```rust
#[derive(Display)]
{
    // Attributes available to this derive:
    #[ignore_extra_doc_attributes]
    #[prefix_enum_doc_attributes]
    #[displaydoc]
}

```

--------------------------------

### Extract Trait Constraints from Source

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Maps generic type parameters to their trait boundaries, considering both declaration site and where clauses. Use to understand the full set of constraints on generic types.

```rust
fn extract_trait_constraints_from_source(
    where_clause: &WhereClause,
    type_params: &[&TypeParam],
) -> HashMap<Ident, Vec<TraitBound>> {
    // Add trait bounds provided at the declaration site of type parameters for the struct/enum.
    let mut param_constraint_mapping: HashMap<Ident, Vec<TraitBound>> = type_params
        .iter()
        .map(|type_param| {
            let trait_bounds: Vec<TraitBound> = type_param
                .bounds
                .iter()
                .flat_map(|bound| match bound {
                    TypeParamBound::Trait(trait_bound) => Some(trait_bound),
                    _ => None,
                })
                .cloned()
                .collect();
            (type_param.ident.clone(), trait_bounds)
        })
        .collect();

    // Add trait bounds from `where` clauses, which may be type parameters or types containing
    // those parameters.
    for predicate in where_clause.predicates.iter() {
        // We only care about type and not lifetime constraints here.
        if let WherePredicate::Type(ref pred_ty) = predicate {
            let ident = match &pred_ty.bounded_ty {
                Type::Path(TypePath { path, qself: None }) => match path.get_ident() {
                    None => continue,
                    Some(ident) => ident,
                },
                _ => continue,
            };
            // We ignore any type constraints that aren't direct references to type
            // parameters of the current enum of struct definition. No types can be
            // constrained in a `where` clause unless they are a type parameter or a generic

```

--------------------------------

### Display with Debug Constraint for Generic Type Parameters

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

Illustrates that if a generic type parameter must be constrained with `Debug` for formatting (e.g., `{:?}`), this constraint must be explicitly specified at the struct or enum definition site and propagated to callers.

```rust
use core::fmt::Debug;
use displaydoc::Display;

/// oh no, an error: {0:?}
#[derive(Display)]
pub struct Error<E: Debug>(pub E);

// `E: Debug` now has to propagate to callers.
fn generate_error<E: Debug>(e: E) -> Error<E> { Error(e) }

assert!("oh no, an error: \"cool\"" == &format!("{}", generate_error("cool")));

// Try this with a struct that doesn't impl `Display` at all, unlike `str`.
#[derive(Debug)]
pub struct Oh;
assert!("oh no, an error: Oh" == &format!("{}", generate_error(Oh)));

```

--------------------------------

### Deriving Display with Generic Type Parameters

Source: https://docs.rs/displaydoc/latest/src/displaydoc/lib.rs.html

Use this macro to implement `fmt::Display` for structs or enums. Generic type parameters do not require an explicit `Display` constraint on the struct definition, as the macro adds it implicitly.

```rust
use displaydoc::Display;

/// oh no, an error: {0}
#[derive(Display)]
pub struct Error<E>(pub E);

// No need to require `E: Display`, since `displaydoc::Display` adds that implicitly.
fn generate_error<E>(e: E) -> Error<E> { Error(e) }

assert!("oh no, an error: muahaha" == &format!("{}", generate_error("muahaha")));
```

--------------------------------

### Expand Shorthand Formatting String

Source: https://docs.rs/displaydoc/latest/src/displaydoc/fmt.rs.html

Transforms shorthand format strings like `"error {var}"` into standard format strings `"error {}"` and generates the corresponding arguments. This function is crucial for simplifying custom display implementations.

```rust
use crate::attr::Display;
use proc_macro2::TokenStream;
use quote::quote_spanned;
use syn::{Ident, LitStr};

macro_rules! peek_next {
    ($read:ident) => {
        match $read.chars().next() {
            Some(next) => next,
            None => return,
        }
    };
}

impl Display {
    // Transform `"error {var}"` to `"error {}"`, var.
    pub(crate) fn expand_shorthand(&mut self) {
        let span = self.fmt.span();
        let fmt = self.fmt.value();
        let mut read = fmt.as_str();
        let mut out = String::new();
        let mut args = TokenStream::new();

        while let Some(brace) = read.find('{') {
            out += &read[..=brace];
            read = &read[brace + 1..];

            // skip cases where we find a {{ 
            if read.starts_with('{') {
                out.push('{');
                read = &read[1..];
                continue;
            }

            let next = peek_next!(read);

            let var = match next {
                '0'..='9' => take_int(&mut read),
                'a'..='z' | 'A'..='Z' | '_' => take_ident(&mut read),
                _ => return,
            };

            let ident = Ident::new(&var, span);

            let next = peek_next!(read);

            let arg = if cfg!(feature = "std") && next == '}' {
                quote_spanned!(span=> , #ident.__displaydoc_display())
            } else {
                quote_spanned!(span=> , #ident)
            };

            args.extend(arg);
        }

        out += read;
        self.fmt = LitStr::new(&out, self.fmt.span());
        self.args = args;
    }
}
```

--------------------------------

### Generate Display for Enum with Variants

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Generates a `Display` implementation for an enum with variants. It constructs a `match` statement based on variant fields and their associated display information.

```Rust
impl #impl_generics ::core::fmt::Display for #ty #ty_generics #where_clause {
    fn fmt(&self, formatter: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        #[allow(unused_variables)]
        match self {
            #(#arms,)*
        }
    }
}
```

--------------------------------

### Implement attribute parsing and display generation

Source: https://docs.rs/displaydoc/latest/src/displaydoc/attr.rs.html

Defines structures for display formatting and helper methods to extract and process doc attributes from Rust types.

```rust
1use proc_macro2::TokenStream;
2use quote::{quote, ToTokens};
3use syn::{Attribute, LitStr, Meta, Result};
4
5#[derive(Clone)]
6pub(crate) struct Display {
7    pub(crate) fmt: LitStr,
8    pub(crate) args: TokenStream,
9}
10
11pub(crate) struct VariantDisplay {
12    pub(crate) r#enum: Option<Display>,
13    pub(crate) variant: Display,
14}
15
16impl ToTokens for Display {
17    fn to_tokens(&self, tokens: &mut TokenStream) {
18        let fmt = &self.fmt;
19        let args = &self.args;
20        tokens.extend(quote! {
21            write!(formatter, #fmt #args)
22        });
23    }
24}
25
26impl ToTokens for VariantDisplay {
27    fn to_tokens(&self, tokens: &mut TokenStream) {
28        if let Some(ref r#enum) = self.r#enum {
29            r#enum.to_tokens(tokens);
30            tokens.extend(quote! { ?; write!(formatter, ": ")?; });
31        }
32        self.variant.to_tokens(tokens);
33    }
34}
35
36pub(crate) struct AttrsHelper {
37    ignore_extra_doc_attributes: bool,
38    prefix_enum_doc_attributes: bool,
39}
40
41impl AttrsHelper {
42    pub(crate) fn new(attrs: &[Attribute]) -> Self {
43        let ignore_extra_doc_attributes = attrs
44            .iter()
45            .any(|attr| attr.path().is_ident("ignore_extra_doc_attributes"));
46        let prefix_enum_doc_attributes = attrs
47            .iter()
48            .any(|attr| attr.path().is_ident("prefix_enum_doc_attributes"));
49
50        Self {
51            ignore_extra_doc_attributes,
52            prefix_enum_doc_attributes,
53        }
54    }
55
56    pub(crate) fn display(&self, attrs: &[Attribute]) -> Result<Option<Display>> {
57        let displaydoc_attr = attrs.iter().find(|attr| attr.path().is_ident("displaydoc"));
58
59        if let Some(displaydoc_attr) = displaydoc_attr {
60            let lit = displaydoc_attr
61                .parse_args()
62                .expect("#[displaydoc(\"foo\")] must contain string arguments");
63            let mut display = Display {
64                fmt: lit,
65                args: TokenStream::new(),
66            };
67
68            display.expand_shorthand();
69            return Ok(Some(display));
70        }
71
72        let num_doc_attrs = attrs
73            .iter()
74            .filter(|attr| attr.path().is_ident("doc"))
75            .count();
76
77        if !self.ignore_extra_doc_attributes && num_doc_attrs > 1 {
78            panic!("Multi-line comments are disabled by default by displaydoc. Please consider using block doc comments (/** */) or adding the #[ignore_extra_doc_attributes] attribute to your type next to the derive.");
79        }
80
81        for attr in attrs {
82            if attr.path().is_ident("doc") {
83                let lit = match &attr.meta {
84                    Meta::NameValue(syn::MetaNameValue {
85                        value:
86                            syn::Expr::Lit(syn::ExprLit {
87                                lit: syn::Lit::Str(lit),
88                                ..
89                            }),
90                        ..
91                    }) => lit,
92                    _ => unimplemented!(),
93                };
94
95                // Make an attempt at cleaning up multiline doc comments.
96                let doc_str = lit
97                    .value()
98                    .lines()
99                    .map(|line| line.trim().trim_start_matches('*').trim())
100                    .collect::<Vec<&str>>()
101                    .join("\n");
102
103                let lit = LitStr::new(doc_str.trim(), lit.span());
104
105                let mut display = Display {
106                    fmt: lit,
107                    args: TokenStream::new(),
108                };
109
110                display.expand_shorthand();
111                return Ok(Some(display));
112            }
113        }
114
115        Ok(None)
116    }
117
118    pub(crate) fn display_with_input(
119        &self,
120        r#enum: &[Attribute],
121        variant: &[Attribute],
122    ) -> Result<Option<VariantDisplay>> {
123        let r#enum = if self.prefix_enum_doc_attributes {
124            let result = self
125                .display(r#enum)?
126                .expect("Missing doc comment on enum with #[prefix_enum_doc_attributes]. Please remove the attribute or add a doc comment to the enum itself.");
127
128            Some(result)
129        } else {
130            None
131        };
132
133        Ok(self
134            .display(variant)?
135            .map(|variant| VariantDisplay { r#enum, variant }))
136    }
137}
```

--------------------------------

### Using Debug Implementations with Type Parameters

Source: https://docs.rs/displaydoc/latest/displaydoc/derive.Display.html

Details the scenario where a generic type parameter needs to be constrained with the `Debug` trait for formatting fields with `{:?}`. It highlights that this constraint must be explicitly specified at the struct or enum definition site and propagated to callers.

```APIDOC
### Using `Debug` Implementations with Type Parameters

However, if a type parameter must instead be constrained with the `Debug` trait so that some field may be printed with `{:?}`, that constraint must currently still also be specified redundantly at the struct or enum definition site. If a struct or enum field is being formatted with `{:?}` via `displaydoc`, and a generic type parameter must implement `Debug` to do that, then that struct or enum definition will need to propagate the `Debug` constraint to every type parameter it’s instantiated with:

```rust
use core::fmt::Debug;
use displaydoc::Display;

/// oh no, an error: {0:?}
#[derive(Display)]
pub struct Error<E: Debug>(pub E);

// `E: Debug` now has to propagate to callers.
fn generate_error<E: Debug>(e: E) -> Error<E> { Error(e) }

assert!("oh no, an error: \"cool\"" == &format!("{}", generate_error("cool")));

// Try this with a struct that doesn't impl `Display` at all, unlike `str`.
#[derive(Debug)]
pub struct Oh;
assert!("oh no, an error: Oh" == &format!("{}", generate_error(Oh)));
```
```

--------------------------------

### Struct Display Implementation

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Generates the Display trait implementation for structs by destructuring fields and applying the display attribute.

```rust
fn impl_struct(input: &DeriveInput, data: &DataStruct) -> Result<TokenStream> {
    let ty = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
    let where_clause = generate_where_clause(&input.generics, where_clause);

    let helper = AttrsHelper::new(&input.attrs);

    let display = helper.display(&input.attrs)?.map(|display| {
        let pat = match &data.fields {
            Fields::Named(fields) => {
                let var = fields.named.iter().map(|field| &field.ident);
                quote!(Self { #(#var),* })
            }
            Fields::Unnamed(fields) => {
                let var = (0..fields.unnamed.len()).map(|i| format_ident!("_{}", i));
                quote!(Self(#(#var),*))
            }
            Fields::Unit => quote!(_),
        };
        quote! {
            impl #impl_generics ::core::fmt::Display for #ty #ty_generics #where_clause {
                fn fmt(&self, formatter: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
                    // NB: This destructures the fields of `self` into named variables (for unnamed
                    // fields, it uses _0, _1, etc as above). The `#[allow(unused_variables)]`
                    // section means it doesn't have to parse the individual field references out of
                    // the docstring.
                    #[allow(unused_variables)]
                    let #pat = self;
                    #display
                }
            }
        }
    });

    Ok(quote! { #display })
}
```

--------------------------------

### Helper Function to Take Integer from String Slice

Source: https://docs.rs/displaydoc/latest/src/displaydoc/fmt.rs.html

Extracts a sequence of digits from the beginning of a string slice, advancing the slice past the consumed digits. Used internally for parsing format arguments.

```rust
fn take_int(read: &mut &str) -> String {
    let mut int = String::new();
    int.push('_');
    for (i, ch) in read.char_indices() {
        match ch {
            '0'..='9' => int.push(ch),
            _ => {
                *read = &read[i..];
                break;
            }
        }
    }
    int
}
```

--------------------------------

### Generate Display for Empty Enum

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Generates a `Display` implementation for an enum with no variants. This case is considered uninstantiable and thus unprintable.

```Rust
impl #impl_generics ::core::fmt::Display for #ty #ty_generics #where_clause {
    fn fmt(&self, formatter: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        unreachable!("empty enums cannot be instantiated and thus cannot be printed")
    }
}
```

--------------------------------

### Extract Trait Constraints from Source

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Extracts trait constraints from a `WhereClause` for a given set of type parameters. This function helps in determining which type parameters already have constraints.

```rust
fn extract_trait_constraints_from_source(
    where_clause: &WhereClause,
    type_params: &[&TypeParam],
) -> Vec<(Ident, Vec<TypeParamBound>) > {
    let mut param_constraint_mapping = Vec::new();

    for type_param in type_params {
        let ident = type_param.ident.clone();
        let mut known_bounds = Vec::new();

        // Check if this type parameter is already constrained in the where clause.
        for predicate in &where_clause.predicates {
            if let WherePredicate::Type(pred_ty) = predicate {
                // Check if the predicate's type matches the current type parameter.
                if let Type::Path(TypePath { path, .. }) = &pred_ty.bounded_ty {
                    if path.get_ident().map_or(false, |id| *id == ident) {
                        // Add all trait bounds from this predicate.
                        for bound in pred_ty.bounds.iter() {
                            if let TypeParamBound::Trait(ref bound) = bound {
                                known_bounds.push(bound.clone());
                            }
                        }
                        break; // Found the constraint for this type param, move to the next.
                    }
                }
            }
        }
        param_constraint_mapping.push((ident, known_bounds));
    }

    param_constraint_mapping
}
```

--------------------------------

### Match Arm for Enum Variant with Named Fields

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Generates a `match` arm for an enum variant that has named fields. It quotes the variant identifier and its fields, followed by the display logic.

```Rust
Ok(match &variant.fields {
    Fields::Named(fields) => {
        let var = fields.named.iter().map(|field| &field.ident);
        quote!(Self::#ident { #(#var),* } => { #display })
    }
    Fields::Unnamed(fields) => {
        let var = (0..fields.unnamed.len()).map(|i| format_ident!(
```

--------------------------------

### Generate Where Clause for Display Trait

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Generates a `where` clause that ensures all generic type parameters implement `core::fmt::Display` unless they are already constrained. This is useful for struct/enum definitions deriving `Display`.

```rust
fn generate_where_clause(generics: &Generics, where_clause: Option<&WhereClause>) -> WhereClause {
    let mut where_clause = where_clause.cloned().unwrap_or_else(new_empty_where_clause);
    let type_params: Vec<&TypeParam> = generics.type_params().collect();
    ensure_where_clause_has_display_for_all_unconstrained_members(&mut where_clause, &type_params);
    where_clause
}
```

--------------------------------

### Ensure Display in Where Clause for Type

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Hygienically adds a `where _: Display` constraint to the set of `TypeParamBound`s for a given identifier, creating the set if necessary. This function is crucial for ensuring that type parameters can be formatted.

```rust
fn ensure_display_in_where_clause_for_type(where_clause: &mut WhereClause, ident: Ident) {
    for pred_ty in where_clause
        .predicates
        .iter_mut()
        // Find the `where` predicate constraining the current type param, if it exists.
        .flat_map(|predicate| match predicate {
            WherePredicate::Type(pred_ty) => Some(pred_ty),
            // We're looking through type constraints, not lifetime constraints.
            _ => None,
        })
    {
        // Do a complicated destructuring in order to check if the type being constrained in this
        // `where` clause is the type we're looking for, so we can use the mutable reference to
        // `pred_ty` if so.
        let matches_desired_type = matches!(
            &pred_ty.bounded_ty,
            Type::Path(TypePath { path, .. }) if Some(&ident) == path.get_ident());
        if matches_desired_type {
            add_display_constraint_to_type_predicate(pred_ty);
            return;
        }
    }

    // If there is no `where` predicate for the current type param, we will construct one.
    let mut new_type_predicate = new_empty_where_type_predicate(ident);
    add_display_constraint_to_type_predicate(&mut new_type_predicate);
    append_where_clause_type_predicate(where_clause, new_type_predicate);
}
```

--------------------------------

### Append Type Predicate to Where Clause

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Appends a new type predicate to an existing where clause. Ensures a comma is added if the where clause is not empty.

```rust
fn append_where_clause_type_predicate(
    where_clause: &mut WhereClause,
    new_type_predicate: PredicateType,
) {
    // Push a comma at the end if there are already any `where` predicates.
    if !where_clause.predicates.is_empty() {
        where_clause.predicates.push_punct(Comma {
            spans: [Span::call_site()],
        });
    }
    where_clause
        .predicates
        .push_value(WherePredicate::Type(new_type_predicate));
}
```

--------------------------------

### Helper Function to Take Identifier from String Slice

Source: https://docs.rs/displaydoc/latest/src/displaydoc/fmt.rs.html

Extracts an identifier (alphanumeric characters and underscore) from the beginning of a string slice, advancing the slice past the consumed characters. Used internally for parsing format arguments.

```rust
fn take_ident(read: &mut &str) -> String {
    let mut ident = String::new();
    for (i, ch) in read.char_indices() {
        match ch {
            'a'..='z' | 'A'..='Z' | '0'..='9' | '_' => ident.push(ch),
            _ => {
                *read = &read[i..];
                break;
            }
        }
    }
    ident
}
```

--------------------------------

### Conditional Specialization Traits

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Provides helper traits for Display and Path types, conditionally included based on the 'std' feature flag.

```rust
#[cfg(feature = "std")]
fn specialization() -> TokenStream {
    quote! {
        trait DisplayToDisplayDoc {
            fn __displaydoc_display(&self) -> Self;
        }

        impl<T: ::core::fmt::Display> DisplayToDisplayDoc for &T {
            fn __displaydoc_display(&self) -> Self {
                self
            }
        }

        // If the `std` feature gets enabled we want to ensure that any crate
        // using displaydoc can still reference the std crate, which is already
        // being compiled in by whoever enabled the `std` feature in
        // `displaydoc`, even if the crates using displaydoc are no_std.
        extern crate std;

        trait PathToDisplayDoc {
            fn __displaydoc_display(&self) -> std::path::Display<'_>;
        }

        impl PathToDisplayDoc for std::path::Path {
            fn __displaydoc_display(&self) -> std::path::Display<'_> {
                self.display()
            }
        }

        impl PathToDisplayDoc for std::path::PathBuf {
            fn __displaydoc_display(&self) -> std::path::Display<'_> {
                self.display()
            }
        }
    }
}

#[cfg(not(feature = "std"))]
fn specialization() -> TokenStream {
    quote! {}
}
```

--------------------------------

### Add Display Constraint to Type Predicate

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Adds a `core::fmt::Display` trait bound to a type predicate. This is useful for ensuring a type implements the Display trait.

```rust
fn add_display_constraint_to_type_predicate(
    predicate_that_needs_a_display_impl: &mut PredicateType,
) {
    // Create a `Path` of `::core::fmt::Display`.
    let display_path = join_paths(&["core", "fmt", "Display"], UseGlobalPrefix::LeadingColon);

    let display_bound = TypeParamBound::Trait(TraitBound {
        paren_token: None,
        modifier: TraitBoundModifier::None,
        lifetimes: None,
        path: display_path,
    });
    if !predicate_that_needs_a_display_impl.bounds.is_empty() {
        predicate_that_needs_a_display_impl.bounds.push_punct(Plus {
            spans: [Span::call_site()],
        });
    }

    predicate_that_needs_a_display_impl
        .bounds
        .push_value(display_bound);
}
```

--------------------------------

### Add Display Constraint to Type Predicate

Source: https://docs.rs/displaydoc/latest/src/displaydoc/expand.rs.html

Adds a `core::fmt::Display` trait bound to a type predicate. This is used when a type parameter needs to implement `Display`.

```rust
fn add_display_constraint_to_type_predicate(pred_ty: &mut TypePredicate) {
    for bound in pred_ty.bounds.iter_mut() {
        // We only care about trait bounds here.
        if let TypeParamBound::Trait(ref mut bound) = bound {
            // Check if it's already Display
            if bound.path.get_ident().map_or(false, |ident| ident == "Display") {
                return;
            }
        }
    }
    // Add Display bound
    let mut display_bound = Path::from(quote! { ::core::fmt::Display });
    pred_ty
        .bounds
        .push(TypeParamBound::Trait(TraitBound {
            path: display_bound,
            ..Default::default()
        }));
}
```
Tokens:
Raw