Debian Codegraph @

README

raw
1 NAME
2
3 Protocol::IRC - IRC protocol handling
4
5 DESCRIPTION
6
7 This mix-in class provides a base layer of IRC message handling logic.
8 It allows reading of IRC messages from a string buffer and dispatching
9 them to handler methods on its instance.
10
11 Protocol::IRC::Client provides an extension to this logic that may be
12 more convenient for IRC client implementations. Much of the code
13 provided here is still useful in client applications, so the reader
14 should be familiar with both modules.
15
16 MESSAGE HANDLING
17
18 Every incoming message causes a sequence of message handling to occur.
19 First, the message is parsed, and a hash of data about it is created;
20 this is called the hints hash. The message and this hash are then
21 passed down a sequence of potential handlers.
22
23 Each handler indicates by return value, whether it considers the
24 message to have been handled. Processing of the message is not
25 interrupted the first time a handler declares to have handled a
26 message. Instead, the hints hash is marked to say it has been handled.
27 Later handlers can still inspect the message or its hints, using this
28 information to decide if they wish to take further action.
29
30 A message with a command of COMMAND will try handlers in following
31 places:
32
33 1. A method called on_message_COMMAND
34
35 $irc->on_message_COMMAND( $message, \%hints )
36
37 2. A method called on_message
38
39 $irc->on_message( 'COMMAND', $message, \%hints )
40
41 For server numeric replies, if the numeric reply has a known name, it
42 will be attempted first at its known name, before falling back to the
43 numeric if it was not handled. Unrecognised numerics will be attempted
44 only at their numeric value.
45
46 Because of the wide variety of messages in IRC involving various types
47 of data the message handling specific cases for certain types of
48 message, including adding extra hints hash items, or invoking extra
49 message handler stages. These details are noted here.
50
51 Many of these messages create new events; called synthesized messages.
52 These are messages created by the Protocol::IRC object itself, to
53 better represent some of the details derived from the primary ones from
54 the server. These events all take lower-case command names, rather than
55 capitals, and will have a synthesized key in the hints hash, set to a
56 true value. These are dispatched and handled identically to regular
57 primary events, detailed above.
58
59 If any handler of the synthesized message returns true, then this marks
60 the primary message handled as well.
61
62 If a message is received that has a gating disposition, extra
63 processing is applied to it before the processing above. The effect on
64 its gate is given as a string (one of more, done, fail) to handlers in
65 the following places:
66
67 1. A method called on_message_gate_EFFECT_GATE
68
69 $irc->on_message_gate_EFFECT_GATE( $message, \%hints )
70
71 2. A method called on_message_gate_EFFECT
72
73 $irc->on_message_gate_EFFECT( 'GATE', $message, \%hints )
74
75 3. A method called on_message_gate
76
77 $irc->on_message_gate( 'EFFECT', 'GATE', $message, \%hints )
78
79 Message Hints
80
81 When messages arrive they are passed to the appropriate message
82 handling method, which the implementation may define. As well as the
83 message, a hash of extra information derived from or relating to the
84 message is also given.
85
86 The following keys will be present in any message hint hash:
87
88 handled => BOOL
89
90 Initially false. Will be set to true the first time a handler returns
91 a true value.
92
93 prefix_nick => STRING
94
95 prefix_user => STRING
96
97 prefix_host => STRING
98
99 Values split from the message prefix; see the Protocol::IRC::Message
100 prefix_split method.
101
102 prefix_name => STRING
103
104 Usually the prefix nick, or the hostname in case the nick isn't
105 defined (usually on server messages).
106
107 prefix_is_me => BOOL
108
109 True if the nick mentioned in the prefix refers to this connection.
110
111 Added to this set, will be all the values returned by the message's
112 named_args method. Some of these values may cause yet more values to be
113 generated.
114
115 If the message type defines a target_name:
116
117 * target_type => STRING
118
119 Either channel or user, as returned by classify_name.
120
121 * target_is_me => BOOL
122
123 True if the target name is a user and refers to this connection.
124
125 Any key whose name ends in _nick or _name will have a corresponding key
126 added with _folded suffixed on its name, containing the value
127 casefolded using casefold_name. This is for the convenience of string
128 comparisons, hash keys, etc..
129
130 Any of these keys that are not the prefix_name will additionally have a
131 corresponding key with _is_me replacing the _nick or _name, containing
132 the boolean result of calling the is_nick_me method on that name. This
133 makes it simpler to detect commands or results affecting the user the
134 connection represents.
135
136 METHODS
137
138 on_read
139
140 $irc->on_read( $buffer )
141
142 Informs the protocol implementation that more bytes have been read from
143 the peer. This method will modify the $buffer directly, and remove from
144 it the prefix of bytes it has consumed. Any bytes remaining should be
145 stored by the caller for next time.
146
147 Any messages found in the buffer will be passed, in sequence, to the
148 incoming_message method.
149
150 incoming_message
151
152 $irc->incoming_message( $message )
153
154 Invoked by the on_read method for every incoming IRC message. This
155 method implements the actual dispatch into various handler methods as
156 described in the "MESSAGE HANDLING" section above.
157
158 This method is exposed so that subclasses can override it, primarily to
159 wrap extra logic before or after the main dispatch (e.g. for logging or
160 other processing).
161
162 send_message
163
164 This method takes arguments in three different forms, depending on
165 their number and type.
166
167 If the first argument is a reference then it must contain a
168 Protocol::IRC::Message instance which will be sent directly:
169
170 $irc->send_message( $message )
171
172 Otherwise, the first argument must be a plain string that gives the
173 command name. If the second argument is a hash, it provides named
174 arguments in a form similar to "new_from_named_args" in
175 Protocol::IRC::Message, otherwise the remaining arguments must be the
176 prefix string and other positional arguments, as plain strings:
177
178 $irc->send_message( $command, { %args } )
179
180 $irc->send_message( $command, $prefix, @args )
181
182 Named Argument Mangling
183
184 For symmetry with incoming message processing, this method applies some
185 adjustment of named arguments for convenience of callers.
186
187 * Callers may define a named argument of target; it will be renamed
188 to target_name.
189
190 * If a named argument of text is defined and an "encoder" exists, the
191 argument value will be encoded using this encoder.
192
193 send_ctcp
194
195 $irc->send_ctcp( $prefix, $target, $verb, $argstr )
196
197 Shortcut to sending a CTCP message. Sends a PRIVMSG to the given
198 target, containing the given verb and argument string.
199
200 send_ctcpreply
201
202 $irc->send_ctcpreply( $prefix, $target, $verb, $argstr )
203
204 Shortcut to sending a CTCP reply. As send_ctcp but using a NOTICE
205 instead.
206
207 ISUPPORT-DRIVEN UTILITIES
208
209 The following methods are controlled by the server information given in
210 the ISUPPORT settings. They use the isupport required method to query
211 the information required.
212
213 casefold_name
214
215 $name_folded = $irc->casefold_name( $name )
216
217 Returns the $name, folded in case according to the server's CASEMAPPING
218 ISUPPORT. Such a folded name will compare using eq according to whether
219 the server would consider it the same name.
220
221 Useful for use in hash keys or similar.
222
223 cmp_prefix_flags
224
225 $cmp = $irc->cmp_prefix_flags( $lhs, $rhs )
226
227 Compares two channel occupant prefix flags, and returns a signed
228 integer to indicate which of them has higher priviledge, according to
229 the server's ISUPPORT declaration. Suitable for use in a sort()
230 function or similar.
231
232 cmp_prefix_modes
233
234 $cmp = $irc->cmp_prefix_modes( $lhs, $rhs )
235
236 Similar to cmp_prefix_flags, but compares channel occupant MODE command
237 flags.
238
239 prefix_mode2flag
240
241 $flag = $irc->prefix_mode2flag( $mode )
242
243 Converts a channel occupant MODE flag (such as o) into a name prefix
244 flag (such as @).
245
246 prefix_flag2mode
247
248 $mode = $irc->prefix_flag2mode( $flag )
249
250 The inverse of prefix_mode2flag.
251
252 classify_name
253
254 $classification = $irc->classify_name( $name )
255
256 Returns channel if the given name matches the pattern of names allowed
257 for channels according to the server's CHANTYPES ISUPPORT. Returns user
258 if not.
259
260 is_nick_me
261
262 $me = $irc->is_nick_me( $nick )
263
264 Returns true if the given nick refers to that in use by the connection.
265
266 INTERNAL MESSAGE HANDLING
267
268 The following messages are handled internally by Protocol::IRC.
269
270 PING
271
272 PING messages are automatically replied to with PONG.
273
274 NOTICE and PRIVMSG
275
276 Because NOTICE and PRIVMSG are so similar, they are handled together by
277 synthesized events called text, ctcp and ctcpreply. Depending on the
278 contents of the text, and whether it was supplied in a PRIVMSG or a
279 NOTICE, one of these three events will be created.
280
281 In all cases, the hints hash will contain a is_notice key being true or
282 false, depending on whether the original messages was a NOTICE or a
283 PRIVMSG, a target_name key containing the message target name, a
284 case-folded version of the name in a target_name_folded key, and a
285 classification of the target type in a target_type key.
286
287 For the user target type, it will contain a boolean in target_is_me to
288 indicate if the target of the message is the user represented by this
289 connection.
290
291 For the channel target type, it will contain a restriction key
292 containing the channel message restriction, if present.
293
294 For normal text messages, it will contain a key text containing the
295 actual message text.
296
297 For either CTCP message type, it will contain keys ctcp_verb and
298 ctcp_args with the parsed message. The ctcp_verb will contain the first
299 space-separated token, and ctcp_args will be a string containing the
300 rest of the line, otherwise unmodified. This type of message is also
301 subject to a special stage of handler dispatch, involving the CTCP verb
302 string. For messages with VERB as the verb, the following are tried.
303 CTCP may stand for either ctcp or ctcpreply.
304
305 1. A method called on_message_CTCP_VERB
306
307 $irc->on_message_CTCP_VERB( $message, \%hints )
308
309 2. A method called on_message_CTCP
310
311 $irc->on_message_CTCP( 'VERB', $message, \%hintss )
312
313 3. A method called on_message
314
315 $irc->on_message( 'CTCP VERB', $message, \%hints )
316
317 REQUIRED METHODS
318
319 As this class is an abstract base class, a concrete implementation must
320 provide the following methods to complete it and make it useable.
321
322 write
323
324 $irc->write( $string )
325
326 Requests the byte string to be sent to the peer
327
328 encoder
329
330 $encoder = $irc->encoder
331
332 Optional. If supplied, returns an Encode object used to encode or
333 decode the bytes appearing in a text field of a message. If set, all
334 text strings will be returned, and should be given, as Unicode strings.
335 They will be encoded or decoded using this object.
336
337 invoke
338
339 $result = $irc->invoke( $name, @args )
340
341 Optional. If provided, invokes the message handling routine called
342 $name with the given arguments. A default implementation is provided
343 which simply attempts to invoke a method of the given name, or return
344 false if no method of that name exists.
345
346 If an implementation does override this method, care should be taken to
347 ensure that methods are tested for and invoked if present, in addition
348 to any other work the method wishes to perform, as this is the basis by
349 which derived message handling works.
350
351 isupport
352
353 $value = $irc->isupport( $field )
354
355 Should return the value of the given ISUPPORT field.
356
357 As well as the all-capitals server-supplied fields, the following
358 fields may be requested. Their names are all lowercase and contain
359 underscores, to distinguish them from server-supplied fields.
360
361 prefix_modes => STRING
362
363 The mode characters from PREFIX (e.g. ohv)
364
365 prefix_flags => STRING
366
367 The flag characters from PREFIX (e.g. @%+)
368
369 prefixflag_re => Regexp
370
371 A precompiled regexp that matches any of the prefix flags
372
373 prefix_map_m2f => HASH
374
375 A map from mode characters to flag characters
376
377 prefix_map_f2m => HASH
378
379 A map from flag characters to mode characters
380
381 chanmodes_list => ARRAY
382
383 A 4-element array containing the split portions of CHANMODES;
384
385 [ $listmodes, $argmodes, $argsetmodes, $boolmodes ]
386
387 channame_re => Regexp
388
389 A precompiled regexp that matches any string beginning with a channel
390 prefix character in CHANTYPES.
391
392 nick
393
394 $nick = $irc->nick
395
396 Should return the current nick in use by the connection.
397
398 nick_folded
399
400 $nick_folded = $irc->nick_folded
401
402 Optional. If supplied, should return the current nick as case-folded by
403 the casefold_name method. If not provided, this will be performed by
404 case-folding the result from nick.
405
406 AUTHOR
407
408 Paul Evans <[email protected]>
409