Daisuke Maki > Morris > Morris

Download:
Morris-0.01000_01.tar.gz

Dependencies

Annotate this POD

Module Version: 0.01000_01   Source  

NAME ^

Morris - An IRC Bot Based On Moose/AnyEvent

SYNOPSIS ^

    # If you just want to start using Morris, please checkout 
    # misc/sample.conf in the distro for a sample config file, 
    # which is the best way to figure out how to configure Morris.

    use Morris;

    my $morris = Morris->new(
        connections => [
            Morris::Connection->new( ... )
        ]
    );
    $morris->run();

    # or when you instantiate from a config file
    my $config = read_config_file( $config_file );
    my $morris = Morris->new_from_config( $config );
    $morris->run;

CONFIG FILE ^

The configuration file shipped with Morris is written in Config::General syntax, but since our underlying config read is Config::Any, we support any format supported by Config::Any family. Our docs will be written in Config::General format, but you may choose whichever format you like.

ARCHITECTURE ^

Morris is a simple IRC bot. Its architecture is loosely depicted below:

                                                -----------------------
                                             ---| Morris::Plugin::Foo |
                    ----------------------   |  -----------------------
                 ---| Morris::Connection |---|--| Morris::Plugin::Bar |
    ----------   |  ----------------------   |  -----------------------
    | Morris |---|                           ---| Morris::Plugin::Baz |
    ----------   |  ----------------------      -----------------------
                 ---| Morris::Connection |...
                    ---------------------- 

What this means is that you can have multiple Morris::Connection objects, which in turn represent single client-to-server connection. For each connection, you can define plugins that react to events or do other intersting stuff with that connection.

For example, if you have a connection to freenode, EFnet, and your own private IRC server. You can define difference plugin sets for each connection, and have Morris act differently depending on which connection you are using.

Morris uses a simple plugin mechanism to add extra capabilities (if you're familiar with how Plagger works, it's similar to it).

Plugins are loaded on demand based on the config file specification, and are initialized with the parameters in the config file. After that, they are given a chance to register hooks to Morris (actually, Morris::Connection, since Morris' main features revolve around Morris::Connection, and so plugins are also registered on a per-connection base)

BASIC CONFIGURATION ^

Morris expects to have a configuration file with at least the following specifications:

    <Config>
      <Connection YourConnectionName>
        Network YourNetworkName
        ... plugins ...
      </Connection>

      <Network YourNetworkName>
        ... network config ...
      </Network>
    </Config>

Network CLAUSE

The Network clause defines how to connect to a certain IRC network. Normally you need to set the following fields:

    <Network YourNetworkName>
      Server         irc.freenode.net # the host name to connect to
      Port           6667             # Port number. Defaults to 6667
      Username       YourUsername     # Username to connect as
      Nickname       YourNickname     # Nick name to use
      # If the server is password protected, specify a password
      # Password       YourPassword
    </Network>

The same Network definition may be re-used between multiple Connection clauses. This will allow multiple bots (if the network allows such thing)

Note that The above information may be overridden on a per-connection basis (so to allow multiple, differently named bots on a same network). However, it is recommended that you keep the "master" configuration for a Network separate from a Connection

Connection CLAUSE

The Connection clause defines the actual connection and the plugins that are supposed to be registered to that connection.

The Connection name is just a symbolic name to differentiate from other connections, so as long as its unique, you can use whatever you like.

You can skip defining Plugin clauses, but that will just create a bot that connect to a network, but does nothing.

Plugin CLAUSE

The Plugin clause is where all the plugins are defined, and it must be found inside a Connection clause. Multiple plugin sections are allowed.

The order of initialization is NOT guaranteed.

Plugins should be specified without the preceeding Morris::Plugin:: part from their module name.

    <Plugin Join> # Loads Morris::Plugin::Join
      ....
    </Plugin>

If you would like to explicitly specify a fully qualified plugin name, you should prefix it with a single '+', like so:

    <Plugin +My::Other::Plugin>
      ...
    </Plugin>

Here's the current list of plugins:

Morris::Plugin::DBI

Enables a database handle, so that other DB-dependent plugins can use it. On its own, it doesn't do anything

Morris::Plugin::Dictionary

Add ability to remember certain key = value combinations.

Morris::Plugin::Join

Automatically join a channel on connect

Morris::Plugin::Log::DBI

Log every privmsg to a database

Morris::Plugin::MP

Enable AnyEvent::MP for Morris.

Morris::Plugin::Oper

Automatically give out oper to matched users.

Morris::Plugin::PeekURL

When a URL-like string pattern appears in a privmsg, attemps to fetch it and display some information about it (like title, or image size, if it's a image)

Morris::Plugin::QOTD

Remember phrases, and display them in a weird fashin.

Morris::Plugin::Reputation

When a string like morris++ or morris-- is found, remembers that and keeps tab of the target's reputation

Morris::Plugin::YSearch

Allows Yahoo! Search to run.

METHODS ^

new(%args)

new_from_config (\%config)

Instantiate a new morris instance

run

Starts the servicing.

WHY IS IT CALLED MORRIS? ^

Why do you care? I originally wanted to write a Moose-based IRC bot for practice/toying with, and just thought something starting with "Moo.." would be good. Turns out using the name 'Morris' sounds like I'm refering to a person, which gives me a warm and fuzzy feeling.

...or something like that. No, there's no real reason.

AUTHORS ^

Daisuke Maki <daisuke@endeworks.jp>

LICENSE ^

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

See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: