lib/Net/IRC3.pm

package Net::IRC3;
use strict;
use AnyEvent;
use IO::Socket::INET;

our $ConnectionClass = 'Net::IRC3::Connection';

=head1 NAME

Net::IRC3 - An IRC Protocol module which is event system independend

=head1 VERSION

Version 0.21

=cut

our $VERSION = '0.21';

=head1 SYNOPSIS

   use Net::IRC3;

   my $irc3 = new Net::IRC3;

   my $con = $irc3->connect ("test.not.at.irc.net", 6667);

   ...

=head1 DESCRIPTION

L<Net::IRC3> itself is a simple building block for an IRC client.
It manages connections and parses and constructs IRC messages.

L<Net::IRC3> is I<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 L<Net::IRC3::Client> page instead.

Note that this module uses AnyEvent as it's IO event subsystem.
You can integrate Net::IRC3 into any application with a event system
that AnyEvent has support for (eg. L<Gtk2> or L<Event>).

=head1 METHODS

=over 4

=item B<new ()>

This just creates a L<Net::IRC3> object, which is a management
class for creating and managing connections.

=cut

sub new
{
  my $this = shift;
  my $class = ref($this) || $this;

  my $self = { };

  bless $self, $class;

  return $self;
}

=item B<connect ($host, $port)>

Tries to open a socket to the host C<$host> and the port C<$port>.
If successfull it will return a L<Net::IRC3::Connection> object.
If an error occured it will die (use eval to catch the exception).

=cut

sub connect {
   my ($self, $host, $port) = @_;

   defined $self->{connections}->{"$host:$port"}
      and return;

   my $sock = IO::Socket::INET->new (
      PeerAddr => $host,
      PeerPort => $port,
      Proto    => 'tcp',
      Blocking => 0
   ) or die "couldn't connect to irc server '$host:$port': $!\n";;

   eval "require $ConnectionClass";
   my $con = $ConnectionClass->new ($self, $sock, $host, $port);

   $con->{rw} =
      AnyEvent->io (poll => 'r', fh => $sock, cb => sub {
         my $l = sysread $sock, my $data, 1024;

         $con->feed_irc_data ($data);

         unless ($l) {

            if (defined $l) {
               $con->disconnect ("EOF from IRC server '$host:$port'");
               return;

            } else {
               $con->disconnect ("Error while reading from IRC server '$host:$port': $!");
               return;
            }
         }
      });

   return $con;
}

=item B<connections ()>

Returns a key value list, where the key is C<"$host:$port"> and the
value is the connection object. Only 'active' connections are returned.
That means, if a connection is terminated somehow, it will also disappear
from this list.

=cut

sub connections {
   my ($self) = @_;
   return %{$self->{connections}};
}

=item B<connection ($host, $port)> or B<connection ("$host:$port")>

Returns the L<Net::IRC3::Connection> object for the C<$host> C<$port>
pair. If no such connection exists, undef is returned.

=cut

sub connection {
   my ($self, $host, $port) = @_;
   if ($host =~ m/^[^:]+:(\d+)$/) {
      return $self->{connections}->{$host}
   } else {
      return $self->{connections}->{$host.':'.$port}
   }
}

=back

=head1 EXAMPLES

See the samples/ directory for some examples on how to use Net::IRC3.

=head1 AUTHOR

Robin Redeker, C<< <elmex@ta-sa.org> >>

=head1 SEE ALSO

L<Net::IRC3::Connection>

L<Net::IRC3::Client>

L<AnyEvent>

RFC 2812 - Internet Relay Chat: Client Protocol

=head1 BUGS

Please report any bugs or feature requests to
C<bug-net-irc3 at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IRC3>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::IRC3

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Net-IRC3>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Net-IRC3>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IRC3>

=item * Search CPAN

L<http://search.cpan.org/dist/Net-IRC3>

=back

=head1 ACKNOWLEDGEMENTS

Thanks to Marc Lehmann for the new AnyEvent module!

=head1 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.

=cut

1;
Revision:	1.6
Committed:	Sun Jul 16 19:44:50 2006 UTC (20 years, 2 months ago) by elmex
Branch:	MAIN
Changes since 1.5:	+0 -210 lines
Log Message:	moved utilitys to Util.pm and fixed a bug in nick chasing
#	User	Rev	Content
1	elmex	1.1	package Net::IRC3;
2			use strict;
3			use AnyEvent;
4			use IO::Socket::INET;
5	elmex	1.2
6	elmex	1.3	our $ConnectionClass = 'Net::IRC3::Connection';
7	elmex	1.2
8	elmex	1.1	=head1 NAME
9
10			Net::IRC3 - An IRC Protocol module which is event system independend
11
12			=head1 VERSION
13
14	elmex	1.4	Version 0.21
15	elmex	1.1
16			=cut
17
18	elmex	1.4	our $VERSION = '0.21';
19	elmex	1.1
20			=head1 SYNOPSIS
21
22			use Net::IRC3;
23
24			my $irc3 = new Net::IRC3;
25
26	elmex	1.3	my $con = $irc3->connect ("test.not.at.irc.net", 6667);
27	elmex	1.1
28			...
29
30			=head1 DESCRIPTION
31
32			L<Net::IRC3> itself is a simple building block for an IRC client.
33			It manages connections and parses and constructs IRC messages.
34
35			L<Net::IRC3> is I<very> simple, if you don't want to care about
36			all the other things that a client still has to do (like replying to
37			PINGs and remembering who is on a channel), I recommend to read
38			the L<Net::IRC3::Client> page instead.
39
40	elmex	1.4	Note that this module uses AnyEvent as it's IO event subsystem.
41			You can integrate Net::IRC3 into any application with a event system
42			that AnyEvent has support for (eg. L<Gtk2> or L<Event>).
43
44	elmex	1.1	=head1 METHODS
45
46			=over 4
47
48			=item B<new ()>
49
50			This just creates a L<Net::IRC3> object, which is a management
51			class for creating and managing connections.
52
53			=cut
54
55			sub new
56			{
57			my $this = shift;
58			my $class = ref($this) \|\| $this;
59
60			my $self = { };
61
62			bless $self, $class;
63
64			return $self;
65			}
66
67	elmex	1.3	=item B<connect ($host, $port)>
68	elmex	1.1
69			Tries to open a socket to the host C<$host> and the port C<$port>.
70	elmex	1.2	If successfull it will return a L<Net::IRC3::Connection> object.
71	elmex	1.1	If an error occured it will die (use eval to catch the exception).
72
73			=cut
74
75	elmex	1.3	sub connect {
76	elmex	1.1	my ($self, $host, $port) = @_;
77
78			defined $self->{connections}->{"$host:$port"}
79			and return;
80
81			my $sock = IO::Socket::INET->new (
82			PeerAddr => $host,
83			PeerPort => $port,
84			Proto => 'tcp',
85			Blocking => 0
86			) or die "couldn't connect to irc server '$host:$port': $!\n";;
87
88	elmex	1.3	eval "require $ConnectionClass";
89			my $con = $ConnectionClass->new ($self, $sock, $host, $port);
90	elmex	1.1
91			$con->{rw} =
92			AnyEvent->io (poll => 'r', fh => $sock, cb => sub {
93			my $l = sysread $sock, my $data, 1024;
94
95			$con->feed_irc_data ($data);
96
97			unless ($l) {
98
99			if (defined $l) {
100	elmex	1.3	$con->disconnect ("EOF from IRC server '$host:$port'");
101	elmex	1.1	return;
102
103			} else {
104	elmex	1.3	$con->disconnect ("Error while reading from IRC server '$host:$port': $!");
105	elmex	1.1	return;
106			}
107			}
108			});
109
110			return $con;
111			}
112
113	elmex	1.3	=item B<connections ()>
114
115			Returns a key value list, where the key is C<"$host:$port"> and the
116			value is the connection object. Only 'active' connections are returned.
117			That means, if a connection is terminated somehow, it will also disappear
118			from this list.
119
120			=cut
121
122			sub connections {
123			my ($self) = @_;
124			return %{$self->{connections}};
125			}
126
127			=item B<connection ($host, $port)> or B<connection ("$host:$port")>
128
129			Returns the L<Net::IRC3::Connection> object for the C<$host> C<$port>
130			pair. If no such connection exists, undef is returned.
131
132			=cut
133
134			sub connection {
135			my ($self, $host, $port) = @_;
136			if ($host =~ m/^[^:]+:(\d+)$/) {
137			return $self->{connections}->{$host}
138			} else {
139			return $self->{connections}->{$host.':'.$port}
140			}
141			}
142
143	elmex	1.1	=back
144
145	elmex	1.2	=head1 EXAMPLES
146	elmex	1.1
147	elmex	1.2	See the samples/ directory for some examples on how to use Net::IRC3.
148	elmex	1.1
149			=head1 AUTHOR
150
151			Robin Redeker, C<< <elmex@ta-sa.org> >>
152
153			=head1 SEE ALSO
154
155	elmex	1.2	L<Net::IRC3::Connection>
156
157			L<Net::IRC3::Client>
158
159	elmex	1.4	L<AnyEvent>
160
161	elmex	1.1	RFC 2812 - Internet Relay Chat: Client Protocol
162
163			=head1 BUGS
164
165			Please report any bugs or feature requests to
166			C<bug-net-irc3 at rt.cpan.org>, or through the web interface at
167			L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IRC3>.
168			I will be notified, and then you'll automatically be notified of progress on
169			your bug as I make changes.
170
171			=head1 SUPPORT
172
173			You can find documentation for this module with the perldoc command.
174
175			perldoc Net::IRC3
176
177			You can also look for information at:
178
179			=over 4
180
181			=item * AnnoCPAN: Annotated CPAN documentation
182
183			L<http://annocpan.org/dist/Net-IRC3>
184
185			=item * CPAN Ratings
186
187			L<http://cpanratings.perl.org/d/Net-IRC3>
188
189			=item * RT: CPAN's request tracker
190
191			L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IRC3>
192
193			=item * Search CPAN
194
195			L<http://search.cpan.org/dist/Net-IRC3>
196
197			=back
198
199			=head1 ACKNOWLEDGEMENTS
200
201			Thanks to Marc Lehmann for the new AnyEvent module!
202
203			=head1 COPYRIGHT & LICENSE
204
205			Copyright 2006 Robin Redker, all rights reserved.
206
207			This program is free software; you can redistribute it and/or modify it
208			under the same terms as Perl itself.
209
210			=cut
211
212			1;