.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bot::BasicBot::Pluggable::Module 3pm"
.TH Bot::BasicBot::Pluggable::Module 3pm "2017-08-27" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bot::BasicBot::Pluggable::Module \- base module for all BasicBot plugins
.SH "VERSION"
.IX Header "VERSION"
version 1.20
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
You \s-1MUST\s0 override \f(CW\*(C`help()\*(C'\fR, which \s-1MUST\s0 return help text for the module.
.PP
You \s-1MUST\s0 override at least \f(CW\*(C`said()\*(C'\fR, though it is preferred that you
override the more specific \f(CW\*(C`seen()\*(C'\fR, \f(CW\*(C`admin()\*(C'\fR, \f(CW\*(C`told()\*(C'\fR and \f(CW\*(C`fallback()\*(C'\fR
for cleaner code without relying on checks against \f(CW$pri\fR.
.PP
You \s-1MAY\s0 override \f(CW\*(C`chanjoin()\*(C'\fR, \f(CW\*(C`chanpart()\*(C'\fR, \f(CW\*(C`userquit\*(C'\fR,
\&\f(CW\*(C`nick_change\*(C'\fR, \f(CW\*(C`topic\*(C'\fR, \f(CW\*(C`kicked\*(C'\fR and \f(CW\*(C`tick()\*(C'\fR.
.PP
You \s-1MAY\s0 return a response from \f(CW\*(C`said()\*(C'\fR to the event.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Object Store"
.IX Subsection "Object Store"
Every pluggable module gets an object store to save variables in. Access
this store using the \f(CW\*(C`get()\*(C'\fR and \f(CW\*(C`set()\*(C'\fR accessors. Do not access the store
through any other means \- the location of the store, and its method of storage,
may change at any time:
.PP
.Vb 2
\&  my $count = $self\->get("count");
\&  $self\->set( count => $count + 1 );
.Ve
.PP
Keys that begin \*(L"user_\*(R" are considered _USER_ variables, and can be changed by
administrators in the \s-1IRC\s0 channel using Bot::BasicBot::Pluggable::Module::Vars.
Don't use them as unchecked input data.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fInew()\fR" 4
.IX Item "new()"
Standard \f(CW\*(C`new\*(C'\fR method, blesses a hash into the right class and puts any
key/value pairs passed to it into the blessed hash. Calls \f(CW\*(C`init\*(C'\fR to load
any internal or user variables you may have set in your module.
.IP "\fIinit()\fR" 4
.IX Item "init()"
Called as part of new class construction. May or may not be after
server connection. Override this to do things when your module is added
to the bot.
.IP "config($config)" 4
.IX Item "config($config)"
Set every key in the hash reference \f(CW$config\fR to its default value
if it is not already defined in the module store. In that case the
value from the store is used to initialise the variable. Typically
called in the module's init functions.
.IP "\fIstart()\fR" 4
.IX Item "start()"
Indicates that the module is added to the bot, and that the bot is
connected to the \s-1IRC\s0 server. Do things here that need to be done after
you're connected.
.Sp
\&\s-1TODO\s0 \- this method not yet implemented.
.IP "\fIstop()\fR" 4
.IX Item "stop()"
Called just before your module is removed from the bot. Do cleanup here.
.IP "\fIbot()\fR" 4
.IX Item "bot()"
Returns the Bot::BasicBot::Pluggable bot we're running under.
.IP "store" 4
.IX Item "store"
Returns Bot::BasicBot::Pluggable::Store subclass used to store variables.
.IP "get($name)" 4
.IX Item "get($name)"
Returns the value of a local variable from the object store.
.ie n .IP "set($name => $value)" 4
.el .IP "set($name => \f(CW$value\fR)" 4
.IX Item "set($name => $value)"
Set a local variable into the object store.
.IP "unset($name)" 4
.IX Item "unset($name)"
Unsets a local variable \- removes it from the store, not just \f(CW\*(C`undef\*(C'\fRs it.
.IP "var($name, [$value])" 4
.IX Item "var($name, [$value])"
\&\f(CW\*(C`get()\*(C'\fR or \f(CW\*(C`set()\*(C'\fR a local variable from the module store.
.IP "store_keys" 4
.IX Item "store_keys"
Returns a list of all keys in the object store.
.IP "connected" 4
.IX Item "connected"
Called when the bot connects to the server. The return value is meaningless.
.IP "chanjoin($message)" 4
.IX Item "chanjoin($message)"
Called when a user joins a channel.
.IP "userquit($message)" 4
.IX Item "userquit($message)"
Called when a user client quits. See Bot::BasicBot for a description
of the arguments.
.IP "chanpart($message)" 4
.IX Item "chanpart($message)"
Called when a user leaves a channel.
.IP "topic($message)" 4
.IX Item "topic($message)"
Called when the topic of a channel is changed. See Bot::BasicBot for a description
of the arguments.
.IP "kicked($message)" 4
.IX Item "kicked($message)"
Called when a user is kicked from a channel. See Bot::BasicBot for a description
of the arguments.
.IP "nick_change($message)" 4
.IX Item "nick_change($message)"
When a user changes nicks, this will be called. See Bot::BasicBot for a description
of the arguments.
.IP "help" 4
.IX Item "help"
Called when a user asks for help on a topic and thus should return some useful
help text. For Bot::BasicBot::Pluggable, when a user asks the bot 'help',
the bot will return a list of modules. Asking the bot 'help <modulename>' will
call the \f(CW\*(C`help\*(C'\fR function of that module, passing in the first parameter the
message object that represents the question.
.IP "say($message)" 4
.IX Item "say($message)"
Passing through Bot::BasicBot, send messages without replying to a \f(CW\*(C`said()\*(C'\fR:
.Sp
.Vb 1
\&  $self\->say({ who => \*(Aqtom\*(Aq, body => \*(Aqboo\*(Aq, channel => \*(Aqmsg\*(Aq });
.Ve
.ie n .IP "reply($message, $body)" 4
.el .IP "reply($message, \f(CW$body\fR)" 4
.IX Item "reply($message, $body)"
Replies to the given message with the given text. Another passthrough to
\&\f(CW\*(C`Bot::BasicBot\*(C'\fR. The message is used to pre-populate the reply, so it'll
be in the same channel as the question, directed to the right user, etc.
.ie n .IP "tell($nick | $channel, $message)" 4
.el .IP "tell($nick | \f(CW$channel\fR, \f(CW$message\fR)" 4
.IX Item "tell($nick | $channel, $message)"
Convenience method to send message to nick (privmsg) or channel (public):
.Sp
.Vb 2
\&  $self\->tell(\*(Aqtom\*(Aq, "hello there, fool");
\&  $self\->tell(\*(Aq#sailors\*(Aq, "hello there, sailor");
.Ve
.ie n .IP "said($message, $priority)" 4
.el .IP "said($message, \f(CW$priority\fR)" 4
.IX Item "said($message, $priority)"
This method is called whenever the bot sees something said. The first parameter
is a Bot::BasicBot 'message' object, as passed to it's 'said' function \- see
those docs for further details. The second parameter is the priority of the
message \- all modules will have the 'said' function called up to 4 times, with
priorities of 0, 1, 2, and 3. The first module to return a non-null value
\&'claims' the message, and the bot will reply to it with the value returned \-
unless the value is \*(L"1\*(R", in which case the message is considered claimed (no
other module will see it) but no reply will be issued.
.Sp
The exception to this is the 0 priority, which a module \s-1MUST NOT\s0 respond to 
(any response will be ignored).
This is so that all modules will at least see all messages. I suggest:
.Sp
.Vb 3
\&  sub said {
\&    my ($self, $mess, $pri) = @_;
\&    my $body = $mess\->{body};
\&
\&    return unless ($pri == 2); # most common
\&
\&    my ($command, $param) = split(/\es+/, $body, 2);
\&    $command = lc($command);
\&
\&    # do something here
\&
\&    return;       # allows other modules to see this message, or:
\&    return 1;     # "eat" the message, no other module sees it, no reply, or:
\&    return "OK!"; # "eat" the message and send a reply back to the user
\&  }
.Ve
.Sp
The preferred way, however, is to override one of the separate \f(CW\*(C`seen()\*(C'\fR, \f(CW\*(C`admin()\*(C'\fR,
\&\f(CW\*(C`told()\*(C'\fR and \f(CW\*(C`fallback()\*(C'\fR methods, corresponding to priorities 0, 1, 2 and 3
in order \- this will lead to nicer code. This approach is new, though, which
is why it's not yet used in most of the shipped modules yet. It will eventually
become the only thing to do, and I will deprecate \f(CW\*(C`said()\*(C'\fR.
.IP "replied($message,$reply)" 4
.IX Item "replied($message,$reply)"
This method is called every time a module returns an reply. The first
argument is the original message and the second is the returned
string. The return value of this method is actually discarded, so
you can't do anything to prevent the message from being sent. This
is mainly meant to log the bots activity.
.IP "seen($message)" 4
.IX Item "seen($message)"
Like \f(CW\*(C`said()\*(C'\fR; called if you don't override \f(CW\*(C`said()\*(C'\fR, but only for priority 0.
.Sp
As it is called at priority 0, you cannot return a reply from this method.
.IP "admin($message)" 4
.IX Item "admin($message)"
Like \f(CW\*(C`said()\*(C'\fR; called if you don't override \f(CW\*(C`said()\*(C'\fR, but only for priority 1.
.IP "told($message)" 4
.IX Item "told($message)"
Like \f(CW\*(C`said()\*(C'\fR; called if you don't override \f(CW\*(C`said()\*(C'\fR, but only for priority 2.
.IP "fallback($message)" 4
.IX Item "fallback($message)"
Like \f(CW\*(C`said()\*(C'\fR; called if you don't override \f(CW\*(C`said()\*(C'\fR, but only for priority 3.
.ie n .IP "emoted($message, $priority)" 4
.el .IP "emoted($message, \f(CW$priority\fR)" 4
.IX Item "emoted($message, $priority)"
Called when a user emotes something in channel.
.IP "tick" 4
.IX Item "tick"
Called every five seconds. It is probably worth having a counter and not
responding to every single one, assuming you want to respond at all. The
return value is ignored.
.IP "authed($who)" 4
.IX Item "authed($who)"
This is a convenient method that tries to check for the users
authentication level via Auth.pm. It is exactly equivalent to
.Sp
.Vb 2
\&    $self\->bot\->module(\*(AqAuth\*(Aq)
\&      and $self\->bot\->module(\*(AqAuth\*(Aq)\->authed($who);
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Mario Domgoergen <mdom@cpan.org>
.PP
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.