Showing an additional usage line for forced commands

[codevogel]

Say I have a bashly script foo that I run with ./foo

In my bashly.yml I have

commands:
  - name: do
    help: do something with my_arg
    default: force
    args:
      - name: my_arg
        help: my argument to be handled
        required: true

if I then run ./foo I get

❯ ./foo
missing required argument: MY_ARG
usage: foo do MY_ARG

This could be somewhat confusing to a new user, as they have just done foo, not foo do.
Also, ./foo MY_ARG would also be sufficient usage.

So, it would be nice if it instead printed

❯ ./foo
missing required argument: MY_ARG
usage: foo do MY_ARG
       foo MY_ARG

I don't see how I could achieve this with one of the custom_strings, as this would be behavior that is specific to the forced command only.

I tried looking at adding a src/after.sh to evaluate the last line of the output and seeing if it starts with usage: foo do to echo usage: foo MY_ARG, but after.sh does not run if the script already exists due to catching a usage error. It also seems like bad practice to do this with a before.sh

What would be the best way to enable this?

(An alternative way to render this would be something like)

❯ ./foo
missing required argument: MY_ARG
usage: foo MY_ARG
       foo do MY_ARG

or

❯ ./foo
missing required argument: MY_ARG
usage: foo do MY_ARG
 ( or: foo MY_ARG )

[DannyBen]

Good point.

I also see another problem, running ./foo do --help does not mention that this is the default command.

Right now I am thinking that the usage pattern displayed in the error message (and possibly in other places) is:

$ ./cli
missing required argument: MY_ARG
usage: cli [do] MY_ARG

I will look into changing it.

[DannyBen]

I have created #527 to track it. You may want to subscribe to the issue, I hope to have something soon.

[codevogel]

Cool!
Feel free to let me know if there is anything I can do to help.

[codevogel]

It could be an adjacent feature to add an option that, along with the incorrect usage message, prints the examples for the relevant command after the incorrectly using it.

That would allow you to show that they're tied together. That probably isn't enough to cover all scenarios (like for when you don't want to print the examples), but it would be pretty neat.

    examples:
      - foo [do] MY_ARG        

[DannyBen]

It could be an adjacent feature to add an option that, along with the incorrect usage message, prints the examples for the relevant command after the incorrectly using it.

Do you mean that there will be a setting option to show_examples_on_error: true, and when set, will print anything under the examples section of the command whenever the user failed to provide a valid command?

[codevogel]

Yeah so when you enable such an option somewhere in bashly-settings.yml

And borrowing from my example above,

commands:
  - name: do
    help: do something with my_arg
    default: force
    args:
      - name: my_arg
        help: my argument to be handled
        required: true
    examples:
      - foo my_arg
      - foo do my_arg

It would do this (currently, so not taking into account for potential changes in output from #527 )

❯ ./foo
missing required argument: MY_ARG
usage: foo do my_arg
Examples:
  foo my_arg
  foo do my_arg

(Arguably the default string for Examples could be examples to match casing here, but that conflicts with the casing from the already existing examples string for the --help menu)

[DannyBen]

I have implemented both features in #529 and #530

Default commands will now show differently on error

# Before
$ ./cli src
missing required argument: TARGET
usage: cli download SOURCE TARGET

# After
$ ./cli src
missing required argument: TARGET
usage: cli [download] SOURCE TARGET

Examples may be optionally shown on error:

$ ./cli
missing required argument: SOURCE
usage: cli [download] SOURCE TARGET [OPTIONS]
examples:
  cli download example.com
  cli download example.com ./output -f

New settings:

# settings.yml
show_examples_on_error: true

# strings.yml
examples_caption_on_error: 'examples:'

[DannyBen]

@codevogel can you test the edge / master version before I release?

[codevogel]

I'll do that! Give me an hour or two.