====== Synopsis ======
alias \\ 
alias //<alias-name>// \\ 
alias -//<alias-name>// \\ 
alias //<alias-name>// (//<argument-list>//) {//[[block]]//}

====== Summary ======
Aliases are /commands and $function()s that you create that complement the 
built in /commands and $function()s.

Aliases may call built in commands, other aliases, or evaluate expressions.

Aliases may (optionally) return a value, which will be used if you call the
alias as a $function().

====== Forms ======
If you provide no arguments, [[alias]] will display all your aliases.

If you provide an alias name, or an initial part of an alias name, it will display all aliases that start with what you provide

If you provide only an alias name, prefixed with a hyphen ("-name"), it will remove that alias.

If you provide an alias name, a block statement, and an (optional) [[arglist]], the alias will
be created (or replaced if it already exists).

====== Alias names ======
Alias names can contain any character except a nul (ascii 0x00).

Because of how ircII treats a[b][c] as syntactically identical to a.b.c,
if your alias name contains square brackets, they will be silently changed
to dot-notation
	foo[bar][baz]
becomes
	foo.bar.baz

You should avoid beginning an alias name with a left parenthesis ("("), left curly 
brace ("{"), or at-sign ("@"), because they conflict with ircII syntax, and can make 
it difficult to call your alias.

====== Local variables and Return value ======
Aliases can set [[local variables]] which are destroyed when the alias is finished.  
Aliases are automatically provided with a local variable "FUNCTION_RETURN" which is
used for the alias's return value.  You can assign a value directly to it, or use 
the [[return]] command.  If the alias is called as a command, then the return value
is ignored by the caller.

====== Aliases overrule built in commands ======
Aliases take precedence over both built-in commands and built-in functions
(built-in commands only in EPIC4).  You must take special measures to call
the built-in command or function if you have overridden it with an alias.

If you need to call a builtin command after defining an alias with the same
name, use two slashes:  
      //builtincommand args

If you need to call a builtin function after defining an alias with the same
name, use two colons before the name:
      ::builtinfunction(args)

====== Examples ======
To create an alias that overloads a command, and calls it too:
      alias lusers {
         echo -- User Information for ${[$*] ? [$*] : S}
         //lusers $*
         echo -- End User Information
      }

To create a function that returns the sum of two inputs:
      alias sum {
         @ function_return = [$0] + [$1]
      }

To create an alias that uses the new function:
      alias showsum {
         echo The sum of $0 and $1 is $sum($0 $1)
      }

To use the new /showsum command to compute a sum:
      /showsum 4 5

Using the alias as in the previous example will display the following:
      The sum of 4 and 5 is 9

====== History ======
The __alias__ command first appeared in ircII.

#$EPIC: alias_command.txt,v 1.7 2009/08/13 04:25:48 jnelson Exp $