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 <avenj@cobaltirc.org>