no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+#$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:
+     - "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:
+<file>/alias foo echo this is a test!</file>
+   * <rval> is the "value" of an alias, such as "echo this is a test!" in:
+<file>/alias foo echo this is a test!</file>
+   * <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.