A Bash script's ability to handle command-line options such as -h gives some powerful capabilities to direct the program and modify what it does. In the case of the -h option, you want the program to print the Help text to the terminal session and then quit without running the rest of the program.
What is the Windows Command Prompt? Windows Command Prompt (also known as the command line, cmd.exe or simply cmd) is a command shell based on the MS-DOS operating system from the 1980s that enables a user to interact directly with the operating system.
Typically, your help output should include:
[options]
to indicate where the options goarg_name
for a required, singular arg[arg_name]
for an optional, singular argarg_name...
for a required arg of which there can be many (this is rare)[arg_name...]
for an arg for which any number can be suppliedarg_name
should be a descriptive, short name, in lower, snake case-l
) or a long form (e.g. --list
), include them together on the same line, as their descriptions will be the sameGREP_OPTS
Note further that it's good form to accept both -h
and --help
to trigger this message and that you should show this message if the user messes up the command-line syntax, e.g. omits a required argument.
Take a look at docopt. It is a formal standard for documenting (and automatically parsing) command line arguments.
For example...
Usage:
my_program command --option <argument>
my_program [<optional-argument>]
my_program --another-option=<with-argument>
my_program (--either-that-option | <or-this-argument>)
my_program <repeating-argument> <repeating-argument>...
I think there is no standard syntax for command line usage, but most use this convention:
Microsoft Command-Line Syntax, IBM has similar Command-Line Syntax
Text without brackets or braces
Items you must type as shown
<Text inside angle brackets>
Placeholder for which you must supply a value
[Text inside square brackets]
Optional items
{Text inside braces}
Set of required items; choose one
{a|b}
Separator for mutually exclusive items; choose one
<file> …
Items that can be repeated
We are running Linux, a mostly POSIX-compliant OS. POSIX standards it should be: Utility Argument Syntax.
-o
. -o argument
or
-oargument
. -lst
is equivalent to -t -l -s
.-lst
is equivalent to -tls
.-lst
nonoption.--
argument terminates options.-
option is typically used to represent one of the standard input
streams.The GNU Coding Standard is a good reference for things like this. This section deals with the output of --help
. In this case it is not very specific. You probably can't go wrong with printing a table showing the short and long options and a succinct description. Try to get the spacing between all arguments right for readability. You probably want to provide a man
page (and possibly an info
manual) for your tool to provide a more elaborate explanation.
Microsoft has their own Command Line Standard specification:
This document is focused at developers of command line utilities. Collectively, our goal is to present a consistent, composable command line user experience. Achieving that allows a user to learn a core set of concepts (syntax, naming, behaviors, etc) and then be able to translate that knowledge into working with a large set of commands. Those commands should be able to output standardized streams of data in a standardized format to allow easy composition without the burden of parsing streams of output text. This document is written to be independent of any specific implementation of a shell, set of utilities or command creation technologies; however, Appendix J - Using Windows Powershell to implement the Microsoft Command Line Standard shows how using Windows PowerShell will provide implementation of many of these guidelines for free.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With