--- Net-IRC3/lib/Net/IRC3.pm 2006/07/16 02:09:12 1.1 +++ Net-IRC3/lib/Net/IRC3.pm 2006/07/16 02:41:37 1.2 @@ -3,6 +3,14 @@ use AnyEvent; use IO::Socket::INET; +use Exporter; +our @ISA = qw/Exporter/; +our @EXPORT_OK = + qw(mk_msg parse_irc_msg split_prefix prefix_nick + prefix_user prefix_host); + +require Net::IRC3::Connection; + =head1 NAME Net::IRC3 - An IRC Protocol module which is event system independend @@ -61,7 +69,7 @@ =item B Tries to open a socket to the host C<$host> and the port C<$port>. -If successfull it will return a Net::IRC3::Connection object. +If successfull it will return a L object. If an error occured it will die (use eval to catch the exception). =cut @@ -110,6 +118,10 @@ These are some utility functions that might come in handy when handling the IRC protocol. +You can export these with eg.: + + use Net::IRC3 qw/parse_irc_msg/; + =over 4 =item B @@ -196,10 +208,10 @@ EXAMPLES: - $con->mk_msg (undef, "PRIVMSG", "you suck!", "magnus"); + mk_msg (undef, "PRIVMSG", "you suck!", "magnus"); # will return: "PRIVMSG magnus :you suck!\015\012" - $con->mk_msg (undef, "JOIN", undef, "#test"); + mk_msg (undef, "JOIN", undef, "#test"); # will return: "JOIN #magnus\015\012" =cut @@ -281,226 +293,11 @@ return (split_prefix ($prfx))[2]; } -=head1 Net::IRC3::Connection - -The connection class. Here the actual interesting stuff can be done, -such as sending and receiving IRC messages. - -=head2 METHODS - -=over 4 - -=cut - -package Net::IRC3::Connection; - -use strict; -use AnyEvent; -use IO::Socket::INET; - -sub new -{ - my $this = shift; - my $class = ref($this) || $this; - - my $self = { - pirc => $_[0], - s => $_[1], - h => $_[2], - p => $_[3], - cbs => {}, - heap => {} - }; - - bless $self, $class; - - return $self; -} - -=item B - -Unregisters the connection in the main Net::IRC3 object, closes -the sockets and send a 'disconnect' event with C<$reason> as argument. - -=cut - -sub disconnect_server { - my ($self, $reason) = @_; - - $self->event (disconnect => $reason); - - delete $self->{rw}; - delete $self->{ww}; - delete $self->{pirc}->{connections}->{$self->{h} . ":" . $self->{p}}; - - eval { $self->{s}->close } -} - -=item B - -Returns a hash reference that is local to this connection object -that lets you store any information you want. - -=cut - -sub heap { - my ($self) = @_; - return $self->{heap}; -} - -=item B - -This function sends a message to the server. C<@ircmsg> is the argumentlist -for C. - -=cut - -sub send_msg { - my ($self, @msg) = @_; - my $data = mk_msg (@msg); - - my ($host, $port) = ($self->{h}, $self->{p}); - $self->{outbuf} .= $data; - - unless (defined $self->{ww}) { - my $sock = $self->{s}; - $self->{ww} = - AnyEvent->io (poll => 'w', fh => $sock, cb => sub { - my $l = syswrite $sock, $self->{outbuf}; - - substr $self->{outbuf}, 0, $l, ""; - - if (length ($self->{outbuf}) == 0) { delete $self->{ww} } - - unless ($l) { - # XXX: is this behaviour correct or ok? - $self->disconnect_server ("Error while writing to IRC server '$host:$port': $!"); - return; - } - }); - } -} - -=item B - -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: I - -If C<$cmd> starts with 'irc_' the callback C<$cb> will be registered -for a IRC protocol command. The command is the suffix of C<$cmd> then. -The second argument to the callback is the message hash reference -that has the layout that is returned by C. - -EXAMPLE: - - $con->reg_cb (irc_privmsg => \&privmsg_handler); - # privmsg_handler will be called if an IRC message - # with the command 'PRIVMSG' arrives. - -If C<$cmd> is not prefixed with a 'irc_' it will be called when an event -with the name C<$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 C. - -=over 4 - -=item B - -This event will be generated if the connection is somehow terminated. -It will also be emitted when C is called. -The second argument to the callback is C<$reason>, a string that contains -a clue about why the connection terminated. - =back -=cut - -sub reg_cb { - my ($self, $cmd, $cb) = @_; - - if ($cmd =~ m/^irc_(\S+)/i) { - push @{$self->{cbs}->{lc $1}}, $cb; - - } else { - push @{$self->{events}->{$cmd}}, $cb; - } - - 1; -} - -=item B - -This function emits an event with the name C<$event> and the arguments C<@args>. -The registerd callback that has been registered with C will be called -with the first argument being the connection object and the rest of the arguments -being C<@args>. - -EXAMPLE - - $con->reg_cb (test_event => sub { print "Yay, i love $_[1]!!\n"); - $con->event (test_event => "IRC"); +=head1 EXAMPLES - # will print "Yay, i love IRC!!\n" - -=cut - -sub event { - my ($self, $ev, @arg) = @_; - - my $nxt = []; - - for (@{$self->{events}->{lc $ev}}) { - $_->($self, @arg) and push @$nxt, $_; - } - - $self->{events}->{lc $ev} = $nxt; -} - -# internal function, called by the read callbacks above. -sub feed_irc_data { - my ($self, $data) = @_; - - $self->{buffer} .= $data; - - my @msg; - while ($self->{buffer} =~ s/^([^\015\012]*)\015?\012//) { - push @msg, $1; - } - - for (@msg) { - my $m = parse_irc_msg ($_); - - my $nxt = []; - - for (@{$self->{cbs}->{lc $m->{command}}}) { - $_->($self, $m) and push @$nxt, $_; - } - - $self->{cbs}->{lc $m->{command}} = $nxt; - - $nxt = []; - - for (@{$self->{cbs}->{'*'}}) { - $_->($self, $m) and push @$nxt, $_; - } - - $self->{cbs}->{'*'} = $nxt; - } -} - - -=back +See the samples/ directory for some examples on how to use Net::IRC3. =head1 AUTHOR @@ -508,6 +305,10 @@ =head1 SEE ALSO +L + +L + RFC 2812 - Internet Relay Chat: Client Protocol =head1 BUGS