Add option to disable auto generated help for commands

[tzah4748]

Description

The idea is simple, add a new option to commands to not generate the --help | -h
Similar to what argparse has: https://docs.python.org/3/library/argparse.html#add-help

[DannyBen]

Why?

[tzah4748]

There are several use cases for such a thing, the one I'm facing right now is "embedding a parser inside another parser" or more simply put, running a bunch of CLI tools wrapped within the bashly CLI commands.

[DannyBen]

Bashly is not designed to be just a parser, but I am willing to consider it if you can provide a meaningful use case, with sample code / YAML config that demonstrates why having the --help is bad.

[tzah4748]

Consider the following use case where I want to provide a standalone bash file generated with bashly generate, this is the YAML file:

name: bundler
help: Bundles various tools under a single entry point
version: 1.0.0

commands:
- name: compile
  help: Runs the compiler
  catch_all: true

The implementation of compile_command.sh is irrelevant, it is only important to know that I want the --help or -h argument to be forwarded into the underlaying "compiler" tool.
Attempting to do: bundler compile --help will result in:

bundler compile - Runs the compiler

Usage:
  bundler compile [--] [...]
  bundler compile --help | -h

Options:
  --help, -h
    Show this help

It is possible to slightly workaround this by adding the help as an argument to the command in the YAML like so:

args:
  - name: help
    required: false
    help: Show help for the compile command

But this is not what I want to do as it can confuse someone who is also familiar with how the underlaying "compiler" tool is working.

[DannyBen]

Thank you.
In this case, if we allow disabling of "--help" then running bundler compile --help will result in Invalid argument --help. It will not forward it anywhere. Parsing of command line arguments and forwarding them are (usually) mutually exclusive.

In your example, you will have to run bundler compile -- --help - which is undesired I assume.

What am I missing?

[DannyBen]

It just occurred to me that perhaps the Command.extensible feature is more suitable for what you need.

This allows you to delegate commands to any other script, in the same way that git works, and to an extent - like docker CLI works.

# src/bashly.yml
name: bundler
help: Sample extensible application
version: 0.1.0
extensible: true  # <= this

commands:
  - ... the commands you DO handle ...

This config will allow the user to run bundler anything and if there is an executable in the path named bundler-anything, it will be executed and receive the remainder of the ARGV.

👉 see Extensible Scripts - with two modes, and referenced examples.

This keeps the bashly script clean and modular, without contaminating (embedding) it with other scripts, and without CATCH_ALL gymnastics.

[tzah4748]

Thank you. In this case, if we allow disabling of "--help" then running bundler compile --help will result in Invalid argument --help. It will not forward it anywhere. Parsing of command line arguments and forwarding them are (usually) mutually exclusive.

In your example, you will have to run bundler compile -- --help - which is undesired I assume.

What am I missing?

From what I tested with the given YAML, I was able to do the following:
./bundler compile --arguments item1,item2 --another-arg=10 and get all the arguments as is:

other_args:
- ${other_args[*]} = --arguments item1,item2 --another-arg 10
- ${other_args[0]} = --arguments
- ${other_args[1]} = item1,item2
- ${other_args[2]} = --another-arg
- ${other_args[3]} = 10

I would like to pass ${other_args[*]} into the internal tool I wish to execute.

It just occurred to me that perhaps the Command.extensible feature is more suitable for what you need.

This allows you to delegate commands to any other script, in the same way that git works, and to an extent - like docker CLI works.

src/bashly.yml

name: bundler
help: Sample extensible application
version: 0.1.0
extensible: true # <= this

commands:

• ... the commands you DO handle ...
  This config will allow the user to run bundler anything and if there is an executable in the path named bundler-anything, it will be executed and receive the remainder of the ARGV.

👉 see Extensible Scripts - with two modes, and referenced examples.

This keeps the bashly script clean and modular, without contaminating (embedding) it with other scripts, and without CATCH_ALL gymnastics.

As for this, it will not fit my use case because the underlaying tools are all running within a docker container.
The compile_command.sh involves in running a container image which contains the "compiler" tool.

[DannyBen]

I see.

So the need is just to disable the --help | -h flags, and let them fall as they may, and in your case, due to catch_all, delegated to the handler.

1. Will a helpless: true option for a command make sense?
2. If we disable this - I plan on keeping the function that prints the help, in case someone wants to call it manually, yes?

[DannyBen]

Ok - I have a better idea.

I am under the assumption that people may only want to disable --help in conjunction with catch_all.
If this is indeed the case, then I can simply amend the catch_all hash syntax to have another option:

catch_all:
    label: Files
    help: Files to upload
    required: true         # optional
    catch_help_flag: true  # this means "also catch --help / -h"

And still we have the question of should we keep the function that prints this help, in case someone wants to use it, or remove it altogether. I am leaning towards keeping it.

Thoughts?

[tzah4748]

1. I personally think that if --help is automatically generated it surely must come with the default help message printed by the function that prints the command help. But also vise versa, if you don't want --help to be automatically generated for you, you will probably won't use the auto generated print_command_help function.
   That being said... it doesn't hurt having it, removing it is not a must.
2. Also just my opinion here, I think its having the command define a helpless: true or add_help: false is more explicit and is easier to understand than having to dive into what catch_all can offer.
   Also, someone may want to remove the --help but not to catch_all. Unless I've missed something, having this functionality only within the catch_all is restricting, no?
3. If you do decide to go with catch_all, the catch_help_flag is a specific flag solution, assuming there won't be any default flags like the --help in the future, this can fit nicely.

[DannyBen]

All valid points. My thoughts:

1. If I remove the internal usage printing function (e.g. bundler_compile_usage in your case), and someone WILL want to show it by other means, like bundler compile --internal-help) - it will be impossible. While keeping it, may include "dead code" in the generated script, it is probably less worse than needing it and not having it.
2. Yes, I agree that command.helpless is simpler, it is also simpler to implement. However, from user standpoint, I think this is a very, VERY niche case, and by providing this option, it may confuse users as to why at all it is needed? Since I think it will only ever be needed in conjunction with catsh_all - perhaps it belongs there... I am not totally convinced by my own arguments yet - I may implement both and we can choose.
3. There will never by any other so called "fixed flags" - there is only --version | -v on the root command, and --help | -h on all commands - similar to any other CLI framework I ever used.

I am almost done with one (the catch_all.catch_help) implementation - I will push a PR, if you can test it - it will be nice.

[tzah4748]

I'll test any change you push ASAP, much appreciated!