User Tools

Site Tools


programming

Differences

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

Link to this comparison view

programming [2006/08/29 20:18] (current)
Line 1: Line 1:
 +======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 command|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:
 +
 +   - Use variable and alias structures.
 +   - Indent your code consistently. ​ It will be easier to update later.
 +   - Comment your code.  So you'll know what you did a year from now.
 +   - Use serial numbered hooks whenever possible.
 +   - For server output, use the "​end"​ message instead of a [[WAIT]] command.
 +   - 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.
 +
  
programming.txt ยท Last modified: 2006/08/29 20:18 (external edit)