view release on metacpan or  search on metacpan

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

See L<Bot::Cobalt::DB> for complete usage information.

=head3 Bot::Cobalt::Serializer

It is often useful to serialize arbitrary data structures to some 
standardized format. Serialization formats such as B<JSON> and B<YAML> 
are convenient for "speaking" to other networked applications, sharing 
data, or saving persistent data to disk in an easily-retrievable format.

L<Bot::Cobalt> comes with a simple object oriented frontend to some common 
serialization formats, as well as built-in file operations for "freezing" 
and "thawing" data to/from files on disk:

  use Bot::Cobalt::Serializer;

  ## create a JSON serializer:
  my $jsify = Bot::Cobalt::Serializer->new( Format => 'JSON' );

  ## serialize a perl hash:
  my $ref = { Some => { Deep => [ 'Structure' ] } };
  my $json = $jsify->freeze($ref);

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


=head3 Bot::Cobalt::Utils

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 {