NAME
    POE::Session::Irssi - emit POE events for Irssi signals

SYNOPSIS
      use Irssi;
      use Glib;
      use POE qw(Loop::Glib);
      use POE::Session::Irssi;

      %IRSSI = ( ... fill in the usual stuff for scripts here ... );

      POE::Session::Irssi->create (
          irssi_commands => {
              hello => sub {
                my $args = $_[ARG1];
                my ($data, $server, $witem) = @$args;

                $server->command("MSG $witem->{name} Hello $data!");
              },
            },
          irssi_signals => {
              "message join" => sub {
                my $args = $_[ARG1];
                my ($server, $channel, $nick, $address) = @$args;
                my $me = $server->{nick};

                if ($nick eq $me) {
                  $server->command("MSG $channel Hello World!");
                } else {
                  $server->command("MSG $channel Hi there, $nick");
                }
              },
            },
          # Other create() args here..
      );

DESCRIPTION
    This POE::Session subclass helps you integrate POE and Irssi scripting.
    It connects the signals and commands handlers you define as POE events
    with the Irssi machinery. It also tries to clean up as much as possible
    when the script gets unloaded, by removing all the alarms your session
    has running.

    It does this cleaning up by installing an UNLOAD handler that will send
    an unload signal. See SIGNALS below for more information.

CONSTRUCTOR
  create (%args)
    Apart from the normal arguments POE::Session create() supports, there
    are two more arguments.

    * irssi_commands

            irssi_commands => {
                command_name => \&handler_sub,
            }

      As you can see in the example above, this expects a hashref, with the
      keys holding the /command you use in Irssi, and the values being
      references to the handler function. Because POE::Session::Irssi
      creates a postback behind the scenes for each command, your handler
      sub will get two arguments in ARG0 and ARG1. These are the normal
      postback lists, and the arguments you would normally receive in an
      Irssi handler are in the list in ARG1.

      Currently, only this inline_state like syntax is supported. Allowing
      for object/package states is on the TODO list.

    * irssi_signals

            irssi_signals => {
                "signal name" => \&handler_sub,
            }

      This is much the same as for the irssi_commands. One thing to remember
      is that lots of Irssi signals have spaces in their names, so don't
      forget to put them inside quotes.

SIGNALS
    POE allows you to define your own signals, which are handled the same as
    system signals. See POE::Kernel for more information.
    POE::Session::Irssi defines one such signal:

  unload $package
    This signal is sent when irssi tries to unload a script. ARG1 contains
    the package name of the script that is being unloaded.
    POE::Session::Irssi also creates a handler for this signal that does its
    best to clean up for the session by removing any aliases set and
    removing the signal handler

NOTES
    Since you don't need to call POE::Kernel->run() in Irssi scripts
    (because the Glib mainloop is already running), it is no problem at all
    to have more than one Irssi script contain a POE::Session. They will all
    use the same POE::Kernel and POE::Loop.

TODO
    * Allow object/package states

    * Maybe put a list of session aliases in an Irssi setting somewhere This
      would allow discovery of what other sessions we can talk to.

AUTHOR
    Martijn van Beers <martijn@eekeek.org>

COPYRIGHT
    This module is Copyright 2006-2007 Martijn van Beers. It is free
    software; you may reproduce and/or modify it under the terms of the GPL
    licence v2.0. See the file COPYING in the source tarball for more
    information

