Ability to customize help display behaviour of script name & description via `bashly-strings.yml`

[adamscybot]

Description

When executing the --help flag directly on the root script, bashly prints a <root-name>[ - <root-help>] string that identifies the script's global name/purpose on the first line of the output. Generally, that makes sense, but I'd like to suppress or customise it in my use case.

I have a hip, colourful ASCII art preamble that I am currently outputting on all script executions via initialize.sh, which I don't care to report how long I spent crafting whilst procrastinating over my core task 😄.

This presents a couple of minor problems:

1. There is a level of duplication when executing <script> --help in that the <root-name>[ - <root-help>] preamble string is extraneous in my case since that info (and more) is in my custom header.
2. Whilst I am impressed by my own glorious terminal artwork, I have a feeling I will, in the end, only want it to be displayed on <script> --help and not on every execution in order to recognise the reality of the unappreciative user's sanity :P.

Both problems could probably be solved if this string was customisable in bashly-strings.yml. If I only cared about (1) and was happy to keep my preamble on all commands, I could then just null out the hypothetical string template for this in that configuration. If I wanted (2), then I could interpolate some bash into that same string template instead to have my own custom preamble defined there such that it only shows on <script> --help .

Worth noting for anyone googling that it doesn't make sense to change/null this out in the bashly.yaml root name field since that is used for various other operational things and so it's scope is beyond just "display".

An aside: I used this lib some years ago for a whole trough of internal tooling, and it's awesome to see some little challenges I encountered back then have been addressed as I revisit sometime later in an open-source context. Your dedication to this (incredibly time-saving) project that I've noticed whilst lurking on various GitHub threads is admirable! May I suggest a "built with bashly" community-contributed discussion thread/docs page or something?

[DannyBen]

Well, isn't this a good looking issue... thanks for taking the time to write it so vividly :).

Let's triage:

Customizable usage header

Having control over the usage header makes total sense.
However, it has several display modes which makes the update less straight forward than other strings:
https://github.com/DannyBen/bashly/blob/966651b3e0c35bd8d14fb9ec8e771d672be82344/lib/bashly/views/command/usage.gtx#L4-L13
which gets the base string from:
https://github.com/DannyBen/bashly/blob/966651b3e0c35bd8d14fb9ec8e771d672be82344/lib/bashly/script/command.rb#L51-L53

Nevertheless, I will take a closer look to see how we can achieve this without braking anything.

"Built with bashly" page

1. There is currently a list of Real World Examples in the examples page which I edit on demand.
2. Since we recently opened the wiki for public editing, I was considering moving this section of the page to the wiki, so people can edit them without asking me to do it.
3. I held of on moving it there, since the wiki is in "pilot run" - but it may be time to do so.
4. EDIT: Created the Made with Bashly wiki page - I will soon link to it from the examples page (instead of listing the examples there).

[DannyBen]

After further experimentation, here are my conclusions:

1. Using the custom strings facility is not the right place for it, for multiple reasons. The primary ones being:
   • It would be more complicated to implement, considering the different display modes and indentation.
   • It will apply to all commands, and not only the root command.
2. The next best thing I could think of is this:
   • Add another option for command type: header_override.
   • This header will be injected as is (i.e. not wrapped by print or echo) for the long usage display case (--help).
   • This means that it can either be bash code of your choosing, or a call to a function.

Example:

# Inline code
header_override: |
  echo " __  __        _____           _       _"
  echo "|  \/  |      / ____|         (_)     | |"
  echo "| \  / | __ _| (___   ___ _ __ _ _ __ | |_"
  echo "| |\/| |/ _' |\___ \ / __| '__| | '_ \| __|"
  echo "| |  | | (_| |____) | (__| |  | | |_) | |_"
  echo "|_|  |_|\__,_|_____/ \___|_|  |_| .__/ \__|"
  echo "                                | |"
  echo "                                |_|"

# Bring Your Own Function
header_override: print_ascii_art

which is then written as:

# :command.usage
cli_usage() {
  if [[ -n $long_usage ]]; then
    echo " __  __        _____           _       _"
    echo "|  \/  |      / ____|         (_)     | |"
    echo "| \  / | __ _| (___   ___ _ __ _ _ __ | |_"
    echo "| |\/| |/ _' |\___ \ / __| '__| | '_ \| __|"
    echo "| |  | | (_| |____) | (__| |  | | |_) | |_"
    echo "|_|  |_|\__,_|_____/ \___|_|  |_| .__/ \__|"
    echo "                                | |"
    echo "                                |_|"

  else
    printf "cli - Summary line\n\n"
  fi
  # ...

Thoughts?

[DannyBen]

@adamscybot - I am waiting mainly for your input before merging (and updating documentation + schema + examples).

[adamscybot]

Hi, sorry for the delay.

Yes, this would absolutely work for me, thank you. The only suggestion I have to add is that it may be nice to have the name/description from the yaml available in the arguments to the bash function. As you could potentially call something generic that converts said name into the "art" as opposed to having it static; and therefore have the yaml strings as the canonical source of truth. I don't do this -- but it could be in keeping with the scope of the feature.

Other than that, I can see some potential naming confusion over this and the existing header.sh related stuff -- but at the same time, I don't have a better naming suggestion either 😛

[DannyBen]

it may be nice to have the name/description from the yaml available in the arguments to the bash function.

The value of this option is bash code. It may or may not be a name of a function. If it is a function, it is a function of your own choosing, so you can easily create a function that accepts a name or description as an argument:

header_override: generate_ascii_art MyScriptName

I can see some potential naming confusion

Yes, I also had the same thought. Perhaps rename it to help_header_override or usage_header_override ?

[meleu]

Perhaps rename it to help_header_override or usage_header_override ?

My two cents:

• help_header_override: I read this as something that is shown when explicitly using --help
• usage_header_override: I read this as something to be shown in a short usage message when, for example, the user runs the command with invalid arguments.

Given the usecase described in the OP, I think help_header_override makes more sense.

[DannyBen]

Version 1.2.10 is live with this option.
Thanks for the ticket.