#$EPIC: aliasctl,v 1.6 2003/12/05 22:05:03 brian Exp $
Synopsis:
   $aliasctl(<domain> <operation> <operand> [<rval>])
   $aliasctl(<domain> GETPACKAGE <lval>)
   $aliasctl(<domain> GET <lval>)
   $aliasctl(<domain> SETPACKAGE <lval> <package-name>)
   $aliasctl(<domain> SET <lval> <rval>)
   $aliasctl(<domain> MATCH <word>)
   $aliasctl(<domain> PMATCH <pattern>)
   $aliasctl(<domain> EXISTS <lval>)

Technical:
   * This function is a low-level interface to the alias/assign symbol tables.

   --- General Syntax errors:
   * If the <domain>, <operation>, or <operand> argument is omitted, the
	empty string is returned.
   * If the <package-name> argument is omitted for the SETPACKAGE operation,
	the empty string is returned.
   * If the <rval> argument is omitted for the SET operation, the empty
	string is returned.

   --- About Domains:
   * The <domain> argument selects the type of alias you wish to operate
	on, and must be one of the following three strings:
		"ASSIGN"	for /assign (``global variable'') aliases
		"ALIAS"		for /alias (``command/function'') aliases
		"LOCAL"		for /local (``local variable'') aliases.
   * If an invalid <domain> is chosen, the empty string is returned.

   --- General definitions
   * <lval> is the "name" of an alias, such as "foo" in:
		/alias foo echo this is a test!
   * <rval> is the "value" of an alias, such as "echo this is a test!" in:
		/alias foo echo this is a test!
   * <package-name> is the "package" that was in force when the alias
	was loaded;  This was set by the /package command at load-time.

   --- About Operations:
   * The <operation> argument specifies the action you want to take and
	must be one of the following 7 strings:
		"GETPACKAGE"	to get an lval's /package value.
		"GET"		to get an lval's rval.
		"SETPACKAGE"	to set an lval's /package value.
		"SET"		to set an lval's rval.
		"MATCH"		to get the names of all aliases that 
				begin with <word>
		"PMATCH"	to get the names of all aliases that
				are matched by <pattern>.
		"EXISTS"	to determine if an alias exists or not.
   * If an invalid <operation> is chosen, the empty string is returned.

   --- Special explanations:
   * The "GET" operation is the only way to get the "body" of an alias.
	For assigns, it is identical to $::<lval>.
   * The "SET" operation is essentially the same as:
	/alias <lval> <rval>
	/assign <lval> <rval>
   * The "MATCH" operation looks for aliases that begin with the given
	string but do NOT "find" any aliases that include any dots after
	the string that you specify.  This is roughly equivalent to how
	the /foreach command works.  If you need pattern matching, then
	use the PMATCH operation instead.
   * The "PMATCH" operation returns a word list of all the aliases that are
	matched by the pattern.  Obviously the "*" pattern returns the name
	of every alias.
   * The "EXISTS" operation returns 1 if the alias exists, 0 if it does not.

Practical:
   Getting and setting assigns, and setting aliases is provided only for
   completeness.  You really shouldn't use $aliasctl() to obfuscate those
   operations.

   This is the only way to get the "body" of an alias.  This is the only way
   to get a list of aliases/assigns that begin with a given string.  This is
   the only way to get a list of aliases/assigns that "match" a given pattern.
   This is the CHEAPEST way to test to see if an alias exists before you try
   to run it.

   You can tell whether a built in command has been overridden by an alias 
   by doing something like:
		$aliasctl(alias exists join)
   which would return 1 if a "join" alias exists, and 0 if it does not.

Examples:
   $aliasctl(alias get join)            returns current value of alias "join"
   $aliasctl(alias set join //channel)  just like "/alias join //channel"
   $aliasctl(assign match foo)          returns names of all vars that start
					with "foo" but do not contain any 
					more dots after that, such as
					"foobar" but not "foo.bar" nor 
					"foobar.baz"
   $aliasctl(alias match foo.)          returns names of all aliases that 
					start with "foo." but do not contain 
					any more dots after that, such as 
					"foo.bar" but not "foo.bar.baz"
   $aliasctl(alias pmatch foo*)		returns all aliases that match the
					pattern 'foo*' such as 'foobar',
					'foo.bar', 'foobar.baz' and 
					'foo.bar.baz'

Notes:
   Currently, the "MATCH" and "PMATCH" operations do not work with the
   "LOCAL" domain. This may change in the future.

See Also:
   assign(5); alias(5); edit(8)