view release on metacpan or  search on metacpan

lib/Bot/Cobalt/Manual/Plugins.pod  view on Meta::CPAN

L<Bot::Cobalt::Utils> provides a functional-style interface to various tools 
useful in effective plugin authoring.

Tools include flexible (bcrypt-enabled) password hashing and comparison 
functions, string formatting with arbitrary variable replacement rules, 
Cobalt-style glob syntax tools, color/format interpolation, and others.

  ## Import all Bot::Cobalt::Utils funcs:
  use Bot::Cobalt::Utils qw/ :ALL /;

See L<Bot::Cobalt::Utils>.

=head3 IRC::Utils

L<IRC::Utils> is a very useful module covering many basic IRC-related 
tasks, such as host normalization / matching and casemapping-aware IRC 
uppercase/lowercase tools.

It is used extensively by both L<Bot::Cobalt> and 
L<POE::Component::IRC> and therefore guaranteed to be available for use.

See L<IRC::Utils> for upstream's documentation.


=head3 Bot::Cobalt::Plugin::WWW

It's fairly common to want to make some kind of HTTP request from an 
IRC bot. The most common Perl method of speaking HTTP is 
L<LWP::UserAgent> -- which will block the plugin pipeline until the 
request is complete.

L<Bot::Cobalt::Plugin::WWW>, if loaded, dispatches HTTP requests 
asynchronously via L<POE::Component::Client::HTTP> and returns 
L<HTTP::Response> responses to the plugin pipeline:

  ## build a request object via HTTP::Request
  use HTTP::Request;

  ## a simple GET, see HTTP::Request docs for more info:
  my $request = HTTP::Request->new( 'GET', $url );

  ## push it to www_request with a response event:
  broadcast( 'www_request',
    $request,
    'myplugin_resp_recv',

     ## you can include a reference containing args
     ## (or a scalar, if you like)
     ##
     ## here's an example args arrayref telling our handler 
     ## where to send responses:
     [ $context, $channel, $nickname ],
  );
  
  ## handle a response when one is received:
  sub Bot_myplugin_resp_recv {
    my ($self, $core) = splice @_, 0, 2;

    ## if the request was successful, $_[0] is a ref to the 
    ## decoded content from HTTP::Response
    ## (otherwise, it is the HTTP status message)
    my $content  = ${ $_[0] };

    ## $_[1] is the HTTP::Response object, see perldoc HTTP::Response
    my $response = ${ $_[1] };

    ## $_[2] is whatever argument ref was provided in www_request
    my $argref   = ${ $_[2] };

    ## in our example above, it was some contextual info:
    my ($context, $channel, $nickname) = @$argref;

    if ($response->is_success) {
      ## . . . do something with the response . . .
    } else {
      ## request failed (see HTTP::Response)
    }
  
    ## eat this event, we're the only handler:
    return PLUGIN_EAT_ALL
  }

When a response is received, it will be pushed to the plugin pipeline 
as the specified SERVER event.

If the plugin is available, B<< $core->Provided->{www_request} >> will be 
boolean true:

  my $request = HTTP::Request->new( . . . );
  if ($core->Provided->{www_request}) {
    ## send www_request event like above
    . . .   
  } else {
    ## no async available, error out or use LWP or something:
    my $ua = LWP::UserAgent->new(
      timeout => 5,
      max_redirect => 0,
    );
    my $response = $ua->request($request);
    my $content = $response->content;
  }


=head2 Retrieving $core

It may be necessary or convenient to use L<Bot::Cobalt::Core> methods from 
outside of a syndicated event handler.

If your plugin imports L<Bot::Cobalt> via 'use Bot::Cobalt', the 
C<core()> function will retrieve the instanced L<Bot::Cobalt::Core>; 
for example:

  core()->auth->level( . . . )

See L<Bot::Cobalt::Core::Sugar> for details on functions exported when 
you 'use Bot::Cobalt'.

If you don't want to use the sugary functions and 
would rather make method calls directly, L<Bot::Cobalt::Core> is an 
instanced singleton; loaded plugins can always