Programming in EPIC                                                         

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:

   1) Use variable and alias structures.
   2) Indent your code consistently.  It will be easier to update later.
   3) Comment your code.  So you'll know what you did a year from now.
   4) Use serial numbered hooks whenever possible.
   5) For server output, use the "end" message instead of a WAIT command.
   6) Read the client documentation! :)

Refer to Section 5 of these helpfiles for information about specific
commands.  Refer to Section 6 for the client's built-in functions.