knuffel (Rust KDL parser) cheat sheet

knuffel.md

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	SocketAddr, PathBuf
			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

• knuffel https://docs.rs/knuffel/latest/knuffel/
• kdl https://kdl.dev/
• kdl-rs https://github.com/kdl-org/kdl-rs
• quick-xml https://docs.rs/quick-xml/latest/quick_xml/

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.

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

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.

(answer)right
wrong
(direction)right
left