

---

! Standards for Command Line Options in Arch

-*-*-

---


* Parse First, Take Effect Later, With Three Exceptions

  Options are parsed first, then take effect only after all options
  have been parsed.  That allows contradictory options to cancel each
  other.  You can say:  `--dir="a" --dir="b"' and that means that the
  specified directory is `b'.

  Two exceptions are `--help|-h' and `--version|-V' which take effect
  as soon as they are detected, then cause the program to exit
  immediately with status 0.

  A final exception is `--debug' whose meaning is entirely
  implementation dependent.  It can do anything at all.


  $[*bugs in the current implementation:*]$

  Sometimes one option implies others. I _think_ I recall writing code
  of the form:

<<<
	-a)	a_flag=-a
		b_flag=-b
		;;
>>>

  which is bogus.  `b_flag' shouldn't be set until the `process
  default options' code.  However, don't confuse this with options
  that cancel other options:

<<<
	-a)	a_flag=-a
		b_flag=
		;;
>>>

  Those are fine.

---

* No Smashed Together Options

  For simplicity of parsing options in shell scripts, we don't permit
  short options to be combined or permit options to be combined with
  their arguments.  This is a slight deviation from the
  recommendations of Posix.

  For example, these are ok:

<<<
	-a -b
	-d dirname
	--dir dirname
>>>

  But these are not ok:

<<<
	-ab
	-ddirname
	-d=dirname
	--dir=dirname
>>>

  There is one exception to this: the `-X' option (see {Binary
  Options}).

  `arch' implementations are permitted to accept options of the `not
  ok' form, but user scripts that want to be portable to multiple 
  `arch' implementations should not use those forms.

---


* Every Short Option has a Corresponding Long Option

  Short option names are just a convenience.  Long option
  names are self-documenting.  Therefore, every short 
  option should have a corresponding long option.


---

* Options with Option Arguments

  If an option requires an option argument, passing the empty string
  for that argument is equivalent to not setting the option at all.
  For example, the options `--dir="a" --dir=""' are equivalent first
  to `--dir=""' (by the "parse first" rule), then to not passing
  `--dir' at all (by the empty string rule).

---

* Binary Options and Option Cancelling

  If an option doesn't take an option argument, it's a binary option.
  It is either present or not present.  To user's this is like 
  setting a flag (except that setting some flags can implicitly clear
  other flags).

  It's useful to be able to put options on a command line that 
  cancel previous options.  For options with arguments, this is 
  done by passing an empty-string argument.

  For binary options, prefixing the long name with `X' gives an
  option with the opposite meaning.  The short option `X' takes
  a one character argument -- a binary option to negate.

  For example, if `-e' means "edit the log file", then `-Xe' means "do
  not edit the log file" and `-Xe' cancels `-e'.  In long-name
  notation, if `--edit-log' is equivalent to `-e', then `--Xedit-log'
  is equivalent to `-Xe'.

  It is an error to add the `X' prefix to an option that requires an
  argument.

  Note that some binary options cancel earlier, different options.
  An example, from `import' is the options `--begin' and `--finish'.
  For that program:

<<<

	--finish --begin	== 	--begin
	--begin --finish	==	--finish

>>>

  No option with an `X' prefix cancels or implies any other option.
  So, for example:

<<<
	--finish --begin --Xbegin	==	<none>
	--begin --finish --Xfinish	==	<none>
	--begin --finish --Xbegin	==	--finish
	--finish --begin --Xfinish	== 	--begin
>>>

  $[*bugs in the current implementation:*]$

  The `X' prefix is completely new.  It is needed to make LarchAliases
  more useful, but none of the commands current support `X'.



---

* Standard Option Names

  ${_Insert list here_.}$

  For example:


	+ -A --archive _archive-name_ ::: Specify the archive to
		operate on.

	+ -R --root _archive-root_ ::: Specify the root directory of
		the archive to operate on by default.  However, 
		the option `-A|--archive' takes precedence over this.


---

* Non-standard Options

  If an implementation provides non-standard options to some command,
  the long option name should begin with `:' and the short option 
  name should always have ':' prefixed.  For example:

<<<
	--:non-std-option

	-:Q
>>>

  In general, non-standard options should avoid having short names at
  all.

  This is an aid to people who want to write scripts that are portable
  between implementations.  It also makes it easier to standardize 
  a non-standard option.


%%% tag: Tom Lord Wed May  1 23:20:15 2002 (ArchRevCtl.d/OptionStandards)
%%%
