# 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 very thin (but pluggable / extensible) IRC client library using
[POEx::IRC::Backend](https://metacpan.org/pod/POEx::IRC::Backend) and [IRC::Toolkit](https://metacpan.org/pod/IRC::Toolkit) on top of
[MooX::Role::POE::Emitter](https://metacpan.org/pod/MooX::Role::POE::Emitter) and [MooX::Role::Pluggable](https://metacpan.org/pod/MooX::Role::Pluggable).

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](https://metacpan.org/pod/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).

- ssl

    Boolean value indicating whether to (attempt to) connect via SSL.

    Requires [POE::Component::SSLify](https://metacpan.org/pod/POE::Component::SSLify).

- ssl\_opts

    An `ARRAY` containing SSL options passed along to [POE::Component::SSLify](https://metacpan.org/pod/POE::Component::SSLify)
    via [POEx::IRC::Backend](https://metacpan.org/pod/POEx::IRC::Backend); see [POE::Component::SSLify](https://metacpan.org/pod/POE::Component::SSLify) & [Net::SSLeay](https://metacpan.org/pod/Net::SSLeay).

    Not required for basic SSL operation; setting ["ssl"](#ssl) to a true value should
    work for most users.

- reconnect

    Reconnection attempt delay, in seconds.

    **Automatic reconnection is only triggered when an outgoing connector fails!**

    You can trigger a reconnection in your own code by handling
    ["irc\_disconnected"](#irc_disconnected) events. For example:

        sub irc_disconnected {
          # Immediate reconnect; you may want to use a timer (to avoid being banned)
          # Assuming our IRC component's object lives in our session's HEAP:
          $_[HEAP]->{irc}->connect
        }

## 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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"](#notice) that has been quoted via
["ctcp\_quote" in IRC::Toolkit::CTCP](https://metacpan.org/pod/IRC::Toolkit::CTCP#ctcp_quote).)

### 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](https://metacpan.org/pod/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](https://metacpan.org/pod/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

## IRC 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](https://metacpan.org/pod/IRC::Message::Object).

## Special events

### irc\_connected

Emitted when a connection has been successfully opened.

This does not indicate successful server registration, only that the
connection has been opened and registration details have been sent.

`$_[ARG0]` is the [POEx::IRC::Backend::Connect](https://metacpan.org/pod/POEx::IRC::Backend::Connect) object.

### irc\_connector\_failed

Emitted if an outgoing connection could not be established.

`@_[ARG0 .. ARG3]` are the operation, errno, and error string passed in
by [POEx::IRC::Backend](https://metacpan.org/pod/POEx::IRC::Backend); see ["ircsock\_connector\_failure" in POEx::IRC::Backend](https://metacpan.org/pod/POEx::IRC::Backend#ircsock_connector_failure).

### irc\_connector\_killed

Emitted if a connection is terminated during ["preregister"](#preregister).

`$_[ARG0]` is the [POEx::IRC::Backend::Connect](https://metacpan.org/pod/POEx::IRC::Backend::Connect) object.

### irc\_private\_message

Emitted for PRIVMSG-type messages not covered by ["irc\_public\_message"](#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](https://metacpan.org/pod/IRC::Message::Object) produced by
["ctcp\_extract" in IRC::Toolkit::CTCP](https://metacpan.org/pod/IRC::Toolkit::CTCP#ctcp_extract).

An example of sending a CTCP reply lives in ["SYNOPSIS"](#synopsis).
See [IRC::Toolkit::CTCP](https://metacpan.org/pod/IRC::Toolkit::CTCP) for CTCP-related helpers.

### irc\_ctcpreply\_TYPE

Emitted for incoming CTCP replies.

Mirrors the behavior of ["irc\_ctcp\_TYPE"](#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](https://metacpan.org/pod/POEx::IRC::Backend).

`$_[ARG1]` is the [POEx::IRC::Backend::Connect](https://metacpan.org/pod/POEx::IRC::Backend::Connect) that was disconnected.

# Pluggable Events

These are events explicitly dispatched to plugins 
via ["process" in MooX::Role::POE::Emitter](https://metacpan.org/pod/MooX::Role::POE::Emitter#process); 
see [MooX::Role::POE::Emitter](https://metacpan.org/pod/MooX::Role::POE::Emitter) and [MooX::Role::Pluggable](https://metacpan.org/pod/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](https://metacpan.org/pod/POEx::IRC::Backend::Connect) object.

Returning EAT\_ALL (see [MooX::Role::Pluggable::Constants](https://metacpan.org/pod/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](https://metacpan.org/pod/POEx::IRC::Backend) instance) -- your plugin's handler could receive a
HASH, an [IRC::Message::Object](https://metacpan.org/pod/IRC::Message::Object), a raw line, or something invalid.

Returning EAT\_ALL will skip sending the item.

# SEE ALSO

[POE::Component::IRC](https://metacpan.org/pod/POE::Component::IRC), a fully-featured POE IRC client library

[IRC::Toolkit](https://metacpan.org/pod/IRC::Toolkit)

[POEx::IRC::Backend](https://metacpan.org/pod/POEx::IRC::Backend)

[POE::Filter::IRCv3](https://metacpan.org/pod/POE::Filter::IRCv3)

[MooX::Role::POE::Emitter](https://metacpan.org/pod/MooX::Role::POE::Emitter)

[MooX::Role::Pluggable](https://metacpan.org/pod/MooX::Role::Pluggable)

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>
