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

====== Description ======
The alias command lets you create your own command and functions.
Aliases are barely more sophisticated than macros.
You can use an alias as a command in a command statement, or 
as a function name in a function call.
You can pass arguments to an alias, and these areguments are put into
the $* special variable, unless you use an //<argument-list>//, then
they are [[assigned]] to local variables.
Each time you call an alias, either as a command or as a function, the 
//[[block]]// statement is executed.

If you call [[alias]] with no arguments, it will list all existing alias
names and blocks.  If you call [[alias]] with just a name argument, it
will list that name and that alias's block.  If you call [[alias]] with
just a name prefixed with a dash, it will delete that alias.

If you call [[alias]] with an argument name and a block statement, it will
create the alias and you can start using it immediately.  When your alias
is called, the argument list will be contained in $*.

If you call [[alias]] with an argument name, an argument list, and a 
block statement, it will create the alias and you can start using it 
immediately.  When your alias is called, the argument list will be 
[[assign]]ed to local variables in accordance with however you set up 
the argument list.

The following are the arguments to __alias__:

===== Alias name =====
The alias name may contain any character but you should not use the left 
parenthesis because it will have special meaning in the future.

===== Argument List =====
See [[arglists]] for a length discussion of argument lists.

The alias argument list is a list of comma-separated-values enclosed in 
parenthesis.  Each value represents a local variable that should be initialized
using values from the argument list before the alias is run.  

===== Code block =====
The [[block|code block]] is a string of semicolon-separated statements 
surrounded in curly braces.  These are the statements that will be executed 
each time the alias is invoked.  If the alias is to be invoked as a function, 
it should [[return]] a value.

===== Calling the builtin =====
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

====== Other Notes ======
Do not confuse the syntax of the __ALIAS__ command with the oddness
of the [[LOAD]]er.  Command bodies in aliases must always be 
separated by semicolons, and usually the [[LOAD|loader]] does this kind of
stuff for you.  But that does not mean the semicolons aren't there.
A lot of the structure and layout that people are used to with ircII
and epic scripts is a peculiarity of the [[LOAD]] command and does
NOT have anything to do with how __ALIAS__ works.

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

#$EPIC: alias_command.txt,v 1.6 2007/08/05 13:49:54 jnelson Exp $