User Tools

Site Tools


aliasctl

#$EPIC: aliasctl.txt,v 1.3 2007/08/06 21:25:50 jnelson 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:
    1. “ASSIGN” for /assign (“global variable”) aliases
    2. “ALIAS” for /alias (“command/function”) aliases
    3. “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.

aliasctl.txt · Last modified: 2007/08/06 21:25 (external edit)