11

I have a number of functions defined in my .bashrc, intented to be used interactively in a terminal. I generally preceded them with a comment describing its intended usage:

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

This is fine if browsing the source code, but it's nice to run type in the terminal to get a quick reminder of what the function does. However this (understandably) doesn't include comments:

$ type foo
foo is a function
foo ()
{
    ...
}

Which got me thinking "wouldn't it be nice if these sort of comments persisted so that type could display them?" And in the spirit of Python's docstrings I came up with this:

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

Now the usage is included right in the type output! Of course as you can see quoting becomes an issue which could be error-prone, but it's a nicer user experience when it works.

So my question is, is this a terrible idea? Are there better alternatives (like a man/info for functions) for providing users of Bash functions with additional context?

Ideally I'd still like the usage instructions to be located nearby the function definition so that people viewing the source code also get the benefit, but if there's a "proper" way to do this I'm open to alternatives.

Edit these are all fairly simple helper-style functions and I'm just looking to get a little extra context interactively. Certainly for more complex scripts that parse flags I'd add a --help option, but for these it would be somewhat burdensome to add help flags to everything. Perhaps that's just a cost I should accept, but this : hack seems to work reasonably well without making the source much harder to read our edit.

8

I don't think that there is just one good way to do this.

Many functions, scripts, and other executables provide a help message if the user provides -h or --help as an option:

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

For example:

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz
  • Yep, I should have mentioned that. These are simple functions and I'm trying to avoid making them overly complex. For commands that merit parsing flags I'd certainly add a --help option. – dimo414 Jul 10 '16 at 22:01
  • In programming, consistency is a virtue. Also, it depends on what you mean by "complex". – John1024 Jul 10 '16 at 22:08
  • And, your approach is clever and good (and your question already has my +1). – John1024 Jul 10 '16 at 22:20
  • 1
    Thanks; your implementation of --help is also non-invasive, which I think is my primary criteria in this case. I may end up using the : trick since it more directly fits my use-case, but I appreciate you pointing out that it's not hard to support --help and that most users will expect it. – dimo414 Jul 11 '16 at 4:33
  • 1
    +1. i was going to answer "use getopts" but this works well enough if there are no other options. if the function has other options, use getopts. – cas Jul 12 '16 at 6:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.