Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
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