1 ZenIRC 2.0 - Sun Feb 27 12:37:31 MST 1994 - ALPHA2
5 THIS IS REALLY OUT OF DATE, THE ONLY REASON IT'S KEPT AROUND IS THAT
6 IT DOES DESCRIBE SOME THINGS PRETTY GOOD. BEFORE YOU BELIEVE WHAT THIS
7 FILE SAYS, LOOK AT `zenirc-example.el' AND THE SOURCE.
13 KNOWN FEATURES AND INSTRUCTIONS:
15 Here is a list of variables you might want to frobnicate in your .emacs or
18 zenirc-buffer-name, change the buffer name to something besides "*zenirc*"
20 zenirc-IRCSERVER-alist - Association list of port/password/nick info for
23 Zenirc will attempt to connect to each `host' at `port' in turn until a
24 successful connection is made, using the username `user' (and `password' if
25 the server requests one). Your nickname is set to the value `nick'.
27 The default value of this alist is determined by the value of the
28 environment variable `IRCSERVER', which should be in the format
29 `host:port:password:nickname:username'. If more than one host:etc group is
30 desired, separate each group with any nonzero amount of whitespace composed
31 of spaces, tabs, and/or newlines.
33 The actual data types of the atoms of each association are string (server),
34 int (port), string (password), string (nickname), string (username).
36 zenirc-server - The hostname of the IRC server to which to connect.
38 This is initialized to the first server in `zenirc-IRCSERVER-alist' if that
39 variable is non-`nil', or "irc-2.mit.edu" by default.
41 zenirc-servername - The server name of the IRC server current connected to.
42 (hmm. this should be a setq, I think)
44 zenirc-port - The TCP port associated with the irc server specified
47 If the server initially specified in `zenirc-server' appears in
48 `zenirc-IRCSERVER-alist', and a port is explicitly associated with that
49 server, `zenirc-port' is initialized to that port. Otherwise,
50 `zenirc-port' defaults to 6667.
52 zenirc-user-login-name - the username with which you signon IRC.
54 This is usually your username on the system as returned by the function
55 `user-login-name'. However, if the server initially specified in
56 `zenirc-server' appears in `zenirc-IRCSERVER-alist' and a username is
57 explicitly associated with that server, `zenirc-user-login-name' is
58 initialized to that value.
60 zenirc-nick - If the server initially specified in `zenirc-server' appears in
61 `zenirc-IRCSERVER-alist' and a nickname is explicitly associated with that
62 server, `zenirc-nick' is initialized to that nickname. If this is not the
63 case but the environment variable `IRCNICK' is set, `zenirc-nick' is
64 initialized from that. As a last resort, it defaults to the value of the
65 variable `zenirc-user-login-name'.
67 zenirc-name - The name which you use on IRC.
68 The default is your GECOS information.
70 zenirc-password - Connection password for your IRC server.
73 zenirc-userinfo - Reply to USERINFO ctcp
75 zenirc-mode-map - Sparse keymap for zenirc-mode
77 zenirc-ignorance-list - A list of regexps matching annoying
78 things that should be ignored.
80 zenirc-signal-list - A list of regexps matching things that should cause the
81 user to be notified of them.
83 zenirc-beep-on-signal - Set to t if notification of something matching a regexp
84 in zenirc-signal-list should cause emacs to beep.
86 zenirc-send-ctcp-errmsg-on-unknown - Set to t if ZenIRC should reply with an
87 ERRMSG to unknown CTCP queries.
89 zenirc-send-ctcp-errmsg-on-unbalanced - Set to t if ZenIRC should send an
90 ERRMSG to an unbalanced CTCP query.
92 zenirc-verbose-ctcp - Set to t if you want ZenIRC to tell you when it sends
93 CTCP replies to people who query you.
95 zenirc-fingerdata - CTCP FINGER reply data.
97 zenirc-source - CTCP SOURCE reply data
99 zenirc-text-list - insert note about function to set here
101 zenirc-clientinfo-list - association list of CTCP CLIENTINFO help strings.
103 zenirc-clientinfo - Help string, showing list of CTCP commands supported.
105 zenirc-debug-mainloop, zenirc-debug-ignore, zenirc-debug-signal,
106 zenirc-debug-ctcp, zenirc-debug-commands zenirc-debug-timer -
107 debugging flags. If you're using these, then the help file is old news
108 as you've read the source.
110 The client is designed to be extensible and customizable, in the
111 spirit of ircII. It uses an extended version of the emacs 19 hook
112 mechanism, dubbed "zenhooks".
114 The basic idea behind the zenhook mechanism is that we want to be able to
115 attach multiple functions to a given hook. Rather than just specifying a
116 single hook by creating a function with a certain name, instead hooks become
117 variables which contain a list of functions to be called. You can add a new
118 function to a hook variable with the function zenirc-add-hook. If you do
119 something like (zenirc-add-hook 'zenirc-timer-hook 'ruru), it will cause
120 the function "ruru" to be added to the hook variable, zenirc-timer-hook.
122 Hooks are removed from a hook variable with the function
123 zenirc-delete-hook - ie, (zenirc-delete-hook 'zenirc-timer-hook 'ruru)
124 would remove ruru from the list of functions to be called when
125 zenirc-timer-hook is run.
127 zenhooks are run with the function zenirc-run-hook. This function,
128 unlike the emacs 19 hook functions, passes any extra arguments to
129 zenirc-run-hook to each function in the hook list as it is
130 run. In addition, if any function sets zenirc-run-next-hook to nil,
131 then remaining hooks in the hooklist are not called, and
132 zenirc-run-hook returns immediately.
134 For the timer code, zenirc uses a hook variable called
135 zenirc-timer-hook. This hook is called at most once a minute, and at
136 least as often as the irc server pings the client. The functions in
137 zenirc-timer-hook take a single argument, a process, the ZenIRC
138 process. An example of adding a new function to zenirc-timer-hook is
139 scripts/zenirc-stamp.el, which implements Kiwi client style timestamps
140 in the ZenIRC buffer.
142 The signal code is called via a hook variable called
143 zenirc-signal-hook. scripts/zenirc-fancy-signal.el shows an example of
144 using this hook as well as the variable zenirc-run-next-hook.
145 zenirc-signal-hook is called with two arguments, the first is the
146 zenirc process, and the second is a string, the unparsed servermessage
147 that caused the signal to occur.
149 In various places in the IRC protocol, the IRC server sends the client
150 strings of the form `nick!user@host' where some parts of this are
151 optional (see the RFC). The zenhook used to format these is
152 `zenirc-format-nickuserhost-hook', and is called with a single argument,
153 the string to format. It returns the formatted string.
155 To add new commands to ZenIRC, you create zenhooks with names of the
156 form "zenirc-command-WHATEVER-hook". The hook will be run with
157 the arguments "proc" and "parsedcmd". The first argument is the zenirc
158 process, and the second argument is a slightly parsed form of what the
159 user typed. The "parsedcmd" argument is a list with two elements. The
160 first is the first word on the line the user typed, and the second is
161 the rest of the line. For instance, if the user issued the command
162 "/FOO BAR", then parsedcmd would be set to ("FOO" "BAR"). Commands
163 used to use the old hook mechanism, but that is now obsolete.
165 CTCP is similarly extensible, only the format of the hook variable
166 names are zenirc-ctcp-query-WHATEVER-hook and
167 zenirc-ctcp-reply-WHATEVER-hook. A "query" is a CTCP inside a PRIVMSG
168 server message, and a "reply" is a CTCP inside a NOTICE server
169 message. These hooks are called with four arguments, the zenirc filter
170 process, a parsed ctcp message of the form ("CTCP_COMMAND" .
171 "ARGUMENTS"), the sender of the ctcp, and the reciever of the ctcp.
172 CTCP used to use the old hook mechanism, but that is now obsolete.
174 All server message handling hook variables have names of the form:
175 zenirc-server-MESSAGE-hook, and take two arguments, the zenirc filter
176 procedure, and a parsed message, which is an array that looks like
177 (sender MESSAGE arg1 arg2 ...). If you want to create a handler for a
178 message that does not currently have a handler, create your own
179 hook variable with a name of this form that accepts these arguments, and
180 ZenIRC will call your subroutine whenever it gets that server message.
181 To override or modify the behavior of a server message that already
182 has a hook, call zenirc-add-hook to add your subroutine to the hook
183 variable. You can override by setting zenirc-run-next-hook to nil, and
184 you can delete your entry in the hook variable with zenirc-delete-hook.
186 Some documents that may prove helpful in extending the client are the
187 RFC protocol specification for IRC and ctcp.doc. these are both included
190 Please send any comments, questions, ideas, bugfixes or whatever to
projects / packages / blob