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

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

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

           $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, "<elmex@ta-sa.org>"

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
        <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.2
Committed:	Sun Jul 16 02:41:37 2006 UTC (20 years, 2 months ago) by elmex
Branch:	MAIN
Changes since 1.1:	+181 -21 lines
Log Message:	some major change on the module layout
#	User	Rev	Content
1	elmex	1.1	NAME
2			Net::IRC3 - An IRC Protocol module which is event system independend
3
4			VERSION
5			Version 0.01
6
7			SYNOPSIS
8	elmex	1.2	use Net::IRC3;
9
10	elmex	1.1	my $irc3 = new Net::IRC3;
11
12			my $con = $irc3->connect_server ("test.not.at.irc.net", 6667);
13
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			METHODS
26			new ()
27			This just creates a Net::IRC3 object, which is a management class
28			for creating and managing connections.
29
30			connect_server ($host, $port)
31			Tries to open a socket to the host $host and the port $port. If
32			successfull it will return a Net::IRC3::Connection object. If an
33			error occured it will die (use eval to catch the exception).
34
35			FUNCTIONS
36			These are some utility functions that might come in handy when handling
37			the IRC protocol.
38
39			parse_irc_msg ($ircline)
40			This method parses the $ircline, which is one line of the IRC
41			protocol without the trailing "\015\012".
42
43			It returns a hash which has the following entrys:
44
45			prefix
46			The message prefix.
47
48			command
49			The IRC command.
50
51			params
52			The parameters to the IRC command in a array reference, this
53			includes the trailing parameter (the one after the ':' or the
54			14th parameter).
55
56			trailing
57			This is set if there was a trailing parameter (the one after the
58			':' or the 14th parameter).
59
60			mk_msg ($prefix, $command, $trailing, @params)
61			This function assembles a IRC message. The generated message will
62			look like (pseudo code!)
63
64			:<prefix> <command> <params> :<trail>
65
66			Please refer to RFC 2812 how IRC messages normally look like.
67
68			The prefix and the trailing string will be omitted if they are
69			"undef".
70
71			EXAMPLES:
72
73			$con->mk_msg (undef, "PRIVMSG", "you suck!", "magnus");
74			# will return: "PRIVMSG magnus :you suck!\015\012"
75
76			$con->mk_msg (undef, "JOIN", undef, "#test");
77			# will return: "JOIN #magnus\015\012"
78
79			split_prefix ($prefix)
80			This function splits an IRC user prefix as described by RFC 2817
81			into the three parts: nickname, user and host. Which will be
82			returned as a list with that order.
83
84			$prefix can also be a hash like it is returned by "parse_irc_msg".
85
86			prefix_nick ($prefix)
87			A shortcut to extract the nickname from the $prefix.
88
89			$prefix can also be a hash like it is returned by "parse_irc_msg".
90
91			prefix_user ($prefix)
92			A shortcut to extract the username from the $prefix.
93
94			$prefix can also be a hash like it is returned by "parse_irc_msg".
95
96			prefix_host ($prefix)
97			A shortcut to extract the hostname from the $prefix.
98
99			$prefix can also be a hash like it is returned by "parse_irc_msg".
100
101			Net::IRC3::Connection
102			The connection class. Here the actual interesting stuff can be done,
103			such as sending and receiving IRC messages.
104
105			METHODS
106			disconnect_server ($reason)
107			Unregisters the connection in the main Net::IRC3 object, closes
108			the sockets and send a 'disconnect' event with $reason as
109			argument.
110
111			heap ()
112			Returns a hash reference that is local to this connection object
113			that lets you store any information you want.
114
115			send_msg (@ircmsg)
116			This function sends a message to the server. @ircmsg is the
117			argumentlist for "mk_msg".
118
119			reg_cb ($cmd, $cb)
120			This registers a callback in the connection class. These
121			callbacks will be called by internal events and by IRC protocol
122			commands.
123
124			The first argument to the callbacks is always the connection
125			object itself.
126
127			If a callback returns a false value, it will be unregistered.
128
129			NOTE: A callback has to return true to stay alive
130
131			If $cmd starts with 'irc_' the callback $cb will be registered
132			for a IRC protocol command. The command is the suffix of $cmd
133			then. The second argument to the callback is the message hash
134			reference that has the layout that is returned by
135			"parse_irc_msg".
136
137			EXAMPLE:
138
139			$con->reg_cb (irc_privmsg => \&privmsg_handler);
140			# privmsg_handler will be called if an IRC message
141			# with the command 'PRIVMSG' arrives.
142
143			If $cmd is not prefixed with a 'irc_' it will be called when an
144			event with the name $cmd is emitted. The arguments to the
145			callback depend on the event that is emitted (but remember: the
146			first argument will always be the connection object)
147
148			Following events are emitted by this module and shouldn't be
149			emitted from a module user call to "event".
150
151			disconnect $reason
152			This event will be generated if the connection is somehow
153			terminated. It will also be emitted when "disconnect_server"
154			is called. The second argument to the callback is $reason, a
155			string that contains a clue about why the connection
156			terminated.
157
158			event ($event, @args)
159			This function emits an event with the name $event and the
160			arguments @args. The registerd callback that has been registered
161			with "reg_cb" will be called with the first argument being the
162			connection object and the rest of the arguments being @args.
163
164			EXAMPLE
165
166			$con->reg_cb (test_event => sub { print "Yay, i love $_[1]!!\n");
167			$con->event (test_event => "IRC");
168
169			# will print "Yay, i love IRC!!\n"
170
171	elmex	1.1	AUTHOR
172	elmex	1.2	Robin Redeker, "<elmex@ta-sa.org>"
173
174			SEE ALSO
175			RFC 2812 - Internet Relay Chat: Client Protocol
176	elmex	1.1
177			BUGS
178	elmex	1.2	Please report any bugs or feature requests to "bug-net-irc3 at
179			rt.cpan.org", or through the web interface at
180			<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IRC3>. I will be
181			notified, and then you'll automatically be notified of progress on
182			your bug as I make changes.
183	elmex	1.1
184			SUPPORT
185	elmex	1.2	You can find documentation for this module with the perldoc command.
186	elmex	1.1
187	elmex	1.2	perldoc Net::IRC3
188	elmex	1.1
189	elmex	1.2	You can also look for information at:
190	elmex	1.1
191	elmex	1.2	* AnnoCPAN: Annotated CPAN documentation
192			<http://annocpan.org/dist/Net-IRC3>
193	elmex	1.1
194	elmex	1.2	* CPAN Ratings
195			<http://cpanratings.perl.org/d/Net-IRC3>
196	elmex	1.1
197	elmex	1.2	* RT: CPAN's request tracker
198			<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-IRC3>
199	elmex	1.1
200	elmex	1.2	* Search CPAN
201			<http://search.cpan.org/dist/Net-IRC3>
202	elmex	1.1
203			ACKNOWLEDGEMENTS
204	elmex	1.2	Thanks to Marc Lehmann for the new AnyEvent module!
205	elmex	1.1
206			COPYRIGHT & LICENSE
207	elmex	1.2	Copyright 2006 Robin Redker, all rights reserved.
208	elmex	1.1
209	elmex	1.2	This program is free software; you can redistribute it and/or modify
210			it under the same terms as Perl itself.
211	elmex	1.1