 # Mudlib Documentation
 
   File    : /std/user/user/alias.c
   Brief   : Documentation of alias system inheritable
   Date    : 20-JAN-06
   Updated : 20-JAN-06
   
  INTRODUCTION:
  
/std/user/user/alias.c is inherited by user.c which makes
calls from the command hook that are contained in that file
which handle the storage and parsing of aliases (parse_str).
The commands "alias" and "unalias" also make calls to the
user object to functions that are contained in that file to
allow users to manage local aliases.

A local alais is an alias created by the user, not inherited
from the global alias daemon.

  ADDING AN ALIAS:
  
To add an alias, there is the function add_alias(string verb, string args);
The first argument is the verb to be aliases and the second argument is the
actual alias. If the verb starts with the character '$', it will be added
an an xverb. Otherwise, it is added as a normal alias.

If the object calling is not the same object or a member of the admin
group (confirmed with the adminp simul-efun), then it will return without
adding the alias.

  REMOVING AN ALIAS:
  
To remove an alias, there is the function remove_alias(string verb);
The lone argument is the verb to be unaliased. This function only allows
the unaliasing of local aliases (aliases defined by the user). The function
will first see if the verb is a normal alias and will remove it and return 1;
If it is not a normal alias, it will then check to see if it was aliased
as an xerb and if it was then it will return 1; If no alias was found, it
will return 0; 

If the object calling is not the same object or a member of the admin
group (confirmed with the adminp simul-efun), then it will return without
removing any aliases.

  GETTING ALIASES:
  
The function 'mapping get_aliases(int all);' will allow you to get mapping
containing alias data. If the argument is greater then 0, then it will also
include aliases that are inherited from the global alias daemon. The mapping's
keys are the verb and the value is the actual alias.

  XVERBS:
 
xverbs allow you to alias the first part of a verb. For example, if you xverb
alias ":" then anything types after : will be parsed as that alias. This means
that instead of being limted to ": <args>", you could also type ":<args>".
It basically removes the space between the verb and the first argument.

  PARSING OF ALIASES:

The alias system will parse certain token in the the alias. All tokens
begin with '$'. For example, the arguments are exploded with the delimiter
" ", and if you place a number after the '$' it will replace the token
with the word that matches that index (with the index starting at one, instead
of zero). Incase there is no matching word, it will replace it with "" and will
also take care of whitespaces as if the token never existed.
"$*" will be replaced at the end of the parsing with all remaining words
imploded together with the delimter " ". The token will be replaced with ""
if there are no words remaining and will also take care of surronding
whitespaces to ensure proper parsing.

To parse an alias normally, you would call 'string parse_str(string verb, string args);'
with the first argument being the verb and the second argument being the input
following the verb. The function will return a parsed string.

  NOTES:
  
It should be noted that the system has been designed to allow users
to override aliases inherited from the global alias daemon.  

Also, great care has been taking to ensure whitespaces are taken
care of correctly.
  
    
   