NAME

Bot::ChatBots::Role::Poller - Bot::ChatBots Role for Pollers

SYNOPSIS

   package Something;
   use Moo;
   with 'Bot::ChatBots::Role::Poller';

   sub poll {
      my ($self, $callback, $args) = @_;
      ...
   }

   sub parse_response {
      my ($self, $data) = @_;
      ...
   }

   sub normalize_record {
      my ($self, $record) = @_;
      ...
   }
   1;

   # later that night...
   my $something = Something->new(
      interval => 30, # polling interval
      processor => \&process_record,
   );
   Mojo::IOLoop->start;

DESCRIPTION

This is a poller role for bots. This role is actually a derivation of Bot::ChatBots::Role::Source.

A poller works like this:

• "schedule" installs a recurring call to whatever "poller" returns. Nothing is executed until "start" in Mojo::IOLoop is run.

• "poller" wraps a call to "poll", which is the real workhorse for fetching data. The wrapping is such that "poll" will not be called if another instance of it is already running.

• "poll" - provided by your class - fetches new data and pushes this new data to a callback. This allows asynchronous implementations, e.g. based on Mojo::UserAgent (which accepts a callback).

• "parse_response", "process_updates" and "normalize_record" (required by the base Bot::ChatBots::Role::Source) are then called for implementing the usual pipeline (parsing data into updates, process them and normalize the resulting records).

What Should You Provide/Override

This is what you should provide and probably override in the general case:

• "normalize_record" as per Bot::ChatBots::Role::Source.

• "parse_response" is where you dissect received data into updates.

• "poll" is called regularly to fetch some updates.

METHODS

It should be safe to override the following methods in your classes composing this role.

args

   my $args_aref = $obj->args;

Set a list of arguments eventually consumed by "poll", inside an array reference.

interval

   my $interval = $obj->interval;

Interval for scheduling calls to "poll".

poller

   my $sub_ref = $obj->poller;

Generate a sub reference that is called regularly.

schedule

   $obj->schedule($interval);

Set the recurrent polling. Called automatically upon object creation.

REQUIRED METHODS

This class defines a Moo::Role, so it's not a standalone thing by itself. The following methods are required to exist in the class that composes this role. Note that this role derives from Bot::ChatBots::Role::Source, so its requirements have to be honored as well (namely, "normalize_record" in Bot::ChatBots::Role::Source).

parse_response

   my @updates = $obj->parse_response($data);

This method is called with whatever data is returned by "poll", and is supposed to return a list of updates for further processing by "process_updates" in Bot::ChatBots::Role::Source.

poll

   $obj->poll($callback, $args);

This method is supposed to fetch new data and feed it to the $callback, like this:

   $callback->($data);

Whatever you set, it will be passed over to "parse_response" where the actual parsing will be performed.

SEE ALSO

Bot::ChatBots, Bot::ChatBots::Role::Source.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2018 by Flavio Poletti <polettix@cpan.org>

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm Bot::ChatBots

perl -MCPAN -e shell
install Bot::ChatBots