POE::Component::IRC::Plugin::WWW::Lipsum - plugin to generate Lorem Ipsum text in IRC

    use strict;
    use warnings;

    use POE qw(Component::IRC  Component::IRC::Plugin::WWW::Lipsum);

    my $irc = POE::Component::IRC->spawn(
        nick        => 'LipsumBot',
        server      => 'irc.freenode.net',
        port        => 6667,
        ircname     => 'Lorem Ipsum Bot',
        plugin_debug => 1,
    );

    POE::Session->create(
        package_states => [
            main => [ qw(_start irc_001) ],
        ],
    );

    $poe_kernel->run;

    sub _start {
        $irc->yield( register => 'all' );

        $irc->plugin_add(
            'lipsum' =>
                POE::Component::IRC::Plugin::WWW::Lipsum->new
        );

        $irc->yield( connect => {} );
    }

    sub irc_001 {
        $_[KERNEL]->post( $_[SENDER] => join => '#zofbot' );
    }




    <Zoffix> LipsumBot, lipsum
    <LipsumBot> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut velit lectus, ullamcorper non, sagittis id.
    <Zoffix> LipsumBot, lipsum 10
    <LipsumBot> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Mauris volutpat.
    <Zoffix> LipsumBot, lipsum 10/paras
    <LipsumBot> Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Curabitur sodales justo in nibh. Aenean placerat pretium nisl. Nulla enim arcu, porta in, molestie nec, consequat sed, nisi. Quisque eu urna. In hac habitasse platea dictumst. Sed sed augue. Pellentesque pellentesque fringilla pede. Nulla pharetra mattis dui. Donec diam ligula, imperdiet et,
    <Zoffix> LipsumBot, lipsum 10/paras/no
    <LipsumBot> Fusce dignissim, urna quis posuere cursus, erat est elementum dolor, non sollicitudin ligula nisl sed enim. Vivamus magna mi, pretium in, blandit non, ultrices ac, velit. Morbi nisl. Aenean quam massa, faucibus a, adipiscing at, sollicitudin nec, eros. Morbi pellentesque, erat ac porttitor ultricies, lacus arcu congue dolor, at malesuada urna nunc
    <Zoffix> LipsumBot, lipsum 10/paras/no/1
    <LipsumBot> <p> Aliquam quis est eget nulla ornare volutpat. Mauris a sapien. Nullam interdum justo quis metus. Quisque ultricies est eget dolor. Suspendisse nec neque nec diam semper gravida. In in odio in purus scelerisque sagittis. Nam suscipit quam vel lorem. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Praesent i
    <Zoffix> LipsumBot, lipsum 10 paras no 1
    <LipsumBot> <p> Suspendisse potenti. Ut ligula libero, posuere ac, euismod sit amet, dignissim eu, quam. Donec massa. Cras mollis pulvinar risus. Aenean porta porttitor nulla. Suspendisse potenti. Etiam nulla nisi, scelerisque vel, consequat vitae, ultrices aliquam, mauris. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;

This module is a POE::Component::IRC plugin which uses POE::Component::IRC::Plugin for its base. It provides interface to get Lorem Ipsum text generated by http://lipsum.com/. It accepts input from public channel events, /notice messages as well as /msg (private messages); although that can be configured at will.

    LipsumBot, lipsum [AMOUNT] [WHAT] [START WITH LOREM] [MAKE HTML]

All arguments are optional. Plugin can be triggered without any arguments, if that's the case then plugin will output 15 words of Lorem Ipsum text.

Arguments can be separated either by whitespace, the / character or , character.

You cannot skip arguments, if you want to generate 15 paragraphs you CANNOT use LipsumBot, lipsum paras even though 15 is the default for AMOUNT. (proper use is LipsumBot, lipsum 15 paras)

    LipsumBot, lipsum 20

The AMOUNT argument takes a positive integer which represents how many of WHAT (see below) to generate. Defaults to: 15

To prevent extremely creative people lagging out the plugin the following maximum values for the AMOUNT argument are imposed depending on the kind of WHAT argument (see below) used:

    words   => 7000,
    paras   => 100,
    lists   => 100,
    bytes   => 56000,

Currently these limits are not configurable. Let me know if you need them to be so.

    LipsumBot, lipsum 20 paras

The WHAT argument specifies what kind of entity to generate, possible values are:

    paras    - generate paragraphs
    words    - generate words
    bytes    - generate bytes
    lists    - generate lists

With paras and lists the MAKE HTML argument (see below) plays a role. Defaults to: words

    LipsumBot, lipsum 20 words no

Specifies whether or not the generated text should start with "Lorem ipsum dolor sit amet". There are only two possible values: yes and no. Defaults to: yes

    LipsumBot, lipsum 20 paras no yes

Applies only when WHAT is set to either paras or lists. Indicates whether or not the plugin should wrap paragraphs into <p> or <li> HTML elements. There are only two possible values: yes and no. Defaults to: no

    # plain and simple
    $irc->plugin_add(
        'WWW::Lipsum' => POE::Component::IRC::Plugin::WWW::Lipsum->new
    );

    # juicy flavor
    $irc->plugin_add(
        'WWW::Lipsum' =>
            POE::Component::IRC::Plugin::WWW::Lipsum->new(
                auto             => 1,
                response_event   => 'irc_lipsum',
                banned           => [ qr/aol\.com$/i ],
                addressed        => 1,
                line_lengths     => 350,
                max_lines        => 5,
                root             => [ qr/mah.net$/i ],
                trigger          => qr/^lipsum\s*/i,
                triggers         => {
                    public  => qr/^EXAMPLE\s*/i,
                    notice  => qr/^EXAMPLE\s*/i,
                    privmsg => qr/^EXAMPLE\s*/i,
                },
                listen_for_input => [ qw(public notice privmsg) ],
                eat              => 1,
                debug            => 0,
            )
    );

The new() method constructs and returns a new POE::Component::IRC::Plugin::WWW::Lipsum object suitable to be fed to POE::Component::IRC's plugin_add method. The constructor takes a few arguments, but all of them are optional. The possible arguments/values are as follows:

    ->new( auto => 0 );

Optional. Takes either true or false values, specifies whether or not the plugin should auto respond to requests. When the auto argument is set to a true value plugin will respond to the requesting person with the results automatically. When the auto argument is set to a false value plugin will not respond and you will have to listen to the events emited by the plugin to retrieve the results (see EMITED EVENTS section and response_event argument for details). Defaults to: 1.

    line_lengths => 350,

    line_lengths => {
        public  => 100,
        notice  => 200,
        privmsg => 350,
    }

Optional. Specifies the length of one "line" the plugin will output, but line is ment one message sent to IRC. The value can be either a hashref or a scalar. When the value is a hashref, possible keys of it are public, notice and privmsg which correspond to appropriate type of IRC messages, where public is the message which came from the channel. If you omit a certain key, it will take on its default value. Thus the following two are equivalent:

    line_lengths => { public => 300 }

    line_lengths => {
        public  => 300,
        notice  => 350,
        privmsg => 350,
    }

You can also specify a scalar value to line_lengths key, in this case all of the keys (public, notice and privmsg) will be set to that value. Defaults to: 350 for all message types.

    max_lines => 5,

    max_lines => {
        public  => 1,
        notice  => 8,
        privmsg => 8,
    },

Optional. Specifies the maximum number of "lines" (see the line_lengths argument for definition of "lines" in this context) which plugin will output. As a value takes either a scalar or a hashref, the same principles as for line_lengths argument apply to max_lines as well. Defaults to: 1 for public messages and 5 for notice and privmsg messages.

    ->new( response_event => 'event_name_to_recieve_results' );

Optional. Takes a scalar string specifying the name of the event to emit when the results of the request are ready. See EMITED EVENTS section for more information. Defaults to: irc_lipsum

    ->new( banned => [ qr/aol\.com$/i ] );

Optional. Takes an arrayref of regexes as a value. If the usermask of the person (or thing) making the request matches any of the regexes listed in the banned arrayref, plugin will ignore the request. Defaults to: [] (no bans are set).

    ->new( root => [ qr/\Qjust.me.and.my.friend.net\E$/i ] );

Optional. As opposed to banned argument, the root argument allows access only to people whose usermasks match any of the regexen you specify in the arrayref the argument takes as a value. By default: it is not specified. Note: as opposed to banned specifying an empty arrayref to root argument will restrict access to everyone.

    ->new( trigger => qr/^lipsum\s*/i );

Optional. Takes a regex as an argument. Messages matching this regex, irrelevant of the type of the message, will be considered as requests. See also addressed option below which is enabled by default as well as trigggers option which is more specific. Note: the trigger will be removed from the message, therefore make sure your trigger doesn't match the actual data that needs to be processed. Defaults to: qr/^lipsum\s*/i

    ->new( triggers => {
            public  => qr/^EXAMPLE\s+(?=\S)/i,
            notice  => qr/^EXAMPLE\s+(?=\S)/i,
            privmsg => qr/^EXAMPLE\s+(?=\S)/i,
        }
    );

Optional. Takes a hashref as an argument which may contain either one or all of keys public, notice and privmsg which indicates the type of messages: channel messages, notices and private messages respectively. The values of those keys are regexes of the same format and meaning as for the trigger argument (see above). Messages matching this regex will be considered as requests. The difference is that only messages of type corresponding to the key of triggers hashref are checked for the trigger. Note: the trigger will be matched irrelevant of the setting in triggers, thus you can have one global and specific "local" triggers. See also addressed option below which is enabled by default as well as trigggers option which is more specific. Note: the trigger will be removed from the message, therefore make sure your trigger doesn't match the actual data that needs to be processed. By default not specified (i.e. everything is triggered by trigger)

    ->new( addressed => 1 );

Optional. Takes either true or false values. When set to a true value all the public messages must be addressed to the bot. In other words, if your bot's nickname is Nick and your trigger is qr/^trig\s+/ you would make the request by saying Nick, trig EXAMPLE. When addressed mode is turned on, the bot's nickname, including any whitespace and common punctuation character will be removed before matching the trigger (see above). When addressed argument it set to a false value, public messages will only have to match trigger regex in order to make a request. Note: this argument has no effect on /notice and /msg requests. Defaults to: 1

    ->new( listen_for_input => [ qw(public  notice  privmsg) ] );

Optional. Takes an arrayref as a value which can contain any of the three elements, namely public, notice and privmsg which indicate which kind of input plugin should respond to. When the arrayref contains public element, plugin will respond to requests sent from messages in public channels (see addressed argument above for specifics). When the arrayref contains notice element plugin will respond to requests sent to it via /notice messages. When the arrayref contains privmsg element, the plugin will respond to requests sent to it via /msg (private messages). You can specify any of these. In other words, setting ( listen_for_input = [ qr(notice privmsg) ] )> will enable functionality only via /notice and /msg messages. Defaults to: [ qw(public notice privmsg) ]

    ->new( eat => 0 );

Optional. If set to a false value plugin will return a PCI_EAT_NONE after responding. If eat is set to a true value, plugin will return a PCI_EAT_ALL after responding. See POE::Component::IRC::Plugin documentation for more information if you are interested. Defaults to: 1

    ->new( debug => 1 );

Optional. Takes either a true or false value. When debug argument is set to a true value some debugging information will be printed out. When debug argument is set to a false value no debug info will be printed. Defaults to: 0.

    $VAR1 = {
        'out' => [
                    'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque placerat pede non metus. Vivamus tellus. '
                ],
        'what' => '',
        'who' => 'Zoffix!n=Zoffix@unaffiliated/zoffix',
        'type' => 'public',
        'channel' => '#zofbot',
        'lipsum' => [
                    'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque placerat pede non metus. Vivamus tellus. '
                    ],
        'message' => 'LipsumBot, lipsum'
    };

The event handler set up to handle the event, name of which you've specified in the response_event argument to the constructor (it defaults to irc_lipsum) will recieve input every time request is completed. The input will come in $_[ARG0] on a form of a hashref. The possible keys/values of that hashrefs are as follows:

        'out' => [
                    'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque placerat pede non metus. Vivamus tellus. '
                ],

The out key will contain an arrayref of the messages (or "lines") sent to IRC. The content here is affected by line_lengths and max_lines constructor arguments.

        'lipsum' => [
                    'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Pellentesque placerat pede non metus. Vivamus tellus. '
                    ],

The lipsum key will contain Lorem Ipsum text before it was chopped up and limited by line_lengths and max_lines constructor arguments.

    { 'who' => 'Zoffix!Zoffix@i.love.debian.org', }

The who key will contain the user mask of the user who sent the request.

    { 'what' => '20 paras yes no', }

The what key will contain user's message after stripping the trigger (see CONSTRUCTOR).

    { 'message' => 'LipsumBot, lipsum 20 paras yes no' }

The message key will contain the actual message which the user sent; that is before the trigger is stripped.

    { 'type' => 'public', }

The type key will contain the "type" of the message the user have sent. This will be either public, privmsg or notice.

    { 'channel' => '#zofbot', }

The channel key will contain the name of the channel where the message originated. This will only make sense if type key contains public.

POE, POE::Component::IRC, WWW::Lipsum

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

Please report any bugs or feature requests to bug-poe-component-irc-plugin-www-lipsum at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-IRC-Plugin-WWW-Lipsum. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::IRC::Plugin::WWW::Lipsum

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-IRC-Plugin-WWW-Lipsum

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/POE-Component-IRC-Plugin-WWW-Lipsum

* CPAN Ratings

http://cpanratings.perl.org/d/POE-Component-IRC-Plugin-WWW-Lipsum

* Search CPAN

http://search.cpan.org/dist/POE-Component-IRC-Plugin-WWW-Lipsum

Copyright 2008 Zoffix Znet, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.