Filewatcher File Search File Search
Catalog
Content Search
» » » » » libnet-irc-perl_0.75-6_all.deb » Content »
pkg://libnet-irc-perl_0.75-6_all.deb:70826/usr/share/man/man3/  info  control  downloads

libnet-irc-perl - IRC (Internet Relay Chat) interface module for Perl…  more info»

Net::IRC.3pm.gz

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 comprehensive Perl implementation of the IRC
       protocol (RFC 1459), developed 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:

       ·   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 file‐
           handles. 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.

       ·   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 com‐
           mand 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.

       ·   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. Inciden‐
           tally, the only argument passed to a handler function.

       ·   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 "Connec‐
           tion->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:

       ·   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.

       ·   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.

       ·   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:

       ·   Nick

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

       ·   Server

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

       ·   Port

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

       ·   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.

       ·   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.

       ·   Password

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

       ·   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 han‐
       dlers 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 han‐
           dler 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 subroutines, you need to add them to the list of han‐
       dlers as either a global handler (affects all Connection
       objects) or a local handler (affects only a single Connec‐
       tion). 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 documenta‐
       tion 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 connections 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 pro‐
       vided for your convenience. 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. Functions take no
       arguments unless otherwise specified in their description.

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

       ·   addconn()

           Adds the specified object's socket to the select loop in
           "do_one_loop()".  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
           "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.

       ·   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()" deter‐
               mines 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.

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

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

       ·   do_one_loop()

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

       ·   new()

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

       ·   newconn()

           Creates and returns a new Connection object. All argu‐
           ments are passed straight to "Net::IRC::Connec‐
           tion->new()"; examples of common arguments can be found
           in the Synopsis or Getting Started sections.

       ·   removeconn()

           Removes the specified object's socket from
           "do_one_loop()"'s list of select()able filehandles. This
           is mostly for the use of Connection and DCC objects (and
           for pre-0.5 compatibility)... for most (read: all) pur‐
           poses, 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

       ·   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

       ·   start()

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

       ·   timeout()

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

           Takes 1 optional arg:

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

       ·   flush_output_queue()

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

AUTHORS
       ·   Conceived and initially developed by Greg Bacon <gba‐
           con@adtran.com> and Dennis Taylor <dennis@funk‐
           planet.com>.

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

       ·   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
           .

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
       ·   perl(1).

       ·   RFC 1459: The Internet Relay Chat Protocol

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



perl v5.8.8                  2006-10-03                     IRC(3pm)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com