NAME Net::IRC3 - An IRC Protocol module which is event system independend VERSION Version 0.01 SYNOPSIS use Net::IRC3; my $irc3 = new Net::IRC3; my $con = $irc3->connect_server ("test.not.at.irc.net", 6667); ... DESCRIPTION Net::IRC3 itself is a simple building block for an IRC client. It manages connections and parses and constructs IRC messages. Net::IRC3 is *very* simple, if you don't want to care about all the other things that a client still has to do (like replying to PINGs and remembering who is on a channel), I recommend to read the Net::IRC3::Client page instead. METHODS new () This just creates a Net::IRC3 object, which is a management class for creating and managing connections. connect_server ($host, $port) Tries to open a socket to the host $host and the port $port. If successfull it will return a Net::IRC3::Connection object. If an error occured it will die (use eval to catch the exception). FUNCTIONS These are some utility functions that might come in handy when handling the IRC protocol. parse_irc_msg ($ircline) This method parses the $ircline, which is one line of the IRC protocol without the trailing "\015\012". It returns a hash which has the following entrys: prefix The message prefix. command The IRC command. params The parameters to the IRC command in a array reference, this includes the trailing parameter (the one after the ':' or the 14th parameter). trailing This is set if there was a trailing parameter (the one after the ':' or the 14th parameter). mk_msg ($prefix, $command, $trailing, @params) This function assembles a IRC message. The generated message will look like (pseudo code!) : : Please refer to RFC 2812 how IRC messages normally look like. The prefix and the trailing string will be omitted if they are "undef". EXAMPLES: $con->mk_msg (undef, "PRIVMSG", "you suck!", "magnus"); # will return: "PRIVMSG magnus :you suck!\015\012" $con->mk_msg (undef, "JOIN", undef, "#test"); # will return: "JOIN #magnus\015\012" split_prefix ($prefix) This function splits an IRC user prefix as described by RFC 2817 into the three parts: nickname, user and host. Which will be returned as a list with that order. $prefix can also be a hash like it is returned by "parse_irc_msg". prefix_nick ($prefix) A shortcut to extract the nickname from the $prefix. $prefix can also be a hash like it is returned by "parse_irc_msg". prefix_user ($prefix) A shortcut to extract the username from the $prefix. $prefix can also be a hash like it is returned by "parse_irc_msg". prefix_host ($prefix) A shortcut to extract the hostname from the $prefix. $prefix can also be a hash like it is returned by "parse_irc_msg". Net::IRC3::Connection The connection class. Here the actual interesting stuff can be done, such as sending and receiving IRC messages. METHODS disconnect_server ($reason) Unregisters the connection in the main Net::IRC3 object, closes the sockets and send a 'disconnect' event with $reason as argument. heap () Returns a hash reference that is local to this connection object that lets you store any information you want. send_msg (@ircmsg) This function sends a message to the server. @ircmsg is the argumentlist for "mk_msg". reg_cb ($cmd, $cb) This registers a callback in the connection class. These callbacks will be called by internal events and by IRC protocol commands. The first argument to the callbacks is always the connection object itself. If a callback returns a false value, it will be unregistered. NOTE: *A callback has to return true to stay alive* If $cmd starts with 'irc_' the callback $cb will be registered for a IRC protocol command. The command is the suffix of $cmd then. The second argument to the callback is the message hash reference that has the layout that is returned by "parse_irc_msg". EXAMPLE: $con->reg_cb (irc_privmsg => \&privmsg_handler); # privmsg_handler will be called if an IRC message # with the command 'PRIVMSG' arrives. If $cmd is not prefixed with a 'irc_' it will be called when an event with the name $cmd is emitted. The arguments to the callback depend on the event that is emitted (but remember: the first argument will always be the connection object) Following events are emitted by this module and shouldn't be emitted from a module user call to "event". disconnect $reason This event will be generated if the connection is somehow terminated. It will also be emitted when "disconnect_server" is called. The second argument to the callback is $reason, a string that contains a clue about why the connection terminated. event ($event, @args) This function emits an event with the name $event and the arguments @args. The registerd callback that has been registered with "reg_cb" will be called with the first argument being the connection object and the rest of the arguments being @args. EXAMPLE $con->reg_cb (test_event => sub { print "Yay, i love $_[1]!!\n"); $con->event (test_event => "IRC"); # will print "Yay, i love IRC!!\n" AUTHOR Robin Redeker, "" SEE ALSO RFC 2812 - Internet Relay Chat: Client Protocol BUGS Please report any bugs or feature requests to "bug-net-irc3 at rt.cpan.org", or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SUPPORT You can find documentation for this module with the perldoc command. perldoc Net::IRC3 You can also look for information at: * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * RT: CPAN's request tracker * Search CPAN ACKNOWLEDGEMENTS Thanks to Marc Lehmann for the new AnyEvent module! COPYRIGHT & LICENSE Copyright 2006 Robin Redker, all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.