This short (very short) document describes EPIC's programming language (some would argue it's but a scripting language) and how to use it.
The first thing to remember about scripts is that command characters are not required for commands! In fact, their use is discouraged, as it only makes more work for the client when parsing the command. There is, of course, an exception to this rule (but only one). Because the client allows commands to be overloaded by aliases, there needs to be a way to access the original command. This is done by giving the command character twice. For instance:
alias mode {
if ( (index(#&+ $0) == 0) || ([$0] == N) ) {
//mode $*
} {
//mode $C $*
}
}
The above alias overloads the built-in MODE command. It first checks whether the first argument passed was a channel name or your own nickname. If so, it executes the real MODE command using the arguments given. Otherwise, it executes the real MODE command for the current channel. Even though the user can change the command character, the / character is always accepted as a command character in a script. There is no need to use that nasty ${K}${K} hack as you do in ircII – using two slashes works just fine in EPIC.
Good: //mode $C $*
Bad: ${K}${K}mode $C $*
Certain characters have special meaning in scripts and inside certain commands that they don't necessarily have on the input line. The semicolon (;), when used inside a {} command construct (from an alias, key binding, hook, timer action, etc.), is a command separator. For example:
alias blah {
on hook * echo hooked: $*;echo oops!
}
When the /blah alias is run, “oops!” will be displayed. However, we didn't want that. We wanted it to be displayed whenever the HOOK command was called. You should always put curly braces (“{” and “}”) around anything that you want to be considered as one command, like so:
alias blah {
on hook * {echo hooked: $*;echo oops!}
}
The backslash (\) character “escapes” the next character in a script (but not on the input line). The character after a backslash loses any special meaning that it might have (such as semicolons, or newlines, or double-quotes). In addition to this, if the backslash character is the last character on a line (no spaces after it – nothing at all) then the backslash character will do line-continuation:
if ( foo == 1 && \
bar == 2 ) { ... }
behaves exactly as if you had done:
if ( foo == 1 && bar == 2 ) { ... }
In general, no matter what the circumstance, anything that is enclosed within parenthesis, curly braces or square braces, is protected against expansion until it is actually needed. This is what permits the curly- brace thing to work in the above example:
alias blah {
on hook * {echo hooked: $*;echo oops!}
}
Unlike ircII, you can use curly braces anywhere you want in EPIC in order to protect early expansion.
Speaking of quoting characters, the client's quoting rules can be confusing. In general, everything works as described above; quote special characters to use them in text context. However, the rules change when the client needs to parse a command more than once. USERHOST is a classic example of this. Let's say we've created this alias:
alias foo userhost $0 -cmd echo ($*)
That won't do at all, because both $expandos are parsed once, before the command is even executed, which isn't what we want. So we need to do some quoting on the -cmd part:
alias foo userhost $0 -cmd echo \($$*\)
Note that we quoted the '$' with the form '$$'. This is a special expando that expands to a single '$'. We could have escaped it with a backslash, but the $$ expando is faster. Anyway, that alias won't work either. Why? Because the parentheses cause the whole statement to be parsed twice, so we're right back where we started. We need to add another level of quoting to the parentheses:
alias foo userhost $0 -cmd echo \\\($$*\\\)
After the initial parse run, the parenthesis are still quoted, because '\\' expands to '\', and '\(' expands to '(', which together make '\('. After the command is executed, the ECHO command is then parsed, this time correctly.
Other miscellaneous tips:
Refer to Section 5 of these helpfiles for information about specific commands. Refer to Section 6 for the client's built-in functions.