Grammar Details

Youness IABITEN edited this page Dec 16, 2015 · 10 revisions

If you're not familiar with *nix command line environment, you should know that this library was inspired by C function getopt.

You may want read also this Wikipedia article.

These conventions allow two kinds of arguments, options and values:

  • values can be or not be bound to options.
  • options can be defined with short name, long name or both.

Short Name

A short name is defined with a single character (in .NET context a System.Char) and is invoked using single dash or hyphen:

$ coolapp -f my.file

But this is not the only valid syntax. When a short name is mapped to a System.Boolean, you have to invoke or omit it. You can't type coolapp -v true or coolapp -v false; it's simply not allowed by the specification.

$ coolapp -v

With the previous example I say coolapp to activate the option named v. To deactivate it, I simply omit its invocation from the command line:

$ coolapp

Short options can be grouped, so that:

;; this is valid (omitting space between short options)
$ coolapp -vf my.file

;; and also this (omitting space between short option and its value)
$ coolapp -vfmy.file

Say I have a, b, c, d, e and the same f options:

;; this is a valid syntax:
$ coolapp -abcdef my.file

And so what is not allowed?

$ coolapp -fv my.file

Values are always supplied by proximity and since v doesn't accept values, because bound to a boolean, in this case:

  • you're telling coolapp that the file is called v as the option
  • and my.file is left as unbound value

Long Name

Options with long name are defined with two dashes (or two hyphens if you prefer):

;; this...
$ coolapp --file script.sql

;; ...and this are both valid syntax
$ coolapp --file=script.sql

When invoked with short options, you have to supply proper spacing.

;; this is not allowed
$ coolapp -v--file=script.sql

;; this obviously yes
$ coolapp -v --file script.sql

Unbound Values

Unbound values are values not bound to any specific options (the parser has its means to handle these).

$ fakecompiler source1.cs source2.cs source3.cs source4.cs --optimize-all

For clarity I've put optimize-all at the end, but for the sake of example we suppose it is bound to a boolean. I could have put it anywhere:

$ fakecompiler source1.cs source2.cs --optimize-all source3.cs source4.cs

All other values (source*.cs) are unbound values.