Skip to content

Instantly share code, notes, and snippets.

@pksunkara
Created December 16, 2011 12:27
Show Gist options
  • Save pksunkara/1485856 to your computer and use it in GitHub Desktop.
Save pksunkara/1485856 to your computer and use it in GitHub Desktop.
Command Line Arguments Specification

Command Line Arguments Specification

This specification defines Command Line Arguments level 1 (CLARG 1.0). This document aims to direct development of command line tools conform to a set of rules while parsing options.

Arguments

The different type of arguments are:

  • Short Option
  • Long Option
  • Non Option
  • Terminator

Short Option

  • All short options should start with - (prefix) followed by either lower case or upper case alphabet (name)
program -w
program -Q
  • All short options which require a single value can be followed by = and the value
program -u=name
  • All short options which require values can be followed by a space and the value and so on
program -u name
program -u name1 name2 name3
  • All short options which require a single value can be followed by the value immediately
program -uname
  • All short options which require no values can be aggregated in either direction and can be followed immediately by one of the short options
program -wQ
program -Qw
program -wQ -l name
program -wQl name

Long Option

  • All long options should start with -- (prefix) followed by lowercase alphanumeric string which can contain - and starting with an alphabet
program --write
program --std99
program --Util # Not allowed
program --ipPe # Not allowed
program --82sh # Not allowed
  • All long options which require a single value can be followed by = and the value
program --user=name
  • All long options which require values can be followed by a space and the value and so on
program --user name
program --user name1 name2 name3

Non Option

  • All non options should be used only after the ending of short and long options and maybe a terminator

  • All non options should start with an alphabet or number and followed by alphanumeric string which can contain a -

program create
program create-server
program Create
program 83
program -create # Not Allowed
program create_server # Not Allowed

Terminator

  • A terminator is represented by -- with a space on either sides

  • A terminator can be used in denoting the end of all long and short options and the start of non options

program -edevelopment server
program -w -- server # Explained below

Variables

Some options are used to set variables in the program. The different type of variables are:

  • Direct variable
  • Optional variable
  • Boolean variable
  • List variable

Direct Variable

  • All variables which require a value are called direct variables

  • All direct variables should be represented by long option. Short option representation is optional

program --env staging
program -e # This is optional
  • All direct variables representation should follow the above mentioned rules
program --env development
program -eproduction
  • All direct variables should be aggregated with other short options only if it is at the end
program -l -ax
program -l name -ax
program -axl name
program -alx # Not Allowed

Optional Variable

  • All variables which either takes a value or none are called optional variables

  • All optional variables will follow the rules of direct variable if a value is given

program --write=OUTPUT
program -wOUTPUT
  • All optional variables for which no value is given should be followed by either a long/short option or a terminator and non options
program -w -a create
program -w -- create
program -w create # Not Allowed
  • All optional variables should be aggregated with other short options only if it is at the end
program -w -ax
program -w OUTPUT -ax
program -axw OUTPUT
program -awx # Not Allowed

Boolean Variable

  • All variables which take a boolean value are called boolean variables

  • All boolean variables should be represented by long option. Short option representation is optional

program --doc
program -d # This is optional
  • Prefix for boolean long option should be -- when true and --no- when false
program --doc # True
program --no-doc # False
  • All boolean short options should have different names for true and false
program -d # True, --doc
program -b # False, --no-doc

List Variable

  • All variables which takes a list as value are called list variables where list is considered to have atleast 1 value
program -l name
program -l name1 name2 name3
program -l # Not Allowed
  • All list variables should be represented by long option. Short option representation is optional
program --logins
program -l # This is optional
  • All list variables should be followed by either a long/short option or a terminator and non options
program -l name1 name2 -a create
program -l name1 name2 -- create
program -l name1 name2 create # Not Allowed
  • All list variables should be aggregated with other short options only if it is at the end
program -l -ax
program -l name1 name2 -ax
program -axl name1 name2
program -alx # Not Allowed

Special Cases

  • All programs which is a combination of different programs can use a non option initially to denote the program
git diff -p master develop
# Equivalents to
git-diff -p master develop

Recommendations

The following are not mandatory

  • All boolean short options should be lowercase for true and uppercase for false of the same alphabet
program -d # True, --doc
program -D # False, --no-doc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment