Explore positional arg suport

[lread]

Babashka CLI supports rolling args into options.
This is convenient, but it comes with some interesting CLI usability issues.

Coercing/Validating

(require '[babashka.cli :as cli])

(cli/parse-args ["myarg" "--myopt" "myval"] {:args->opts [:my-arg]
                                             :spec {:my-arg {:coerce :long}}})

But the error message this presents to the end-user is confusing:

Invalid value for option --my-arg: cannot transform input "myarg" to long

The CLI doesn't have a --my-arg option.
I might expect maybe an error like:

Invalid value for arg <myarg>: cannot transform to long 

Perhaps <myarg> would come from :ref.

Requiring

And it is nice that we can require a positional arg, but again, the error message is misleading:

(cli/parse-args ["--myopt" "myval"] {:args->opts [:my-arg]
                                     :spec {:my-arg {:require true}}})
;; => Execution error (ExceptionInfo) at babashka.cli/->error-fn$fn (cli.cljc:294).
;;    Required option: --my-arg

We could maybe instead use :ref again?: Required arg <myarg>

Allows for positional args to be specified as options

And... also, rolling in args->opts technique does allow for positional args to be specified as options.
This could be seen as a bug or a feature.

(cli/parse-args ["--myopt" "myval" "--my-arg" "boop"] {:args->opts [:my-arg]
                                                       :spec {:my-arg {:require true}}})
;; => {:opts {:myopt "myval", :my-arg "boop"}}

I like to create strict CLI interfaces, so this one is not great for me.
Perhaps we could add something to the spec to say this should be an arg only.

Failing on extra positional args?

And... I'm not sure if there is a way to error on extra args (without custom code):

(cli/parse-args ["--myopt" "myval" "arg" "extra-arg"] {:restrict true
                                                       :args->opts [:my-arg]
                                                       :spec {:myopt {}
                                                              :my-arg {:require true}}})
;; => {:args ["extra-arg"], :opts {:myopt "myval", :my-arg "arg"}}

Thoughts

Babashka CLI focuses on options.

The dispatch fn does support positional arg validation as commands.

If you are interested some or all of the above, I can help to flesh out more and create issues as appropriate.

[borkdude]

So this is more about error messages than anything else, correct?

[lread]

Mostly, yes.

A developer learns that they can use :args->opts to tap into the features available for options for positional args.

But positional args aren't really options, and bb cli doesn't make that distinction yet.
This shows itself in the error messages above.
(And allowing positional args expressed via :args->opts to be passed in as an options.)

But... dispatch does understand and treat leading positional args as commands, and it has validation for commands.

[borkdude]

But positional args aren't really options, and bb cli doesn't make that distinction yet.

Hmm, I don't see the difference either so that may be on me. I see them as command line values you pass to a Clojure function. How you pass those values doesn't really matter to me, in the same way that Clojure can have positional args or :keys args.

For dispatch this is different because subcommands can interfere with leading subcommands.

[borkdude]

But having said that, micro-issues/PRs welcome if you have any ideas.

[lread]

Thanks, I'm looking from the CLI user's perspective. Although internally the bb CLI lib can treat positional args as options, a CLI user won't see them as such. And I think that the usage help would not describe them as such.

And, I feel, error messages should not describe them as such. To me, that's an implementation detail leak.

Thanks for being open to ideas. I'll do some pondering.