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

pksunkara/clarg.md