86

Assume that I have a script that can be run in either of the following ways.

./foo arg1 arg2
./foo

Is there a generally accepted way to denote that arg1 and arg2 aren't mandatory arguments when printing the correct usage of the command?

I've sometimes noticed usage printed with the arguments wrapped in brackets like in the following usage printout.

Usage: ./foo [arg1] [arg2]

Do these brackets mean that the argument is optional or is there another generally accepted way to denote that an argument is optional?

Anthony Jack
  • 5,333
  • 7
  • 28
  • 47

4 Answers4

141

I suppose this is as much a standard as anything.

The Open Group Base Specifications Issue 7

IEEE Std 1003.1, 2013 Edition

Copyright © 2001-2013 The IEEE and The Open Group

Ch. 12 - Utility Conventions

Although it doesn't seem to mention many things I have commonly seen over the years used to denote various meanings:

  • square brackets [optional option]
  • angle brackets <required argument>
  • curly braces {default values}
  • parenthesis (miscellaneous info)

Edit: I should add, that these are just conventions. The important thing is to pick a convention which is sensible, clearly state your convention, and stick to it consistently. Be flexible and create conventions which seem to be most frequently encountered on your target platform(s). They will be the easiest for users to adapt to.

Community
  • 1
  • 1
  • "The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility" - looks like it doesn't talk about the mandatoriness of the parameter, no? – sekmo May 04 '18 at 09:22
  • 2
    If you read just 1 sentence before, it clearly says as much. "Frequently, names of parameters that require substitution by actual values are shown with embedded characters." Names that require (i.e. mandatory) substitution by actual values. As I previously mentioned, these are commonly seen conventions. There really is no hard standard. I have seen these conventions in use for 25+ years, several years before The Open Group Base Specifications existed. Those "specifications" merely attempt to formally describe such conventions, though they are written fairly poorly. –  Sep 05 '18 at 16:48
55

I personally have not seen a 'standard' that denotes that a switch is optional (like how there's a standard that defines how certain languages are written for example), as it really is personal choice, but according to IBM's docs and the Wiki, along with numerous shell scripts I've personally seen (and command line options from various programs), and the IEEE, the 'defacto' is to treat square bracketed ([]) parameters as optional parameters. Example from Linux:

ping (output trimmed...)

usage: ping [-c count] [-t ttl] host

where [-c count] and [-t ttl] are optional parameters but host is not (as defined in the help).

I personally follow the defacto as well by using [] to mean they are optional parameters and make sure to note that in the usage of that script/program.

I should note that a computer standard should define how something happens and its failure paths (either true fail or undefined behavior). Something along the lines of the command line interpreter _shall_ treat arguments as optional when enclosed in square brackets, and _shall_ treat X as Y when Z, etc.. Much like the ISO C standard says how a function shall be formed for it to be valid (otherwise it fails). Given that there are no command line interpreters, from ASH to ZSH and everything in between, that fail a script for treating [] as anything but optional, one could say there is not a true standard.

txtechhelp
  • 6,625
  • 1
  • 30
  • 39
19

Yes, the square brackets indicate optional arguments in Unix man pages.

From "man man":

[-abc] any or all arguments within [ ] are optional.

mpez0
  • 2,815
  • 17
  • 12
1

I've never wondered if they're formally specified somewhere, I've always just assumed they come from conventions used in abstract algebra, in particular, in BNF grammars.

zakmck
  • 2,715
  • 1
  • 37
  • 53