[ViewVC] Annotation of: cvs/Net-IRC3/README

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

VERSION
    Version 0.21

SYNOPSIS
       use Net::IRC3;

       my $irc3 = new Net::IRC3;

       my $con = $irc3->connect ("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.

    Note that this module uses AnyEvent as it's IO event subsystem. You can
    integrate Net::IRC3 into any GUI application that AnyEvent has support
    for.

METHODS
    new ()
        This just creates a Net::IRC3 object, which is a management class
        for creating and managing connections.

    connect ($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).

    connections ()
        Returns a key value list, where the key is "$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.

    connection ($host, $port) or connection ("$host:$port")
        Returns the Net::IRC3::Connection object for the $host $port pair.
        If no such connection exists, undef is returned.

FUNCTIONS
    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/;

    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!)

           :<prefix> <command> <params> :<trail>

        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:

           mk_msg (undef, "PRIVMSG", "you suck!", "magnus");
           # will return: "PRIVMSG magnus :you suck!\015\012"

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

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

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

SEE ALSO
    Net::IRC3::Connection

    Net::IRC3::Client

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

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
        <http://annocpan.org/dist/Net-IRC3>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/Net-IRC3>

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IRC3>

    * Search CPAN
        <http://search.cpan.org/dist/Net-IRC3>

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.

Revision:	1.4
Committed:	Sun Jul 16 11:50:58 2006 UTC (20 years, 2 months ago) by elmex
Branch:	MAIN
Changes since 1.3:	+5 -1 lines
Log Message:	added AnyEvent dependency to Makefile.PL and documented it.
#	User	Rev	Content
1	elmex	1.1	NAME
2			Net::IRC3 - An IRC Protocol module which is event system independend
3
4			VERSION
5	elmex	1.4	Version 0.21
6	elmex	1.1
7			SYNOPSIS
8	elmex	1.2	use Net::IRC3;
9
10	elmex	1.1	my $irc3 = new Net::IRC3;
11
12	elmex	1.3	my $con = $irc3->connect ("test.not.at.irc.net", 6667);
13	elmex	1.1
14			...
15
16	elmex	1.2	DESCRIPTION
17			Net::IRC3 itself is a simple building block for an IRC client. It
18			manages connections and parses and constructs IRC messages.
19
20			Net::IRC3 is very simple, if you don't want to care about all the
21			other things that a client still has to do (like replying to PINGs and
22			remembering who is on a channel), I recommend to read the
23			Net::IRC3::Client page instead.
24
25	elmex	1.4	Note that this module uses AnyEvent as it's IO event subsystem. You can
26			integrate Net::IRC3 into any GUI application that AnyEvent has support
27			for.
28
29	elmex	1.2	METHODS
30			new ()
31			This just creates a Net::IRC3 object, which is a management class
32			for creating and managing connections.
33
34	elmex	1.3	connect ($host, $port)
35	elmex	1.2	Tries to open a socket to the host $host and the port $port. If
36			successfull it will return a Net::IRC3::Connection object. If an
37			error occured it will die (use eval to catch the exception).
38
39	elmex	1.3	connections ()
40			Returns a key value list, where the key is "$host:$port" and the
41			value is the connection object. Only 'active' connections are
42			returned. That means, if a connection is terminated somehow, it will
43			also disappear from this list.
44
45			connection ($host, $port) or connection ("$host:$port")
46			Returns the Net::IRC3::Connection object for the $host $port pair.
47			If no such connection exists, undef is returned.
48
49	elmex	1.2	FUNCTIONS
50			These are some utility functions that might come in handy when handling
51			the IRC protocol.
52
53	elmex	1.3	You can export these with eg.:
54
55			use Net::IRC3 qw/parse_irc_msg/;
56
57	elmex	1.2	parse_irc_msg ($ircline)
58			This method parses the $ircline, which is one line of the IRC
59			protocol without the trailing "\015\012".
60
61			It returns a hash which has the following entrys:
62
63			prefix
64			The message prefix.
65
66			command
67			The IRC command.
68
69			params
70			The parameters to the IRC command in a array reference, this
71			includes the trailing parameter (the one after the ':' or the
72			14th parameter).
73
74			trailing
75			This is set if there was a trailing parameter (the one after the
76			':' or the 14th parameter).
77
78			mk_msg ($prefix, $command, $trailing, @params)
79			This function assembles a IRC message. The generated message will
80			look like (pseudo code!)
81
82			:<prefix> <command> <params> :<trail>
83
84			Please refer to RFC 2812 how IRC messages normally look like.
85
86			The prefix and the trailing string will be omitted if they are
87			"undef".
88
89			EXAMPLES:
90
91	elmex	1.3	mk_msg (undef, "PRIVMSG", "you suck!", "magnus");
92	elmex	1.2	# will return: "PRIVMSG magnus :you suck!\015\012"
93
94	elmex	1.3	mk_msg (undef, "JOIN", undef, "#test");
95	elmex	1.2	# will return: "JOIN #magnus\015\012"
96
97			split_prefix ($prefix)
98			This function splits an IRC user prefix as described by RFC 2817
99			into the three parts: nickname, user and host. Which will be
100			returned as a list with that order.
101
102			$prefix can also be a hash like it is returned by "parse_irc_msg".
103
104			prefix_nick ($prefix)
105			A shortcut to extract the nickname from the $prefix.
106
107			$prefix can also be a hash like it is returned by "parse_irc_msg".
108
109			prefix_user ($prefix)
110			A shortcut to extract the username from the $prefix.
111
112			$prefix can also be a hash like it is returned by "parse_irc_msg".
113
114			prefix_host ($prefix)
115			A shortcut to extract the hostname from the $prefix.
116
117			$prefix can also be a hash like it is returned by "parse_irc_msg".
118
119	elmex	1.3	EXAMPLES
120			See the samples/ directory for some examples on how to use Net::IRC3.
121	elmex	1.2
122	elmex	1.3	AUTHOR
123			Robin Redeker, "<elmex@ta-sa.org>"
124	elmex	1.2
125	elmex	1.3	SEE ALSO
126			Net::IRC3::Connection
127	elmex	1.2
128	elmex	1.3	Net::IRC3::Client
129	elmex	1.2
130	elmex	1.3	RFC 2812 - Internet Relay Chat: Client Protocol
131	elmex	1.1
132			BUGS
133	elmex	1.3	Please report any bugs or feature requests to "bug-net-irc3 at
134			rt.cpan.org", or through the web interface at
135			<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IRC3>. I will be
136			notified, and then you'll automatically be notified of progress on your
137			bug as I make changes.
138	elmex	1.1
139			SUPPORT
140	elmex	1.3	You can find documentation for this module with the perldoc command.
141	elmex	1.1
142	elmex	1.3	perldoc Net::IRC3
143	elmex	1.1
144	elmex	1.3	You can also look for information at:
145	elmex	1.1
146	elmex	1.3	* AnnoCPAN: Annotated CPAN documentation
147			<http://annocpan.org/dist/Net-IRC3>
148	elmex	1.1
149	elmex	1.3	* CPAN Ratings
150			<http://cpanratings.perl.org/d/Net-IRC3>
151	elmex	1.1
152	elmex	1.3	* RT: CPAN's request tracker
153			<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IRC3>
154	elmex	1.1
155	elmex	1.3	* Search CPAN
156			<http://search.cpan.org/dist/Net-IRC3>
157	elmex	1.1
158			ACKNOWLEDGEMENTS
159	elmex	1.3	Thanks to Marc Lehmann for the new AnyEvent module!
160	elmex	1.1
161			COPYRIGHT & LICENSE
162	elmex	1.3	Copyright 2006 Robin Redker, all rights reserved.
163	elmex	1.1
164	elmex	1.3	This program is free software; you can redistribute it and/or modify it
165			under the same terms as Perl itself.
166	elmex	1.1