What is the standard usage argument style?

Question

I'm making some command-line tools for some research I'm doing. I'd like these tools to follow commonly used conventions regarding command line programs in Unix.

Should I use flags or just list parameters?

program one two three
program -a one -b two -c three

• Where in the list of commands does the input file normally go, or is it better to < it into the program?
• What about the output filename?
• Should I specify the file extension for the output format, or have my program automatically put the correct extension on?
• When the user enters an invalid command, is there a prototypical "correct usage" message?
• Is "--help" or "-h" required?

Also, is there some sort of header file I can include that would help with managing these?

Answer 1

If you're looking for a "standard", then you could do worse than look at GNU's Standards for Command Line Interfaces. Other standards are available.

As far as coding for this goes, take a look at boost::program_options. Not only will this save you rolling a lot of your own code, but it does a good job of formatting the options for presenting to the user (the prototypical "correct usage" message, you asked for).

In answer to your specific questions:

• Where in the list of commands does the input file normally go, or is it better to < it into the program?

I would expect these to come at the end of a command line. Like in GNU grep. If you are only processing one file and would like to make stdin available as an input source, that would not surprise most users.

If your command processes lots of files, then it would be unusual to have to specify a switch before the filenames. Think cat.

• What about the output filename?

A -o or --output option is fairly common. If your file takes exactly one input and one output, then program inputfile outputfile would not surprise many users. If no output file is specified, perhaps you'll output to stdout; that would not be unusual behaviour and would allow your users to pipe the output through other commands (such as grep, less, etc...), They could also redirect stdout to a file using >.

• Should I specify the file extension for the output format, or have my program automatically put the correct extension on?

This is probably a matter for debate. If I specified an output filename, I would expect to find that file created (or replaced, after a prompt) without the program changing the name.

• When the user enters an invalid command, is there a prototypical "correct usage" message?

Using GNU grep as an example again:

grep: unrecognized option '--incorrect'
Usage: grep [OPTION]... PATTERN [FILE]...
Try 'grep --help' for more information.

This wouldn't surprise too many users and points them in the right direction if they've made a typo without swamping them with information.

• Is "--help" or "-h" required?

That depends on your customer! I find it frustrating when this option isn't available.

Answer 2

Usually speaking, flags are there for providing options and parameter are for passing information. If you have input,output file as command line argument, use flags like -i -o, so sequence will not matter. -h is required if you want to (and need to) give documentation.