1
//! [`KeySpecifier`] derive-adhoc macro and its support code
2
//!
3
//! # STABILITY - NOTHING IN THIS MODULE IS PART OF THE STABLE PUBLIC API
4
//!
5
//! The `pub` items in this module are accessible as `$crate::key_specifier_derive`,
6
//! but `#[doc(hidden)]` is applied at the top level.
7
//!
8
//! (Recall that the actual derive-adhoc macro
9
//! `KeySpecifier` ends up in the crate toplevel,
10
//! so that *does* form part of our public API.)
11

            
12
use std::iter;
13

            
14
use derive_deftly::define_derive_deftly;
15
use itertools::{izip, EitherOrBoth, Itertools};
16

            
17
use super::*;
18
use crate::DENOTATOR_SEP;
19

            
20
pub use crate::KeyPathInfoBuilder;
21
pub use tor_error::{internal, into_internal, Bug};
22

            
23
/// Trait for (only) formatting as a [`KeySpecifierComponent`]
24
///
25
/// Like the formatting part of `KeySpecifierComponent`
26
/// but implemented for Option and &str too.
27
pub trait RawKeySpecifierComponent {
28
    /// Append `self`s `KeySpecifierComponent` string representation to `s`
29
    //
30
    // This is not quite like `KeySpecifierComponent::to_slug`,
31
    // since that *returns* a String (effectively) and we *append*.
32
    // At some future point we may change KeySpecifierComponent,
33
    // although the current API has the nice feature that
34
    // the syntax of the appended string is checked before we receive it here.
35
    fn append_to(&self, s: &mut String) -> Result<(), Bug>;
36
}
37
impl<T: KeySpecifierComponent> RawKeySpecifierComponent for T {
38
2170
    fn append_to(&self, s: &mut String) -> Result<(), Bug> {
39
2170
        self.to_slug()?.as_str().append_to(s)
40
2170
    }
41
}
42
impl<T: KeySpecifierComponent> RawKeySpecifierComponent for Option<T> {
43
88
    fn append_to(&self, s: &mut String) -> Result<(), Bug> {
44
88
        let v: &dyn RawKeySpecifierComponent = match self.as_ref() {
45
32
            Some(v) => v,
46
56
            None => &"*",
47
        };
48
88
        v.append_to(s)
49
88
    }
50
}
51
impl<'s> RawKeySpecifierComponent for &'s str {
52
71697
    fn append_to(&self, s: &mut String) -> Result<(), Bug> {
53
71697
        s.push_str(self);
54
71697
        Ok(())
55
71697
    }
56
}
57

            
58
/// Make a string like `pc/pc/pc/lc_lc_lc`
59
19060
fn arti_path_string_from_components(
60
19060
    path_comps: &[&dyn RawKeySpecifierComponent],
61
19060
    leaf_comps: &[&dyn RawKeySpecifierComponent],
62
19060
) -> Result<String, Bug> {
63
19060
    let mut path = String::new();
64

            
65
60602
    for comp in path_comps {
66
41542
        comp.append_to(&mut path)?;
67
41542
        path.push('/');
68
    }
69
30153
    for (delim, comp) in izip!(
70
19060
        iter::once(None).chain(iter::repeat(Some(DENOTATOR_SEP))),
71
19060
        leaf_comps,
72
19060
    ) {
73
30153
        if let Some(delim) = delim {
74
11093
            path.push(delim);
75
19060
        }
76
30153
        comp.append_to(&mut path)?;
77
    }
78

            
79
19060
    Ok(path)
80
19060
}
81

            
82
/// Make an `ArtiPath` like `pc/pc/pc/lc_lc_lc`
83
///
84
/// This is the engine for the `KeySpecifier` macro's `arti_path()` impls.
85
///
86
/// The macro-generated code sets up couple of vectors.
87
/// Each vector entry is a pointer to the field in the original struct,
88
/// plus a vtable pointer saying what to do with it.
89
///
90
/// For fixed elements in the path,
91
/// the vtable entry's data pointer is a pointer to a constant &str.
92
///
93
/// In the macro, this is done by the user-defined expansion `ARTI_FROM_COMPONENTS_ARGS`.
94
///
95
/// Doing it this way minimises the amount of macro-generated machine code.
96
18680
pub fn arti_path_from_components(
97
18680
    path_comps: &[&dyn RawKeySpecifierComponent],
98
18680
    leaf_comps: &[&dyn RawKeySpecifierComponent],
99
18680
) -> Result<ArtiPath, ArtiPathUnavailableError> {
100
18680
    Ok(arti_path_string_from_components(path_comps, leaf_comps)?
101
18680
        .try_into()
102
18680
        .map_err(into_internal!("bad ArtiPath from good components"))?)
103
18680
}
104

            
105
/// Make a `KeyPathPattern::Arti` like `pc/pc/pc/lc_lc_lc`
106
380
pub fn arti_pattern_from_components(
107
380
    path_comps: &[&dyn RawKeySpecifierComponent],
108
380
    leaf_comps: &[&dyn RawKeySpecifierComponent],
109
380
) -> Result<KeyPathPattern, Bug> {
110
380
    Ok(KeyPathPattern::Arti(arti_path_string_from_components(
111
380
        path_comps, leaf_comps,
112
380
    )?))
113
380
}
114

            
115
/// Error returned from [`RawKeySpecifierComponentParser::parse`]
116
#[derive(Debug)]
117
#[allow(clippy::exhaustive_enums)] // Not part of public API
118
pub enum RawComponentParseResult {
119
    /// This was a field
120
    ///
121
    /// The `Option` has been filled with the actual value.
122
    /// It has an entry in the `keys` argument to [`parse_key_path`].
123
    ParsedField,
124
    /// This was a literal, and it matched
125
    MatchedLiteral,
126
    /// Becomes [`KeyPathError::PatternNotMatched`]
127
    PatternNotMatched,
128
    /// `InvalidKeyPathComponentValue`
129
    Invalid(InvalidKeyPathComponentValue),
130
}
131

            
132
use RawComponentParseResult as RCPR;
133

            
134
/// Trait for parsing a path component, used by [`parse_key_path`]
135
///
136
/// Implemented for `Option<impl KeySpecifierComponent>`,
137
/// and guarantees to fill in the Option if it succeeds.
138
///
139
/// Also implemented for `&str`: just checks that the string is right,
140
/// (and, doesn't modify `*self`).
141
pub trait RawKeySpecifierComponentParser {
142
    /// Check that `comp` is as expected, and store any results in `self`.
143
    fn parse(&mut self, comp: &Slug) -> RawComponentParseResult;
144
}
145

            
146
impl<T: KeySpecifierComponent> RawKeySpecifierComponentParser for Option<T> {
147
598
    fn parse(&mut self, comp: &Slug) -> RawComponentParseResult {
148
598
        let v = match T::from_slug(comp) {
149
598
            Ok(v) => v,
150
            Err(e) => return RCPR::Invalid(e),
151
        };
152
598
        *self = Some(v);
153
598
        RCPR::ParsedField
154
598
    }
155
}
156
impl<'s> RawKeySpecifierComponentParser for &'s str {
157
5802
    fn parse(&mut self, comp: &Slug) -> RawComponentParseResult {
158
5802
        if comp.as_str() == *self {
159
5802
            RCPR::MatchedLiteral
160
        } else {
161
            RCPR::PatternNotMatched
162
        }
163
5802
    }
164
}
165

            
166
/// List of parsers for fields
167
type Parsers<'p> = [&'p mut dyn RawKeySpecifierComponentParser];
168

            
169
/// Parse a `KeyPath` as an `ArtiPath` like pc/pc/pc/lc_lc_lc
170
///
171
/// `keys` is the field names for each of the path_parsers and leaf_parsers,
172
/// *but* only the ones which will return `RCPR::ParsedField` (or `::Invalid`).
173
///
174
/// As with `arti_path_string_components` etc., we try to minimise
175
/// the amount of macro-generated machine code.
176
///
177
/// The macro-generated impl again assembles two vectors,
178
/// one for the path components and one for the leaf components.
179
///
180
/// For a field, the vector entry is a pointer to `&mut Option<...>`
181
/// for the field, along with a `RawKeySpecifierComponentParser` vtable entry.
182
/// (The macro-generated impl must unwrap each of these Options,
183
/// to assemble the final struct.  In principle this could be avoided with
184
/// use of `MaybeUninit` and unsafe.)
185
///
186
/// For a fixed string component, the vector entry data pointer points to its `&str`.
187
/// "Parsing" consists of checking that the string is as expected.
188
///
189
/// We also need the key names for error reporting.
190
/// We pass this as a *single* array, and a double-reference to the slice,
191
/// since that resolves to one pointer to a static structure.
192
2901
pub fn parse_key_path(
193
2901
    path: &KeyPath,
194
2901
    keys: &&[&str],
195
2901
    path_parsers: &mut Parsers,
196
2901
    leaf_parsers: &mut Parsers,
197
2901
) -> Result<(), KeyPathError> {
198
2901
    let (path, arti_path) = match path {
199
2901
        KeyPath::Arti(path) => (path.as_str(), path),
200
        KeyPath::CTor(_path) => {
201
            // TODO (#858): support ctor stores
202
            return Err(internal!("not implemented").into());
203
        }
204
    };
205

            
206
2901
    let (path, leaf) = match path.rsplit_once('/') {
207
2901
        Some((path, leaf)) => (Some(path), leaf),
208
        None => (None, path),
209
    };
210

            
211
2901
    let mut keys: &[&str] = keys;
212
2901

            
213
2901
    /// Split a string into components and parse each one
214
5802
    fn extract(
215
5802
        arti_path: &ArtiPath,
216
5802
        input: Option<&str>,
217
5802
        delim: char,
218
5802
        parsers: &mut Parsers,
219
5802
        keys: &mut &[&str],
220
5802
    ) -> Result<(), KeyPathError> {
221
14375
        for ent in Itertools::zip_longest(
222
6006
            input.map(|input| input.split(delim)).into_iter().flatten(),
223
5802
            parsers,
224
2901
        ) {
225
14375
            let EitherOrBoth::Both(comp, parser) = ent else {
226
2901
                // wrong number of components
227
2901
                return Err(KeyPathError::PatternNotMatched(arti_path.clone()));
228
2901
            };
229
2901

            
230
2901
            // TODO would be nice to avoid allocating again here,
231
2901
            // but I think that needs an `SlugRef`.
232
14375
            let comp = Slug::new(comp.to_owned())
233
14375
                .map_err(ArtiPathSyntaxError::Slug)
234
14375
                .map_err(|error| KeyPathError::InvalidArtiPath {
235
102
                    error,
236
102
                    path: arti_path.clone(),
237
14375
                })?;
238
2901

            
239
14375
            let missing_keys = || internal!("keys list too short, bad args to parse_key_path");
240
2901

            
241
14375
            match parser.parse(&comp) {
242
2901
                RCPR::PatternNotMatched => Err(KeyPathError::PatternNotMatched(arti_path.clone())),
243
2901
                RCPR::Invalid(error) => Err(KeyPathError::InvalidKeyPathComponentValue {
244
                    error,
245
                    key: keys.first().ok_or_else(missing_keys)?.to_string(),
246
                    path: arti_path.clone(),
247
                    value: comp,
248
2901
                }),
249
2901
                RCPR::ParsedField => {
250
8573
                    *keys = keys.split_first().ok_or_else(missing_keys)?.1;
251
8573
                    Ok(())
252
2901
                }
253
5802
                RCPR::MatchedLiteral => Ok(()),
254
2901
            }?;
255
2901
        }
256
5802
        Ok(())
257
5802
    }
258
2901

            
259
2901
    extract(arti_path, path, '/', path_parsers, &mut keys)?;
260
2901
    extract(
261
2901
        arti_path,
262
2901
        Some(leaf),
263
2901
        DENOTATOR_SEP,
264
2901
        leaf_parsers,
265
2901
        &mut keys,
266
2901
    )?;
267
2901
    Ok(())
268
2901
}
269

            
270
/// Wrapper for `KeySpecifierComponent` that `Displays` via `fmt_pretty`
271
struct KeySpecifierComponentPrettyHelper<'c>(&'c dyn KeySpecifierComponent);
272

            
273
impl Display for KeySpecifierComponentPrettyHelper<'_> {
274
10
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
275
10
        KeySpecifierComponent::fmt_pretty(self.0, f)
276
10
    }
277
}
278

            
279
/// Build a `KeyPathInfo` given the information about a key specifier
280
///
281
/// Calling pattern, to minimise macro-generated machine code,
282
/// is similar `arti_path_from_components`.
283
///
284
/// The macro-generated code parses the path into its KeySpecifier impl
285
/// (as an owned value) and then feeds references to the various fields
286
/// to `describe_via_components`.
287
2
pub fn describe_via_components(
288
2
    summary: &&str,
289
2
    role: &dyn RawKeySpecifierComponent,
290
2
    extra_keys: &&[&str],
291
2
    extra_info: &[&dyn KeySpecifierComponent],
292
2
) -> Result<KeyPathInfo, KeyPathError> {
293
2
    let mut info = KeyPathInfoBuilder::default();
294
2
    info.summary(summary.to_string());
295
2
    info.role({
296
2
        let mut s = String::new();
297
2
        role.append_to(&mut s)?;
298
2
        s
299
    });
300
10
    for (key, value) in izip!(*extra_keys, extra_info) {
301
10
        let value = KeySpecifierComponentPrettyHelper(*value).to_string();
302
10
        info.extra_info(*key, value);
303
10
    }
304
2
    Ok(info
305
2
        .build()
306
2
        .map_err(into_internal!("failed to build KeyPathInfo"))?)
307
2
}
308

            
309
define_derive_deftly! {
310
    /// A helper for implementing [`KeySpecifier`]s.
311
    ///
312
    /// Applies to a struct that has some static components (`prefix`, `role`),
313
    /// and a number of variable components represented by its fields.
314
    ///
315
    /// Implements `KeySpecifier` etc.
316
    ///
317
    /// Each field is either a path field (which becomes a component in the `ArtiPath`),
318
    /// or a denotator (which becomes *part* of the final component in the `ArtiPath`).
319
    ///
320
    /// The `prefix` is the first component of the [`ArtiPath`] of the [`KeySpecifier`].
321
    ///
322
    /// The role should be the name of the key in the Tor Specifications.
323
    /// The **lowercased** `role` is used as the _prefix of the last component_
324
    /// of the [`ArtiPath`] of the specifier.
325
    /// The `role` is followed by the denotators of the key.
326
    ///
327
    /// The denotator fields, if there are any,
328
    /// should be annotated with `#[denotator]`.
329
    ///
330
    /// The declaration order of the fields is important.
331
    /// The inner components of the [`ArtiPath`] of the specifier are built
332
    /// from the string representation of its path fields, taken in declaration order,
333
    /// followed by the encoding of its denotators, also taken in the order they were declared.
334
    /// As such, all path fields, must implement [`KeySpecifierComponent`].
335
    /// and all denotators must implement [`KeySpecifierComponent`].
336
    /// The denotators are separated from the rest of the path, and from each other,
337
    /// by `+` characters.
338
    ///
339
    /// For example, a key specifier with `prefix` `"foo"` and `role` `"bar"`
340
    /// will have an [`ArtiPath`] of the form
341
    /// `"foo/<field1_str>/<field2_str>/../bar[+<denotators>]"`.
342
    ///
343
    /// A key specifier of this form, with denotators that encode to "d1" and "d2",
344
    /// would look like this: `"foo/<field1_str>/<field2_str>/../bar+d1+d2"`.
345
    ///
346
    /// ### Results of applying this macro
347
    ///
348
    /// `#[derive(Deftly)] #[derive_deftly(KeySpecifier)] struct SomeKeySpec ...`
349
    /// generates:
350
    ///
351
    ///  * `impl `[`KeySpecifier`]` for SomeKeySpec`
352
    ///  * `struct SomeKeySpecPattern`,
353
    ///    a derived struct which contains an `Option` for each field.
354
    ///    `None` in the pattern means "any".
355
    ///  * `impl `[`KeySpecifierPattern`]` for SomeKeySpecPattern`
356
    ///  * `impl TryFrom<`[`KeyPath`]> for SomeKeySpec`
357
    ///  * Registration of an impl of [`KeyPathInfoExtractor`]
358
    ///    (on a private unit struct `SomeKeySpecInfoExtractor`)
359
    ///
360
    /// ### Custom attributes
361
    ///
362
    ///  * **`#[deftly(prefix)]`** (toplevel):
363
    ///    Specifies the fixed prefix (the first path component).
364
    ///    Must be a literal string.
365
    ///
366
    ///  * **`#[deftly(role = "...")]`** (toplevel):
367
    ///    Specifies the role - the initial portion of the leafname.
368
    ///    This should be the name of the key in the Tor Specifications.
369
    ///    Must be a literal string.
370
    ///    This or the field-level `#[deftly(role)]` must be specified.
371
    ///
372
    ///  * **`[adhoc(role)]` (field):
373
    ///    Specifies that the role is determined at runtime.
374
    ///    The field type must implement [`KeyDenotator`].
375
    ///
376
    ///  * **`#[deftly(summary = "...")]`** (summary, mandatory):
377
    ///    Specifies the summary; ends up as the `summary` field in [`KeyPathInfo`].
378
    ///    (See [`KeyPathInfoBuilder::summary()`].)
379
    ///    Must be a literal string.
380
    ///
381
    ///  * **`#[deftly(denotator)]`** (field):
382
    ///    Designates a field that should be represented
383
    ///    in the key file leafname, after the role.
384
    ///
385
    ///  * **`#[deftly(ctor_path = "expression")]`** (toplevel):
386
    ///    Specifies that this kind of key has a representation in C Tor keystores,
387
    ///    and provides an expression for computing the path.
388
    ///    The expression should have type `impl Fn(&Self) -> CTorPath`.
389
    ///
390
    ///    If not specified, the generated [`KeySpecifier::ctor_path`]
391
    ///    implementation will always return `None`.
392
    ///
393
    ///  * **`#[deftly(fixed_path_component = "component")]`** (field):
394
    ///    Before this field insert a fixed path component `component`.
395
    ///    (Can be even used before a denotator component,
396
    ///    to add a final fixed path component.)
397
    ///
398
    pub KeySpecifier for struct =
399

            
400
    // A condition that evaluates to `true` for path fields.
401
    ${defcond F_IS_PATH not(any(fmeta(denotator), fmeta(role)))}
402
    ${defcond F_IS_ROLE all(fmeta(role), not(tmeta(role)))}
403

            
404
    #[doc = concat!("Pattern matching some or all [`", stringify!($tname), "`]")]
405
    #[allow(dead_code)] // Not everyone will need the pattern feature
406
    $tvis struct $<$tname Pattern><$tdefgens>
407
    where $twheres
408
    ${vdefbody $vname $(
409
        ${fattrs doc}
410
        ///
411
        /// `None` to match keys with any value for this field.
412
        $fvis $fname: Option<$ftype>,
413
    ) }
414

            
415
    // ** MAIN KNOWLEDGE OF HOW THE PATH IS CONSTRUCTED **
416
    //
417
    // These two user-defined expansions,
418
    //   $ARTI_PATH_COMPONENTS
419
    //   $ARTI_LEAF_COMPONENTS
420
    // expand to code for handling each path and leaf component,
421
    // in the order in which they appear in the ArtiPath.
422
    //
423
    // The "code for handling", by default, is:
424
    //   - for a field, take a reference to the field in `self`
425
    //   - for a fixed component, take a reference to a &'static str
426
    // in each case with a comma appended.
427
    // So this is suitable for including in a &[&dyn ...].
428
    //
429
    // The call site can override the behaviour by locally redefining,
430
    // the two user-defined expansions DO_FIELD and DO_LITERAL.
431
    //
432
    // DO_FIELD should expand to the code necessary to handle a field.
433
    // It probably wants to refer to $fname.
434
    //
435
    // DO_LITERAL should expand to the code necessary to handle a literal value.
436
    // When DO_LITERAL is called the user-defined expansion LIT will expand to
437
    // something like `${fmeta(...) as str}`, which will in turn expand to
438
    // a string literal.
439
    //
440
    // For use sites which want to distinguish the role from other fields:
441
    // DO_ROLE_FIELD and DO_ROLE_LITERAL are used for the role.
442
    // They default to expanding $DO_FIELD and $DO_LITERAL respectively.
443
    //
444
    // This is the *only* place that knows how ArtiPaths are constructed,
445
    // when the path syntax is defined using the KeySpecifier d-a macro.
446
    //
447
    // The actual code here is necessarily rather abstract.
448
    ${define ARTI_PATH_COMPONENTS {
449
        // #[deftly(prefix = ...)]
450
        ${define LIT ${tmeta(prefix) as str}}
451
        $DO_LITERAL
452

            
453
        ${for fields {
454
            // #[deftly(fixed_path_component = ...)]
455
            ${if fmeta(fixed_path_component) {
456
                // IWVNI d-a allowed arguments to use-defined expansions, but this will do
457
                ${define LIT ${fmeta(fixed_path_component) as str}}
458
                $DO_LITERAL
459
            }}
460
            // Path fields
461
            ${if F_IS_PATH { $DO_FIELD }}
462
        }}
463
    }}
464
    ${define ARTI_LEAF_COMPONENTS {
465
        ${if tmeta(role) {
466
            // #[deftly(role = ...)] on the toplevel
467
            ${define LIT { stringify!(${snake_case ${tmeta(role)}}) }}
468
            $DO_ROLE_LITERAL
469
        }}
470
        ${for fields {
471
            // #[deftly(role)] on a field
472
            ${if F_IS_ROLE { $DO_ROLE_FIELD }}
473
        }}
474
        ${for fields {
475
            // #[deftly(denotator)]
476
            ${if fmeta(denotator) { $DO_FIELD }}
477
        }}
478
    }}
479

            
480
    ${define DO_FIELD { &self.$fname, }}
481
    ${define DO_LITERAL { &$LIT, }}
482
    ${define DO_ROLE_FIELD { $DO_FIELD }}
483
    ${define DO_ROLE_LITERAL { $DO_LITERAL }}
484

            
485
    impl<$tgens> $crate::KeySpecifier for $ttype
486
    where $twheres
487
    {
488
1222
        fn arti_path(
489
1222
            &self,
490
1222
        ) -> std::result::Result<$crate::ArtiPath, $crate::ArtiPathUnavailableError> {
491
            use $crate::key_specifier_derive::*;
492

            
493
            arti_path_from_components(
494
                &[ $ARTI_PATH_COMPONENTS ],
495
                &[ $ARTI_LEAF_COMPONENTS ],
496
            )
497
        }
498

            
499
4
        fn ctor_path(&self) -> Option<$crate::CTorPath> {
500
            ${if tmeta(ctor_path) {
501
                // TODO (#858): the HsSvcKeySpecifier will need to be configured with all the
502
                // directories used by C tor. The resulting CTorPath will be prefixed with the
503
                // appropriate C tor directory, based on the HsSvcKeyRole.
504
                //
505
                // Ie, provide the #[deftly(ctor_path)] attribute
506
                Some( ${tmeta(ctor_path) as tokens} (self) )
507
            } else {
508
                None
509
            }}
510
        }
511
    }
512

            
513
    impl<$tgens> $crate::KeySpecifierPattern for $<$tname Pattern><$tdefgens>
514
    where $twheres
515
    {
516
32
        fn arti_pattern(
517
32
            &self,
518
32
        ) -> std::result::Result<$crate::KeyPathPattern, $crate::key_specifier_derive::Bug> {
519
            use $crate::key_specifier_derive::*;
520

            
521
            arti_pattern_from_components(
522
                &[ $ARTI_PATH_COMPONENTS ],
523
                &[ $ARTI_LEAF_COMPONENTS ],
524
            )
525
        }
526

            
527
206
        fn new_any() -> Self {
528
            $< $tname Pattern > {
529
                $( $fname: None, )
530
            }
531
        }
532
    }
533

            
534
    struct $< $tname InfoExtractor >;
535

            
536
    impl<$tgens> $crate::KeyPathInfoExtractor for $< $tname InfoExtractor >
537
    where $twheres
538
    {
539
2
        fn describe(
540
2
            &self,
541
2
            path: &$crate::KeyPath,
542
2
        ) -> std::result::Result<$crate::KeyPathInfo, $crate::KeyPathError> {
543
            use $crate::key_specifier_derive::*;
544

            
545
            // Parse this path
546
            #[allow(unused_variables)] // Unused if no fields
547
            let spec = $ttype::try_from(path)?;
548

            
549
            // none of this cares about non-role literals
550
            // all the others three be explicitly defined each time
551
            ${define DO_LITERAL {}}
552

            
553
            static NON_ROLE_FIELD_KEYS: &[&str] = &[
554
                ${define DO_FIELD { stringify!($fname), }}
555
                ${define DO_ROLE_FIELD {}}
556
                ${define DO_ROLE_LITERAL {}}
557
                $ARTI_PATH_COMPONENTS
558
                $ARTI_LEAF_COMPONENTS
559
            ];
560

            
561
            describe_via_components(
562
                &${tmeta(summary) as str},
563

            
564
                // role
565
                ${define DO_FIELD {}}
566
                ${define DO_ROLE_FIELD { &spec.$fname, }}
567
                ${define DO_ROLE_LITERAL { &$LIT, }}
568
                $ARTI_LEAF_COMPONENTS
569

            
570
                &NON_ROLE_FIELD_KEYS,
571

            
572
                &[
573
                    ${define DO_FIELD { &spec.$fname, }}
574
                    ${define DO_ROLE_FIELD {}}
575
                    ${define DO_ROLE_LITERAL {}}
576
                    $ARTI_PATH_COMPONENTS
577
                    $ARTI_LEAF_COMPONENTS
578
                ],
579
            )
580
        }
581
    }
582

            
583
    impl<$tgens> TryFrom<&$crate::KeyPath> for $tname
584
    where $twheres
585
    {
586
        type Error = $crate::KeyPathError;
587

            
588
204
        fn try_from(path: &$crate::KeyPath) -> std::result::Result<$tname, Self::Error> {
589
            use $crate::key_specifier_derive::*;
590

            
591
            static FIELD_KEYS: &[&str] = &[
592
                ${define DO_LITERAL {}}
593
                ${define DO_FIELD { stringify!($fname), }}
594
                $ARTI_PATH_COMPONENTS
595
                $ARTI_LEAF_COMPONENTS
596
            ];
597

            
598
            #[allow(unused_mut)] // not needed if there are no fields
599
            #[allow(unused_variables)] // not needed if there are no fields
600
            let mut builder =
601
                <$<$tname Pattern>::<$tgens> as $crate::KeySpecifierPattern>::new_any();
602

            
603
            ${define DO_FIELD { &mut builder.$fname, }}
604
            ${define DO_LITERAL { &mut $LIT, }}
605

            
606
            parse_key_path(
607
                path,
608
                &FIELD_KEYS,
609
                &mut [ $ARTI_PATH_COMPONENTS ],
610
                &mut [ $ARTI_LEAF_COMPONENTS ],
611
            )?;
612

            
613
            #[allow(unused_variables)] // not needed if there are no fields
614
            let handle_none = || internal!("bad RawKeySpecifierComponentParser impl");
615

            
616
            Ok($tname { $(
617
                $fname: builder.$fname.ok_or_else(handle_none)?,
618
            ) })
619
        }
620
    }
621

            
622
    // Register the info extractor with `KeyMgr`.
623
    $crate::inventory::submit!(&$< $tname InfoExtractor > as &dyn $crate::KeyPathInfoExtractor);
624
}