[FEATURE]: Generics, lifetimes, where clauses and internal field variant formatting

[jngls]

This is a considerable update of the proc macro which supports optional custom format strings per variant with full access to variant fields via the #[variant_display(format = "xyz")] attribute.

I recommend reading the code in isolation rather than as a diff.

Summary

• Added EnumAttrs which handles parsing of the main enum_display attribute
• Added VariantAttrs which handles parsing of the new variant_display field attribute
• variant_display field attribute allows the user to customise each variant
  • The format = "xyz" argument defines a custom display format (see below for Format Behaviour) - if omitted, the original crate behaviour is used
• Introduced a new Intermediate Representation (IR) to hold variant info and allow for more complex processing:
  • VariantInfo holds properties common to all variant types
  • NamedVariantIR, UnnamedVariantIR, and UnitVariantIR are the intermediate representations of variant types
  • VariantIR wraps all of those
• Pipeline updated to account for new Intermediate Representation
  • Parsing of syn tokens is moved to the from_*() methods of EnumAttrs, VariantAttrs, and VariantIR
  • We detect if any variant specifies a "format" string - this is to ensure all match arms return the same type
  • Finally we generate match arm tokens with the VariantIR::gen() method
• Tests have been updated

Format Behaviour

Format strings behave almost identically to using format!() in normal rust code so it should be very familiar to users. Besides a bit of translation of unnamed fields, the string specified by the user is the string that ends up as the parameter to format!() in each match arm.

The following considerations apply:

• To print the case adjusted variant name, you use the {variant} placeholder
• To print named variant fields, you use the field name placeholder, eg. if we have Variant { my_field: u32 }, you use the {my_field} placeholder
• To print unnamed variant fields, you use a numbered placeholder, eg. if we have Variant(u32), you use the {0} placeholder (to access the first tuple element)
• It is not currently possible to access fields within fields - each field must implment its own Display or Debug
• Most of the common inline format specs are supported, eg. {my_field:?} displays my_field using its Debug implementation, {0:5} displays the first unnamed field with a width of 5 - however - format spec options which depend on extra arguments passed into format!() are not supported

Additional Notes

• I haven't included any doc changes in this PR - if you like the PR, then I'll happily update the docs
• I've left it to the user to decide if their target platform supports format!() - perhaps instead, we should extern alloc and hide it behind a feature flag?
• This branch accidentally includes code from Implement generics, lifetimes, bounds and where clause support #4 as that was small and done in main - let me know if you want them separated. Otherwise merging Implement generics, lifetimes, bounds and where clause support #4 first or discarding and just merging this would also work.

Full examples

#[derive(EnumDisplay)]
enum TestEnum {
    // Displayed as "Name"
    Name,

    // Displayed as "Unit: NameFullFormat"
    #[variant_display(format = "Unit: {variant}")]
    NameFullFormat,

    // Displayed as "Address"
    Address {
        street: String,
        city: String,
        state: String,
        zip: String,
    },

    // Displayed as "Named: AddressPartialFormat {123 Main St, 12345}"
    #[variant_display(format = "Named: {variant} {{{street}, {zip}}}")]
    AddressPartialFormat {
        street: String,
        city: String,
        state: String,
        zip: String,
    },

    // Displayed as "Named: AddressFullFormat {123 Main St, Any Town, CA, 12345}"
    #[variant_display(format = "Named: {variant} {{{street}, {city}, {state}, {zip}}}")]
    AddressFullFormat {
        street: String,
        city: String,
        state: String,
        zip: String,
    },

    // Displayed as "DateOfBirth"
    DateOfBirth(u32, u32, u32),

    // Displayed as "Unnamed: DateOfBirthPartialFormat(1999)"
    #[variant_display(format = "Unnamed: {variant}({2})")]
    DateOfBirthPartialFormat(u32, u32, u32),

    // Displayed as "Unnamed: DateOfBirthFullFormat(1, 2, 1999)"
    #[variant_display(format = "Unnamed: {variant}({0}, {1}, {2})")]
    DateOfBirthFullFormat(u32, u32, u32),
}

#[test]
fn test_unit_field_variant() {
    assert_eq!(TestEnum::Name.to_string(), "Name");
    assert_eq!(TestEnum::NameFullFormat.to_string(), "Unit: NameFullFormat");
}

#[test]
fn test_named_fields_variant() {
    assert_eq!(
        TestEnum::Address {
            street: "123 Main St".to_string(),
            city: "Any Town".to_string(),
            state: "CA".to_string(),
            zip: "12345".to_string()
        }
        .to_string(),
        "Address"
    );
    assert_eq!(
        TestEnum::AddressPartialFormat {
            street: "123 Main St".to_string(),
            city: "Any Town".to_string(),
            state: "CA".to_string(),
            zip: "12345".to_string()
        }
        .to_string(),
        "Named: AddressPartialFormat {123 Main St, 12345}"
    );
    assert_eq!(
        TestEnum::AddressFullFormat {
            street: "123 Main St".to_string(),
            city: "Any Town".to_string(),
            state: "CA".to_string(),
            zip: "12345".to_string()
        }
        .to_string(),
        "Named: AddressFullFormat {123 Main St, Any Town, CA, 12345}"
    );
}

#[test]
fn test_unnamed_fields_variant() {
    assert_eq!(TestEnum::DateOfBirth(1, 2, 1999).to_string(), "DateOfBirth");
    assert_eq!(TestEnum::DateOfBirthPartialFormat(1, 2, 1999).to_string(), "Unnamed: DateOfBirthPartialFormat(1999)");
    assert_eq!(TestEnum::DateOfBirthFullFormat(1, 2, 1999).to_string(), "Unnamed: DateOfBirthFullFormat(1, 2, 1999)");
}

[jngls]

Simplified the code a bit. It was previously checking that the user actually referenced each field before emitting variables for them, but this adds unnecessary complexity. We can just emit all field variables and let the compiler decide if they're unused.

[jngls]

Btw, my specific use case was this:

#[derive(Debug, Clone, PartialEq, Eq, EnumDisplay)]
#[enum_display(case = "Lower")]
pub enum ParserErrorKind<I> {
    NomError(ErrorKind),
    #[variant_display(format = "{variant}: {0}")]
    Keyword(Keyword),
    Ident(Ident<I>),
    ...
}

Where I wanted to provide a general impl of Display for most variants, but be specific for required Keywords.

[SeedyROM]

Thanks for submitting these PRs! Both the generics impl and this. I'll have time next weekend to actually look at this and critique. From the 1000 mile overview it looks like a solid addition to this library.

It seems like the build pipeline is currently failing and I'll investigate that more as well. Is it possibly due to different version of rustc or possibly the implementation itself??? I never intended this project to get this deep into generics and lifetimes so I might be a bit naive on if this code is correct or not.

Thanks again!

[jngls]

Cheers! Glad you like it on the surface.

The generics side of things was actually really simple (almost like the code equivalent of copy paste - you take the generics from syn and forward them on), so I'd be surprised if that was at fault.

I've had a quick look at the build issue and it's very weird. Does indeed look like maybe a version mismatch.

Anyway, yeah, like you, I'll be able to spend more time on this next weekend.

[SeedyROM]

@jngls I created a branch on top of your changes you pushed here and have got the CI/CD pipeline building and fixed a few other things here: #6. You can see the fixes that were needed.

I'm unfortunately not a git master, so I think some of the history got borked with my changes being pushed upstream to my repo from your fork/branch. Feel free to add my commits to your PR and it works great if you want to properly preserve your impact on the codebase.

Thanks again for the great code and suggestions here. I hope my fixes are good enough for you!

[SeedyROM]

Almost forgot, we should update the docs if there's anything missing and the README.md so that all the latest features of the API are visible to everyone using the crate! Just saying this outloud so neither of us forget.