CLOPS — Reference

Command Line Interface

CLOPS generates this description of its own command line interface.

Option Types and Their Properties

Table 1 provides an overview of the built-in option types and their properties. Each option-type has all of the properties that are defined in one of its predecessors. Options that cannot appear in an CLOPS description are called abstract.

All option types derive from the abstract option-type basic. The property default is the value to which the option is set before parsing begins and thus it will have this value if no assignments were performed to this option. The property suffixregexp is the regular expression appended to the aliases given in the option declaration. The following snippet declares a declaration of the option lines whose alias (prefix) is - (hyphen) and the suffix is a nonempty sequence of digits followed by the separator.

 lines:{"-"}:{int}:[suffixregexp="([0-9]+)\0"]

In effect the option lines will match on inputs as -12345. The separator (\0) means that the user needs to separate the following option on the command line (by space for example). The property suffixregexp is rather advanced and is needed only for strangely shaped options.

The abstract option-type oneArgumentOption is for the options that are specified as OptAlias VALUE or OptAlias=VALUE. The regular expression between determines how the alias is separated from the value and the regular expression argumentshape determines the form of the value string. The default value for between is [\0=] (a separator or the equals sign); the default value for argumentshape is .*. If the value is empty or not provided, the property defaultvalue determines the value. The oneArgumentOption is used as a base class for most of the other options.

The following declaration exemplifies the difference between defaultvalue and default. The option n will have the value 0, if not specified on the command line at all. It will have the value 123, if specified as -n (no value). Otherwise the value can be specified as -nVALUE.

  n:{"-n"}:{int}:[between="" argumentshape="[0-9]*" 
                  defaultvalue="123" default="0"]

The type boolean is for options that are either false, true, or unset. The property allowarg determines whether the user may explicitly specify the option's value (e.g. -o=false). Setting allowarg and default to false yields the behavior we usually see in command-line programs. An option is false unless it appears on the command-line. The following declaration exemplifies an option verbose defaulting to false, which cannot be set explicitly to false by the end-user.

verbose:{"-v", "--verbose"}:[default="false", allowarg="false"]

The option-type counted-boolean is for options for which we want to know how many times it was written on the command-line. The property countstart specifies where the count should start (default is 0), countmax is the maximum for the counter. If warnonexceedingmax or erroronexceedingmax is set, an error or warning, respectively, is produced when the maximum is exceeded. The following is an example from gzip for which one may write gzip -v -v to increase verbosity level.

verbose:{"-v","--verbose"}:{counted-boolean}:
  [countmax="3",warnonexceedingmax]

The option-types string, int, and float are self-explanatory.

The option-type string-regexp enables to specify a regular expression limiting the strings that the user may write on the command line as a value. The option-type string-enum is a restricted version of string-regexp for which we can specify a finite number of string values. These values are specified as a comma-separated list. If one of these values is an empty string, the user may decide not to provide a value.

The option-type file accepts a file-name as an argument and its properties can be used to require the file's (non)existence and whether is must or must not be a directory.

The option-type list is an abstract predecessor for options which the end-user several values on the command-line. These values are separated according to the regular expression given by the property splitter (it is "," if not specified). The option-types string-list and file-list are list of string and lists, respectively.

Table 1: Built-in option types and properties. Abstract types are typeset in italics. T is the type of the concrete option's value.

Name	Inherits from	Java type	Properties
basic	None	T	default[T], suffixregexp[string]
oneArgumentOption	basic	T	between[string], argumentshape[string], defaultvalue[T]
boolean	basic	boolean	allowarg[boolean]
counted-boolean	basic	int	countstart[int], countmax[int], warnonexceedingmax[boolean], erroronexceedingmax[boolean]
string	oneArgumentOption	String
string-regexp	string	String	regexp[string]
string-enum	string	String	choices[string], casesensitive[boolean]
int	oneArgumentOption	int	minvalue[int], maxvalue[int]
float	oneArgumentOption	float	minvalue[float], maxvalue[float]
file	oneArgumentOption	file	canexist[boolean], mustexist[boolean], canbedir[boolean], mustbedir[boolean], allowdash[boolean]
list	oneArgumentOption	List<T>	allowmultiple[boolean], splitter[string]
string-list	list	List<String>
file-list	list	List<File>	canexist[boolean], mustexist[boolean], canbedir[boolean], mustbedir[boolean], allowdash[boolean]

API

Describe the programming interface.

Rules

General type of rules. Then a description of each of them.

Command Line Interface

Option Types and Their Properties

API

Rules

Other Documentation