Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Help Message for Shell Scripts

samizdat.dev

Post reply on HN
Print view View original

61–70 of 129 posts

Re: Help Message for Shell Scripts

#61

Post by gpanders »

ahnick wrote: post #43
sicromoft wrote: post #39

Earlier quoted context omitted.

Note that this doesn't work on macOS, where the builtin `man` command doesn't support the `-l` option.

Ah interesting, is there any workaround for Mac? Otherwise, I may just have to fallback to stripping the man page formatting and sending it to less.

The actual `man` command does this:

    /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | /usr/bin/less -is
So you could do it "manually" that way. Not the cleanest or prettiest solution but it's much lighter weight than using something like pandoc.

EDIT: Full example:

    { /usr/bin/tbl | /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -c | /usr/bin/less -is; }

Re: Help Message for Shell Scripts

#62

Post by sillysaurusx »

pavon wrote: post #59
adrianmonk wrote: post #5

You can also use a "here document" help() { cat Options: Input file to read. Output file to write. Use '-' for stdout. -h Show this message. EOH } If the indentation bugs you, you can use a simpler sed trick to remove leading space so that you can indent it as desired: help() { sed -e 's/ //' Options: Input file to read. Output file to write. Use '-' for stdout. -h Show this message. EOH }

Or just a multiline string: #!/bin/bash USAGE="my-script — does one thing well Usage: my-script Options: Input file to read. Output file to write. Use '-' for stdout. -h Show this message. " help() { echo "$USAGE" } This is my standard approach which is cleaner for putting the documentation at the very top of the file like the linked article.

Thank you! I had no idea that multiline strings were valid bash.

Re: Help Message for Shell Scripts

#63

Post by jeffrom »

Something I've wanted to do for a while is build a library to parse and generate use lines / documentation that adheres to the posix useline spec (can't find the link at the moment) while also being able to idempotently (de)serialize and be descriptive enough to define arguments and flags in a way a human could easily understand. iirc the spec seemed probably too vague to just work with all the currently existing man pages, but it would be nice to have a spec all programs can follow that machines can parse on my os.

Re: Help Message for Shell Scripts

#64

Post by j1elo »

I learnt the same trick some years ago, from an article called Shell Scripts Matter:

https://dev.to/thiht/shell-scripts-matter

So I took some of the advice and tips offered in there, and wrote a template file to be used as a baseline when writing scripts for any project that might need one:

https://github.com/j1elo/shell-snippets/blob/master/template...

Other resources that I link in the readme of that repo, because they were a great guide to write better and more robust scripts, are:

- Writing Robust Bash Shell Scripts: https://www.davidpashley.com/articles/writing-robust-shell-s...

- Common shell script mistakes: http://www.pixelbeat.org/programming/shell_script_mistakes.h...

- Bash Pitfalls: http://mywiki.wooledge.org/BashPitfalls

- The Bash Hackers Wiki: https://wiki.bash-hackers.org/

EDIT: -for anyone who would like to read some actual examples- I have to manage a bunch of scripts so actually a slightly more up to date version of the template is put into practice by means of a common bash.conf file that then gets sourced by all scripts: https://github.com/Kurento/adm-scripts/blob/master/bash.conf...

Re: Help Message for Shell Scripts

#65

Post by layoutIfNeeded »

jeffrom wrote: post #63

Something I've wanted to do for a while is build a library to parse and generate use lines / documentation that adheres to the posix useline spec (can't find the link at the moment) while also being able to idempotently (de)serialize and be descriptive enough to define arguments and flags in a way a human could easily understand. iirc the spec seemed probably too vague to just work with all the currently existing man…

http://docopt.org/ ?

Re: Help Message for Shell Scripts

#67

Post by mey »

blondin wrote: post #60
dastx wrote: post #54

Earlier quoted context omitted.

I suppose it depends on the use case. Personally I've always thought argparse is good enough, and have never hit a roadblock "because I'm using argparse" so to say. Having said that, I do like the pattern click is going for. If it argparse allowed the same pattern, in my opinion that would be cool, and it would probably be my first choice.

argparse should not be the first thing to reach for, imo, when good old sys.argv can do the job.

At that point I wouldn't leave bash. I feel like argparse allows for better documentation, error handling and input validation.

Re: Help Message for Shell Scripts

#68

Post by krick »

owenshen24 wrote: post #66

Unrelated: Is there any connection between the author and the other sam[]zdat who writes about society and other intriguing topics? https://samzdat.com/

I wouldn't know, but there is no reason for me to be thinking something like that. "Samizdat" is not really a name or something, it's a transliteration of "самиздат", which is a short/colloquial for "самостоятельное издательство", which literally means "self-publishing" (this was a thing during the USSR, where "self-publishing" was basically opposed to "real, official government-approved publishing"). I believe it's just a "clever" domain somebody was able to acquire, nothing more.

Re: Help Message for Shell Scripts

#69

Post by meddlepal »

gavinray wrote: post #41
40four wrote: post #14

Earlier quoted context omitted.

Thumbs up for 'Click'. I used it for a project once, and I was really happy with it. Easy to use, good docs. Would use it again.

Googling the library appears to be about ~8,000 lines of code (core.py is ~2,000 alone). Is that really reasonable sounding to most people for parsing CLI input/output and display manpages or helptext?

I'm not trying to be antagonistic here... but who cares how many lines it has unless you plan to maintain it?

Re: Help Message for Shell Scripts

#70

Post by mey »

Spivak wrote: post #20
mey wrote: post #7

Handling of arguments is one of the reasons I reach for Python or Powershell instead of a bash script when writing my own stuff. https://docs.python.org/3/library/argparse.html is great. Powershell has the Param keyword that functions like argparse in Python https://docs.microsoft.com/en-us/powershell/module/microsoft...

But handling args isn't that bad in bash. while [[ $# -gt 0 ]]; do case "$1" in -h|--help) do_help exit ;; -v|--version) do_version exit ;; -d|--debug) debug=true shift ;; -a|--arg) arg_value=$2 shift 2 ;; esac done

    import argparse
    parser = argparse.ArgumentParser()
    parser.add_argument('-v','--version',action='version', version='demo',help='Print version information')
    parser.add_argument('-d','--debug', help='Enable Debug Mode')
    parser.add_argument('a','arg', help="Argument Documentation")
    args = parser.parse_args()
Personally I feel like this is more readable code, gets me better validation, and help docs for "free". That's the attraction.
Post reply on HN