feat!: Add double-dash (--) support

Also, migrate from ariadne to miette. The core engine is completely
rewritten and much lighter, and tests that weren't run at all have
been removed from now. Some documentation was added.

Author: fasterthanlime

Cargo.lock

@@ -11,22 +11,23 @@ keywords = ["cli", "args", "parser", "facet"]
 categories = ["command-line-interface"]
 
 [dependencies]
-facet-reflect = { version = "0.28.3" }
-facet-core = { version = "0.28.3" }
+facet-reflect = { version = "0.29" }
+facet-core = { version = "0.29" }
 log = "0.4.28"
-owo-colors = "4.2.2"
-ariadne = { version = "0.5.1", optional = true }
+heck = "0.5.0"
+miette = { version = "7.6.0", default-features = false }
 
 [dev-dependencies]
 cargo-husky = { version = "1.5.0", default-features = false, features = [
     "user-hooks",
 ] }
 eyre = "0.6.12"
-facet = { version = "0.28.3" }
-facet-pretty = { version = "0.28.0" }
-facet-testhelpers = { version = "0.28" }
+facet = { version = "0.29" }
+facet-pretty = { version = "0.29" }
+facet-testhelpers = { version = "0.29" }
 insta = "1.43.2"
+miette = { version = "7.6.0", default-features = false, features = ["fancy"] }
 
 [features]
 default = ["rich-diagnostics"]
-rich-diagnostics = ["dep:ariadne"]
+rich-diagnostics = []

Cargo.toml

@@ -31,6 +31,21 @@ Ok(())
 # }
 ```
 
+## Behavior
+
+The behavior of facet-args is still in flux, but here are the broad strokes:
+
+  * We're always parsing to a struct (not an enum, vec etc.)
+  * The struct we're parsing to is always owned — no borrowing happening here, it
+    gets too complicated with `&'slice [&'text str]`
+  * Arguments are either `positional` or `named` — fields lacking either annotation are ignored
+  * Accepted syntaxes for short flags are: `short = 'v'` and `short = "v"` (where v can be any letter)
+  * `positional` args of type `Vec` (or anything that has a `Def::List`) will soak up all the positional
+    arguments — if followed by `positional` arguments of type `String` for example, those will never
+    get filled
+  * After parsing every available argument, uninitialized struct fields are filled with their default value
+    if they have `facet(default)` set: this includes `Vec`.
+
 ## Sponsors
 
 Thanks to all individual sponsors:

README.md

@@ -22,3 +22,18 @@ eprintln!("args: {}", args.pretty());
 Ok(())
 # }
 ```
+
+## Behavior
+
+The behavior of facet-args is still in flux, but here are the broad strokes:
+
+  * We're always parsing to a struct (not an enum, vec etc.)
+  * The struct we're parsing to is always owned — no borrowing happening here, it
+    gets too complicated with `&'slice [&'text str]`
+  * Arguments are either `positional` or `named` — fields lacking either annotation are ignored
+  * Accepted syntaxes for short flags are: `short = 'v'` and `short = "v"` (where v can be any letter)
+  * `positional` args of type `Vec` (or anything that has a `Def::List`) will soak up all the positional
+    arguments — if followed by `positional` arguments of type `String` for example, those will never
+    get filled
+  * After parsing every available argument, uninitialized struct fields are filled with their default value
+    if they have `facet(default)` set: this includes `Vec`.

README.md.in

@@ -1,18 +1,29 @@
-use crate::deserialize::{Subspan, SubspanMeta};
-use alloc::borrow::Cow;
-
 #[derive(Debug)]
 pub(crate) enum ArgType<'a> {
-    LongFlag(Cow<'a, str>),
+    // A `--` separator after which we only expect positional arguments
+    DoubleDash,
+
+    // `--{arg}`
+    LongFlag(&'a str),
+
+    // `-{a}`
     ShortFlag(&'a str),
+
+    // `{a}`
     Positional,
+
+    // End of the argument list
     None,
 }
 
 impl<'a> ArgType<'a> {
     pub(crate) fn parse(arg: &'a str) -> Self {
         if let Some(key) = arg.strip_prefix("--") {
-            ArgType::LongFlag(Self::kebab_to_snake(key))
+            if key.is_empty() {
+                ArgType::DoubleDash
+            } else {
+                ArgType::LongFlag(key)
+            }
         } else if let Some(key) = arg.strip_prefix('-') {
             ArgType::ShortFlag(key)
         } else if !arg.is_empty() {
@@ -21,67 +32,4 @@ impl<'a> ArgType<'a> {
             ArgType::None
         }
     }
-
-    pub(crate) fn kebab_to_snake(input: &str) -> Cow<'_, str> {
-        if !input.contains('-') {
-            return Cow::Borrowed(input);
-        }
-        Cow::Owned(input.replace('-', "_"))
-    }
-}
-
-// This trait implementation allows for using a Subspan together with an arg string
-impl<'a> From<(&'a Subspan, &'a str)> for ArgType<'a> {
-    /// Converts a subspan and argument string into the appropriate ArgType.
-    ///
-    /// - For KeyValue metadata: key part (offset 0) is parsed normally (ShortFlag or LongFlag),
-    ///   value part (offset > 0) is treated as Positional
-    /// - For Delimiter metadata: treated as Positional
-    /// - For no metadata: parsed normally
-    fn from((subspan, arg): (&'a Subspan, &'a str)) -> Self {
-        if subspan.offset >= arg.len() {
-            return ArgType::None;
-        }
-
-        let end = core::cmp::min(subspan.offset + subspan.len, arg.len());
-        let part = &arg[subspan.offset..end];
-
-        // Check metadata for special handling
-        if let Some(meta) = &subspan.meta {
-            match meta {
-                SubspanMeta::KeyValue => {
-                    // For KeyValue, if it's the value part (offset > 0),
-                    // treat it as a positional argument regardless of content
-                    if subspan.offset > 0 {
-                        return if !part.is_empty() {
-                            ArgType::Positional
-                        } else {
-                            ArgType::None
-                        };
-                    }
-                    // Otherwise parse key part normally with parse()
-                }
-                SubspanMeta::Delimiter(_) => {
-                    // For delimited values, treat as positional
-                    return if !part.is_empty() {
-                        ArgType::Positional
-                    } else {
-                        ArgType::None
-                    };
-                }
-            }
-        }
-
-        // Default parsing for keys and non-special cases
-        ArgType::parse(part)
-    }
-}
-
-/// Extracts a substring from arg based on a subspan
-pub(crate) fn extract_subspan<'a>(subspan: &Subspan, arg: &'a str) -> &'a str {
-    if subspan.offset >= arg.len() {
-        return "";
-    }
-    let end = core::cmp::min(subspan.offset + subspan.len, arg.len());
-    &arg[subspan.offset..end]
 }