.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "IRC 3pm" .TH IRC 3pm "2017-11-19" "perl v5.26.1" "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" Net::IRC \- DEAD SINCE 2004 Perl interface to the Internet Relay Chat protocol .SH "USE THESE INSTEAD" .IX Header "USE THESE INSTEAD" This module has been abandoned and is no longer developed. This release serves only to warn current and future users about this and to direct them to supported and actively-developed libraries for connecting Perl to \s-1IRC.\s0 Most new users will want to use Bot::BasicBot, whereas more advanced users will appreciate the flexibility offered by POE::Component::IRC. We understand that porting code to a new framework can be difficult. Please stop by #perl on irc.freenode.net and we'll be happy to help you out with bringing your bots into the modern era. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::IRC; \& \& $irc = new Net::IRC; \& $conn = $irc\->newconn(Nick => \*(Aqsome_nick\*(Aq, \& Server => \*(Aqsome.irc.server.com\*(Aq, \& Port => 6667, \& Ircname => \*(AqSome witty comment.\*(Aq); \& $irc\->start; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module has been abandoned and deprecated since 2004. The original authors have moved onto POE::Component::IRC and more modern techniques. This distribution is not maintained and only uploaded to present successively louder \&\*(L"don't use this\*(R" warnings to those unaware. .PP Welcome to Net::IRC, a work in progress. First intended to be a quick tool for writing an \s-1IRC\s0 script in Perl, Net::IRC has grown into a comprehensive Perl implementation of the \s-1IRC\s0 protocol (\s-1RFC 1459\s0), developed by several members of the EFnet \s-1IRC\s0 channel #perl, and maintained in channel #net\-irc. .PP There are 4 component modules which make up Net::IRC: .IP "\(bu" 4 Net::IRC .Sp The wrapper for everything else, containing methods to generate Connection objects (see below) and a connection manager which does an event loop on all available filehandles. Sockets or files which are readable (or writable, or whatever you want it to \fIselect()\fR for) get passed to user-supplied handler subroutines in other packages or in user code. .IP "\(bu" 4 Net::IRC::Connection .Sp The big time sink on this project. Each Connection instance is a single connection to an \s-1IRC\s0 server. The module itself contains methods for every single \s-1IRC\s0 command available to users (Net::IRC isn't designed for writing servers, for obvious reasons), methods to set, retrieve, and call handler functions which the user can set (more on this later), and too many cute comments. Hey, what can I say, we were bored. .IP "\(bu" 4 Net::IRC::Event .Sp Kind of a struct-like object for storing info about things that the \&\s-1IRC\s0 server tells you (server responses, channel talk, joins and parts, et cetera). It records who initiated the event, who it affects, the event type, and any other arguments provided for that event. Incidentally, the only argument passed to a handler function. .IP "\(bu" 4 Net::IRC::DCC .Sp The analogous object to Connection.pm for connecting, sending and retrieving with the \s-1DCC\s0 protocol. Instances of \s-1DCC\s0.pm are invoked from \&\f(CW\*(C`Connection\->new_{send,get,chat}\*(C'\fR in the same way that \&\f(CW\*(C`IRC\->newconn\*(C'\fR invokes \f(CW\*(C`Connection\->new\*(C'\fR. This will make more sense later, we promise. .PP The central concept that Net::IRC is built around is that of handlers (or hooks, or callbacks, or whatever the heck you feel like calling them). We tried to make it a completely event-driven model, a la Tk \*(-- for every conceivable type of event that your client might see on \s-1IRC,\s0 you can give your program a custom subroutine to call. But wait, there's more! There are 3 levels of handler precedence: .IP "\(bu" 4 Default handlers .Sp Considering that they're hardwired into Net::IRC, these won't do much more than the bare minimum needed to keep the client listening on the server, with an option to print (nicely formatted, of course) what it hears to whatever filehandles you specify (\s-1STDOUT\s0 by default). These get called only when the user hasn't defined any of his own handlers for this event. .IP "\(bu" 4 User-definable global handlers .Sp The user can set up his own subroutines to replace the default actions for \fIevery\fR \s-1IRC\s0 connection managed by your program. These only get invoked if the user hasn't set up a per-connection handler for the same event. .IP "\(bu" 4 User-definable per-connection handlers .Sp Simple: this tells a single connection what to do if it gets an event of this type. Supersedes global handlers if any are defined for this event. .PP And even better, you can choose to call your custom handlers before or after the default handlers instead of replacing them, if you wish. In short, it's not perfect, but it's about as good as you can get and still be documentable, given the sometimes horrendous complexity of the \s-1IRC\s0 protocol. .SH "GETTING STARTED" .IX Header "GETTING STARTED" .SS "Initialization" .IX Subsection "Initialization" To start a Net::IRC script, you need two things: a Net::IRC object, and a Net::IRC::Connection object. The Connection object does the dirty work of connecting to the server; the \s-1IRC\s0 object handles the input and output for it. To that end, say something like this: .PP .Vb 1 \& use Net::IRC; \& \& $irc = new Net::IRC; \& \& $conn = $irc\->newconn(Nick => \*(Aqsome_nick\*(Aq, \& Server => \*(Aqsome.irc.server.com\*(Aq); .Ve .PP \&...or something similar. Acceptable parameters to \fInewconn()\fR are: .IP "\(bu" 4 Nick .Sp The nickname you'll be known by on \s-1IRC,\s0 often limited to a maximum of 9 letters. Acceptable characters for a nickname are \f(CW\*(C`[\ew{}[]\e\`^|\-]\*(C'\fR. If you don't specify a nick, it defaults to your username. .IP "\(bu" 4 Server .Sp The \s-1IRC\s0 server to connect to. There are dozens of them across several widely-used \s-1IRC\s0 networks, but the oldest and most popular is EFNet (Eris Free Net), home to #perl. See http://www.irchelp.org/ for lists of popular servers, or ask a friend. .IP "\(bu" 4 Port .Sp The port to connect to this server on. By custom, the default is 6667. .IP "\(bu" 4 Username .Sp On systems not running identd, you can set the username for your user@host to anything you wish. Note that some \s-1IRC\s0 servers won't allow connections from clients which don't run identd. .IP "\(bu" 4 Ircname .Sp A short (maybe 60 or so chars) piece of text, originally intended to display your real name, which people often use for pithy quotes and URLs. Defaults to the contents of your \s-1GECOS\s0 field. .IP "\(bu" 4 Password .Sp If the \s-1IRC\s0 server you're trying to write a bot for is password-protected, no problem. Just say "\f(CW\*(C`Password =\*(C'\fR 'foo'>" and you're set. .IP "\(bu" 4 \&\s-1SSL\s0 .Sp If you wish to connect to an irc server which is using \s-1SSL,\s0 set this to a true value. Ie: "\f(CW\*(C`SSL =\*(C'\fR 1>". .SS "Handlers" .IX Subsection "Handlers" Once that's over and done with, you need to set up some handlers if you want your bot to do anything more than sit on a connection and waste resources. Handlers are references to subroutines which get called when a specific event occurs. Here's a sample handler sub: .PP .Vb 3 \& # What to do when the bot successfully connects. \& sub on_connect { \& my $self = shift; \& \& print "Joining #IRC.pm..."; \& $self\->join("#IRC.pm"); \& $self\->privmsg("#IRC.pm", "Hi there."); \& } .Ve .PP The arguments to a handler function are always the same: .ie n .IP "$_[0]:" 4 .el .IP "\f(CW$_\fR[0]:" 4 .IX Item "$_[0]:" The Connection object that's calling it. .ie n .IP "$_[1]:" 4 .el .IP "\f(CW$_\fR[1]:" 4 .IX Item "$_[1]:" An Event object (see below) that describes what the handler is responding to. .PP Got it? If not, see the examples in the irctest script that came with this distribution. Anyhow, once you've defined your handler subroutines, you need to add them to the list of handlers as either a global handler (affects all Connection objects) or a local handler (affects only a single Connection). To do so, say something along these lines: .PP .Vb 2 \& $self\->add_global_handler(\*(Aq376\*(Aq, \e&on_connect); # global \& $self\->add_handler(\*(Aqmsg\*(Aq, \e&on_msg); # local .Ve .PP 376, incidentally, is the server number for \*(L"end of \s-1MOTD\*(R",\s0 which is an event that the server sends to you after you're connected. See Event.pm for a list of all possible numeric codes. The 'msg' event gets called whenever someone else on \s-1IRC\s0 sends your client a private message. For a big list of possible events, see the \fBEvent List\fR section in the documentation for Net::IRC::Event. .SS "Getting Connected" .IX Subsection "Getting Connected" When you've set up all your handlers, the following command will put your program in an infinite loop, grabbing input from all open connections and passing it off to the proper handlers: .PP .Vb 1 \& $irc\->start; .Ve .PP Note that new connections can be added and old ones dropped from within your handlers even after you call this. Just don't expect any code below the call to \f(CW\*(C`start()\*(C'\fR to ever get executed. .PP If you're tying Net::IRC into another event-based module, such as perl/Tk, there's a nifty \f(CW\*(C`do_one_loop()\*(C'\fR method provided for your convenience. Calling \&\f(CW\*(C`$irc\->do_one_loop()\*(C'\fR runs through the \s-1IRC\s0.pm event loop once, hands all ready filehandles over to the appropriate handler subs, then returns control to your program. .SH "METHOD DESCRIPTIONS" .IX Header "METHOD DESCRIPTIONS" This section contains only the methods in \s-1IRC\s0.pm itself. Lists of the methods in Net::IRC::Connection, Net::IRC::Event, or Net::IRC::DCC are in their respective modules' documentation; just \f(CW\*(C`perldoc Net::IRC::Connection\*(C'\fR (or Event or \s-1DCC\s0 or whatever) to read them. Functions take no arguments unless otherwise specified in their description. .PP By the way, expect Net::IRC to use AutoLoader sometime in the future, once it becomes a little more stable. .IP "\(bu" 4 \&\fIaddconn()\fR .Sp Adds the specified object's socket to the select loop in \f(CW\*(C`do_one_loop()\*(C'\fR. This is mostly for the use of Connection and \s-1DCC\s0 objects (and for pre\-0.5 compatibility)... for most (read: all) purposes, you can just use \f(CW\*(C`addfh()\*(C'\fR, described below. .Sp Takes at least 1 arg: .RS 4 .IP "1." 4 An object whose socket needs to be added to the select loop .IP "2." 4 \&\fBOptional:\fR A string consisting of one or more of the letters r, w, and e. Passed directly to \f(CW\*(C`addfh()\*(C'\fR... see the description below for more info. .RE .RS 4 .RE .IP "\(bu" 4 \&\fIaddfh()\fR .Sp This sub takes a user's socket or filehandle and a sub to handle it with and merges it into \f(CW\*(C`do_one_loop()\*(C'\fR's list of \fIselect()\fRable filehandles. This makes integration with other event-based systems (Tk, for instance) a good deal easier than in previous releases. .Sp Takes at least 2 args: .RS 4 .IP "1." 4 A socket or filehandle to monitor .IP "2." 4 A reference to a subroutine. When \f(CW\*(C`select()\*(C'\fR determines that the filehandle is ready, it passes the filehandle to this (presumably user-supplied) sub, where you can read from it, write to it, etc. as your script sees fit. .IP "3." 4 \&\fBOptional:\fR A string containing any combination of the letters r, w or e (standing for read, write, and error, respectively) which determines what conditions you're expecting on that filehandle. For example, this line \&\fIselect()\fRs \f(CW$fh\fR (a filehandle, of course) for both reading and writing: .Sp .Vb 1 \& $irc\->addfh( $fh, \e&callback, "rw" ); .Ve .RE .RS 4 .RE .IP "\(bu" 4 \&\fIdo_one_loop()\fR .Sp \&\f(CW\*(C`select()\*(C'\fRs on all open filehandles and passes any ready ones to the appropriate handler subroutines. Also responsible for executing scheduled events from \f(CW\*(C`Net::IRC::Connection\->schedule()\*(C'\fR on time. .IP "\(bu" 4 \&\fInew()\fR .Sp A fairly vanilla constructor which creates and returns a new Net::IRC object. .IP "\(bu" 4 \&\fInewconn()\fR .Sp Creates and returns a new Connection object. All arguments are passed straight to \f(CW\*(C`Net::IRC::Connection\->new()\*(C'\fR; examples of common arguments can be found in the \fBSynopsis\fR or \fBGetting Started\fR sections. .IP "\(bu" 4 \&\fIremoveconn()\fR .Sp Removes the specified object's socket from \f(CW\*(C`do_one_loop()\*(C'\fR's list of \&\fIselect()\fRable filehandles. This is mostly for the use of Connection and \s-1DCC\s0 objects (and for pre\-0.5 compatibility)... for most (read: all) purposes, you can just use \f(CW\*(C`removefh()\*(C'\fR, described below. .Sp Takes 1 arg: .RS 4 .IP "1." 4 An object whose socket or filehandle needs to be removed from the select loop .RE .RS 4 .RE .IP "\(bu" 4 \&\fIremovefh()\fR .Sp This method removes a given filehandle from \f(CW\*(C`do_one_loop()\*(C'\fR's list of selectable filehandles. .Sp Takes 1 arg: .RS 4 .IP "1." 4 A socket or filehandle to remove .RE .RS 4 .RE .IP "\(bu" 4 \&\fIstart()\fR .Sp Starts an infinite event loop which repeatedly calls \f(CW\*(C`do_one_loop()\*(C'\fR to read new events from all open connections and pass them off to any applicable handlers. .IP "\(bu" 4 \&\fItimeout()\fR .Sp Sets or returns the current \f(CW\*(C`select()\*(C'\fR timeout for the main event loop, in seconds (fractional amounts allowed). See the documentation for the \&\f(CW\*(C`select()\*(C'\fR function for more info. .Sp Takes 1 optional arg: .RS 4 .IP "1." 4 \&\fBOptional:\fR A new value for the \f(CW\*(C`select()\*(C'\fR timeout for this \s-1IRC\s0 object. .RE .RS 4 .RE .IP "\(bu" 4 \&\fIflush_output_queue()\fR .Sp Flushes any waiting messages in the output queue if pacing is enabled. This method will not return until the output queue is empty. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Conceived and initially developed by Greg Bacon and Dennis Taylor . .IP "\(bu" 4 Ideas and large amounts of code donated by Nat \*(L"King\*(R" Torkington . .IP "\(bu" 4 Currently being hacked on, hacked up, and worked over by the members of the Net::IRC developers mailing list. For details, see http://www.execpc.com/~corbeau/irc/list.html . .SH "URL" .IX Header "URL" Up-to-date source and information about the Net::IRC project can be found at http://www.sourceforge.net/projects/net\-irc/ . .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 \&\fIperl\fR\|(1). .IP "\(bu" 4 \&\s-1RFC 1459:\s0 The Internet Relay Chat Protocol .IP "\(bu" 4 http://www.irchelp.org/, home of fine \s-1IRC\s0 resources.