.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Protocol::IRC::Client 3pm" .TH Protocol::IRC::Client 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Protocol::IRC::Client" \- IRC protocol handling for a client .SH "DESCRIPTION" .IX Header "DESCRIPTION" This mix-in class provides a layer of \s-1IRC\s0 message handling logic suitable for an \s-1IRC\s0 client. It builds upon Protocol::IRC to provide extra message processing useful to \s-1IRC\s0 clients, such as handling inbound server numerics. .PP It provides some of the methods required by \f(CW\*(C`Protocol::IRC\*(C'\fR: .IP "\(bu" 4 isupport .SH "INHERITED METHODS" .IX Header "INHERITED METHODS" The following methods, inherited from Protocol::IRC, are notable here as being particularly useful for a client. .SS "send_message" .IX Subsection "send_message" .Vb 3 \& $irc\->send_message( $message ) \& $irc\->send_message( $command, { %args } ) \& $irc\->send_message( $command, $prefix, @args ) .Ve .PP See \*(L"send_message\*(R" in Protocol::IRC .SH "METHODS" .IX Header "METHODS" .SS "isupport" .IX Subsection "isupport" .Vb 1 \& $value = $irc\->isupport( $key ) .Ve .PP Returns an item of information from the server's \f(CW\*(C`005 ISUPPORT\*(C'\fR lines. Traditionally \s-1IRC\s0 servers use all-capital names for keys. .SS "server_info" .IX Subsection "server_info" .Vb 1 \& $info = $irc\->server_info( $key ) .Ve .PP Returns an item of information from the server's \f(CW004\fR line. \f(CW$key\fR should one of .IP "\(bu" 8 host .IP "\(bu" 8 version .IP "\(bu" 8 usermodes .IP "\(bu" 8 channelmodes .SH "GATING MESSAGES" .IX Header "GATING MESSAGES" If messages with a gating disposition are received, extra processing is applied. Messages whose gating effect is \f(CW\*(C`more\*(C'\fR are simply collected up by pushing the hints hash to an array. Added to this hash is the command name itself, so that in the case of multiple message types (for example \f(CW\*(C`WHOIS\*(C'\fR replies) the individual messages can still be identified. .PP When the effect of \f(CW\*(C`done\*(C'\fR or \f(CW\*(C`fail\*(C'\fR is eventually received, this collected array is passed as \f(CW$data\fR to a handler in one of the following places: .IP "1." 4 A method called \f(CW\*(C`on_gate_EFFECT_GATE\*(C'\fR .Sp .Vb 1 \& $client\->on_gate_EFFECT_GATE( $message, $hints, $data ) .Ve .IP "2." 4 A method called \f(CW\*(C`on_gate_EFFECT\*(C'\fR .Sp .Vb 1 \& $client\->on_gate_EFFECT( \*(AqGATE\*(Aq, $message, $hints, $data ) .Ve .IP "3." 4 A method called \f(CW\*(C`on_gate\*(C'\fR .Sp .Vb 1 \& $client\->on_gate( \*(AqEFFECT, \*(AqGATE\*(Aq, $message, $hints, $data ) .Ve .IP "4." 4 If the gate effect is \f(CW\*(C`done\*(C'\fR, two more places are tried; looking like regular event handling on a command whose name is the (lowercase) gate name .Sp .Vb 1 \& $client\->on_message_GATE( $message, $hints ) \& \& $client\->on_message( \*(AqGATE\*(Aq, $message, $hints ) .Ve .PP For the following types of gate, the \f(CW$data\fR is further processed in the following way to provide extra hints fields. .SS "who" .IX Subsection "who" The hints hash will contain an extra key, \f(CW\*(C`who\*(C'\fR, which will be an \s-1ARRAY\s0 ref containing the lines of the \s-1WHO\s0 reply. Each line will be a \s-1HASH\s0 reference containing: .IP "user_ident" 8 .IX Item "user_ident" .PD 0 .IP "user_host" 8 .IX Item "user_host" .IP "user_server" 8 .IX Item "user_server" .IP "user_nick" 8 .IX Item "user_nick" .IP "user_nick_folded" 8 .IX Item "user_nick_folded" .IP "user_flags" 8 .IX Item "user_flags" .PD .SS "names" .IX Subsection "names" The hints hash will contain an extra key, \f(CW\*(C`names\*(C'\fR, which will be an \s-1ARRAY\s0 ref containing the usernames in the channel. Each will be a \s-1HASH\s0 reference containing: .IP "nick" 8 .IX Item "nick" .PD 0 .IP "flag" 8 .IX Item "flag" .PD .SS "bans" .IX Subsection "bans" The hints hash will contain an extra key, \f(CW\*(C`bans\*(C'\fR, which will be an \s-1ARRAY\s0 ref containing the ban lines. Each line will be a \s-1HASH\s0 reference containing: .IP "mask" 8 .IX Item "mask" User mask of the ban .IP "by_nick" 8 .IX Item "by_nick" .PD 0 .IP "by_nick_folded" 8 .IX Item "by_nick_folded" .PD Nickname of the user who set the ban .IP "timestamp" 8 .IX Item "timestamp" \&\s-1UNIX\s0 timestamp the ban was created .SS "motd" .IX Subsection "motd" The hints hash will contain an extra key, \f(CW\*(C`motd\*(C'\fR, which will be an \s-1ARRAY\s0 ref containing the lines of the \s-1MOTD.\s0 .SS "whois" .IX Subsection "whois" The hints hash will contain an extra key, \f(CW\*(C`whois\*(C'\fR, which will be an \s-1ARRAY\s0 ref of entries that mostly relate to the received \f(CW\*(C`RPL_WHOIS*\*(C'\fR numerics. .PP Each \f(CW\*(C`RPL_WHOIS*\*(C'\fR reply will be stripped of the standard hints hash keys, leaving whatever remains. Added to this will be a key called \f(CW\*(C`whois\*(C'\fR, whose value will be the command name, minus the leading \f(CW\*(C`RPL_WHOIS\*(C'\fR, and converted to lowercase. .SS "join" .IX Subsection "join" No additional keys. .SS "next_gate_future" .IX Subsection "next_gate_future" .Vb 1 \& $f = $client\->next_gate_future( $gate, $target ) .Ve .PP As an alternative to using the event handlers above, a client can instead obtain a Future that will succeed or fail the next time a result on a given gate is received for a given target. This is often more convenient to use in a client, as it represents the result of running a command. .PP If the gate completes successfully, then so will the future, yielding the same values as would be passed to the \f(CW\*(C`on_gate_done_GATE\*(C'\fR event; namely that .PP .Vb 1 \& ( $message, $hints, $data ) = $f\->get .Ve .PP If the gate fails, then so will the future, containing the text message from the error numeric as its failure message, \f(CW\*(C`irc_gate\*(C'\fR as its category, and the full message and hints for it as the details. .SH "INTERNAL MESSAGE HANDLING" .IX Header "INTERNAL MESSAGE HANDLING" The following messages are handled internally by \f(CW\*(C`Protocol::IRC::Client\*(C'\fR. .SS "\s-1CAP\s0" .IX Subsection "CAP" This message takes a sub-verb as its second argument, and a list of capability names as its third. On receipt of a \f(CW\*(C`CAP\*(C'\fR message, the verb is extracted and set as the \f(CW\*(C`verb\*(C'\fR hint, and the list capabilities set as the keys of a hash given as the \f(CW\*(C`caps\*(C'\fR hint. These are then passed to an event called .PP .Vb 1 \& $irc\->on_message_cap_VERB( $message, \e%hints ) .Ve .PP or .PP .Vb 1 \& $irc\->on_message_cap( \*(AqVERB\*(Aq, $message, \e%hints ) .Ve .SS "\s-1MODE\s0 (on channels) and 324 (\s-1RPL_CHANNELMODEIS\s0)" .IX Subsection "MODE (on channels) and 324 (RPL_CHANNELMODEIS)" These messages involve channel modes. The raw list of channel modes is parsed into an array containing one entry per affected piece of data. Each entry will contain at least a \f(CW\*(C`type\*(C'\fR key, indicating what sort of mode or mode change it is: .IP "list" 8 .IX Item "list" The mode relates to a list; bans, invites, etc.. .IP "value" 8 .IX Item "value" The mode sets a value about the channel .IP "bool" 8 .IX Item "bool" The mode is a simple boolean flag about the channel .IP "occupant" 8 .IX Item "occupant" The mode relates to a user in the channel .PP Every mode type then provides a \f(CW\*(C`mode\*(C'\fR key, containing the mode character itself, and a \f(CW\*(C`sense\*(C'\fR key which is an empty string, \f(CW\*(C`+\*(C'\fR, or \f(CW\*(C`\-\*(C'\fR. .PP For \f(CW\*(C`list\*(C'\fR and \f(CW\*(C`value\*(C'\fR types, the \f(CW\*(C`value\*(C'\fR key gives the actual list entry or value being set. .PP For \f(CW\*(C`occupant\*(C'\fR types, a \f(CW\*(C`flag\*(C'\fR key gives the mode converted into an occupant flag (by the \f(CW\*(C`prefix_mode2flag\*(C'\fR method), \f(CW\*(C`nick\*(C'\fR and \f(CW\*(C`nick_folded\*(C'\fR store the user name affected. .PP \&\f(CW\*(C`boolean\*(C'\fR types do not create any extra keys. .SH "COMMAND-SENDING METHODS" .IX Header "COMMAND-SENDING METHODS" The following methods actually send \s-1IRC\s0 commands. Each is named after the underlying \s-1IRC\s0 command it sends, using capital letters for methods that simply send that command. .SS "do_PRIVMSG" .IX Subsection "do_PRIVMSG" .SS "do_NOTICE" .IX Subsection "do_NOTICE" Sends a \f(CW\*(C`PRIVMSG\*(C'\fR or \f(CW\*(C`NOTICE\*(C'\fR command. .PP For convenience, a single \f(CW\*(C`target\*(C'\fR argument may be provided which will be renamed to \f(CW\*(C`targets\*(C'\fR. If \f(CW\*(C`targets\*(C'\fR is an \s-1ARRAY\s0 reference, it will be turned into a comma-separated string. .SH "REQUIRED METHODS" .IX Header "REQUIRED METHODS" As this class is an abstract base class, a concrete implementation must provide the following methods to complete it and make it useable. .SS "new_future" .IX Subsection "new_future" .Vb 1 \& $f = $client\->new_future .Ve .PP Returns a new Future instance or subclass thereof. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans