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

9
bitchx-docs/7_Docs/7_Docs Normal file
View File

@@ -0,0 +1,9 @@
Section 7: Other Documentation 
This section is for general information about BitchX, and about irc. Most of
the documents contained herein describe a particular feature of the client
that may not be immediately obvious from the commands alone. Others are
aimed expressly at new users, to help out when they're just getting started.
The major portion of the documentation was taken from the epic projects help
files, which was then modified for BitchX specifically.

60
bitchx-docs/7_Docs/About_BitchX Normal file
View File

@@ -0,0 +1,60 @@
BitchX is the Enhanced Programmable (I)RC-II (C)lient. 
BitchX is about 90% backwards compatible with ircII and close too 99%
compatible with EPIC because BitchX is based on epic. BitchX
was originally built upon the ircII 2.8 client, until the epic client was
able to run phoenix.irc. At which time I switched the BitchX codebase from
ircII to an epic base.
BitchX is quite abit larger than ircII/epic, but that is mostly because of
the multitude of new features and the large amount of re-written code in an
attempt to make ircII faster, more efficient, and more powerful as well as
have color and a semi functional client right out of the box WITHOUt scripts
of any sort.
BitchX is derived directly from EPIC which is derived from IRC-II which is
currently maintained by Matthew Green, and includes in whole all the
additions included in the "plus" clients by Jeremy Nelson and all of the
modifications in the "mod" clients by Jake Khuon. BitchX is currently
maintained by Colten Edwards and a few others. EPIC is maintained by Jeremy
Nelson aka "hop". Alot of changes that appear within BitchX are backported
to EPIC as I am a contributor to epic.
You can get a copy of the BitchX client via ftp from these mirrors:
Not all sites will be always up to date, but many of them try.
Site Directory Maintainer
ftp.bitchx.com /pub/BitchX Mhacker/panasync
ftp.bitchx.org /pub/BitchX sideshow
If you want to mirror the BitchX client, please drop an email to Colten
Edwards (panasync@BitchX.com) telling him the host and directory where
we can count on you to keep a copy of the current version of the BitchX
client. The BitchX client takes about 1.2m, the help files take about 150k,
and from time to time there are other patches that range from 5k to 30k in
size.
A mailing list for all things related to BitchX exists. Send email to
majordomo@lists.bitchx.com with the words "subscribe bitchx" in the body
(and nothing else!). This list exists for bug reports, discussion about and
requests for new features, and anything else that has to do with BitchX.
* BitchX is completely safe: There are no hidden trap doors.
We value your trust, and will not do anything to abuse it.
* BitchX is programmable: While ircII does contain a wide range of commands
and functions, BitchX contains hundreds more.
* BitchX supports bots: We do not agree with those who feel that script
bots are all the evil of irc, and we feel that scripts bots must not be
squelched by those who have the stranglehold of control on irc. BitchX
will support bots for as long as we maintain it.
* BitchX is complete: EPIC supplies over 100 various functions and
commands which allow you to do things very quickly things that required
very large or slow scripts in the past. BitchX adds too the list of
functions and command so that with BitchX you do not need that same
script to run a good easy client as most of those same scripted commands
are available in the client itself. This has a problem however in a
increase in memory usage.

65
bitchx-docs/7_Docs/Arrays Normal file
View File

@@ -0,0 +1,65 @@
Karll's Array Suite 
BitchX and EPIC supports a large number of different data types. Among the
least used, and least understood, are Karll's arrays. This is mostly due to
the lack of publicized documentation for them. No more.
IrcII has long supported an array type. These are best identified as hash
arrays (or associative arrays, for Perl hackers). However, Karll's arrays
are different, more in line with the traditional notion of an array. Due to
how BitchX stores information, these arrays are not like normal variables or
hashes, and require special function to access and manipulate them.
Arrays are indexed sequentially, starting with 0 (zero). An array is
created when item 0 in a previously nonexistent array is defined:
$setitem(booya 0 random data)
This sets element 0 of array "booya" to the text string "random data".
Further items may be added sequentially; the next new element in the array
must be 1, and anything above 1 will result in an error. Existing array
elements may be freely overwritten:
$setitem(booya 0 other data)
Now element 0 of array "booya" contains the string "other data". Any item
may be deleted from the array. If the deleted element is not the last one
in the array (the one with the highest item number), all items after it
are shifted down by one; this prevents an array from having "holes" in it.
$setitem(booya 1 new data)
$delitem(booya 0)
This first adds a new element, then deletes the first element. The result
is an array that is one item in size. Item 1 become item 0.
One powerful feature of arrays not present in hashes is the ability to
search through the array elements for random data. The simplest methods are
probably already familiar to you. They operate in much the same manner as
the $match() and $rmatch() functions. Given that some array "blah" held
the following items (in order, from 0):
james@merlin.ocslink.com nelson@nemesis.acronet.net
foobar@blah.booya.com jbriggs@bigscreen.drivein.com
One could then use $matchitem() to find the element that best matches an
arbitrary input pattern. Similarly, if an array contained a set of wildcard
patterns, $rmatchitem() could find which one best matched some non-wildcard
string.
The most powerful searching feature is $finditem(). Like the matching
functions, it runs through an array looking for an item that matches the
input string. However, it looks for an exact match, and is sensitive to
case. This function uses a binary search algorithm, and is quite fast.
The other feature of note is an array's ability to be sorted on the fly.
All array elements have an item number (the order in which it was added) and
an index number (it's sorted position in the array). Array elements are
fetched by item number with $getitem() and by index number with $igetitem().
The result is that you can sequentially print out an array's elements using
$igetitem(), and they will be sorted automatically.
There is more to these arrays than is presented here. Each function used to
access and manipulate them is fully documented in Section 6 of these help
files. Refer to that section for more information.

31
bitchx-docs/7_Docs/Command_Line Normal file
View File

@@ -0,0 +1,31 @@
Command Line Usage of BitchX 
The BitchX irc client has a number of options available to it from the command
line. The basic command-line syntax is:
BitchX [<switches>] [<nickname> [<server list>]]
The nickname may be at most 30 characters long. The server list may be a
space-delimited list of server addresses. Each server name may use the
server:port notation if a port other than the default (usually 6667) is
desired. The available switches are as follows:
-b loads ~/.ircrc at client startup, instead of on connect
-c <chan> makes client join given channel on startup (if possible)
-p <port> set a different default port (normally 6667)
-f let terminal handle flow control (^S/^Q)
-F let the client handle flow control (default)
-s do not connect on startup, but show server list instead
-S use a separate server processes, ircserv
-d run the client in "dumb" terminal mode
-q skip loading of ~/.ircrc startup file
-a add default servers and command line servers to server list
-x run the client in "debug" mode
-v print the client's version string and exit
-b force the client to fork and return you to your shell
-l <file> loads <file> in place of your .ircrc
-L <file> loads <file> in place of your .ircrc and expands $ expandos
Unlike other Unix programs, switches for BitchX cannot be combined.
Something like "-db" is not allowed, "-d -b" must be used.

54
bitchx-docs/7_Docs/Compile_Opts Normal file
View File

@@ -0,0 +1,54 @@
Compile-Time Options Available for BitchX 
BitchX supports numerous configuration options that may be selectively
included or excluded from the client at compile time. Since many of these
enable or disable certain special features, it is useful to script writers
to be able to find out what options are present while the client is running.
The $info() function, used with the `O' command (`oh', not `zero'), will
return a text string that represents these options. Each option is assigned
unique letter or number to identify it. The options represented are most
of the #define options in the client's config.h file. The default settings
would produce the following string: 2cefgnxz
This is a list of the #define options represented. The letter designating
each option is listed, followed by its #define name, and whether it is
enabled or disabled by default in the config.h.
b NO_BOTS (disabled)
if enabled, the -b command-line option is not available
c CONTROL_C_COLOR (disabled)
if enabled, control-c color code parsing is available
d DEBUG (disabled)
if enabled, the client will spew out general debugging info
e EXEC_COMMAND (enabled)
if enabled, the /exec command is available
f USE_FLOW_CONTROL (enabled)
if enabled, the tty does flow control (disabled, ircII does it)
g INCLUDE_GLOB_FUNCTION (enabled)
if enabled, the $glob() function is available
i MIRC_BROKEN_DCC_RESUME (disabled)
if enabled, the client supports DCC RESUME
k HACKED_DCC_WARNING (disabled)
if enabled, client tries to warn if an incoming DCC request may be
from a bogus address (hostname/handshake mismatch)
m NEW_CONTROL_C_COLOR
if enabled, the client supports /SET COLOR instead of /SET
CONTROL_C_COLOR
n ALLOW_LONG_NICKNAMES (enabled)
if enabled, allows nicks up to 30 characters (a la DALnet)
o ENFORCE_STRICTER_PROTOCOL (disabled)
if enabled, disallows using /kick, /msg, etc. in response to a /who
or /whois
q QUIT_ON_OPERATOR_KILL (disabled)
if enabled, the client will exit if oper /kill'ed
r RESTRICTED (disabled)
if enabled, /exec is disabled, and novice mode is forced
s STRIP_EXTRANEOUS_SPACES (disabled)
if enabled, leading spaces on numeric expandos are stripped off
u UNAME_HACK (disabled)
if enabled, your system type is not shown in /ctcp version (a
generic "*IX" is shown instead)
z ALLOW_STOP_IRC (enabled)
if enabled, allows the client process to be suspended

40
bitchx-docs/7_Docs/Copyright Normal file
View File

@@ -0,0 +1,40 @@
Copyright Information About ircII, EPIC and BitchX 
/*
* Copyright (c) 1990 Michael Sandroff.
* Copyright (c) 1991, 1992 Troy Rollo.
* Copyright (c) 1992-1996 Matthew Green.
* Copyright 1993, 1997 Jeremy Nelson.
* Copyright 1994 Jake Khuon.
* Copyright 1995, 1998 Jeremy Nelson and others ("EPIC Software Labs").
* Copyright 1996, 1998 Colten Edwards and many others.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* 3. The names of the author(s) may not be used to endorse or promote
* products derived from this software without specific prior written
* permission.
*
* THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
* IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
*/
One module of the source code, glob.c is copyright 1993 by the Regents of
the University of California, with modifications. All rights are reserved
by the University of California.

40
bitchx-docs/7_Docs/Environment Normal file
View File

@@ -0,0 +1,40 @@
Environment Settings Relevant to BitchX 
Numerous environment variables are recognized by . Environment variables are
various settings that describe your login process on a Unix system. How they
are set mainly depends on the command shell you use.
* For csh and tcsh shells:
setenv variable "value"
* For bash, ksh, and zsh shells:
export variable="value"
* For sh (a true Bourne shell) and ash shells, and Bourne-like shells:
variable="value"
export variable
* For the rc and es shells (Plan 9 descendants):
variable='value'
For all shells (except rc and es), either single quotes (') or double quotes
(") may be used. For all shells, the case of the variable is significant.
Environment variables are, by convention, in all uppercase, and BitchX is no
exception. The following variables are used by BitchX:
IRCNICK default nickname when connecting to a server
IRCNAME any lunacy you want instead of your real name
IRCHOST default local host name to use on multihomed hosts
IRCSERVER default server list, space delimited, serv:port:pass ok
IRCPORT default server port to connect to
IRCUMODE initial user mode (does not work on all servers)
IRCPATH same as LOAD_PATH setting
IRCRC alternate startup file (in lieu of ~/.ircrc)
IRC_SERVERS_FILE same as compile-time SERVERS_FILE, specifies a file
to get a list of servers from
BitchX also uses the TERM and HOME variables, which are usually set when you
login to your Unix system. All environment variables are available for
use inside BitchX as normal variables, assuming another variable of the same
name does not exist.

79
bitchx-docs/7_Docs/Etiquette Normal file
View File

@@ -0,0 +1,79 @@
 Etiquette on irc 
- or -
 How to Avoid Getting Yourself Kicked out of Channels 
Original Authors: Lea Viljanen (LadyBug) <viljanen@kreeta.helsinki.fi>
Ari Husa (luru) <so-luru@tolsun.oulu.fi>
Modified By: Troy Rollo (Troy) <troy@plod.cbme.unsw.oz.au>
Further Modified By: James Sneeringer (CrowMan) <jvs@ocslink.com>
1) Language
The most widely spoken and understood language on irc is English. This
does not mean it is the only language on irc! Far from it, in fact. In
general, it is ok to speak any language. The usual protocol is to use a
language that is understood by the majority of the channel you're in.
Some channels prefer that only a single language, or select group of
them, be used in their channel. This is particularly true of channels
dedicated to particular countries. They may tolerate other languages,
but their preference naturally lies with their native tongue. These
channels may even have a topic set that says what the channel's
preferred language is.
2) Hello and Goodbye
It is not necessary to greet each and every person that joins a channel
you're on. On a busy channel, this would quickly become annoying, as
everyones' screens become filled up with "hello" messages, and nothing
else. If you feel inclined to greet someone that you don't know, send
a private message with the /msg command.
Having established that a screenful of greetings is A Bad Thing, it
follows that automated greetings are worse. A drawback of the client's
ability to react to any arbitrary event with an arbitrary action is
that it is often misused. While you may only be trying to be polite to
everyone, you are in fact being just the opposite. Automated greetings
are impersonal at best.
3) Channel Discussion
As a general rule, there is no general rule about what sort of discussion
may be taking place on a channel at any given time. Usually, the topic
of discussion will be related in some way to the channel's name. People
on #perl probably answer questions about the Perl programming language
and discuss new features. However, this is not always the case!
The best strategy is to watch the discussion for a bit to get an idea of
what the channel is really all about. Unless you know otherwise (such
as from the channel topic), you should always feel free to contribute to
the conversation, though you should take care not to try to force the
discussion in a direction that it isn't flowing toward.
4) } { | ` ~ ] [ \ @ ^
No, it isn't line noise, and no, someone didn't make a typing error. On
irc, there is a large population of users from Scandinavian countries,
and the above characters represent letters in their alphabet. Since not
everyone has access to a terminal that can use or display the real
letters, these characters are instead substituted.
{ is an A with 2 dots over it (<28>)
} is an A with a small circle above it (<28>)
| is either an O with 2 dots over it or an O with a dash (/)
through it (either <20> or <20>)
` is an e with an accent over it (<28>)
~ is an u with 2 dots over it (<28>)
[, ], \, @ and ^ are the preceding five letters in upper case.
Of course, the irony here is that the French and German mappings are not
the same. Oh well...
5) ATTENTION!
If you remember nothing else from this document, remember this. People
on irc form their opinions about you based solely on your actions,
writings, and comments on irc. Think before you type.

224
bitchx-docs/7_Docs/Expressions Normal file
View File

@@ -0,0 +1,224 @@
Expression Syntax in BitchX 
This document describes the "expression" context of a statement, as used with
the ${} expando, the @ operator, and the FOR, IF, UNLESS, UNTIL, and WHILE
commands.
The normal context is "text", meaning everything is assumed to be plain text,
unless it is preceded by a '$'. With "expression" context, everything is
assumed to be a variable unless contained in square brackets '[]'. To enter
expression context explicitly while in text context, use the ${} notation.
Unlike text context, whitespace is not significant in expression context
(but see below).
The @ operator is a special case that allows any arbitrary expression to be
evaluated. Unlike the other commands listed above, however, the return
value of the expression is always thrown away. In many cases, the behavior
of @ is much like that of EVAL. The following statements are equivalent:
@ foo = 3
@ ::foo = 3 # two colons declare GLOBAL variables
eval (foo = 3)
Also note the use of variables local to a script's current scope. These could
be assigned with the local(5) command as opposed to assign(5) for global
variables. They can also be created with the @ operator (as shown above).
The following statements are equivalent:
@ :foo = 3 # one colon declares LOCAL variables
local foo 3
BitchX's expression syntax is modeled after that of C++, and BitchX's
operators (in general) hold the same precedence as they do in C++. Most
of the C/C++ operator set is represented in BitchX, and their operation is
the same. The following operators, from highest to lowest precedence,
are supported:
 1: () []
 2: ! ~ ++ --
 3: * / % **
 4: + - ##
 5: < <= > >= << >>
 6: == !=
 7: &
 8: ^
 9: |
10: &&
11: ^^
12: ||
13: ?:
14: = += -= *= /= %= &= ^= |= #= #~ =~ !~
15: ,
The string concatenation operators, ##, #=, and #~, are a special case, as they
are not present in C or C++. As their name indicates, they are used to join
two or more strings together, end to end. For example:
@ foo = [foo] ## [bar] /* sets $foo to "foobar" */
@ foo #= [blah] /* sets $foo to "foobarblah" */
@ foo #~ [hmm] /* sets $foo to "hmmfoobarblah" */
Also like C/C++, parentheses may be used to force certain parts of the
expression to be evaluated first (mainly in the event that the user wishes
for it to evaluate in an order other than that of operator precedence).
Parentheses may be nested. For example, if some variable $foo is set to 3:
foo * 4 + 5 /* returns 17 */
foo * (4 + 5) /* returns 27 */
4 + ((foo + 9) / 3) /* returns 8 */
All assignment operators always return the value assigned, which allows for
the assignment of multiple variables at once. Keep in mind that expressions
are evaluated right to left. For example, if $foo is 12 and $bar is 11:
@ foo += bar *= 2 /* $bar is 22, $foo is 34 */
Since the release of the EPIC4 pre-betas, the client has been growing ever
more perlish. Like perl, the =~ and !~ operators match with wildcards. =~ is
a direct opposite of !~, where it returns true if the patterns patch, while
!~ returns false. In this example, $bar is "epic":
@ foo = bar =~ [*pi*] /* returns 1 */
@ foo = bar !~ [*z*] /* returns 1 */
The various bitwise operators are of special interest also. Assuming $foo is 12
and $bar is 11:
foo & bar /* returns 8 */
foo | bar /* returns 15 */
foo ^ bar /* returns 7 */
The exponential operator takes numbers to various powers. It is especially
useful, since many script writers create a $power() function for this purpose.
It supports negative and fractional exponents as long as the system's math
library (libm) does. Assuming $foo is 9:
foo ** 2 /* returns 81 */
foo ** 0.5 /* returns 3 */
The {pre,post}fix {in,de}crement operators are big timesavers that C and C++
users everywhere swear by. They have also been known to swear at them, for
reasons you will soon see. Assume $foo is 5, each column shows 3 ways of
doing the same thing, from least efficient to most efficient:
@ foo = foo + 1 @ foo = foo - 1
@ foo += 1 @ foo -= 1
@ foo++ @ foo--
However, these operators have pitfalls, which are mainly discovered by those
who do not understand how they work. Both may either prefix or postfix a
variable; prefix causes it to evaluate before the operation, postfix causes
it to evaluate aster. For the examples shown above, it makes no difference.
However, it does make a difference in this example:
while ( foo++ < 10 ) { ... }
The expression is evaluated for whether $foo is less than 10, and then $foo
is incremented. If the autoincrement operator was instead used in prefix
form, $foo would be incremented before the expression was evaluated, which
would cause the loop to have one less iteration.
Another pitfall of the autoincrement and decrement operators is the
ambiguity introduced by insufficient whitespace when used in conjunction
with addition and subtraction operators. Consider the following:
@ foo = 4
@ bar = 8
@ foobar = foo+++bar
How should one interpret the last assignment? Should it really look like
${foo++ + bar} or ${foo + ++bar}? It's hard to tell. The best solution is
to not write code that looks so silly and unreadable. Add a couple spaces,
and there is no ambiguity. (The answer is, the first one.)
Another popular operator familiar to most C/C++ programmers is the tertiary
operator (sometimes referred to as the alternation operator). It performs
a function similar to IF, except is much more compact and efficient. We'll
let $foo be 5 again:
@ bar = foo > 3 ? 1 : 0 /* sets $bar to 1 */
@ bar = foo > 8 ? 1 : 0 /* sets $bar to 0 */
Functions (builtin and scripted) can also be used within expressions. The
function will be evaluated, and its return value is used in the expression:
@ foo = pattern(b* foo bar blah) /* sets $foo to "bar blah" */
All functions implicitly use a special operator, (). That is, the pair of
parentheses themselves compose an operator, though of course it is somewhat
different in nature from more traditional operators like '+' or '<' or '&'.
Functions (aliases with return values) require the () to function properly.
A similar operator is [], which is used for alias and variable structures.
We've already seen that it can be used to explicitly switch the evaluation
context to text. This can be extended to structure elements, such that
they can be expanded on the fly:
@ foo.1.1 = foo
@ foo.1.2 = bar
alias blah echo $foo[1][$0]
/blah 2 /* expands to $foo.1.2 -> "bar" */
The same can be applied to aliases and functions as well. Because of the
nature of the [] operator, anything may be expanded inside it, variables and
functions alike.
Operator parse tree:
NU_POIX = varexp++ |
varexp-- |
NU_EXPR
NU_EXPR = NU_ASSN
NU_ASSN = varexp = NU_ASSN |
varexp += NU_ASSN |
varexp -= NU_ASSN |
varexp *= NU_ASSN |
varexp /= NU_ASSN |
varexp %= NU_ASSN |
varexp &= NU_ASSN |
varexp ^= NU_ASSN |
varexp |= NU_ASSN |
varexp #= NU_ASSN |
NU_TERT
NU_TERT = NU_COMP ? NU_COMP : NU_COMP |
NU_CONJ
NU_CONJ = NU_CONJ && NU_CONJ |
NU_CONJ || NU_CONJ |
NU_CONJ ^^ NU_CONJ |
NU_BITW
NU_BITW = NU_COMP & NU_COMP |
NU_COMP | NU_COMP |
NU_COMP ^ NU_COMP |
NU_COMP
NU_COMP = NU_COMP == NU_COMP |
NU_COMP != NU_COMP |
NU_COMP > NU_COMP |
NU_COMP >= NU_COMP |
NU_COMP < NU_COMP |
NU_COMP <= NU_COMP |
NU_ADD
NU_ADD = NU_ADD + NU_ADD |
NU_ADD - NU_ADD |
NU_ADD ## NU_ADD |
NU_MULT
NU_MULT = NU_MULT * NU_MULT |
NU_MULT / NU_MULT |
NU_MULT % NU_MULT |
NU_UNIT
NU_UNIT = token NUX_MODIF |
unaryop token |
( NU_EXPR ) |
[ expression ] NUX_MODIF |
NU_PRIX
NU_PRIX = ++varexp |
--varexp
NUX_MODIF = ( expression ) NUX_MODIF |
[ expression ] NUX_MODIF
unaryop = ! |
~
See Also:
Patterns(7); Programming(7); Special_Vars(7)

61
bitchx-docs/7_Docs/Introduction Normal file
View File

@@ -0,0 +1,61 @@
Crash Course in irc with BitchX/EPIC 
You are using the BitchX irc client. Assuming you have the correct help
files for your client. BitchX is a variant of EPIC and ircII clients that
contains countless enhancements, while retaining near full backward
compatibility with ircII version 2.8.2.
BitchX offers a staggering number of features, far too many to describe here.
Instead, this document will show you the basics you'll need to get started
with irc and with BitchX/EPIC.
All commands in BitchX are prefixed with a '/'. This is called the command
character, and is used to distinguish typed commands from messages intended
for a channel. Here are some basic commands that you should become familiar
with. In these examples, do not actually include the <> characters when you
enter the command.
/help <n> <topic> This is the single most important command available
in this client. If you don't know what a command
does, chances are it is documented in the online
help. When all else fails, look here. The 'n' is
a section number, and 'topic' is the command to
get help on. If you use /help by itself, a list
of sections is given.
/join <channel> This makes you join the specified channel. For all
intents and purposes, channels always start with a
'#' character.
/part <channel> This makes you leave the specified channel.
/nick <new nick> This lets you choose a new nickname. You may use
any nickname you like, as long as someone else isn't
currently using it.
/msg <someone> This lets you send a private message to the specified
nickname.
/server <server> This lets you switch to a new irc server.
/whois <someone> This will give you some information about the given
nickname, such as the person's Internet address, the
channels and server s/he is on, etc.
/names <channel> This shows you a list of everyone on the specified
channel. You will automatically see a listing for
any channel you join.
/list This lets you list all the channels on your irc
network. This may not be a good idea, because some
networks have several thousand channels.
These commands should be sufficient to get you started. If you want to learn
more about BitchX, reading the online help is a good way to start. If you
have questions about irc in general, join one of the irc help channels and
ask someone. On EFnet, the channel is #irchelp, #epic and #bitchx.
See Also:
help(1); join(1); list(2); msg(1); names(2); nick(1); part(1); server(1);
whois(2)

53
bitchx-docs/7_Docs/Key_Bindings Normal file
View File

@@ -0,0 +1,53 @@
How to Use Key Bindings in BitchX 
One of the strengths of this client is its /bind command. It permits any
key or sequences to keys to be bound to any arbitrary action. You are most
likely already familiar with using keyboard shortcuts with other programs.
The general allowable key sequences that may be bound are as follows:
Sequence Description 
c any single character may be bound (case sensitive)
^c any letter (case insensitive) may be bound as a control key,
as well as any of: ? [ ] \ ^ @
METAn-c any meta key (1..9) may be used in conjunction with a single
key (as in the first form, above)
METAn-^c meta keys (1..9) may also be used in conjunction with control
keys (as in the second form, above)
mc this is another form of using meta keys, except in this case
the key bound to a META function is specified
m^c same as above, except used in conjunction with control keys
Meta keys may also be bound to other meta keys, such that a sequences may
be several characters in length. Some examples:
Whenever the '|' key is typed, the client will try to use that nick:
bind | parse_command nick |
This lets ^X (control-x) be used as a meta key in other bindings
bind ^X meta2_character
Either of these can be used to switch to a new window:
bind meta2-w next_window
bind ^Xw next_window
Either of these can be used to switch back to the previous window
bind meta2-^W previous_window
bind ^X^W previous window
A binding can also use a block of commands:
bind ^^ {
echo 1
echo 2
}
The client uses these bindings automatically for the arrow keys
bind ^[ meta1_character
bind meta1-[ meta2_character
bind meta2-A backward_history /* up arrow */
bind meta2-B forward_history /* down arrow */
bind meta2-C backward_character /* left arrow */
bind meta2-D forward_character /* right arrow */
Refer to the BIND command in section 4 for more information.

47
bitchx-docs/7_Docs/New_User Normal file
View File

@@ -0,0 +1,47 @@
 NEW USER INFORMATION ABOUT IRC 
++ This file is for users new to irc. Its intention is to briefly ++
++ describe what irc is all about. It is not a command summary. ++
++ Please refer to /help 7 introduction to get started with the ++
++ various BitchX/EPIC commands. ++
Irc stands for Internet Relay Chat. It is a networked, real-time, online
chat system. Its popularity has grown enormously since its invention
more than 7 years ago, and shows no signs of stopping anytime soon.
There are currently upwards of 30 irc "networks" scattered around the
Internet, serving every corner of the globe; do not expect everyone to
speak your own native language. At any given time, there are usually
upwards of 60,000 people using the various established irc networks.
The primary means of identification on irc is currently the nickname.
All users have a nickname. Your nickname can be changed with the /nick
command. No two users on the same irc network may use the same nickname
at the same time. For all intents and purposes, nicknames are NOT owned.
Anyone can use any nickname they like, including your favorite if you
aren't already using it on irc, and irc operators are under no obligation
whatsoever to "get it back" for you. For this reason, it is recommended
that you use the /whois command if you are unsure if a nickname is someone
you know or not.
It is important to recognize the nature of irc. Not everyone you meet
will be friendly and good-natured. Just like in real life, you will meet
jerks, and other types you may not care to associate with. You may meet
people who will try to deceive you. In particular, you may run across
someone who will ask you to issue some commands. USE CAUTION in these
situations. If you don't know what the command does, don't do it. If
the command involves the /on or /exec commands, don't do it unless you
are sure you know what you are doing. If all else fails, ask an irc
operator or a help channel (such as #irchelp) for help.
One final note on commands. The various BitchX commands can be
abbreviated (to the shortest possible unambiguous string). For example,
/na would run the /names command. This is mentioned because,
occasionally, you will run across pranksters trying to get new users to
type /sign or something similar (/sign is an abbreviation of /signoff).
As previously mentioned, use caution whenever anyone asks you to use a
command you are unfamiliar with or uncertain about.
Lastly, if you have not already done so, please read /help 7 etiquette
and /help 7 introduction. The former describes the basic accepted
behavior on irc, while the latter is a beginning command rundown.

31
bitchx-docs/7_Docs/Patterns Normal file
View File

@@ -0,0 +1,31 @@
Pattern Matching 
Literally, any string is a pattern. In general, though, a pattern is a
string intended to match, or be matched by, one or more other strings. The
pattern will usually contain one or more wildcards, but it doesn't need to.
The following wildcard characters are supported:
* matches zero or more characters
% matches zero or more characters, except spaces
? matches exactly one character
Assuming we have a variable $foo set to "hello there":
hello* /* pattern matches */
hello% /* pattern does not match */
hello%?% /* pattern matches */
h?llo?th?r? /* pattern matches */
Patterns may also contain multiple "branches". Each branch is tested when
a match attempt is made. Branches are formed with the \\[ \\] construct.
For example:
\\[foo bar\\]blah /* matches "fooblah" and "barblah" */
The branching construct may be used anywhere that wildcards are used,
including the various pattern matching functions, and in hook events.
See Also:
Expressions(7); match(6); on(4); pattern(6); rmatch(6); rpattern(6)

96
bitchx-docs/7_Docs/Programming Normal file
View File

@@ -0,0 +1,96 @@
Programming in BitchX 
This short (very short) document describes BitchX/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 builtin 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. Note that, because
the command character can be changed, it is recommended that $K be used in
lieu on a '/', as it will always represent the current command character:
$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 any {} command construct (from an alias, key binding,
hook, timer action, etc.), acts as 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. The solution is the quote, or escape, the semicolon with the
backslash:
alias blah {
on hook * echo hooked: $*\;echo oops!
}
Naturally, the backslash (\) is another character with special meaning in
scripts (but, again, not on the input line). It quote, or escapes, the
character immediately in front of it. Escaping characters takes away any
special meaning they might have (such as with semicolons, above). One neat
side effect from this is that it permits line-continuation in expressions:
if ( foo == 1 && \
bar == 2 ) { ... }
Speaking of quoting characters, the client's quoting rules can be confusing.
In general, everything works as described above; quote special characters to
use them in text context. However, the rules change when the client needs
to parse a command more than once. USERHOST is a classic example of this.
Let's say we've created this alias:
alias foo userhost $0 -cmd echo ($*)
That won't do at all, because both $expandos are parsed once, before the
command is even executed, which isn't what we want. So we need to do some
quoting on the -cmd part:
alias foo userhost $0 -cmd echo \($$*\)
Note that we quoted the '$' with the form '$$'. This is a special expando
that expands to a single '$'. We could have escaped it with a backslash,
but the $$ expando is faster. Anyway, that alias won't work either. Why?
Because the parentheses cause the whole statement to be parsed twice, so
we're right back where we started. We need to add another level of quoting
to the parentheses:
alias foo userhost $0 -cmd echo \\\($$*\\\)
After the initial parse run, the parenthesis are still quoted, because '\\'
expands to '\', and '\(' expands to '(', which together make '\('. After the
command is executed, the ECHO command is then parsed, this time correctly.
Other miscellaneous tips:
1) Use variable and alias structures.
2) Indent your code consistently. It will be easier to update later.
3) Comment your code. So you'll know what you did a year from now.
4) Use serial numbered hooks whenever possible.
5) For server output, use the "end" message instead of a WAIT command.
6) Read the client documentation! :)
Refer to Section 5 of these helpfiles for information about specific
commands. Refer to Section 6 for the client's builtin functions.

33
bitchx-docs/7_Docs/Security Normal file
View File

@@ -0,0 +1,33 @@
Security Issues 
BitchX is an extremely flexible client. To borrow a phrase from many a C
programmer, it gives you enough rope to hang yourself. With caution and
some common sense, this isn't a problem.
By far, the most potentially dangerous facility is ON. Because hooks can
be set to activate on any arbitrary input, and because they can perform
most any action when activated, they are often used for malicious purposes.
Consider the following:
on ^msg "% obey *" {
$2-
}
This allows anyone to make your client perform any command, simply by
sending you a message beginning with "obey", followed by any command. On
top of that, you won't even see the message, and if the perpetrator is
careful, you won't see its output either.
Social engineering is also a problem on irc. BitchX and EPIC attempt to
combat this with special configuration settings that disable certain
"dangerous" commands. Of course, experienced users can disable these
settings, but novices should think twice before doing so.
Above all, lack of education is probably the biggest problem associated
with the client. Think twice before typing a command you aren't familiar
with. Think twice before loading a script someone has given you, if you
don't understand how it works.
See Also:
New_User(7); set(4) exec_protection, novice, security

26
bitchx-docs/7_Docs/Serial_Numbers Normal file
View File

@@ -0,0 +1,26 @@
Using Hooks with Serial Numbers 
One of the neat things about ON hooks is that multiple hooks of the same
type may be given different priorities. A serial number may be any number,
positive or negative; zero is the default and should not be used directly.
The numbers themselves don't really matter, rather their relation to other
serial numbers is what's important. For example:
on hook "*" echo foobar
on #-hook -5 "*" echo booya
on #-hook 5 "*" echo yadda yadda yadda
Then, when any HOOK command is issued, the following three lines will be
displayed, in this order:
booya
foobar
yadda yadda yadda
In general, it is always advisable to use serial numbers, if for no other
reason than to prevent hooks from conflicting with each other. This is
particularly true of the TIMER hook, which should always use serial numbers.
See Also:
on(5)

48
bitchx-docs/7_Docs/Server_List Normal file
View File

@@ -0,0 +1,48 @@
Server List Format in BitchX 
There are several ways to set a predefined list of servers for EPIC to use.
In general, though, they all use the same basic format:
server:port:password:nickname
The server is the name of the server to connect to. The port is the port
number on the server's host to connect on. The password is only required
for servers that require one to connect. The nickname is the nick to use
once connected to the server. Only the server name is required. The
remaining parameters may be specified as needed. For example, to ignore
the password and nickname parameters:
server:port
As parameters on the end are omitted, the colons separating them too are
omitted. However, if a parameter in the "middle" is left out, but one that
comes after it is specified, the colons are required. If you only wanted
to give a server and nickname:
server:::nickname
A list of servers can exist in several forms. The primary list is hardcoded
into the client. It is usually overridden by a systemwide irc servers file
(usually called ircII.servers). Any number of server definitions may be
specified, separated by whitespace (newline, space, tab). A typical server
file might look like:
irc.foobar.com
irc.blah.net:6668
irc.cia.gov:31337:cl00bie:Mr_Prez
The system server list may be overridden by your IRCSERVER environment
variable, which may contain a space-delimited list of servers:
export IRCSERVER="irc.foobar.com irc.cia.gov:31337::Mr_Prez"
Finally, a list of servers may also be specified on the command line:
irc Mr_Prez irc.foobar.com irc.cia.gov:31337:secret-password
As well a list of servers can be placed in the file ~/.ircservers which will
augment the IRCSERVER variable or the built-in list of servers.
See Also:
Command_Line(7); Environment(7); server(1)

26
bitchx-docs/7_Docs/Server_Numerics Normal file
View File

@@ -0,0 +1,26 @@
Hooking Server Numerics 
In addition to the numerous named hooks provided by the client (refer to the
ON command in Section 5), BitchX and EPIC can hook any numeric reply sent
by a server. They are treated no differently from named hooks. Space
constraints prevent a full discussion of all server numerics, not to mention
that they tend to differ from network to network.
A small subset of commonly used numerics are provided for convenience. A
mostly full listing can be found in the irc protocol specification, RFC 1459
(though you should look in the ircd source code for an exact list; they are
in the file s_err.c in standard ircd distributions).
Replies to /whois: 311-313, 317-319
Replies to /mode +b: 367, 368
Replies to /trace: 200-206, 208, 209, 261, 262
Replies to /stats: 211-219, 241-244
Common error numerics: 401 (nickname doesn't exist)
: 404 (can't send message to channel)
: 421 (unknown command)
: 436 (nickname collision server kill)
: 465 (you're banned from server)
: 473 (can't going channel, invite-only)
: 482 (you're not a channel operator)

20
bitchx-docs/7_Docs/Signals Normal file
View File

@@ -0,0 +1,20 @@
Process Signals Relevant to the Operation of BitchX 
BitchX's behavior can be controlled (to an extent) from the Unix command line
via signals. The following signals have notable affects on the client:
SIGSEGV cause the client to dump core, if compiled with BITCHX_DEBUG
SIGTERM cause the client to immediately, but gracefully, exit
SIGKILL cause the client to die immediately, no cleanup
SIGUSR1 cause the client to close all DCC connections and any EXEC'd
processes that are still active
Typically, these signals are delivered with kill(1). The client's process
id (PID) must be known to send it a signal. The PID may be obtained with the
ps(1) command, or other utilities that display running processes. The basic
form would be:
% kill -USR1 <PID>
Refer to your system's manual pages for more information.

126
bitchx-docs/7_Docs/Special_Vars Normal file
View File

@@ -0,0 +1,126 @@
Special Variables and Expandos 
In addition to normal variables created with ASSIGN, and the builtin SET
variables, BitchX also supports a number of reserved, dynamic variables,
sometimes referred to as expandos. They are special in that the client is
constantly updating their values automatically. There are also numerous
variable modifiers available.
Modifier Description 
$variable A normal variable, expanding to the first match of:
| 1) a variable created with ASSIGN or @
| 2) an internal SET variable
| 3) an environment variable
| 4) an empty string
$[num]variable Expands to the variables value, with 'num' width. If
| the number is negative, the value is right-aligned.
| The value is truncated or padded to meet the width.
$#variable Expands to the number of words in $variable. If $variable
| is omitted, it assumes $*
$@variable Expands to the number of characters in $variable. if
| $variable is omitted, it assumes $*
$($subvariable) This is somewhat similar to a pointer, in that the
| value of $subvar is taken as the name of the
| variable to expand to. Nesting is allowed.
${expression} Expands to the return value of the expression. In
| addition, ${} permits the value to be embedded in
| another string unambiguously.
$!history! Expands to a matching entry in the client's command
| history, wildcards allowed.
$"some text" Uses 'text' as an input prompt, and returns whatever
| is typed next. This usage is deprecated, use the
| INPUT command instead.
Whenever an alias is called, these expandos are set to the arguments passed
to it. If none of these expandos are used in the alias, or the $() form
shown above, any arguments passed will automatically be appended to the last
command in the alias.
Expando Description 
$* expands to all arguments passed to an alias
$n expands to argument 'n' passed to an alias (counting from zero)
$n-m expands to arguments 'n' through 'm' passed to an alias
$n- expands to all arguments from 'n' on passed to an alias
$-m expands to all arguments up to 'm' passed to an alias
$~ expands to the last argument passed to an alias
These variables are set and updated dynamically by the client. The case of
$A .. $Z is important. Also note that $A .. $Z can be overridden by ASSIGN,
so it is usually good practice to make variable names 2 or more characters
long.
Variable Description 
$, last person who sent you a MSG
$. last person to whom you sent a MSG
$: last person to join a channel you are on
$; last person to send a public message to a channel you are on
$` your current uptime
$A text of your AWAY message, if any
$B body of last MSG you sent
$C current channel
$D last person that NOTIFY detected a signon for
$E idle time
$F time client was started, $time() format
$G the current value of set SHOW_NUMERICS_STR
$H current server numeric being processed
$I channel you were last INVITEd to
$J client version text string
$K current value of CMDCHARS
$L current contents of the input line
$M modes of current channel, if any
$N current nickname
$O value of STATUS_OPER if you are an irc operator
$P if you are a channel operator in $C, expands to a '@'
$Q nickname of whomever you are QUERYing
$R version of current server
$S current server name
$T target of current input (channel or QUERY nickname)
$U value of cutbuffer
$V client release date (numeric version string)
$W current working directory
$X your /userhost $N address (user@host)
$Y value of REALNAME
$Z time of day (hh:mm)
$a the full version string
$b a smaller version string
$h current running hook name
$n current network name if available ie. efnet, dalnet
$s the server port your on.
$t the currently running alias name
$u your away time
$v is tcl supported or not
$$ a literal '$'
For example, assume you have the following alias:
alias blah { msg $D Hi there! }
If /blah is passed any arguments, they will automatically be appended to the
MSG text. For example:
/blah oops /* command as entered */
"Hi there! oops" /* text sent to $D */
One of the more confusing expandos to look at is the $() form. It evaluates
the variable or function inside the parenthesis, and whatever is returned is
used as the name of the variable to expand. For example:
assign foo blah /* inside variable */
assign blah 10 /* real variable */
/eval echo $($foo) /* $foo expands to "blah" */
"10" /* $blah expands to "10" */
Another useful form is ${}. In general, variables can be embedded inside
strings without problems, assuming the surrounding text could not be
misinterpreted as part of the variable name. This form guarantees that
surrounding text will not affect the expression's return value.
/eval echo foo$Nfoo /* breaks, looks for $nfoo */
/eval echo foo${N}foo /* ${N} returns current nickname */
fooYourNickfoo /* returned by above command */
/eval echo ${[foo]}bar /* expression parser may be used */
foobar /* returned by above command */
See Also:
Expressions(7); Programming(7); assign(5); input(5)

6
bitchx-docs/7_Docs/Status_Line Normal file
View File

@@ -0,0 +1,6 @@
The status line contains a number of important pieces of information that
updates dynamically as conditions around the client change. This includes
your nickname, channel, current user and channel modes, etc. Refer to
"SET STATUS_USER" in Section 4 for more information about customizing the
status line.

60
bitchx-docs/7_Docs/Text_Highlight Normal file
View File

@@ -0,0 +1,60 @@
Special Text Highlighting Techniques 
Although BitchX is a text-based irc client, with several GUI ports it still
has many ways of marking text such that it stands out from the rest. The
simplest kinds of text highlighting are boldface, underline, and
reverse video. They work simply by surrounding the desired text with the
appropriate control characters:
Char Input Description 
^B B toggles boldfacing on/off
^V V toggles reverse video on/off
^_ _ toggles underlining on/off
^O O turns off all highlighting
The "char" is the character typed to achieve the desired effect; ^B means
control-b, etc. The "input" is how the character appears if typed on the
input line. The settings BOLD_VIDEO, INVERSE_VIDEO, and UNDERLINE_VIDEO
govern whether they will actually be displayed in the display window. In
truth, other keys may be bound to the highlighting characters, but they will
always be displayed as shown above.
In addition, BitchX also supports the use of ANSI escape sequences inside the
display window (ircII itself does not). The main use for this is for using
color. ANSI escape sequences are really much more powerful than that, but
a full discussion is beyond the scope of this document. We will focus on
how to use them to colorize text output.
BitchX controls whether escape sequences are passed to the display window with
the DISPLAY_ANSI setting. It is off by default. All of the above effects
can be achieved with escape sequences as well. For text highlighting, all
sequences have the following form (E is the ESC character):
E[#m
The '#' is some number. Multiple effects can be set at once (assuming they
don't clash with each other) with either of these forms:
E[#mE[#m
E[#;#m
For the purposes of this discussion, the following numbers may be used:
Code Effect  | Code Text/Background Color 
0 turn off all highlighting | 30/40 black
1 turn bold on | 31/41 red
2 turn bold off | 32/42 green
3 turn underline on | 33/43 yellow
5 turn blink on | 34/44 blue
7 turn reverse video on | 35/45 magenta (purple)
| 36/46 cyan (aqua)
| 37/47 white
For example, the first word in the following text would be red:
E[31m***E[0m Alert! Alert!
See Also:
bind(4) bold, highlight_off, reverse, underline; set(4) bold_video,
display_ansi, inverse_video, underline_video

3421
bitchx-docs/7_Docs/Updates Normal file
View File

File diff suppressed because it is too large Load Diff