Linux.pl
Opcje wyszukiwania podręcznika man:
Lista stron man zaczynających się od znaku:
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z   ALPHA   NUM   OTHER   ALL
IRC(3pm)              User Contributed Perl Documentation             IRC(3pm)

NAME
       Net::IRC - Perl interface to the Internet Relay Chat protocol

SYNOPSIS
           use Net::IRC;

           $irc = new Net::IRC;
           $conn = $irc->newconn(Nick    => 'some_nick',
                                 Server  => 'some.irc.server.com',
                                 Port    =>  6667,
                                 Ircname => 'Some witty comment.');
           $irc->start;

DESCRIPTION
       Welcome to Net::IRC, a work in progress. First intended to be a quick
       tool for writing an IRC script in Perl, Net::IRC has grown into a com-
       prehensive Perl implementation of the IRC protocol (RFC 1459), devel-
       oped by several members of the EFnet IRC channel #perl, and maintained
       in channel #net-irc.

       There are 4 component modules which make up Net::IRC:

       o   Net::IRC

           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 select() for)
           get passed to user-supplied handler subroutines in other packages
           or in user code.

       o   Net::IRC::Connection

           The big time sink on this project. Each Connection instance is a
           single connection to an IRC server. The module itself contains
           methods for every single IRC 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.

       o   Net::IRC::Event

           Kind of a struct-like object for storing info about things that the
           IRC 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 func-
           tion.

       o   Net::IRC::DCC

           The analogous object to Connection.pm for connecting, sending and
           retrieving with the DCC protocol. Instances of DCC.pm are invoked
           from "Connection->new_{send,get,chat}" in the same way that
           "IRC->newconn" invokes "Connection->new". This will make more sense
           later, we promise.

       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 IRC,
       you can give your program a custom subroutine to call. But wait,
       there's more! There are 3 levels of handler precedence:

       o   Default handlers

           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 (STDOUT
           by default). These get called only when the user hasn't defined any
           of his own handlers for this event.

       o   User-definable global handlers

           The user can set up his own subroutines to replace the default
           actions for every IRC connection managed by your program. These
           only get invoked if the user hasn't set up a per-connection handler
           for the same event.

       o   User-definable per-connection handlers

           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.

       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
       IRC protocol.

GETTING STARTED
       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 IRC object handles the input and
       output for it.  To that end, say something like this:

           use Net::IRC;

           $irc = new Net::IRC;

           $conn = $irc->newconn(Nick    => 'some_nick',
                                 Server  => 'some.irc.server.com');

       ...or something similar. Acceptable parameters to newconn() are:

       o   Nick

           The nickname you'll be known by on IRC, often limited to a maximum
           of 9 letters. Acceptable characters for a nickname are
           "[\w{}[]\`^|-]". If you don't specify a nick, it defaults to your
           username.

       o   Server

           The IRC server to connect to. There are dozens of them across sev-
           eral widely-used IRC 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.

       o   Port

           The port to connect to this server on. By custom, the default is
           6667.

       o   Username

           On systems not running identd, you can set the username for your
           user@host to anything you wish. Note that some IRC servers won't
           allow connections from clients which don't run identd.

       o   Ircname

           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 GECOS field.

       o   Password

           If the IRC server you're trying to write a bot for is password-pro-
           tected, no problem. Just say ""Password =" 'foo'>" and you're set.

       o   SSL

           If you wish to connect to an irc server which is using SSL, set
           this to a true value.  Ie: ""SSL =" 1>".

       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:

           # 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.");
           }

       The arguments to a handler function are always the same:

       $_[0]:
           The Connection object that's calling it.

       $_[1]:
           An Event object (see below) that describes what the handler is
           responding to.

       Got it? If not, see the examples in the irctest script that came with
       this distribution. Anyhow, once you've defined your handler subrou-
       tines, 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:

           $self->add_global_handler('376', \&on_connect);     # global
           $self->add_handler('msg', \&on_msg);                # local

       376, incidentally, is the server number for "end of MOTD", 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 IRC sends your client a private message. For a
       big list of possible events, see the Event List section in the documen-
       tation for Net::IRC::Event.

       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 connec-
       tions and passing it off to the proper handlers:

           $irc->start;

       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 "start()" to ever get executed.

       If you're tying Net::IRC into another event-based module, such as
       perl/Tk, there's a nifty "do_one_loop()" method provided for your con-
       venience. Calling "$irc->do_one_loop()" runs through the IRC.pm event
       loop once, hands all ready filehandles over to the appropriate handler
       subs, then returns control to your program.

METHOD DESCRIPTIONS
       This section contains only the methods in IRC.pm itself. Lists of the
       methods in Net::IRC::Connection, Net::IRC::Event, or Net::IRC::DCC are
       in their respective modules' documentation; just "perldoc
       Net::IRC::Connection" (or Event or DCC or whatever) to read them. Func-
       tions take no arguments unless otherwise specified in their descrip-
       tion.

       By the way, expect Net::IRC to use AutoLoader sometime in the future,
       once it becomes a little more stable.

       o   addconn()

           Adds the specified object's socket to the select loop in
           "do_one_loop()".  This is mostly for the use of Connection and DCC
           objects (and for pre-0.5 compatibility)... for most (read: all)
           purposes, you can just use "addfh()", described below.

           Takes at least 1 arg:

           0.  An object whose socket needs to be added to the select loop

           1.  Optional: A string consisting of one or more of the letters r,
               w, and e.  Passed directly to "addfh()"... see the description
               below for more info.

       o   addfh()

           This sub takes a user's socket or filehandle and a sub to handle it
           with and merges it into "do_one_loop()"'s list of select()able
           filehandles. This makes integration with other event-based systems
           (Tk, for instance) a good deal easier than in previous releases.

           Takes at least 2 args:

           0.  A socket or filehandle to monitor

           1.  A reference to a subroutine. When "select()" determines that
               the filehandle is ready, it passes the filehandle to this (pre-
               sumably user-supplied) sub, where you can read from it, write
               to it, etc. as your script sees fit.

           2.  Optional: 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 file-
               handle. For example, this line select()s $fh (a filehandle, of
               course) for both reading and writing:

                   $irc->addfh( $fh, \&callback, "rw" );

       o   do_one_loop()

           "select()"s on all open filehandles and passes any ready ones to
           the appropriate handler subroutines. Also responsible for executing
           scheduled events from "Net::IRC::Connection->schedule()" on time.

       o   new()

           A fairly vanilla constructor which creates and returns a new
           Net::IRC object.

       o   newconn()

           Creates and returns a new Connection object. All arguments are
           passed straight to "Net::IRC::Connection->new()"; examples of com-
           mon arguments can be found in the Synopsis or Getting Started sec-
           tions.

       o   removeconn()

           Removes the specified object's socket from "do_one_loop()"'s list
           of select()able filehandles. This is mostly for the use of Connec-
           tion and DCC objects (and for pre-0.5 compatibility)... for most
           (read: all) purposes, you can just use "removefh()", described
           below.

           Takes 1 arg:

           0.  An object whose socket or filehandle needs to be removed from
               the select loop

       o   removefh()

           This method removes a given filehandle from "do_one_loop()"'s list
           of selectable filehandles.

           Takes 1 arg:

           0.  A socket or filehandle to remove

       o   start()

           Starts an infinite event loop which repeatedly calls
           "do_one_loop()" to read new events from all open connections and
           pass them off to any applicable handlers.

       o   timeout()

           Sets or returns the current "select()" timeout for the main event
           loop, in seconds (fractional amounts allowed). See the documenta-
           tion for the "select()" function for more info.

           Takes 1 optional arg:

           0.  Optional: A new value for the "select()" timeout for this IRC
               object.

       o   flush_output_queue()

           Flushes any waiting messages in the output queue if pacing is
           enabled. This method will not return until the output queue is
           empty.

AUTHORS
       o   Conceived and initially developed by Greg Bacon <gbacon@adtran.com>
           and Dennis Taylor <dennis@funkplanet.com>.

       o   Ideas and large amounts of code donated by Nat "King" Torkington
           <gnat@frii.com>.

       o   Currently being hacked on, hacked up, and worked over by the mem-
           bers of the Net::IRC developers mailing list. For details, see
           http://www.execpc.com/~corbeau/irc/list.html .

URL
       Up-to-date source and information about the Net::IRC project can be
       found at http://www.sourceforge.net/projects/net-irc/ .

SEE ALSO
       o   perl(1).

       o   RFC 1459: The Internet Relay Chat Protocol

       o   http://www.irchelp.org/, home of fine IRC resources.

perl v5.8.8                       2008-01-24                          IRC(3pm)

Time taken: 0.00046 seconds


Created with the man page lookup class by Andrew Collington, php@amnuts.com