philippelh/bitchx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial import of the ircii-pana-1.1-final source tree.

Browse Source 
git-svn-id: svn://svn.code.sf.net/p/bitchx/code/tags/ircii-pana-1.1-final@1 13b04d17-f746-0410-82c6-800466cd88b0
This commit is contained in:
Kevin Easton
2008-02-25 09:25:32 +00:00
commit 28febcfea9
1429 changed files with 250653 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
bitchx-docs/5_Programming/5_Programming Normal file
View File

@@ -0,0 +1,13 @@
Section 5: Programming EPIC 
This section is mostly of interest to programmers. EPIC provides a rich,
feature-filled scripting language that allows you to customize the client
to no end.
Detailed in this section are the language's various control structures
(conditional and looping statements), methods for dealing with variables,
procedures (called aliases) and other data structures, methods for
script inclusion in other files, and much, much more.
A collection of built-in functions is in the next section.

103
bitchx-docs/5_Programming/alias Normal file
View File

@@ -0,0 +1,103 @@
Synopsis:
alias [[-]<alias name> [<commands>]]
Description:
ALIAS is one of ircII-EPIC's most powerful user interfaces. It allows
the user to execute an arbitrary series of commands with one single
command.
It actually serves a dual purpose. The primary usage is as described,
a convenient mechanism for issuing multiple commands in succession.
It may also be used to define custom functions that can be used in
conditional or assignment statements. The real power of aliases comes
from the fact that the client allows aliases to overload built-in
commands (but not built-in functions).
Usage
Aliases are used just like normal commands (and functions). They
may be called from the input line by prepending the command character
(see CMDCHARS) to them, or may be used in a script. Likewise,
scripted functions may be called using the normal $name() notation.
Aliases have no functional differences between built-in commands and
functions.
Syntax
Alias definitions with multiple commands may delimit the commands
with semicolons, or the commands may span multiple lines if
surrounded with curly braces. Users familiar with C/C++ or Perl
programming will note numerous similarities in the command syntax.
Like those languages, routines and functions are distinguished by
whether the alias has a return value; functions do, routines don't.
Aliases of both types may also accept arbitrary parameters, called
expandos. They are used just like variables, and are numbered
sequentially, starting with 0 (zero).
Current aliases may be displayed by only giving the alias name in the
command; all aliases matching the name are returned (such that "foo"
might return aliases "foo" and "foobar"). If no alias name is given,
all aliases are displayed. An alias may be removed by prepending its
name with a hyphen (-).
As mentioned previously, the client's builtin commands may be overloaded
by aliases. This naturally poses a problem when one needs to use the
real command, and needs to be sure it isn't some alias. The simple
answer is to use the "//command" form. That is, the client will skip
alias expansion for any command when it is preceded by the any command
character twice. Other methods include STACK, or avoiding command
overloading in the first place.
Examples:
To create an alias that overloads a command, and calls it too:
alias lusers {
echo ======= User Information for ${[$*] ? [$*] : S}
//lusers $*
echo ======= End User Information
}
To create a function that returns the sum of two inputs:
alias sum {
@ function_return = [$0] + [$1]
}
To create an alias that uses the new function:
alias showsum {
echo *** The sum of $0 and $1 is $sum($0 $1)
}
An alternate way of definite the same alias:
alias showsum echo The sum of $0 and $1 is $sum($0 $1)
To use the new /showsum command to compute a sum:
/showsum 4 5
Using the alias as in the previous example will display the following:
*** The sum of 4 and 5 is 9
See Also:
assign(5); say(1); send(5); set(4) cmdchars; stack(5)
Restrictions:
As mentioned above, aliases can overload commands, but not functions.
Alias names can consist of any character that isn't already a meta
character for EPIC (the @ symbol, square brackets, curly braces, semi-
colons, parenthesis, etc.). Note, however, that functions will not
when the name contains certain characters. A good rule of thumb is to
limit alias names to alphanumeric characters (and the underscore).
Bugs:
The exact syntax rules for alias structures (see ASSIGN for information
about structures) is somewhat ambiguous. Structures can be represented
as either name.sub or name[sub], but neither notation is guaranteed to
work in all instances. Functions, for instance, do not work with the
latter. This isn't necessarily a bug, but a feature of the syntax that
may produce some unexpected results.
Other Notes:
Like C, whitespace in scripts is generally not significant (there are
exceptions, such as with literal text to be ECHOed). An alias can
literally be defined on one line, or on as many lines as desired.
Code indentation is not required, though is done by convention, as
with most structured languages. Braces in multiline aliases may be
placed anywhere, as in C.

41
bitchx-docs/5_Programming/assign Normal file
View File

@@ -0,0 +1,41 @@
Synopsis:
assign [[-]<variable name> [<value>]]
Description:
ASSIGN is the general-purpose interface for creating and manipulating
variables. Just about any value can be assigned, whether it be a
string or a number. Internally, ircII-EPIC treats the contents of all
variables as strings, though it is smart enough to distinguish between
strings and numerical values for mathematical purposes.
The rules for variable names are similar to those of the C language;
they may consist of any letter, digit, or the underscore (_) character,
and they must begin with a letter. Unlike C, variable names are not
case-sensitive (nor are their contents, though they are case-preserving).
ASSIGN is primarily used for string assignments. It can be used for
mathematical purposes as well, using the ${} construct, but it can very
quickly become awkward and cumbersome. Mathematical operations are
better suited to the @ modifier (see Expressions).
Examples:
To assign a text string to the variable $foo:
assign foo this is some text string
To compute the sum of two integers:
assign foo ${4 + 5}
To delete a variable:
assign -foo
See Also:
Expressions(7); Special_Vars(7); alias(5); eval(5); set(4) input_aliases
Other Notes:
The default behavior of the client is to not treat variables specially
on the command line; they are passed as literal text. Variables normally
are only expanded when used inside an alias. This naturally poses a
problem for using ASSIGN with the ${} construct from the input line. To
force $ expansion on the input line, set INPUT_ALIASES to on, or use EVAL.
This is not a bug, it is a general feature of all commands.

49
bitchx-docs/5_Programming/bless Normal file
View File

@@ -0,0 +1,49 @@
Synopsis:
bless
Technical:
The bless command allows an asynchronous atomic scope (eg, inside an
on), to gain access to the local variables of an enclosing scope.
Care must be taken to make sure that this command is only executed in a
situation where this is an enclosing scope to gain access to.
Normally when an "atomic scope" is invoked (an "atomic scope" is by
definition an alias (or alias function) invocation or any asynchronous
event (an on, a timer, a wait -cmd, a queue)), a new
stack frame is created and access to any local variables in previous
stack frames is not allowed (because there is no guarantee just what
exactly is in the scope below us, so accessing their variables could be
disastrous.) However, in some cases, there is reasonable assurance that
an atomic asynchronous scope will in fact be executed synchronously, and
that the previous stack is well-known, and that access to the local
variables in that stack is desirable. The semantics of this are straight-
forward. The enclosing (outer) scope must take some action to ensure that
it will not "end", thus ending its stack frame, until the enclosed (inner)
scope is done manipulating its local variables. This is most often done
by a wait command in the enclosing scope. The enclosed scope then
would do a bless, and it would gain access to the local variables of
the enclosing frame.
In general, this is re-entrant safe. That is to say, the client keeps
track of each stack as it is locked by wait, and matches it up with
the each bless request, so that no matter how many times wait
may be nested, it will be correctly matched up with each bless.
Practical:
This is best demonstrated with an example:
alias uh
{
^local blahblah
wait for {
^userhost $* -cmd {
bless
push blahblah $3@$4
}
}
return $blahblah
}
See Also:
wait(1); on(1); timer(1); queue(1)

16
bitchx-docs/5_Programming/break Normal file
View File

@@ -0,0 +1,16 @@
Synopsis:
break
Description:
Break, like its C counterpart, breaks out of a loop.
Examples:
@loop = 0
while (0==0) { /* endless loop? */
@loop++
if (loop==20) break
} /* loop only made 20 iterations */
See Also:
alias(5); continue(5); return(5); for(5); while(4) until

35
bitchx-docs/5_Programming/call Normal file
View File

@@ -0,0 +1,35 @@
Synopsis:
call
Description:
CALL produces a gdb/dbx-like stack trace of the alias currently being
executed. It returns a list of the commands currently being executed,
tracing back from the current command, to the command that called it,
and so forth until the CALL command itself it listed. A deeply nested
alias might have the following alias stack:
[ 0] call
[ 1] go
[ 2] get_set
[ 3] get_ready
[ 4] on_your_marks
[ 5] /superalias
In this example, CALL was run from the "go" alias, which in turn was
called from "get_set", which was called from "get_ready", and so on, all
the way down to the original command executed.
Command names appear precisely as they are typed in (which means, if
an alias is called with a / in front of it, the slash will appear in
the stack listing). Additionally, in the (unlikely) event that EPIC
were to crash, CALL is executed before the client terminates, to aid
in debugging.
See Also:
set(4) debug
Restrictions:
This command requires that the client be compiled with the WIND_STACK
#define enabled; it is enabled by default. If the client was compiled
with it, the $info(o) string will have an 'a' in it.

38
bitchx-docs/5_Programming/comment Normal file
View File

@@ -0,0 +1,38 @@
Synopsis:
comment [<anything>]
Description:
This is exactly what it says, a comment. It does nothing. It is useful
in scripts for explaining bits of code, adding disclaimers or copyright
notices, etc.
There are also several symbolic comments. Both the # and : characters
may be used to designate comments. There is no functional difference
between any of them. Additionally, EPIC supports C /* */ multiline
comments.
Examples:
These are some comments:
comment this was the first comment
# this is a newer comment
: this is a new comment too, but it isn't used much
/* this is an elite comment unique to EPIC */
See Also:
set(4) comment_hack
Restrictions:
In order to facilitate the use of older scripts (those designed for old
or non-EPIC clients), the default behavior is to recognize C-like
comments only if they start at the beginning of a line. This allows
for '/*' sequence to appear in ECHOed text, etc. This default can be
changed to the traditional C behavior by setting COMMENT_HACK off.
There is no restriction on where the closing '*/' may appear. Also,
unlike C, a command may not begin before a comment, and end after it;
the /* */ effectively acts like a line terminator.
Other Notes:
Executing an alias whose name begins with a '*' by calling it as '/*'
will lose, as it will be interpreted as a comment. The solution here is
to limit alias names to alphanumeric characters.

16
bitchx-docs/5_Programming/continue Normal file
View File

@@ -0,0 +1,16 @@
Synopsis:
continue
Description:
Continue skips certain loops. In a for() or while(), continue will jump to
the end of the current loop and continue to the next iteration.
Examples:
for (@loop=0,loop<=10,@loop++) {
if (loop==4) continue
echo $loop of 10, skipping 4.
}
See Also:
alias(5); break(5); return(5); for(5); while(4) until

34
bitchx-docs/5_Programming/do Normal file
View File

@@ -0,0 +1,34 @@
Synopsis:
do <commands>
do { <commands> } [while (<condition>)]
Description:
In its base form, DO behaves much like EVAL. It evaluates its input
once, then executes it. It is superior in some respects, however. For
instance, it can cope with complex commands (multiple commands within
curly braces).
Furthermore, DO has the ability to mimic the WHILE command. While the
operation is not identical, it is similar. It only differs in that the
condition is evaluated after each loop iteration, so the loop is
guaranteed to run for at least one iteration.
See Also:
To force expansion of some variable $foo:
/do echo the variable $$foo expands to $foo
To run the same command in indefinite number of times, but at least once:
assign blah 2
do {
echo $blah is lower than 3
}
while ( blah = rand(5) < 3 )
See Also:
eval(5); while(5)
Other Notes:
This command is mostly supported for compatibility with previous ircII
clients. Internally, it uses more resources than EVAL, so it isn't of
much practical use, save for its looping ability.

26
bitchx-docs/5_Programming/dump Normal file
View File

@@ -0,0 +1,26 @@
Synopsis:
dump [all|alias|variables|on]
Description:
This purges all aliases, variables, and/or hooks in the client's current
memory. This is useful if a script is not behaving as expected, letting
the use dump everything and reload the script without restarting the
client. It is also useful for dumping any scripts that the client loads
automatically upon startup.
If no specific data type is specified, 'all' is used as the default.
Options:
alias purges all aliases in memory
variables purges all variables in memory
on purges all hooks in memory
all all of the above
Bugs:
The client will not return an error message if an invalid type is given.
In fact, it will report that the given type was indeed dumped!
Other Notes:
This command does not affect the .ircrc or any other file in any way.
It only affects the client's current state.

21
bitchx-docs/5_Programming/echo Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
echo [<anything>]
Description:
This command prints its arguments back to the screen. That's it. It
is useful for printing status messages from inside scripts, or inside
hooks for redefining server messages.
The ECHO command is also the only command (one of two, actually; see
XECHO) that can write to the screen when DISPLAY is off. ECHO now
has no length limitation, it can display any string within the confines
of memory.
See Also:
eval(5); set(4) display, input_aliases; xecho(5)
Other Notes:
ECHO will not normally expand variables unless it is used inside an
alias. To force expansion, use EVAL or set INPUT_ALIASES on. This is
not a bug, it is an intentional feature common to all commands.

23
bitchx-docs/5_Programming/eval Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
eval <commands>
Description:
EVAL takes the commands given it and passes them through EPIC's internal
inline parser before executing them. This means that variables will be
expanded once, and the command terminator (;) is honored. This has the
same effect as executing a command with INPUT_ALIASES turned on.
Examples:
To force the display of a variable when not inside an alias:
eval echo The variable's value is $foo
See Also:
set(4) input_aliases
Other Notes:
Care should be taken when using EVAL with untrusted input. If EVAL
must be used, it is important to first strip out any characters that
have special meaning to the inline parser, such as ';'. Using EVAL in
this manner can very easily lead to a hijacked client or compromised
account.

115
bitchx-docs/5_Programming/exec Normal file
View File

@@ -0,0 +1,115 @@
Synopsis:
exec [<shell commands>]
exec -direct <commands>
exec -name <name> <shell commands>
exec -out <process id|shell commands>
exec -msg <nickname|channel> <process id|shell commands>
exec -notice <nickname|channel> <process id|shell commands>
exec -in <process id> <text to send to process>
exec -window <process id|shell commands>
exec -<signal> <process id>
exec -close <process id>
Description:
EXEC allows you to spawn other processes from within your client,
which are naturally treated as child processes. For example, if you
wished to check your email without suspending your client (or
quitting irc), you could simply EXEC your favorite mail program.
Processes can be given unique names, allowing them to be referred to
more intuitively than trying to figure out its process id number.
Processes can also accept any signal normally available through use
of the Unix "kill" command (letting you kill, suspend, etc. any
process that accepts such a signal). Process identifiers begin with
a "%". Thus, a process named "mail" with pid 0 could be referred to
as either "%mail" or "%0".
EXEC can take several different flags, each of which allow you to
manipulate the subprocess in different ways. At the most basic
level, the only argument you really need to give is the external
program to run. If no arguments are given at all, a list of any
currently running processes is returned.
When using the -OUT, -MSG, or -NOTICE flags, output can be sent to
the target upon startup of the subprocess, or redirected to it after
it's already running by using its process id.
Another flag of note, -CLOSE, can be used to shut down renegade
subprocesses that simply won't go away (i.e. with their own quit
command, with the KILL signal, etc.). This actually just severs the
link between the subprocess and the client, so it will die on its
own the next time it tries to send data to the client.
Something to remember when worried about a shell processing arguments
is the -DIRECT flag, which executes the commands without spawning a
shell. This can cut down on security risks, and save some memory.
Options:
-direct executes commands without spawning a shell
-name give the subprocess a logical name
-out send subprocess output to your current channel
-msg send subprocess output to a nick or channel with MSG
-notice send subprocess output to a nick or channel with NOTICE
-in send a text string to the specified subprocess
-window redirect subprocess output to another window
-<signal> send SIG<signal> to the subprocess
-close forcibly kill the subprocess and its children
Examples:
(Assume that the process used with these examples is the Unix mail
program.)
To start a process:
/exec mail
To start a process without a shell interfering:
/exec -direct mail
To start a process and give it a human-readable name:
/exec -name mail mail
To send the output of a new subprocess to your current channel:
/exec -out mail
To send the output of a running subprocess to JoeBob with a MSG:
/exec -msg joebob %mail
To send the output of a new subprocess to #blah with a NOTICE:
/exec -notice #blah mail
To send a text string (command) to a running subprocess:
/exec -in %mail ?
To send a running subprocess the KILL signal:
/exec -kill %mail
To forcibly close down a stubborn subprocess that just won't die:
/exec -close %mail
Aliases:
When using EXEC with the -IN flag, the functionality is identical to
using MSG to send a message to a process. See MSG for more
information.
See Also:
msg(1); set(4) exec_protection, notify_on_termination, security, shell,
shell_flags, shell_limit
Restrictions:
Use of external programs from within irc can sometimes be dangerous
if you don't know what you're doing. The danger doesn't necessarily
lie in the external programs themselves, but rather in any lack of
knowledge about them you may have. When all else fails, don't use a
command if you don't know what it does.
You can explicitly limit your ability to use EXEC in several ways.
If EXEC_PROTECTION is set to ON, ircII-EPIC will not permit EXEC to
be used from within any ON hook. If SECURITY has the 1 bit set, the
client will only permit EXEC to be used interactively; using it from
within aliases is not allowed. For real security, you can #define
RESTRICTED at compile time, which will completely disable EXEC.
Other Notes:
The available signals that may be sent to a process will vary from system
to system.

61
bitchx-docs/5_Programming/fe Normal file
View File

@@ -0,0 +1,61 @@
Synopsis:
fe (<list>) <variable> [<variable> ...] { <actions> }
Description:
FE is one of several loop types available in ircII-EPIC. This loop
takes a list of items, and for each one, it performs the specified
action.
It may act on more than one item at a time. The list may be a plain
text list, a variable, a function, or any combination. As with aliases
and other control structures, the braces surrounding the action may
appear anywhere. List items are whitespace-delimited. Extended words
(those with spaces in them) are honored when they are surrounded in
double quotes (").
For instance, FE might be used to loop through a list of nicknames
that the user wishes to invite to a channel (or kick from it!).
Any looping mechanism can run through a list one by one. The real
power of FE is its ability to act on multiple list items at once.
One could perform an action on 3 at a time, for instance, such as
setting a +o channel mode on other users. Other loops, such as FOR,
can do this as well, but FE offers a more elegant solution.
Examples:
A simple mode +o script to cluster mode changes 3 at a time:
fe ( $friends ) xx yy zz {
if ( zz ) {
mode #blah +ooo $xx $yy $zz
} {
if ( yy ) {
mode #blah +oo $xx $yy
} {
mode +o $xx
}
}
}
A script to check for upper-case letters in a line of input:
@ caps = 0
fec ( $* ) xx {
if ( ascii($xx) >= 65 || ascii($xx) <= 90 ) {
@ caps++
}
}
echo *** Found $caps upper-case letters
Aliases:
FEC works the same as FE, except it loops through each character in the
list, not each word. Whitespace is only valid if it is between two
other non-whitespace characters. Whitespace that follows the opening
parenthesis, and that leads up to the closing one, is ignored.
See Also:
for(5); foreach(5); until(5); while(5)
Other Notes:
The loop doesn't necessarily have to have an action inside the curly
braces. It doesn't make much sense to omit it, though. Since 01/22/97,
FE and FEC use local(6) variables instead of global.

61
bitchx-docs/5_Programming/fec Normal file
View File

@@ -0,0 +1,61 @@
Synopsis:
fe (<list>) <variable> [<variable> ...] { <actions> }
Description:
FE is one of several loop types available in ircII-EPIC. This loop
takes a list of items, and for each one, it performs the specified
action.
It may act on more than one item at a time. The list may be a plain
text list, a variable, a function, or any combination. As with aliases
and other control structures, the braces surrounding the action may
appear anywhere. List items are whitespace-delimited. Extended words
(those with spaces in them) are honored when they are surrounded in
double quotes (").
For instance, FE might be used to loop through a list of nicknames
that the user wishes to invite to a channel (or kick from it!).
Any looping mechanism can run through a list one by one. The real
power of FE is its ability to act on multiple list items at once.
One could perform an action on 3 at a time, for instance, such as
setting a +o channel mode on other users. Other loops, such as FOR,
can do this as well, but FE offers a more elegant solution.
Examples:
A simple mode +o script to cluster mode changes 3 at a time:
fe ( $friends ) xx yy zz {
if ( zz ) {
mode #blah +ooo $xx $yy $zz
} {
if ( yy ) {
mode #blah +oo $xx $yy
} {
mode +o $xx
}
}
}
A script to check for upper-case letters in a line of input:
@ caps = 0
fec ( $* ) xx {
if ( ascii($xx) >= 65 || ascii($xx) <= 90 ) {
@ caps++
}
}
echo *** Found $caps upper-case letters
Aliases:
FEC works the same as FE, except it loops through each character in the
list, not each word. Whitespace is only valid if it is between two
other non-whitespace characters. Whitespace that follows the opening
parenthesis, and that leads up to the closing one, is ignored.
See Also:
for(5); foreach(5); until(5); while(5)
Other Notes:
The loop doesn't necessarily have to have an action inside the curly
braces. It doesn't make much sense to omit it, though. Since 01/22/97,
FE and FEC use local(6) variables instead of global.

25
bitchx-docs/5_Programming/filedialog Normal file
View File

@@ -0,0 +1,25 @@
Synopsis:
filedialog <options> <initial path> "Dialog title" <ok button text> <apply button text> { code }
Description:
FILEDIALOG creates a file selection dialog based on the options
passed. Possible options:
O = open dialog
S = save as dialog
M = allow multiple selections
A = include apply button (PM only)
The initial path if not specified is the current directory. In some
cases COMMENT_BREAKAGE should be set off. Problems will occur when
something like ~/*.mp3 is specified because /* gets interpretted
as a comment.
Dialog title is the text that is displayed in the dialog's titlebar.
Ok button and Apply button text is displayed on the corresponding
buttons if possible.
Code is the code fragment which is run after a selection is made.
$0 is OK, CANCEL or APPLY based on the user's choice. $1 and on are
the filenames selected, can be more than one in the case of multiple
selection.
See Also:
fontdialog(5) properties(5) popupmsg(5)

12
bitchx-docs/5_Programming/fontdialog Normal file
View File

@@ -0,0 +1,12 @@
Synopsis:
fontdialog <all windows> <default>
Description:
FONTDIALOG creates a dialog which allows you to choose the font
for the current window or all windows. The two parameters can be
ommited. They are either 0 or 1. If it is 1 the check button in
the dialog is checked, if it is 0 it is unchecked.
See Also:
filedialog(5) properties(5) popupmsg(5)

40
bitchx-docs/5_Programming/for Normal file
View File

@@ -0,0 +1,40 @@
Synopsis:
for ([<pre>],[<condition>],[<post>]) { <action> }
Description:
FOR is a general purpose loop. It is modeled on the C for statement,
and works in a very similar manner. Aside from the action, there are
three parts to a FOR loop:
* The "pre" part is executed before the loop begins iterating. This is
often used for initializing counters and other variables that will be
used in the loop.
* Before each loop iteration, the "condition" is checked. Most often,
this is used to see if the counter has exceeded a certain limit. The
condition may contain any expression legal in the IF command.
Because of this, the loop does not necessarily have to iterate at all.
* The "post" part is executed after the condition, if the condition
returns true. This is generally used to increment a counter that
gets checked by the condition statement.
Multiple commands may be used in each part; they must be separated by
semicolons (giving it something of a reverse-C syntax). Note that
there does not necessarily need to be any commands in any part. The
action is optional as well.
Examples:
To display a warning message 3 times:
for ( @ xx = 3, xx > 0, @ xx-- ) {
echo WARNING! This ship will self destruct in $xx seconds!
}
A infinite loop that behaves like the Unix 'yes' command:
for ( ,, ) {
echo yes
}
See Also:
fe(5); fec(5); foreach(5); until(5); while(5)

43
bitchx-docs/5_Programming/foreach Normal file
View File

@@ -0,0 +1,43 @@
Synopsis:
foreach [-]<structure> <variable> { <action> }
Description:
The FOREACH command is a loop type that iterates through the items in
a variable (or alias, see below) structure. This is often useful for
purging an entire structure, or for searching through it for a certain
piece of data.
Variables in the action field are normally not expanded until actual
execution of the action. They can be forced to expand early by quoting
the opening curly brace with a backslash: \{
If a hyphen (-) is prepended to the structure name, the FOREACH loop
will try to iterate through an alias structure instead of a variable
structure. This is primarily useful for purging alias structures.
Examples:
Simple usage of FOREACH, assuming $blah is a structure two levels deep:
foreach blah xx {
foreach blah.${xx} yy {
echo $blah[$xx][$yy]
}
}
To purge an alias structure called booya:
foreach -booya xx {
alias -booya[$xx]
}
See Also:
fe(5); fec(5); until(5); while(5)
Restrictions:
Structures may be referenced as either $var.${subvar}.${subvar} or
$var[$subvar][$subvar] (with any number structure levels, of course).
The notation $var.$subvar.$subvar parses as $var[${subvar.$subvar}],
which of course is incorrect, and should not be used.
Other Notes:
The action portion does not necessarily need to do anything, though there
isn't much point in using the command without it.

28
bitchx-docs/5_Programming/hook Normal file
View File

@@ -0,0 +1,28 @@
Synopsis:
hook <anything>
Description:
HOOK is used for one thing only; to activate a HOOK hook. Don't worry
if that didn't make much sense. The client has a mechanism by which
an arbitrary hook may be defined that can be hooked at any time by
the HOOK command. The hook is created just like any other named
hook, except only the HOOK command may trigger it.
Examples:
This script will echo a line every 10 seconds:
on ^hook "foo" {
timer 10 {
echo This line is repeated every 10 seconds
hook foo
}
}
hook foo
See Also:
on(5) hook
Other Notes:
The same functionality of HOOK can be obtained with normal aliases.
However, use of HOOK is preferred as it avoids the need for recursive
aliases (which have been known to cause trouble).

97
bitchx-docs/5_Programming/if Normal file
View File

@@ -0,0 +1,97 @@
Synopsis:
if (<condition>) <then>
if (<condition>) { <then> } [{ <else> }]
if (<condition>) { <then> } elsif (<condition>) { <then> } else { <then> }
Description:
IF is the general purpose control statement for testing the truth/false
value of a given condition. If the condition is true, it performs
some action; if false, some alternate action. The condition does not
necessarily need to be a numeric comparison. It may be a function whose
return value is evaluated for truth or falsity, or compared against some
other value (which might also be a function return value). Expressions
are generally of the following forms:
( exp ) tests for existence of exp (usually a variable)
( !exp ) tests for non-existence of exp
( exp1 == exp2 ) tests whether exp1 equals exp2
( exp1 != exp2 ) tests whether exp1 does not equal exp2
( exp1 && exp2 ) tests for existence of exp1 and exp2
( exp1 || exp2 ) tests for existence of exp1 or exp2 or both
( exp1 ^^ exp2 ) tests for existence of exp1 or exp2, not both
( exp1 < exp2 ) tests whether exp1 is less than exp2
( exp1 > exp2 ) tests whether exp1 is more than exp2
( exp1 <= exp2 ) tests whether exp1 is less than or equal to exp2
( exp1 >= exp2 ) tests whether exp1 is more than or equal to exp2
The "else" portion of an IF statement is not required. Additionally,
if the "then" portion is only a single statement, the curly braces are
not required either. The expression (exp) is evaluated as though it
were within a ${} construct, such that
if ( blah ) ...
would expand "blah" to $blah, then test the value of $blah. Variables
can also be placed inside the expression parser, such that
if ( [$blah] ) ...
is equivalent to the previous statement (though it isn't as efficient).
Both forms may be combined in the same expression. Numbers are treated
as constants, so in order to expand numeric expandos, such as $0, you
must use the expression parser, as above. Strings must also be passed
through the expression parser (otherwise they are interpreted as
variables), and are compared case-insensitively.
As in C, assignment operators may be used inside IF statements. This is
generally not recommended, if only because it can make the code rather
confusing, but there are times when it can prove to be useful. The
following:
if ( foo = 3 > bar ) ...
would first set the value of $foo to 3, and then compare it with $bar.
Note that the @ operator is not needed (and in fact is not even allowed).
Gratuitous use of parenthesis is recommended with this notation.
Finally, as with other ircII-EPIC control statements, the curly braces
may be placed anywhere.
Examples:
The following two statements are functionally equivalent:
if ( foo == bar ) echo foo and bar are the same
if ( foo == bar ) {
echo foo and bar are the same
}
These are also equivalent:
if ( !foo ) ...
unless ( foo ) ...
Braces are required for a multi-line then portion:
if ( foo == bar ) {
echo foo and bar are the same
echo that's so cool!
}
Like other control statements, IFs may be embedded:
if ( foo ) {
if ( bar ) {
echo foo and bar are the same
echo that's so cool!
}
}
Function return values can be evaluated too:
if ( rmatch(foobar *blah* *bar) ) {
echo it matched
}
Aliases:
UNLESS is the exact opposite of IF. It is essentially the same applying
the negation operator (!) to the entire IF condition.
Other Notes:
The "then" and "else" portions aren't required to contain anything. Use
of the negation operator and UNLESS obsolete this practice, however.

38
bitchx-docs/5_Programming/input Normal file
View File

@@ -0,0 +1,38 @@
Synopsis:
input "<prompt>" <command> [<arguments>]
input_char "<prompt>" <command> [<arguments>]
Description:
This command is primarily for use inside scripts. It allows the client
to present the user with a visible prompt for specific commands. This
can be used for interactive commands, for command confirmation, etc.
Multiple commands may be specified if surrounded with curly braces.
The variant INPUT_CHAR words the same as INPUT, except it only takes a
single character. The primary difference is that it does not require
that a carriage return be entered before executing the command; the first
keystroke will trigger it.
Options:
-noecho stops the echoing of characters as they are typed
Examples:
To let a command ask for confirmation:
input "Are you REALLY sure you want to do this? (y/n) " {
if ( [$0] == [y] ) exec rm -rf *
}
The basis for a simple paging mechanism:
input_char "Press 'q' to quit, any other key to continue: " {
unless ( [$0] == [q] ) {
/* do whatever */
}
}
Aliases:
These commands are functionally equivalent to the $"..." expando. In
truth, they supersedes $"...".
See Also:
Special_Vars(7)

42
bitchx-docs/5_Programming/load Normal file
View File

@@ -0,0 +1,42 @@
Synopsis:
load [-args] <file> [<file> ...]
Description:
LOAD allows for commands contained in external files to be executed.
This has the obvious use of setting up aliases and hooks without having
to type each one in individually. The .ircrc file, for example, it
automatically loaded when the client is started (assuming the -q switch
isn't used).
When attempting to load a script, the client will first search the
directories in the LOAD_PATH for the desired file. The client will
also accept an absolute pathname.
The syntax of an ircII-EPIC script file is rather relaxed. It mostly
resembles C code, aesthetically. As with C, whitespace is usually not
significant, except in literal text. Curly braces used for complex
commands may be placed anywhere.
As with the input line, commands issued directly in a loaded script
are, by default, not evaluated. This means that aliases and functions
will not be expanded, and semicolons are not honored. This can be
overridden script-wide with the -args switch, or by turning the
INPUT_ALIASES setting on inside the script. EVAL should be used if
only select lines need to be evaluated.
If the filename ends in a .tcl extension, the file is automatically
passed to the tcl interpreter if possible.
Options:
-args This switch causes the script to be loaded with INPUT_ALIASES
turned on. In addition, commands may use the special numeric
expandos ($*, $2, etc.), which will expand to the arguments
passed to LOAD.
See Also:
cd(4); set(4) input_aliases, load_path; stub(5); which(4); which(8)
Other Notes:
A large collection of sample scripts is included with the client. Refer
to Section 8, the Script Library, for more information.

6
bitchx-docs/5_Programming/loaddll Normal file
View File

@@ -0,0 +1,6 @@
Synopsis:
loaddll <file>
Description:
LOADDLL loads various plugins which have been written for BitchX. These
plugins add various functionality to the client.

8
bitchx-docs/5_Programming/loadtcl Normal file
View File

@@ -0,0 +1,8 @@
Synopsis:
loadtcl <file>
Description:
LOADTCL allows for commands contained in external files to be executed.
In this case the files contain TCL commands which you want to have
executed or loaded in the client.

23
bitchx-docs/5_Programming/local Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
local [[-]<variable name>[,<variable name>] [<value>]]
Description:
LOCAL creates "local" variables. Local variables are the same as assign(6)
variables, except they're primarily for inside one specific alias. Local
variables cannot be removed. There are several reasons for this, which are
mostly advantages for scripts. A local variable is specific to the alias it
was defined in, causing less confusion with multiple variables in multiple
aliases. They are less cpu-intensive, making them optimal for recursive
functions like for(5). Arrays may also be defined with local.
Examples:
To give the local variable $blah a value of "this is a test":
local blah this is a test
To give both $blah and $foo a value:
local blah,foo local vars are neat
See Also:
Expressions(7); Special_Vars(7); alias(5); assign(5); eval(5);
set(4) input_aliases

11
bitchx-docs/5_Programming/menu Normal file
View File

@@ -0,0 +1,11 @@
Synopsis:
menu (-)<menu name>
Description:
MENU Creates a new menu with the given menu name. Or if "-" is
specified immediately before the menu name, any menu with that name
is removed.
See Also:
menuitem(5) submenu(5); popupmenu(5)

21
bitchx-docs/5_Programming/menuitem Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
menuitem <menu name> <options> <optional refnum> "Menu Text" { code }
Description:
MENUITEM Appends a menuitem to the end of the specified menu.
The possible options are:
-f = framed (PM only - draws a thin line around the text)
-s = static (unselectable)
-d = default (PM only - conditional cascade menus)
-b = break (starts a new vertical line)
The optional refnum is used for setting checks on menuitems.
The menu text is what shows up on the menu. If you put "separator"
instead of menu text a horizontal break will be created. Place
a ~ before a character in the menu text to make an accellerator out
of that key. (i.e. ALT-character will select that menu item)
Code is a code fragment to be executed when this menu item
is selected.
See Also:
menu(5) submenu(5) popupmenu(5)

25
bitchx-docs/5_Programming/on/action Normal file
View File

@@ -0,0 +1,25 @@
Synopsis:
on [<modes>]action [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes a CTCP ACTION. It
will hook when the recipient is either the user or a channel.
Parameters:
$0 nickname of the ACTION sender
$1 target of the ACTION (user's nickname or a channel)
$2- message body of the ACTION
Examples:
To distinguish personal actions from those sent to a channel:
on ^action "*" {
switch ( $1 ) {
( $N ) { echo *> $0 $2- }
( $C ) { echo * $0 $2- }
( * ) { echo * $0/$1 $2- }
}
}
See Also:
ctcp(1) action; describe(1); me(1); on(5) send_action

39
bitchx-docs/5_Programming/on/channel_nick Normal file
View File

@@ -0,0 +1,39 @@
Synopsis:
on [<modes>]channel_nick [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever anyone on a channel common to the client
changes nicknames. It is triggered for any nickname change, including
the client's.
Parameters:
$0 the channel on which the nick change was observed
$1 the person's old nickname
$2 the person's new nickname
Examples:
To make a distinction between the client changing nicks and other people:
on ^channel_nick "*" {
if ( [$0] == C ) {
if ( [$1] == N ) {
echo *** You have changed nicks to $2
} {
echo *** $1 has changed nicks to $2
}
} {
if ( [$1] == N ) {
echo *** You have changed nicks to $2 on $0
} {
echo *** $1 has changed nicks to $2 on $0
}
}
}
See Also:
nick(1); on(5) nickname
Other Notes:
This hook differs from the NICKNAME hook in that it is triggered once per
nick change per channel, whereas NICKNAME is only triggered once per nick
change.

30
bitchx-docs/5_Programming/on/channel_signoff Normal file
View File

@@ -0,0 +1,30 @@
Synopsis:
on [<modes>]channel_signoff [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes someone signoff from
irc. It is not hooked when the client itself signs off.
Parameters:
$0 the channel the signoff was observed on
$1 the nickname of the person leaving irc
$2- signoff message
Examples:
To distinguish signoffs from one channel to another:
on ^channel_nick "*" {
if ( [$0] == C ) {
echo *** Signoff by $1 \($2-\)
} {
echo *** Signoff by $1 from $0 \($2-\)
}
}
See Also:
on(5) quit, signoff; quit(1)
Other Notes:
This hook is not triggered by the client exiting irc. Use the QUIT hook
to perform an action when the client quits. This hook differs from the
SIGNOFF hook in that this is triggered for every channel on which the
person is observed signing off.

21
bitchx-docs/5_Programming/on/connect Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
on [<modes>]connect [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client establishes a connection with
a server.
Parameters:
$0 the server connected to
$1 the port number of the server connected to
$2 server name as reported by the server
Examples:
To display where the client has connected:
on ^connect "*" {
echo *** Connected to $0 ($2) on port $1
}
See Also:
server(1)

38
bitchx-docs/5_Programming/on/ctcp Normal file
View File

@@ -0,0 +1,38 @@
Synopsis:
on [<modes>]ctcp [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a CTCP message,
whether directly or one sent to a channel it is on.
Parameters:
$0 nickname of CTCP message sender
$1 target of CTCP (client's nickname or channel name)
$2 type of CTCP
$3- arguments to CTCP command, if any
Examples:
To customize the normal CTCP message:
on ^ctcp * "*" {
if ( [$1] == C ) {
echo *** $0 sent a CTCP $2 to $1${[$3] ? [: $3-] : []}
} {
echo *** $0 sent you a CTCP $2${[$3] ? [: $3-] : []}
}
}
See Also:
ctcp(1); on(5) ctcp_reply
Restrictions:
Automatic replies from within this hook are limited by the irc protocol.
Since a CTCP is really just a PRIVMSG, the client may only automatically
reply with NOTICEs, not MSGs. Any attempt to send a MSG or CTCP from
within this hook will result in it automatically being converted to a
NOTICE (or CTCP REPLY).
Other Notes:
The client's default behavior of automatically responding to certain CTCP
messages cannot be suppressed with this hook. To prevent the client from
replying to CTCPs, use IGNORE.

34
bitchx-docs/5_Programming/on/ctcp_reply Normal file
View File

@@ -0,0 +1,34 @@
Synopsis:
on [<modes>]ctcp_reply [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a CTCP reply from
another client. Note that the client doesn't necessarily need to send
any CTCP messages to receive a "reply".
Parameters:
$0 nickname of user sending reply
$1 CTCP command being replied to
$2- actual reply to CTCP command (varies, depends on $1)
Examples:
To customize the appearance of CTCP reply strings:
on ^ctcp_reply "*" {
echo *** Reply from $0 for CTCP $1 request: $2-
}
See Also:
ctcp(1); on(5) ctcp
Restrictions:
Automatic replies (MSGs, CTCPs, NOTICEs, etc.) to the sender with this
hook are explicitly prohibited. The protocol disallows it, and the
client will do everything in its power to prevent it. Any attempt will
result in an error message.
Bugs:
There is no way (from within this hook) to know who the actual target
of the reply is. This could be a problem, since it is trivial to send
bogus replies, and there is no way to tell if the client, or a channel,
was the target.

19
bitchx-docs/5_Programming/on/dcc_chat Normal file
View File

@@ -0,0 +1,19 @@
Synopsis:
on [<modes>]dcc_chat [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a message across a
DCC CHAT connection.
Parameters:
$0 nickname of the message sender
$1- message received
See Also:
dcc(1) chat; msg(1); on(5) send_dcc_chat
Other Notes:
DCC falls outside of the irc protocol, and as such there are no
restrictions on automated replies. This creates the potential for
uncontrolled looping, so caution is advised.

33
bitchx-docs/5_Programming/on/dcc_connect Normal file
View File

@@ -0,0 +1,33 @@
Synopsis:
on [<modes>]dcc_connect [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client successfully establishes a
DCC connection with another client. Currently, this is either a CHAT
or a SEND connection.
Parameters:
$0 nickname of remote client
$1 type of DCC connection
$2 ip address of remote client
$3 port on the ip address the client is connected to
$4 file name (SEND only)
$5 file size (SEND only)
Examples:
To customize the connection message:
on ^dcc_connect "*" {
echo *** DCC $1 connection with $0[$2:$3] established
if ( [$1] == [send] ) echo *** Transferring $4 \($5 bytes\)
}
See Also:
dcc(1); on(5) dcc_lost, dcc_request
Other Notes:
Note that establishing a DCC connection does not involve the irc network.
Thus, the $userhost() function will not work inside this hook.
For a DCC SEND connection, this will be hooked twice. Once with $1 being
SEND, and again being GET. This is for compatibility with bitchx.

27
bitchx-docs/5_Programming/on/dcc_list Normal file
View File

@@ -0,0 +1,27 @@
Synopsis:
on [<modes>]dcc_list [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a /dcc or /dcc list command is issued.
The 'banner' of the list can be determined when $0 is "Start", and the
end of the list is determined when $0 is "end".
Parameters:
$0 - The type of DCC connection
$1 - "1" if encryption is on, "0" if its not (future exp)
$2 - Nickname of the peer
$3 - Status of connection
$4 - $time() when connection established, 0 if not connected.
$5 - Size of the file transfer, 0 if not applicable
$6 - Number of bytes transfered, 0 if not connected
$7 - Description field (usually the full filename)
Examples:
To display some extra info about dcc:
on -dcc_list "*" {
if (([$6]/[$5]*100)>90) { echo File $7 from $2 is almost done! }
}
See Also:
dcc(1)

21
bitchx-docs/5_Programming/on/dcc_lost Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
on [<modes>]dcc_lost [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a DCC CHAT or SEND connection is lost.
In the case of SEND, it is triggered only when a connection is lost
before the file transfer is complete.
Parameters:
$0 nickname of the dcc connection
$1- disconnection message (varies)
Examples:
To indicate that dcc connection was terminated:
on ^dcc_lost "*" {
echo *** DCC connection with $0 lost${[$1] ? [: $1-] : []
}
See Also:
dcc(1)

23
bitchx-docs/5_Programming/on/dcc_offer Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
on [<modes>]dcc_offer [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client offers an outbound DCC. This
could be either a DCC CHAT or a file transfer.
Parameters:
$0 person who is being offered the DCC
$1 type of DCC being offered
$2 filename being offered (if type of DCC is 'SEND')
$3- size of file being offered (if type of DCC is 'SEND')
Examples:
To alert user of bad DCC's:
on ^dcc_offer "#*" {
echo *** Offering a DCC to an entire channel will not work as
echo expected. Please direct DCC offers to one person.
}
See Also:
dcc(1)

32
bitchx-docs/5_Programming/on/dcc_raw Normal file
View File

@@ -0,0 +1,32 @@
Synopsis:
on [<modes>]dcc_raw [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a raw message about
a tcp connection established, or a connection attempt, with $connect().
Raw messages are sent across established tcp connections with DCC RAW.
Scripts that use sockets should always set a non-zero serial number for
it. Otherwise, it is very easy to set confusing or conflicting hooks.
Each specific instance of a socket application should use a separate
serial number, to prevent conflicts.
Parameters:
$0 file descriptor for connection (returned by $connect())
$1 host connected to (hostname or ip address)
$2 code for connection type:
c - socket was closed
d - incoming data
e - issued when $connect() returns successfully
n - connection accepted on a port the client is listening to
$3- data for type 'd', port number for types 'e' and 'n', none for 'c'
Examples:
To display all successful socket connections:
on #-dcc_raw 10 "% % e %" {
echo *** Connection with $1 on port $3 \(fd: $0\)
}
See Also:
connect(6); dcc(1) raw; listen(6)

26
bitchx-docs/5_Programming/on/dcc_request Normal file
View File

@@ -0,0 +1,26 @@
Synopsis:
on [<modes>]dcc_request [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a DCC request of some
sort (currently CHAT or SEND).
Parameters:
$0 nickname of remote client
$1 type of DCC connection
$2 description of dcc connection (currently same as $1)
$3 ip address of remote client
$4 port on the ip address the client is connected to
$5 file name (SEND only)
$6 file size (SEND only)
Examples:
To customize the dcc request message:
on ^dcc_request "*" {
echo *** DCC $1 requested by $0!$userhost() [$3:$4]
if ( [$1] == [send] ) echo *** File offered: $4 \($5 bytes\)
}
See Also:
dcc(1) chat, send; on(5) dcc_connect, dcc_lost

23
bitchx-docs/5_Programming/on/disconnect Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
on [<modes>]disconnect [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the ckient is disconnected from a server,
and it is unable to reconnect to the server itself (assuming the
AUTO_RECONNECT setting is turned on). This would be any situation in
which the client would normally print the following message:
*** Use /SERVER to connect to a server
Parameters:
$0 server disconnected from
Examples:
To customize the disconnection message:
on ^disconnect "*" {
echo *** Disconnected from $0 at $Z
}
See Also:
disconnect(1); set(5) auto_reconnect

29
bitchx-docs/5_Programming/on/encrypted_notice Normal file
View File

@@ -0,0 +1,29 @@
Synopsis:
on [<modes>]encrypted_notice [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a NOTICE encrypted
with CTCP SED. This is how the ENCRYPT command normally works.
Parameters:
$0 nickname of message sender
$1- message received
Examples:
To clearly distinguish encrypted NOTICEs from unencrypted ones:
on ^encrypted_notice '% $N *' {
echo -${[$0]}- [ENCRYPTED] $1-
}
See Also:
encrypt(4); notice(1); on(5) encrypted_privmsg, notice
Restrictions:
This hook is subject to the same protocol restrictions as the NOTICE
hook.
Other Notes:
When used with the silent or quiet modes, this hook will suppress the
normal output for NOTICEs. Care should be used, as it can jumble
public hooks.

29
bitchx-docs/5_Programming/on/encrypted_privmsg Normal file
View File

@@ -0,0 +1,29 @@
Synopsis:
on [<modes>]encrypted_privmsg [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a MSG encrypted with
CTCP SED. This is how the ENCRYPT command normally works.
Parameters:
$0 nickname of message sender
$1- message received
Examples:
To clearly distinguish encrypted MSGs from unencrypted ones:
on ^encrypted_privmsg '% $N *' {
echo *$0* V[CRYPT]V $2-
}
See Also:
encrypt(4); msg(1); on(5) encrypted_notice, msg
Restrictions:
This hook is subject to the same protocol restrictions as the MSG
hook.
Other Notes:
When used with the silent or quiet modes, this hook will suppress the
normal output for MSGs. Care should be used, as it can also jumble
public hooks.

22
bitchx-docs/5_Programming/on/exec Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [<modes>]exec [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever an EXECed process generates output to
standard output.
Parameters:
$0 the pid of the EXECed process that triggered the hook (an internal
| number, not the system pid); if the process was started with the
| -name switch, the name specified is returned instead
$1- a line of the process's output stderr
Examples:
To distinguish process output from other window output:
on ^exec "*" {
echo [$0] $1-
}
See Also:
exec(5); on(5) exec_errors, exec_exit, exec_prompt

20
bitchx-docs/5_Programming/on/exec_errors Normal file
View File

@@ -0,0 +1,20 @@
Synopsis:
on [<modes>]exec_errors [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever an EXECed process produces output to
standard error.
Parameters:
$0 process number or name of the EXECed process
$1- a line of the process's output to stderr
Examples:
To distinguish process errors from other window output:
on ^exec_errors "*" {
echo [$0 ERR] $1-
}
See Also:
exec(5); on(5) exec, exec_exit, exec_prompt

28
bitchx-docs/5_Programming/on/exec_exit Normal file
View File

@@ -0,0 +1,28 @@
Synopsis:
on [<modes>]exec_exit [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever an EXECed process exits.
Parameters:
$0 process number or name of the EXECed process
$1 signal that killed the process, or 0 (zero) if it exited normally
$2 exit code (usually zero, unless $1 is non-zero)
Examples:
To display when a process exits:
on ^exec_exit "*" {
if ( [$2] ) {
echo *** Process '$0' exited with code $2 \(signal $1\)
} {
echo *** Process '$0' exited normally
}
}
See Also:
exec(5); on(5) exec, exec_errors, exec_prompt
Other Notes:
The available signals that may be sent to a process will vary from system
to system.

25
bitchx-docs/5_Programming/on/exec_prompt Normal file
View File

@@ -0,0 +1,25 @@
Synopsis:
on [<modes>]exec_prompt [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever an EXECed process displays a "prompt".
More precisely, it is triggered when the process returns any line of
output that is not terminated by a newline. This is generally the case
with interactive commands, such as nslookup(1).
Parameters:
$0 process number of name of the EXECed process
$1 prompt string to look for
Examples:
To hook the prompt when using nslookup interactively:
on ^exec_prompt "% >" {
assign foo $0
input "nslookup> " {
msg %${foo} $*
}
}
See Also:
exec(5); input(5); on(5) exec, exec_errors, exec_exit

23
bitchx-docs/5_Programming/on/exit Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
on [<modes>]exit [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered when the client is about to exit normally (from
the QUIT command, etc.). It is mostly useful for doing cleanup before
exiting, such as saving any current settings. It cannot be used to
trap the QUIT command; the client will exit immediately after this
hook is triggered..
Parameters:
$0 always the string "Exiting"
Examples:
Save current settings before exiting:
on ^exit "*" {
save all
echo Now exiting ircII-${J}...
}
See Also:
exec(5); quit(1)

34
bitchx-docs/5_Programming/on/flood Normal file
View File

@@ -0,0 +1,34 @@
Synopsis:
on [<modes>]flood [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client's internal flood detection
code is activated. The client is "flooded" when it receives a large
number of messages (of any sort) in a relatively short period of time.
Parameters:
$0 nickname of the flooder
$1 type of flood detected
$2 the channel (if any) they're flooding
$3- content of the flood message
Examples:
To automatically ignore flooders:
on ^flood "*" {
echo *** $1 flooding detected by $0
ignore $0 $1
}
To disable flood protection for network services:
on flood ^'\\[X W NickServ ChanServ\\] *'
See Also:
set(4) flood_after, flood_rate, flood_users, flood_warning
Other Notes:
It isn't uncommon for network problems to cause a great deal of data to
be sent to the client at once by the server. Suspending the client for
awhile and then bringing it back can produce similar results. Thus, it
it recommended that KICK or KILL be avoided as automated responses to
possible flooding.

19
bitchx-docs/5_Programming/on/help Normal file
View File

@@ -0,0 +1,19 @@
Synopsis:
on [<modes>]help [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered for each line of output generated by the HELP
command.
Parameters:
$0- a line of text from a helpfile
Examples:
Customizing the HELP output:
on ^help "*" {
echo *?* $*
}
See Also:
help(1)

11
bitchx-docs/5_Programming/on/hook Normal file
View File

@@ -0,0 +1,11 @@
Synopsis:
on [<modes>]hook [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the HOOK command is issued with the
appropriate arguments. Its sole purpose is to be hooked by HOOK. It
is useful for avoiding alias recursion.
Parameters:
$0- text to hook

22
bitchx-docs/5_Programming/on/idle Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [<modes>]idle [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client's idle time reaches the given
value, in minutes. The idle time is reset when the client is given a
command.
Parameters:
$0 minutes idle
Examples:
To automatically set the client away after being idle for 5 minutes:
on ^idle "5" {
away I'm not paying attention again...
}
Other Notes:
Irc servers don't have the same notion of "idle" as the client does. To
most servers, the client only becomes unidle by sending a message to a
channel or a person.

27
bitchx-docs/5_Programming/on/input Normal file
View File

@@ -0,0 +1,27 @@
Synopsis:
on [<modes>]input [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a command is entered on the input line,
or when text is sent to a channel or query.
This is a very powerful mechanism of the client. Used intelligently,
it permits a very fine degree of control over the text entered on the
input line. Used carelessly, and it can easily disable the client.
Use with caution.
If a silent hook is set, one can use a loaded script to do preprocessing
of the input line.
Parameters:
$0- text of input line entered
Examples:
To emulate the INPUT_ALIASES setting:
on ^input "*" {
eval $*
}
See Also:
set(4) input_protection

20
bitchx-docs/5_Programming/on/invite Normal file
View File

@@ -0,0 +1,20 @@
Synopsis:
on [<modes>]invite [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives an invitation to a
channel.
Parameters:
$0 nickname inviting the client to a channel
$1 channel invited to
Examples:
Customizing the appearance of the invitation:
on ^invite "*" {
echo *** $0 cordially invites you to $1
}
See Also:
invite(1)

27
bitchx-docs/5_Programming/on/join Normal file
View File

@@ -0,0 +1,27 @@
Synopsis:
on [<modes>]join [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client joins a channel, or whenever
it observes another client joining a common channel.
Parameters:
$0 nickname of person joining channel
$1 channel joined
$2 address of person joining channel (same as $userhost())
$3 person joining's channel status (on avalon 2.9 servers),
could be either (+o) or (+v)
Examples:
To distinguish between the client and other users joining the channel:
on ^join "*" {
if ( [$0] == N ) {
echo *** You have joined channel $1
} {
echo *** $0 \($2\) has joined channel $1
}
}
See Also:
join(1); userhost(6)

26
bitchx-docs/5_Programming/on/kick Normal file
View File

@@ -0,0 +1,26 @@
Synopsis:
on [<modes>]kick [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes another client (or
itself!) being kicked from a channel.
Parameters:
$0 nickname of user kicked from channel
$1 nickname of user kicking $0 from channel
$2 channel kick observed on
$3- kick message
Examples:
To distinguish who is being kicked on a channel:
on ^kick "*" {
if ( [$0] == N ) {
echo *** You have been kicked from $2 by $1 \($3-\)
} {
echo *** $0 has been kicked from $2 by $1 \($3-\)
}
}
See Also:
kick(1)

22
bitchx-docs/5_Programming/on/kill Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [<modes>]kill [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever someone is kill(3)ed by an oper.
Parameters:
$0 server who sent the message (your server)
$1 the victim being killed
$2 the oper who issued the kill
$3 server path to the oper
$4- reason for the kill
Examples:
To display kills in a more sane manner:
on ^kill "*" {
echo $banner $1 was killed by $2: ($4-)
}
See Also:
kill(3)

24
bitchx-docs/5_Programming/on/leave Normal file
View File

@@ -0,0 +1,24 @@
Synopsis:
on [<modes>]leave [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a client (the user's or any other) is
observed leaving a channel (but not signing off from irc).
Parameters:
$0 the nickname of the person leaving the channel
$1 the channel left by the person
Examples:
To distinguish the client from other users leaving a channel:
on ^leave "*" {
if ( [$0] == N ) {
echo *** You have left channel $1
} {
echo *** $0 \($userhost()\) has left channel $1
}
}
See Also:
part(1); userhost(6)

21
bitchx-docs/5_Programming/on/list Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
on [<modes>]list [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives server output from
the LIST command. Any individual line of output can trigger the hook.
Parameters:
$0 channel name
$1 number of users on the channel
$2- channel topic (if any)
Examples:
To limit output to channels with a topic:
on ^list "*" {
if ( [$2] ) echo *** $[$CHANNEL_NAME_WIDTH]0 $[-2]1 $2-
}
See Also:
list(2); on(5) widelist

24
bitchx-docs/5_Programming/on/mail Normal file
View File

@@ -0,0 +1,24 @@
Synopsis:
on [<modes>]mail [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client detects that the user has new
email locally. It relies on MAIL being non-zero.
Parameters:
$0 number of new email messages
$1 total number of email messages in user's mailbox
Examples:
To keep the new mail message grammatically correct:
on ^mail "*" {
echo *** You have $0 new message${[$0] > 1 ? [s] : []}, $1 total
}
See Also:
set(4) mail
Other Notes:
This hook has no control over the extended output given when MAIL is set
to 2.

26
bitchx-docs/5_Programming/on/mode Normal file
View File

@@ -0,0 +1,26 @@
Synopsis:
on [<modes>]mode [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes a mode change on a
channel, or whenever the client changes its modes.
Parameters:
$0 nickname of person issuing mode change
$1 channel or nickname affected by mode change
$2 modes changed
$3- arguments to modes (if any)
Examples:
To distinguish between user modes and channel modes:
on ^mode "*" {
if ( [$1] == N ) {
echo *** User mode change for $1: $2-
} {
echo *** Mode change for $1 by $0: $2-
}
}
See Also:
mode(1); on(5) mode_stripped

22
bitchx-docs/5_Programming/on/mode_stripped Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [#][<mode>]mode_stripped [<serial#>] [-|^]<match> { <action> }
Description:
This hook is similar to the MODE hook, except it only hooks a single
mode change at a time. This hook relies on MODE_STRIPPER being turned
on. It is mostly useful in scripts that wish to evaluate each
individual mode change.
Parameters:
$0 nickname of person issuing mode change
$1 channel or nickname affected by mode change
$2 mode changed
$3 argument to the mode (does not apply to all modes)
See Also:
mode(1); on(5) mode; set(4) mode_stripper
Other Notes:
This hook does not override the MODE hook; rather, they compliment each
other.

20
bitchx-docs/5_Programming/on/msg Normal file
View File

@@ -0,0 +1,20 @@
Synopsis:
on [<modes>]msg [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a MSG from another
client.
Parameters:
$0 nickname of message sender
$1- text of message
See Also:
msg(1); on(5) encrypted_privmsg, notice, send_msg
Restrictions:
The client does not permit automated responses to a MSG with another MSG.
Such replies may use NOTICE instead. Any attempt to use MSG within this
hook will be automatically converted to a NOTICE. The whole point of
this is to prevent loops between clients.

19
bitchx-docs/5_Programming/on/msg_group Normal file
View File

@@ -0,0 +1,19 @@
Synopsis:
on [<modes>]msg_group [<serial#>] [-|^]<match> { <action> }
Description:
This hook is similar to the MSG hook, except it applies to messages sent
to an undetermined group of people. Typically, this is a server mask or
hostmask, and is sent by an irc operator.
Parameters:
$0 nickname of message sender
$1 group message was sent to
$2- text of message
See Also:
msg(1)
Restrictions:
This hook has the same limitations on automated replies as the MSG hook.

18
bitchx-docs/5_Programming/on/names Normal file
View File

@@ -0,0 +1,18 @@
Synopsis:
on [<modes>]names [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives server output from
the NAMES command.
Parameters:
$0 channel name
$1- nicknames of (visible) users on the channel
See Also:
names(2); on(5) 353, 366
Other Notes:
This hook is not triggered by the implicit NAMES done when the client
joins a channel. Hook the 353 numeric instead.

24
bitchx-docs/5_Programming/on/nickname Normal file
View File

@@ -0,0 +1,24 @@
Synopsis:
on [<modes>]nickname [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes a nickname change.
It only hooks once per nick change, not once per channel.
Parameters:
$0 old nickname
$1 new nickname
Examples:
To distinguish the client from another user:
on ^nickname "*" {
if ( [$0] == N ) {
echo *** Your nickname is now $1
} {
echo *** $0 has changed nicks to $1
}
}
See Also:
nick(1); on(5) channel_nick

20
bitchx-docs/5_Programming/on/note Normal file
View File

@@ -0,0 +1,20 @@
Synopsis:
on [<modes>]note [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a NOTE.
Parameters:
$0 nickname of message sender
$1 time the message was send (accurate +/- 60 seconds)
$2- text of message
Examples:
To customize the display of irc NOTEs:
on ^note "*" {
echo V%$0%V $2- \($1\)
}
See Also:
note(4)

19
bitchx-docs/5_Programming/on/notice Normal file
View File

@@ -0,0 +1,19 @@
Synopsis:
on [<modes>]notice [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a NOTICE from another
client.
Parameters:
$0 nickname of message sender
$1- text of message
See Also:
notice(1); on(5) encrypted_notice, msg, send_notice
Restrictions:
The client does not permit any automated messages to be sent in response
to a NOTICE. Any attempt will result in an error. The whole point of
this is to prevent loops between clients.

13
bitchx-docs/5_Programming/on/notify_signoff Normal file
View File

@@ -0,0 +1,13 @@
Synopsis:
on [<modes>]notify_signoff [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client detects that a nickname on its
internal NOTIFY list has signed off from irc.
Parameters:
$0 nickname that signoff was detected for
See Also:
notify(1); on(5) notify_signon

15
bitchx-docs/5_Programming/on/notify_signon Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]notify_signon [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client detects that a nickname on its
internal NOTIFY list has signed on to irc.
Parameters:
$0 nickname that signon was detected for
$1 user@host of person signing on (if set(4) notify_userhost_automatic
is ON)
See Also:
notify(1); set(4) notify_userhost_automatic; on(5) notify_signoff

17
bitchx-docs/5_Programming/on/odd_server_stuff Normal file
View File

@@ -0,0 +1,17 @@
Synopsis:
on [<modes>]odd_server_stuff [<serial#>] [-|^]<match> { <action> }
Description:
This is easily the most flexible hook available in the client. It allows
any arbitrary string to be hooked from the server's raw output. It is
useful for overriding the client's default behavior when it otherwise
wouldn't permit it, or for hooking information when the available named
hooks won't do.
Parameters:
$0 server that sent it, '*' if unknown
$1- unrecognized command and its arguments
See Also:
quote(5) on(5) raw_irc

129
bitchx-docs/5_Programming/on/on Normal file
View File

@@ -0,0 +1,129 @@
Synopsis:
on [<modes>]<hook> [<serial#>] [-|^]<match> [{ <action> }]
Description:
The ON command is what truly gives ircII-EPIC its versatility. It sets
a hook that allows any arbitrary type of message be acted upon. This
allows for a high degree of automation with the client, as well as a
high degree of customization.
Each hook can have a set of modes associated with it. There are 6
(six) types of modes, and each one has a specific, unique purpose. The
hook name is prefixed with these modes. The first 3 (three) control
the output of the hook.
+ The noisy mode. This causes the client to display everything
| the hook is doing. It will display what event has been hooked,
| and by what specific data. This mode is really only useful for
| script debugging.
- The quiet hook. This suppresses display of the gory details of
| the event hooked.
^ The silent mode. This works similarly to '-', except it will
| completely suppress the default output of the event. Only ECHO
| (and XECHO) will cause it to display anything. This is most
| often used to redefine how an event message looks.
? The ambiguous mode. This mode is special because the override level
| is not determined when the on is registered, but is determined
| separately each time the on is executed. When you use this noise
| level, the "noise" level is always the same as the SILENT level
| (as if you had used '^'), but it will not automatically suppress the
| client's default action as using '^' would. The action of the on is
| taken as an anonymous function: it may return a value with the
| /return command. If the return value of the action is 1 (one), then
| the default action WILL be suppressed (as though you had used ^),
| but if the return value is 0 (zero) then the default action will NOT
| be suppressed (as though you had used -).
Only one of the above three modes may be used per hook. If none are
used, the client defaults to a setting somewhere between noisy and quiet.
It will display what it has hooked, but nothing else unless specifically
coded to do so.
& The local mode. Hooks with this mode will only be triggered for
| events originating on the current server. If the event is not
| local, the client will fall back to other set hooks, or failing
| that, the default behavior.
@ The exclusively local hook. This is the same as '&', except the
| client will not fall back on other hooks if the event is not
| local.
Only one of the above two modes may be used per hook. The last mode
controls the order in which like hooks are triggered.
# The serial hook. This allows the given hook to be assigned a
| unique serial number (see Synopsis). Thus, if multiple hooks of
| the same type are defined, the order in which they are triggered
| can be defined. Refer to Serial_Numbers for more information.
Each of the above sets of modes may be combined with the others (though
only one from each set may be used per hook).
The text matched for the hook is also rather versatile. In the match
string, any wildcard may be used. The match must be surrounded by
quotation marks (unless it is a single word). If double quotes (") are
used, the match string is evaluated when the hook is defined. If single
quotes (') are used, the match string is taken literally and evaluated
each time the event is hooked. This allows for variable matches to be
used. Additionally, the match string may be prepended with its own
mode.
- This isn't really a mode, per se. Rather, it is used to remove
| any hook with the same match string. If no match string is
| given, all hooks for th given event are removed.
^ The exclusion mode. This causes the client to do nothing when
| the hook is triggered with the given match. It is effectively
| the same as only using a COMMENT in the action, or some other
| noop command.
The last part of a hook is the action. This defines what the client is
supposed to do when a hook is triggered. The action can be just about
anything the user wishes. The syntax works basically the same as with
ALIAS. Braces are only required for multiline actions. Also, as with
aliases, hook actions can receive and use numeric expandos (representing
the full event arguments hooked). Also a special "return next" in the
action will cause the next hook of the type to be executed or if it's the
last/only hook executing, the default action will run.
Also, if this command is given with either none or a single argument, it
will list all currently defined hooks matching the argument.
Examples:
To redefine the default JOIN message:
on ^join "*" {
echo B*>*B $0 \($2\) has joined $1 [$Z]
}
on ^channel_synch "#bitchx *" {
echo this and next hook will exec, but the default will not. $*
return next
}
on ^channel_synch "*" {echo 2 $*;return}
To show a special message (quietly) for local users joining a channel:
on -&join "*" {
echo B*>*B VLOCALV $0 \($2\) has joined $1 [$Z]
}
To suppress channel messages from users from certain sites:
assign ignore_em *@*.msn.com *@*.aol.com *@*.goodnet.com
on -join ^'% % $ignore_em'
To remove all hooks for a particular event:
on join -
To show an additional message for a certain site, after the default:
on #-join 10 "% #blah %" {
echo V***V Oh great, yet another person has joined $1
}
See Also:
Etiquette(7); Expressions(7); Programming(7); Serial_Numbers(7);
Server_Numerics(7); alias(5); echo(5); hook(5); xecho(5)
Other Notes:
ON allows for a great deal of automation of client activities. This can
be a bad thing if abused. For instance, using it to automatically send
a greeting to anyone joining a channel is usually considered bad form.
Let common sense dictate when an automated response is appropriate.

20
bitchx-docs/5_Programming/on/oper_notice Normal file
View File

@@ -0,0 +1,20 @@
Synopsis:
on [<modes>]oper_notice [<serial#>] [-|^]<match> { <action> }
Description:
This is triggered whenever a global oper notice is received.
Parameters:
$0 server the notice came from
$1- body of the message
Examples:
To alert the user of global oper notices:
on ^oper_notice "*" {
beep
echo --global notice-- $1-
}
See Also:
on(5) notice

23
bitchx-docs/5_Programming/on/pong Normal file
View File

@@ -0,0 +1,23 @@
Synopsis:
on [<modes>]pong [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a protocol PONG
message. Under normal circumstances, the sender will be a server.
However, clients are also allowed to send PONG messages to each other.
Since there is never any reason for a client to send a PONG to another
client, this hook can be useful for blocking PONG floods.
Parameters:
$0 nickname sending the PONG
$1- argument to PONG (usually the same as $0, but not necessarily)
Examples:
To filter PONG messages from other clients:
on ^pong "*" {
if ( rmatch($0 %.%) ) echo *** Received protocol PONG from $0: $1-
}
See Also:
quote(5)

15
bitchx-docs/5_Programming/on/public Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]public [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a regular public message is sent to the
client's current channel by someone else also on the channel.
Parameters:
$0 nickname sending message
$1 channel sent to
$2- text of message
See Also:
on(5) public_msg, public_notice, public_other, send_public; say(1)

25
bitchx-docs/5_Programming/on/public_msg Normal file
View File

@@ -0,0 +1,25 @@
Synopsis:
on [<mode>]public_msg [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a public message in
a channel from someone not actually in the channel.
Parameters:
$0 nickname sending message
$1 channel sent to
$2- text of message
Examples:
To customize how these messages are displayed:
on ^public_msg "*" {
if ( [$1] == C ) {
echo *** \($0\) $2-
} {
echo *** \($0:$1\) $2-
}
}
See Also:
on(5) public, public_notice, public_notice; msg(1)

25
bitchx-docs/5_Programming/on/public_notice Normal file
View File

@@ -0,0 +1,25 @@
Synopsis:
on [<modes>]public_notice [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a NOTICE is sent to any channel the
client is on from someone not actually on that channel.
Parameters:
$0 nickname sending message
$1 channel sent to
$2- text of message
Examples:
To distinguish NOTICEs sent to the current channel vs. other channels:
on ^public_notice "*" {
if ( [$1] == C ) {
echo +$0+ $2-
} {
echo +$0:$1+ $2-
}
}
See Also:
notice(1); on(5) notice

16
bitchx-docs/5_Programming/on/public_other Normal file
View File

@@ -0,0 +1,16 @@
Synopsis:
on [<modes>]public_other [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes a message sent to
any channel it is on that isn't its current channel, from someone else
on that channel.
Parameters:
$0 nickname sending message
$1 channel sent to
$2- text of message
See Also:
msg(1); on(5) public, public_msg, public_notice

18
bitchx-docs/5_Programming/on/raw_irc Normal file
View File

@@ -0,0 +1,18 @@
Synopsis:
on [<modes>]raw_irc [<serial#>] [-|^]<match> { <action> }
Description:
This is easily the most flexible hook available in the client. It allows
any arbitrary string to be hooked from the server's raw output. It is
useful for overriding the client's default behavior when it otherwise
wouldn't permit it, or for hooking information when the available named
hooks won't do.
Parameters:
$0 server sending message (usually the client's current server)
$1 protocol command used
$2- arguments, if any, to $1
See Also:
quote(5)

13
bitchx-docs/5_Programming/on/redirect Normal file
View File

@@ -0,0 +1,13 @@
Synopsis:
on [<modes>]redirect [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever something is /redirect'd.
Parameters:
$0 Target to which the text is about to be sent
$1- The actual text to be sent
See Also:
redirect(5)

24
bitchx-docs/5_Programming/on/send_action Normal file
View File

@@ -0,0 +1,24 @@
Synopsis:
on [<modes>]send_action [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a CTCP ACTION to a
channel or to another person.
Parameters:
$0 target of the ACTION (nickname or channel)
$1- text of message sent
Examples:
To display separate messages for public and private actions:
on ^send_action "*" {
if ( rmatch($0 #* &* +*) ) {
echo * $0: $N $1-
} {
echo *> $0: $N $1-
}
}
See Also:
ctcp(1) action; describe(1); me(1); on(5) action

22
bitchx-docs/5_Programming/on/send_ctcp Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [<modes>]send_ctcp [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a CTCP request or
reply to another client.
Parameters:
$0 "PRIVMSG" for requests, "NOTICE" for replies
$1 nick the CTCP is being sent to
$2 type of CTCP being sent
$3- optional arguments to the CTCP being sent
Examples:
To show the user when a CTCP request is sent:
on -send_ctcp "PRIVMSG *" {
echo *** Requesting a CTCP $2 from $1: $3-
}
See Also:
ctcp(1); on(5) send_msg

14
bitchx-docs/5_Programming/on/send_dcc_chat Normal file
View File

@@ -0,0 +1,14 @@
Synopsis:
on [<modes>]send_dcc_chat [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a message to another
client across a DCC CHAT connection.
Parameters:
$0 nickname of recipient of message sent
$1- text of message sent
See Also:
dcc(1) chat; msg(1); on(5) dcc_chat

15
bitchx-docs/5_Programming/on/send_msg Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]send_msg [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a MSG to another user.
It is only triggered when sending messages to individual clients, not
to channels.
Parameters:
$0 nickname message is sent to
$1- text of message sent
See Also:
msg(1); on(5) msg

14
bitchx-docs/5_Programming/on/send_notice Normal file
View File

@@ -0,0 +1,14 @@
Synopsis:
on [<modes>]send_notice [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a NOTICE message to a
channel or another client.
Parameters:
$0 nickname or channel the NOTICE is sent to
$1- text of message sent
See Also:
notice(1); on(5) notice

14
bitchx-docs/5_Programming/on/send_public Normal file
View File

@@ -0,0 +1,14 @@
Synopsis:
on [<modes>]send_public [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client sends a regular, public
message to any channel it is on.
Parameters:
$0 the channel the message is sent to
$1- text of message sent
See Also:
on(5) public; say(1)

30
bitchx-docs/5_Programming/on/send_to_server Normal file
View File

@@ -0,0 +1,30 @@
Synopsis:
on [<modes>]send_to_server [<serial#>] [-|^]<match> { <action> }
Description:
This hook, when set, is triggered whenever the client sends data to the
server that matches the hook. It is useful for catching raw messages
destined for the server and redefining them. One such use is with DCC,
as it offers no convenient way to send a raw request. By using the
silent mode, the default action (sending data to the server) is
suppressed, allowing any arbitrary command to be replaced.
When this hook is defined, it causes the client to monitor all traffic
to the server, making it somewhat resource intensive. It is recommended
that it be used sparingly. Caution should be used, as it is easy to
put the client into an infinite loop with this hook.
Parameters:
$0 reference number of the target server
$1 Unix file descriptor of the server connection
$2- text to be sent to the server
Examples:
To change how a DCC handshake is made (on the sending side):
on ^send_to_server "% % % PRIVMSG % :$chr(1)DCC*" {
quote PRIVMSG $4 :$chr(1)SECRET_DCC $6-
}
See Also:
fake-dcc(8); on(5) raw_irc; quote(5)

12
bitchx-docs/5_Programming/on/server_lost Normal file
View File

@@ -0,0 +1,12 @@
Synopsis:
on [<modes>]server_lost [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client is disconnected from any server
for any reason.
Parameters:
$0 server refnum
$1 server name
$2- reason for disconnect. usually the same as your QUIT(1) message

16
bitchx-docs/5_Programming/on/server_notice Normal file
View File

@@ -0,0 +1,16 @@
Synopsis:
on [<modes>]server_notice [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a server sends the client a NOTICE. This
is generally any message that does not have its own unique name or
numeric code, and usually begins with "***"..
Parameters:
$0 server sending the message
$1 first word of the actual message (usually "***")
$2- remainder of message
See Also:
notice(1)

27
bitchx-docs/5_Programming/on/set Normal file
View File

@@ -0,0 +1,27 @@
Synopsis:
on [<modes>]set [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever a /set is issued.
Parameters:
$0 name of variable to be set.
will be "set-error" if an invalid SET variable was specified
$1- value the variable will be set to.
will be "No such variable "FOO"", where FOO is the invalid SET
variable if $0 is "set-error"
Examples:
To make sure EXEC_PROTECTION stays on:
on ^set "exec_protection off" {
echo *** You cannot set EXEC_PROTECTION off!
set exec_protection on
}
To warn of all invalid /SET attempts:
on ^set "set-error *" {
echo *** $1-. Please try again
}
See Also:
set(4)

19
bitchx-docs/5_Programming/on/signoff Normal file
View File

@@ -0,0 +1,19 @@
Synopsis:
on [<modes>]signoff [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client observes another client on
a common channel signing off from irc. It only hooks once per user,
not once per channel.
Parameters:
$0 nickname of person signing off
$1- signoff message
See Also:
on(5) channel_signoff, exit; quit(1)
Other Notes:
This hook is only triggered for other users. To hook your own signoff,
use the EXIT hook.

14
bitchx-docs/5_Programming/on/silence Normal file
View File

@@ -0,0 +1,14 @@
Synopsis:
on [<modes>]silence [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a reply from the
server from a SILENCE command.
Parameters:
$0 a '+' if a pattern was added, '-' if one was removed
$1 the pattern silenced (or unsilenced)
See Also:
silence(1)

15
bitchx-docs/5_Programming/on/status_update Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]status_update [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the status bar of a visible window
**in dumb mode** is updated.
Parameters:
$0 Refnum of the window whose status bar was updated
$1 Which status bar has changed, 0 or 1
$2- The actual status bar that has been updated
See Also:
set(5) status_double; set(5) status_format.

24
bitchx-docs/5_Programming/on/timer Normal file
View File

@@ -0,0 +1,24 @@
Synopsis:
on [#][<mode>]timer [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the specified time (or time glob pattern)
matches the current time. The time may be in one of two formats:
Format Description 
hh:mm<am|pm> 0 <= hh <= 12, 0 <= mm <= 59, am or pm set accordingly
hh:mm 0 <= hh <= 23, 0 <= mm <= 59
Parameters:
$0 current time (format depends on CLOCK_24HOUR setting)
Examples:
To inform the user of the time once per hour on the hour:
on ^timer "%:00*" {
echo *** The time is not $Z
beep
}
See Also:
set(4) clock_24hour

15
bitchx-docs/5_Programming/on/topic Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]topic [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered when the topic is changed on any channel the
client is on.
Parameters:
$0 nickname of person changing topic
$1 channel topic was changed on
$2- new topic
See Also:
on(5) 331, 332; topic(1)

21
bitchx-docs/5_Programming/on/unload Normal file
View File

@@ -0,0 +1,21 @@
Synopsis:
on [<modes>]unload [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the unload(5) command is issued to unload
a packaged script.
Parameters:
$0- the parameters passed to the /package command
(NOTE that passing more than one argument to /package may cause
future incompatibilities, and should be avoided at all costs)
Examples:
To inform the user that a script is exiting:
on ^unload "superscript *" {
echo *** SuperScript exiting. To infinity, and lots farther!
}
See Also:
package(5); unload(5)

11
bitchx-docs/5_Programming/on/wall Normal file
View File

@@ -0,0 +1,11 @@
Synopsis:
on [#][<mode>]wall [<serial#>] [-|^]<match> { <action> }
Description:
This hook used to be triggered whenever the client received a WALL
message. WALL is no longer in use on any known irc network, and this
hook is but a relic of days long gone.
See Also:
on(5) wallop; wallops(3)

15
bitchx-docs/5_Programming/on/wallop Normal file
View File

@@ -0,0 +1,15 @@
Synopsis:
on [<modes>]wallop [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered whenever the client receives a WALLOPS message
(a message sent to all irc operators).
Parameters:
$0 nickname of the message sender
$1 a '+' if the sender is an operator, '-' if not, 'S' if a server
$2- text of message
See Also:
wallops(3)

22
bitchx-docs/5_Programming/on/who Normal file
View File

@@ -0,0 +1,22 @@
Synopsis:
on [#][<mode>]who [<serial#>] [-|^]<match> { <action> }
Description:
This hook is triggered when the client receives server output from the
WHO command. Each line received can trigger the hook.
Parameters:
$0 channel the user is on, of '*' if none or if it is private
$1 nickname of user
$2 status of user: <G|H>[*][@|+]
| 'G' for gone (away), 'H' for here (not away), '*' for irc
| operator, '@' for channel operator, '+' for voice status
$3 username portion of user's address
$4 hostname portion of user's address
$5 user's server
$6 server hopcount from user
$7- user's IRCNAME
See Also:
who(2)

Some files were not shown because too many files have changed in this diff Show More