the big refactor

Author: ModProg

CHANGELOG.md

@@ -4,15 +4,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+### Added
+- Attributes can now be nested, i.e. `#[outer(inner(key = value))]`.
+
+### Changed
+- **Breaking Change** added `span` to `IdentValue`, as this is mostly an implementation detail,
+  most users need not worry about this change.
+- **Breaking Change** changed `FromAttr::from_attributes` to take `[Borrow<Attribute>]`, only relevant for type inference.
+- **Breaking Change** `TokenStream`, when used as field in `FromAttr` now only supports `<name>(<tokens>)` syntax, `<name>=<tokens>` was removed.
+
+### Removed
+- **Breaking Change** mandatory flags
+- **Breaking Change** removed `found_field` in custom error messages
+
 ## [0.8.1] - 2023-09-27
 ### Added
 - Added `FlagOrValue::{is_none, is_flag, is_value, into_value, as_value}`
 
 ## [0.8.0] - 2023-09-18
 ### Changed
 - Renamed `Attribute` to `FromAttr` to not conflict with `syn::Attribute`.
-  The old path is still exported (#[doc(hidden)]). Existing usages should not break.
+  The old path is still exported (`#[doc(hidden)]` and deprecated). Existing usages should not break.
 
 ## [0.7.1] - 2023-09-17
 ### Fixed
@@ -22,7 +35,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated dependencies
 
 ### Added
-- Added `FlagOrValue` to support a value both as a Flag and a Value
+- `FlagOrValue` to support a value both as a Flag and a Value
 
 ### Changed
 - `bool` now allows specifying a flag multiple times.

Cargo.toml

@@ -1,9 +1,12 @@
+[workspace]
+members = ["example"]
+
 [package]
 categories = ["rust-patterns", "development-tools::procedural-macro-helpers", "parsing"]
-description = "Clap for proc macro attributes"
+description = "Clap like parsing for attributes in proc-macros"
 documentation = "https://docs.rs/attribute-derive"
 include = ["src/**/*", "LICENSE", "README.md"]
-keywords = ["derive", "macro"]
+keywords = ["derive", "macro", "attribute", "arguments", "syn", "proc-macro"]
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/ModProg/attribute-derive"
@@ -14,9 +17,11 @@ edition = "2021"
 [lib]
 
 [dependencies]
+derive-where = "1.2.5"
+manyhow = "0.10.3"
 proc-macro2 = "1"
 quote = "1"
-syn =  "2"
+syn = "2"
 
 [features]
 # default = ["syn-full"]
@@ -26,8 +31,10 @@ syn-full = ["syn/full"]
 version = "0.8.1"
 path = "macro"
 
-[workspace]
-members = ["example", "macro"]
+[dev-dependencies]
+insta = "1.34.0"
+quote = "1"
+syn = { version = "2", features = ["extra-traits"] }
 
 [package.metadata.release]
 shared-version = true

docs/traits.html

@@ -0,0 +1,106 @@
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 1em; font-size: 70%;">
+  <style>
+    .node {
+      padding: .5em;
+      border: thin solid;
+      border-radius: 1em;
+    }
+    h3 {
+      margin-top: 0 !important;
+      font-size: 1.25em !important;
+    }
+    h3 code {
+      background: none !important;
+    }
+    .arrow-head {
+      width: 10px;
+      height: 10px;
+      border-top: thin solid;
+      border-right: thin solid;
+      transform: rotate(-45deg);
+      margin-bottom: -11px;
+    }
+    .arrow-v {
+      width: 0px; 
+      min-height: 10px;
+      border-left: thin solid; 
+    }
+    .arrow-h {
+      height: 0px; 
+      border-bottom: thin solid; 
+    }
+    .arrow-label {
+      padding-inline: 5px;
+      background: none !important;
+      text-align: center !important;
+      max-width: calc(100% - 1.5em);
+    }
+    .center-h {
+      margin-inline: auto;
+    }
+    .arrow-cell {
+      display: flex;
+      flex-direction: column;
+      align-content: center;
+      align-items: center;
+    }
+  </style>
+    <div class="node">
+        <h3><a href="../trait.FromAttr.html"><code>FromAttr</code></a></h3>
+        <p>Main entry point. Derived via macro. Anything that can be parsed from one or multiple attributes.</p>
+    </div>
+    <div class="node">
+        <h3><a href="trait.AttributeNamed.html"><code>AttributeNamed</code></a></h3>
+        <p>Values that can be parsed named, e.g. <code>name(&lt;value&gt;)</code>, <code>name = &lt;value&gt;</code>, <code>name</code> (as flag).</p>
+        <p>This is the default parsing mode used for fields in derived <a href="../trait.FromAttr.html"><code>FromAttr</code></a> implementations.</p>
+    </div>
+    <div class="node">
+        <h3><a href="trait.AttributePositional.html"><code>AttributePositional</code></a></h3>
+        <p>Values that can be parsed positionally, i.e., without a name, e.g. <code>"literal"</code>, <code>a + b</code>, <code>true</code>.</p>
+        <p>When deriving <a href="../trait.FromAttr.html"><code>FromAttr</code></a> this is enabled via putting <code>#[attr(positional)]</code> on the field.</p>
+    </div>
+    <div class="arrow-cell" style="grid-column: 1; grid-row: 2;">
+      <div class="arrow-head"></div>
+      <div style="flex: 1" class="arrow-v"></div>
+      <code class="arrow-label">impl &lt;T: AttributeValue&gt; FromAttr for T</code>
+      <div style="flex: 1" class="arrow-v"></div>
+    </div>
+    <div class="arrow-cell" style="grid-column: 2; grid-row: 2;">
+      <div class="arrow-head"></div>
+      <div style="flex: 1" class="arrow-v"></div>
+        <code class="arrow-label">impl &lt;T: AttributeValue&gt; AttributeNamed for T</code>
+      <div style="flex: 1" class="arrow-v"></div>
+    </div>
+    <div class="arrow-cell" style="grid-column: 3; grid-row: 2;">
+      <div class="arrow-head"></div>
+      <div style="flex: 1" class="arrow-v"></div>
+      <code class="arrow-label">impl &lt;T: AttributeValue + PositionalValue&gt; AttributePositional for T</code>
+      <div style="flex: 1" class="arrow-v"></div>
+    </div>
+    <div style="grid-column: 2 / 4; grid-row: 2; position: relative;">
+      <div class="arrow-v" style="left: calc(50% - 1.5em); bottom: 0; height: 50%; position: absolute;"> </div>
+      <div class="arrow-h" style="left: calc(50% - 1.5em); bottom: 50%; width: 3em; position: absolute;"> </div>
+    </div>
+    <div class="arrow-cell">
+      <div style="height: 4em; margin-top: -1em;" class="arrow-v"></div>
+      <div class="arrow-h" style="margin-left: 50%; width: 50%;"></div>
+    </div>
+    <div class="node">
+      <h3><a href="trait.AttributeValue.html"><code>AttributeValue</code></a></h3>
+      Any attribute that has the concept of a value, e.g., <code>"positional"</code>, <code>meta(&lt;value&gt;)</code>, <code>key = &lt;value&gt;</code>.
+    </div>
+    <div class="node">
+      <h3><a href="trait.PositionalValue.html"><code>PositionalValue</code></a></h3>
+      Empty marker trait, defining which <code>AttributeValue</code> implement <code>AttributePositional</code>.
+    </div>
+    <div class="arrow-cell" style="grid-column: 2;">
+      <div class="arrow-head"></div>
+      <div style="flex: 1" class="arrow-v"></div>
+        <code class="arrow-label">impl &lt;T: AttributeMeta&gt; AttributeValue for T</code>
+      <div style="flex: 1" class="arrow-v"></div>
+    </div>
+    <div class="node" style="grid-column: 2;">
+      <h3><a href="trait.AttributeMeta.html"><code>AttributeMeta</code></a></h3>
+        <p>Values in function or meta style attributes, i.e., <code>meta(&lt;value&gt;).</code></p>
+    </div>
+</div>

example/src/lib.rs

@@ -46,8 +46,6 @@ struct Normal {
     #[attribute(example = "2.5")]
     example: f32,
     flag: bool,
-    #[attribute(optional = false)]
-    mandatory_flag: bool,
 }
 #[proc_macro_derive(Normal, attributes(ident, a, b, empty, single))]
 pub fn normal_derive(input: TokenStream) -> proc_macro::TokenStream {
@@ -62,12 +60,10 @@ pub fn normal_derive(input: TokenStream) -> proc_macro::TokenStream {
 #[derive(FromAttr, Debug)]
 #[attribute(ident = ident, aliases = [a, b])]
 #[attribute(error(
-    unknown_field = "found `{found_field}` but expected one of {expected_fields:i(`{}`)(, )}",
+    unknown_field = "expected one of {expected_fields:i(`{}`)(, )}",
     duplicate_field = "duplicate `{field}`",
     missing_field = "missing field `{field}`",
     field_help = "try {attribute}: {field}={example}",
-    missing_flag = "missing flag `{flag}`",
-    flag_help = "try {attribute}: {flag}",
     conflict = "{first} !!! {second}"
 ))]
 struct Custom {
@@ -84,15 +80,13 @@ struct Custom {
     #[attribute(example = "2.5")]
     example: f32,
     flag: bool,
-    #[attribute(optional = false)]
-    mandatory_flag: bool,
 }
 #[derive(FromAttr)]
-#[attribute(ident = empty, error(unknown_field_empty = "found {found_field}, but expected none"))]
+#[attribute(ident = empty, error(unknown_field_empty = "expected nothing"))]
 struct EmptyCustom {}
 
 #[derive(FromAttr)]
-#[attribute(ident = single, error(unknown_field_single = "found {found_field}, but expected {expected_field}"))]
+#[attribute(ident = single, error(unknown_field_single = "expected {expected_field}"))]
 struct SingleCustom {
     field: bool,
 }

example/tests/ui/custom.rs

@@ -14,12 +14,11 @@ struct Example;
     optional_default = 3,
     default = 2,
     conflict_a = "hello",
-    mandatory_flag
 )]
 struct ExampleOI;
 
 #[derive(Custom)]
-#[ident(example = 1., mandatory_flag)]
+#[ident(example = 1.)]
 #[a(conflict_a = "hey")]
 #[b(conflict_b = "hi")]
 struct Conflict;

example/tests/ui/custom.stderr

@@ -8,42 +8,32 @@ error: missing field `example`
   |
   = note: this error originates in the derive macro `Custom` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error: missing flag `mandatory_flag`
-
-       = help: try ident: mandatory_flag
- --> tests/ui/custom.rs:6:10
-  |
-6 | #[derive(Custom)]
-  |          ^^^^^^
-  |
-  = note: this error originates in the derive macro `Custom` (in Nightly builds, run with -Z macro-backtrace for more info)
-
 error: conflict_a !!! conflict_b
-  --> tests/ui/custom.rs:23:5
+  --> tests/ui/custom.rs:22:5
    |
-23 | #[a(conflict_a = "hey")]
+22 | #[a(conflict_a = "hey")]
    |     ^^^^^^^^^^
 
 error: conflict_b !!! conflict_a
-  --> tests/ui/custom.rs:24:5
+  --> tests/ui/custom.rs:23:5
    |
-24 | #[b(conflict_b = "hi")]
+23 | #[b(conflict_b = "hi")]
    |     ^^^^^^^^^^
 
-error: found `hello` but expected one of `optional_implicit`, `optional_explicit`, `optional_default`, `default`, `conflict_a`, `conflict_b`, `example`, `flag`, `mandatory_flag`
-  --> tests/ui/custom.rs:28:9
+error: expected one of `optional_implicit`, `optional_explicit`, `optional_default`, `default`, `conflict_a`, `conflict_b`, `example`, `flag`
+  --> tests/ui/custom.rs:27:9
    |
-28 | #[ident(hello)]
+27 | #[ident(hello)]
    |         ^^^^^
 
-error: found hello, but expected none
-  --> tests/ui/custom.rs:30:9
+error: expected nothing
+  --> tests/ui/custom.rs:29:9
    |
-30 | #[empty(hello)]
+29 | #[empty(hello)]
    |         ^^^^^
 
-error: found hello, but expected field
-  --> tests/ui/custom.rs:29:10
+error: expected field
+  --> tests/ui/custom.rs:28:10
    |
-29 | #[single(hello)]
+28 | #[single(hello)]
    |          ^^^^^

example/tests/ui/normal.rs

@@ -14,12 +14,11 @@ struct Example;
     optional_default = 3,
     default = 2,
     conflict_a = "hello",
-    mandatory_flag
 )]
 struct ExampleOI;
 
 #[derive(Normal)]
-#[ident(example = 1., mandatory_flag)]
+#[ident(example = 1.)]
 #[a(conflict_a = "hey")]
 #[b(conflict_b = "hi")]
 struct Conflict;

example/tests/ui/normal.stderr

@@ -1,49 +1,39 @@
 error: required `example` is not specified
 
-       = help: try `#[ident(example=2.5)]`
+       = help: try `#[ident(example = 2.5)]`
  --> tests/ui/normal.rs:3:10
   |
 3 | #[derive(Normal)]
   |          ^^^^^^
   |
   = note: this error originates in the derive macro `Normal` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error: required `mandatory_flag` is not specified
-
-       = help: try `#[ident(mandatory_flag)]`
- --> tests/ui/normal.rs:6:10
-  |
-6 | #[derive(Normal)]
-  |          ^^^^^^
-  |
-  = note: this error originates in the derive macro `Normal` (in Nightly builds, run with -Z macro-backtrace for more info)
-
 error: `conflict_a` conflicts with mutually exclusive `conflict_b`
-  --> tests/ui/normal.rs:23:5
+  --> tests/ui/normal.rs:22:5
    |
-23 | #[a(conflict_a = "hey")]
+22 | #[a(conflict_a = "hey")]
    |     ^^^^^^^^^^
 
 error: `conflict_b` conflicts with mutually exclusive `conflict_a`
-  --> tests/ui/normal.rs:24:5
+  --> tests/ui/normal.rs:23:5
    |
-24 | #[b(conflict_b = "hi")]
+23 | #[b(conflict_b = "hi")]
    |     ^^^^^^^^^^
 
-error: supported fields are `optional_implicit`, `optional_explicit`, `optional_default`, `default`, `conflict_a`, `conflict_b`, `example`, `flag` and `mandatory_flag`
-  --> tests/ui/normal.rs:28:9
+error: supported fields are `optional_implicit`, `optional_explicit`, `optional_default`, `default`, `conflict_a`, `conflict_b`, `example` and `flag`
+  --> tests/ui/normal.rs:27:9
    |
-28 | #[ident(hello)]
+27 | #[ident(hello)]
    |         ^^^^^
 
 error: expected empty attribute
-  --> tests/ui/normal.rs:30:9
+  --> tests/ui/normal.rs:29:9
    |
-30 | #[empty(hello)]
+29 | #[empty(hello)]
    |         ^^^^^
 
 error: expected supported field `field`
-  --> tests/ui/normal.rs:29:10
+  --> tests/ui/normal.rs:28:10
    |
-29 | #[single(hello)]
+28 | #[single(hello)]
    |          ^^^^^

macro/Cargo.toml

@@ -18,13 +18,13 @@ proc-macro = true
 [dependencies]
 proc-macro2 = "1"
 quote = "1"
-quote-use = { version = "0.7", features = ["namespace_idents"] }
+quote-use = "0.8"
 syn = "2"
 proc-macro-utils = "0.8.0"
 # proc-macro-utils = {path = "../../proc-macro-utils"}
 interpolator = { version = "0.5.0", features = ["iter"] }
 collection_literals = "1"
-manyhow = "0.8"
+manyhow = "0.10"
 
 [package.metadata.release]
 tag = false