
---

! An Alias Mechanism for Larch

* The Need

  Some commands have lots of options and there is no right default
  behavior.  For example, some user's might prefer that `commit' not
  run `tree-lint' by default, others want it to.  Another example,
  some users will always want the `--edit-log' option to `commit',
  while others won't.

---

* Rejected Solutions

  There are some ways to solve this that I don't like.

** User Preferences

  We could add a preference mechanism (`~/.larchrc').  Users could set
  a variable like `commit-always-runs-make-edit' or some such.

  I don't like this idea because it makes the specification of the
  core commands more complicated.  The spec documents would have to
  explain, for example, what each possible preference setting means in
  combination with various options.  That violates one of the
  ArchPrinciples, specifically, *simplicity*.


** Layered Commands

  We could just add the options and stop there, saying to users "ok,
  now you can write your own shell scripts on top of arch".  If
  someone doesn't like "larch commit", they can write their own
  script "cmt" that passes the options they want.

  This is a pretty good solution, but it has the drawback that the 
  new scrips aren't handled by the front-end program `larch'.  They
  don't show up in the output of `larch --help-commands' for example.
  Odds are, too, that they won't handle `--help' reasonably.


---

* Proposed Solution

  The proposed solution is to have a simple language for creating
  new arch commands which are equivalent to existing commands, but
  with some default options.

  For example, you could define the alias `cmt' which invokes `commit'
  but implicitly provides the `--no-lint' and `--edit-log' options.


** System vs. Personal Aliases

  If you have suitable permissions, `larch define-alias --system'
  should install an alias that all users see.  Installing a new
  version of arch shouldn't destroy existing aliases.

  Otherwise, `larch define-alias' creates just a personal alias.


** Alias Interface

*** Defining Aliases

<<<

	% larch define-alias [--system] alias-name command options ...

	 --system			Install the new alias so that
        				it is visible to all users.
	

	Define a new alias for COMMAND.  Subseqently, running:

		% larch ALIAS-NAME [params ...]

	is equivalent to running:

		% larch COMMAND OPTIONS [params ...]

	When this command is invoked, no existing system or personal
	alias must already have the name `alias-name'.  When an
	alias is invoked as a command, if it has both a personal and
	system definition, an error the alias command exits
	immediately with non-0 status (and an error message).

	% larch define-alias --remove [--system] alias-name

	Removes the definition of an alias.
>>>

*** Help Messages for Alias Commands


<<<
	The invocation:

		% larch ALIAS-NAME --help

	prints the three lines:

		*[system-]alias* ALIAS-NAME = COMMAND OPTIONS

		<synopsis for COMMAND>
		<usual --help message for COMMAND>

	However, if the alias is multiply defined (both personal and
	system), instead of a help message, the command prints an
	error message and exits with non-0 status.

>>>





*** Looking Up Aliases

<<<

	% larch alias [alias-name]

	Print the first line of help message output for an alias.

	If the alias is multiply defined, print both definitions.

	If no ALIAS-NAME is specified, print a list of all aliases.

>>>

*** Interaction with Other Features

  Particularly important to make command aliases useful is complete
  and regular support for _option canceling_.  For example,
  let's suppose that you make an alias for `commit' that always
  runs the log file editor, and always permits a commit even if there
  are no changes to a tree:

<<<
	% larch define-alias cmt commit -e --unchanged-ok
>>>

  Sometimes, users may want to use that alias, but _not_ run the 
  log file editor.  With _option canceling_, they can run:

<<<
	% larch cmt -Xe --log-file PREPARED-LOG
>>>

  Option cancelling is one of the new OptionStandards.



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