TODO

[matklad]

Opening this grab bag issue in case anyone wants to cotribute:

• [ ] API docs and a guide (link to fuchsia guidelines)
• [ ] -- support for --flag -- -dashed-value and -- the --rest -o -f arguments
• [ ] Validation of positional arguments: requred optional repeated?
• [ ] Treat subcommand name as a positional argument with respect to validation
• [x] impl From<Strign> for xflags::Error
• [x] in-place update of generated code, a-la expect
• [ ] pluralize repated args

Unclear if we need these:

• [ ] Support for enums: optional --malloc malloc: mimalloc | jemalloc | sys
• [ ] Verbosity(pub u32) type, automatic -v / -q handing
• [ ] ANSI escapes in help a-la bat
• [ ] arg groups to share identical args between subcommands.
• [ ] text-wrapping (shouldn't bring a ton of unicode deps) (just use the wrapping from the source code?)

Don't do these by design

• arg grouping: -xzf
• equals --foo=bar (use --foo -- bar for escaping if needed)

(although I wouldn't be against adding those two behind disabled-by-default feature)

[Geobert]

Is there a way to add a default value to optional flags?

If not, maybe it's something to consider?

[matklad]

I'd just do something like this:

xflags! {
  cmd Foo {
    optional --jobs n: u32
  }
}

impl Foo {
  fn jobs() -> u32 { self.jobs.unwrap_or_else(num_cpus()) }
}

I think that's good enough for complex use-cases.

For simple use-cases, I think we might support

xflags! {
  cmd Foo {
    optional --jobs n: u32 = "4"
  }
}

syntax, if the implementation is easy (I think it should be)

EDIT: to clarify, in the simple use-case, default is a string which is used as a value of the argument. For cases where you want to specify default as a rust experssion, you'd have to write accessor function manually. Yeah, now that I spelled this out, I think we should support desugaring-based defaults.

[thomcc]

Can you elaborate on why --foo=bar is unsupported by design?

It always seemed preferable to me, since it is strictly less ambiguous way of specifying flags, at least in many use cases.

In particular, I've grown somewhat accustomed to always using it, as in my previous (admittedly far hackier and home-grown) arg parsing code, it was required. This was mostly so that I could always skip over an entire --foo=bar argument when I didn't know the whole "argument schema" up front, the way xflags does.

It's not a huge deal, but it feels like it wouldn't be that complex to support either, but perhaps I'm missing some issue or ambiguity.

[matklad]

The primary reason is that what Fuchsia guidelines say:

https://fuchsia.dev/fuchsia-src/concepts/api/cli#keyed_options

xflags are unrelated to fuchsia, but I like to follow they guideline because:

• they are a useful clear and unambiguous spec, rather than a bunch of poorly documented GNU extensions
• for xflags domain, simplicity of implementation generally matters more than user experience

Secondary reasons: I would love to have only one way to do it. Between --foo bar and --foo=bar the former is what I am personally used to, as the one that's easier to type. Although the absense of ambiguity at the call site is definitely an argument in favor of =.

The other problem with = is that it fundamentally changes the implementation -- to support =, one needs to interpret and split a specific argument. The current implementation always consumes an element of args array completely, there isn't within argument lexing.

As I've said, I am not opposed to having this behind a feature flag (it should probably be called gnu and gate all extensions, and not k=v in particular. So, also -xzf style of options)

[vi]

Note that missing -- support prevents using xflags from forwarding entire command line to next process e.g. for building tools like chroot(1). Shall it be prioritised?

[matklad]

Yeah, see https://github.com/matklad/xflags/pull/32