Skip to content

Instantly share code, notes, and snippets.

@rinarakaki
Last active February 13, 2023 17:45
Show Gist options
  • Save rinarakaki/a1817030872c1a1e0ce3afe784c929d4 to your computer and use it in GitHub Desktop.
Save rinarakaki/a1817030872c1a1e0ce3afe784c929d4 to your computer and use it in GitHub Desktop.
knuffel (Rust KDL parser) cheat sheet

TODO

  • New type pattern
  • Box, Arc, Rc, Vec, Option
    • FromIterator cannot be implemented for Option<T> so #[knuffel(child, unwrap(_))] approach can't be used
  • Semantic difference between structs with and without fields (unit/tuple structs)
    • Enum variants with single Decode element without attribute vs variants with single scalar element with attribute
    • Do we need arguments/properties/children? Is there a case where a type can be used for both patterns?
    • Lack of documentation about tuple structs
  • #[knuffel(child, unwrap(children(name)))] plugins: Vec<String> instead of Vec<Plugin> doesn't work?
  • Are there any possible uses of generics?

Cheat Sheet

definition attribute
(#[knuffel(_)])
field/variant
(T : DecodeScalar,
U : Decode)
examples
of X
input → output reference
field
mode
name decode
mode
unwrap doc impl
unit struct - X - - → Default::default()
struct - X - - → Default::default()
argument - - - T -
bool TODO
Option<T>
str X : FromStr SocketAddrPathBuf
bytes X : TryInto<Vec<u8>> Vec<u8>
arguments - - - X : FromIterator<T> Vec<T>
property - - - T -
Option<T>
name - T -
properties - - - X : FromIterator<(S, T)>
    where S : FromStr
HashMap<String, T>
child - - - bool - field/true/false Children.Boolean Child Fields
Option<U> -
U (struct) -
argument T
property T
child T
children - - - Vec<U> (enum) -
name - Vec<U> (struct)
enum - - - Single struct. Enum
argument
arguments
property
properties
child
children

References

@rinarakaki
Copy link
Author

rinarakaki commented Jan 26, 2023

DecodeScalar

Named vs Indexed

Any programmes are written sequentially and hence cannot avoid/can exploit their own ordered-ness.
Tuples/tuple structs can naturally be pattern-matched using their elements' appearing order.
On the contrary, the seeming counterpart for enums, the order of arms in pattern-matching is irrespective.

@rinarakaki
Copy link
Author

rinarakaki commented Jan 27, 2023

Story of knuffel

KDL's Features/Principles

What is the KDL's culmination as a format or language?

  • All nodes have a name
  • Nodes of the same type can appear at different times
    • By this, name value construct has different semantics from name=value one. The former is cumulative, enumerating. The latter is overriding, idempotent.
    • This is a very important –– even departing –– point as
      • if we let the former have nesting mode (value = { name value }), we get KDL, and
      • if we let the latter have nesting mode (value = { name=value }), we get TOML in place.
    • Entry/occurrence of nodes are not arbitrary but predicted by parent nodes.
  • Line breaks are delimiters, no colons

@rinarakaki
Copy link
Author

rinarakaki commented Feb 13, 2023

High-quality code, well command of proc-macros.

As you will see soon below, software redesign is done at once at different features and components.

The original library's low maintenance is not the cause of the set of such misconceptions but the result, demotivating the author.

@rinarakaki
Copy link
Author

(answer)right
wrong
(direction)right
left

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment