Help message for shell scripts

uuspider 2020-7-17 164

Help message for shell scripts
July 7, 2020
Have you ever thought how good it would be to have a help message for your shell script that you wrote a month ago and already forgot what it is supposed to do?

Yeah, there is always a way to show a message using cat (meow) or a bunch of echo calls.

But there is a neat trick.

Add your message with all the required information on top of your file, just right after the shebang.

#!/bin/bash
###
### my-script — does one thing well
###
### Usage:
###   my-script <input> <output>
###
### Options:
###   <input>   Input file to read.
###   <output>  Output file to write. Use '-' for stdout.
###   -h        Show this message.
Halfway done, now need to get this message in runtime with sed.

help() {
    sed -rn 's/^### ?//;T;p' "$0"
}
$0 means a filename of a file that is being executed.

A bit about the magic that is going here:

s — stands for substitute the following pattern;
/ — keyword to define start/end of the pattern;
^### ? — match a string starting with ### and an optional space after;
// — there could be something between the slashes, but since nothing is here, replace the pattern with an empty string;
T — Jumps to the end of sed-script if no s/// has done a successful substitution;
p — Prints the result of the substitution.
Now just call the help function if an arg -h or no args passed.

if [[ $# == 0 ]] || [[ "$1" == "-h" ]]; then
    help
    exit 1
fi
Hope it helps, cheers!

Full gist is available on GitHub: https://gist.github.com/kovetskiy/a4bb510595b3a6b17bfd1bd9ac8bb4a5
最新回复 (2)
  • uuspider 8月前
    引用 2
    @benhutchins commented on 8 Jul 2020 

    This doesn't actually work cross-platform, the -r option does not exist on macOS. You can do the same with awk though, just use:

    awk '/^###/' "$0"

    Complete script:

    #!/bin/bash
    ###
    ### my-script — does one thing well
    ###
    ### Usage:
    ###   my-script <input> <output>
    ###
    ### Options:
    ###   <input>   Input file to read.
    ###   <output>  Output file to write. Use '-' for stdout.
    ###   -h        Show this message.

    help() {
        awk '/^###/' "$0"
    }

    if [[ $# == 0 ]] || [[ "$1" == "-h" ]]; then
        help
        exit 1
    fi

    echo Hello World
  • uuspider 8月前
    引用 3
    @brucewoodward commented on 8 Jul 2020

    That's cool but I think I'll stick with here documents.

    #!/bin/bash

    Help=$(cat <<-"HELP"

     my-script — does one thing well

     Usage:
       my-script <input> <output>

     Options:
       <input>   Input file to read.
       <output>  Output file to write. Use '-' for stdout.
       -h        Show this message.

    HELP
    )

    help() {
        echo "$Help"
    }

    if [[ $# == 0 ]] || [[ "$1" == "-h" ]]; then
        help
        exit 1
    fi

    echo Hello World
返回
发新帖