NAME POEx::IRC::Client::Lite - Minimalist POE IRC interface SYNOPSIS package MyClient; use POE; use POEx::IRC::Client::Lite; use IRC::Toolkit; our @channels = ( '#otw', '#eris' ); POE::Session->create( package_states => [ MyClient => [ qw/ _start recv_irc_001 recv_irc_public_msg recv_irc_ctcp_version / ], ], ); sub _start { my ($kern, $heap) = @_[KERNEL, HEAP]; $heap->{irc} = POEx::IRC::Client::Lite->new( event_prefix => 'recv_', server => "irc.perl.org", nick => "MyNick", username => "myuser", ); $heap->{irc}->connect; } sub recv_irc_001 { my ($kern, $heap) = @_[KERNEL, HEAP]; $heap->{irc}->join(@channels)->privmsg( join(',', @channels), "hello!" ); } sub recv_irc_public_msg { my ($kern, $heap) = @_[KERNEL, HEAP]; my $event = $_[ARG0]; my ($target, $string) = @{ $event->params }; my $from = parse_user( $event->prefix ); if (lc($string||'') eq 'hello') { $heap->{irc}->privmsg($target, "hello there, $from") } } sub recv_irc_ctcp_version { my ($kern, $heap) = @_[KERNEL, HEAP]; my $event = $_[ARG0]; my $from = parse_user( $event->prefix ); $heap->{irc}->notice( $from => ctcp_quote("VERSION a silly Client::Lite example") ); } DESCRIPTION A light-weight, pluggable IRC client library using POEx::IRC::Backend and IRC::Toolkit. No state is maintained; POEx::IRC::Client::Lite provides a minimalist interface to IRC and serves as a base class for stateful clients. This is early development software pulled out of a much larger in-progress project. See POE::Component::IRC for a more mature POE IRC client library. new my $irc = POEx::IRC::Client::Lite->new( event_prefix => $prefix, server => $server, nick => $nickname, username => $username, ); Create a new Client::Lite instance. Optional arguments are: bindaddr Local address to bind to. ipv6 Boolean value indicating whether to prefer IPv6. port Remote port to use (defaults to 6667). reconnect Reconnection attempt delay, in seconds. stop $irc->stop; Disconnect, stop the Emitter, and purge the plugin pipeline. IRC Methods IRC-related methods can be called via normal method dispatch or sent as a POE event: ## These are equivalent: $irc->send( $ircevent ); $irc->yield( 'send', $ircevent ); $poe_kernel->post( $irc->session_id, 'send', $ircevent ); Methods that dispatch to IRC return $self, so they can be chained: $irc->connect->join(@channels)->privmsg( join(',', @channels), 'hello there!' ); connect $irc->connect; Attempt an outgoing connection. disconnect $irc->disconnect($message); Quit IRC and shut down the wheel. send use IRC::Message::Object 'ircmsg'; $irc->send( ircmsg( command => 'oper', params => [ $user, $passwd ], ) ); ## ... or a raw HASH: $irc->send( { command => 'oper', params => [ $user, $passwd ], } ) ## ... or a raw line: $irc->send_raw_line('PRIVMSG avenj :some things'); Use "send()" to send an IRC::Message::Object or a compatible HASH; this method will also take a list of events in either of those formats. send_raw_line Use "send_raw_line()" to send a single raw IRC line. This is rarely a good idea; POEx::IRC::Backend provides an IRCv3-capable filter. set_nick $irc->set_nick( $new_nick ); Attempt to change the current nickname. privmsg $irc->privmsg( $target, $string ); Sends a PRIVMSG to the specified target. notice $irc->notice( $target, $string ); Sends a NOTICE to the specified target. ctcp $irc->ctcp( $target, $type, @params ); Encodes and sends a CTCP request to the target. (To send a CTCP reply, send a "notice" that has been quoted via "ctcp_quote" in IRC::Toolkit::CTCP.) mode $irc->mode( $channel, $modestring ); Sends a MODE for the specified target. Takes a channel name as a string and a mode change as either a string or an IRC::Mode::Set. join $irc->join( $channel ); Attempts to join the specified channel. part $irc->part( $channel, $message ); Attempts to leave the specified channel with an optional PART message. Attributes conn The POEx::IRC::Backend::Connect instance for our connection. nick The nickname we were spawned with. This class doesn't track nick changes; if our nick is changed later, ->nick() is not updated. server The server we were instructed to connect to. Emitted Events All IRC events are emitted as 'irc_$cmd' e.g. 'irc_005' (ISUPPORT) or 'irc_mode' with a few notable exceptions, detailed below. $_[ARG0] is the IRC::Message::Object. irc_connector_killed Emitted if a connection is terminated during "preregister". $_[ARG0] is the POEx::IRC::Backend::Connect object. irc_private_message Emitted for PRIVMSG-type messages not covered by "irc_public_message". irc_public_message Emitted for PRIVMSG-type messages that appear to be destined for a channel target. irc_ctcp_TYPE Emitted for incoming CTCP requests. TYPE is the request type, such as 'version' $_[ARG0] is the IRC::Message::Object produced by "ctcp_extract" in IRC::Toolkit::CTCP. An example of sending a CTCP reply lives in "SYNOPSIS". See IRC::Toolkit::CTCP for CTCP-related helpers. irc_ctcpreply_TYPE Emitted for incoming CTCP replies. Mirrors the behavior of "irc_ctcp_TYPE" irc_disconnected Emitted when an IRC connection has been disconnected at the backend. $_[ARG0] is the disconnect string from POEx::IRC::Backend. $_[ARG1] is the POEx::IRC::Backend::Connect that was disconnected. Pluggable Events These are events explicitly dispatched to plugins via "process" in MooX::Role::POE::Emitter; see MooX::Role::POE::Emitter and MooX::Role::Pluggable for more on making use of plugins. preregister Dispatched to plugins when an outgoing connection has been established, but prior to registration. The first argument is the POEx::IRC::Backend::Connect object. Returning EAT_ALL (see MooX::Role::Pluggable::Constants) to Client::Lite will terminate the connection without registering. outgoing Dispatched to plugins prior to sending output. The first argument is the item being sent. Note that no sanity checks are performed on the item(s) at this stage (this is done after items are passed to the POEx::IRC::Backend instance) -- your plugin's handler could receive a HASH, an IRC::Message::Object, a raw line, or something invalid. Returning EAT_ALL will skip sending the item. SEE ALSO POE::Component::IRC, a fully-featured POE IRC client library IRC::Toolkit POEx::IRC::Backend POE::Filter::IRCv3 MooX::Role::POE::Emitter MooX::Role::Pluggable AUTHOR Jon Portnoy