NAME

Bot::ChatBots::Role::UserAgent - Bot::ChatBots Role for having a user agent

SYNOPSIS

   package Bot::ChatBots::Whatever::Sender;
   use Moo;
   with 'Bot::ChatBots::Role::Sender';
   with 'Bot::ChatBots::Role::UserAgent';

   sub send_message {
      my ($self, $message) = @_;
      $self->ua_request(
         GET => 'http://frobozz.example.com/v1/whatever',
         {Accept => 'application/json'},
         json => $message
      );
   }
   1;

DESCRIPTION

This role adds some user-agent capabilities using Mojo::UserAgent.

ACCESSORS

The following methods have a same-named option that can be passed to the constructor.

callback

   my $cb = $obj->callback;
   $obj->callback(sub {...});

Accessor for a possible callback sub reference. This is/can be used when callling Mojo::UserAgent in non-blocking mode.

start_loop

   say 'loop starts automatically' if $obj->start_loop;
   $obj->start_loop(0); # don't start automatically
   $obj->start_loop(1); # start loop automatically

Accessor for boolean attribute that instructs "ua_request" to start the Mojo::IOLoop automatically. This can still be overridden by anything passed with key start_loop in "ua_request".

Defaults to 0 (false).

ua

   my $ua = $obj->ua;
   $obj->ua(Mojo::UserAgent->new);

Accessor for a Mojo::UserAgent compatible object.

METHODS

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

BUILD_ua

Builder for "ua". Defaults to a new fresh instance of Mojo::UserAgent.

clear_callback

   $obj->clear_callback;

Remove any "callback" currently set.

has_callback

   say 'yes' if $obj->has_callback;

Predicate function to assess whethere a "callback" is set or not.

may_start_loop

   $self->may_start_loop(%args);
   $self->may_start_loop(\%args);

Evaluates conditions for starting Mojo::IOLoop. These conditions are:

• if the provided %args contains a key start_loop, it is used to establish whether to start the loop or not, OTHERWISE

• if "start_loop" is false, the loop is not started, OTHERWISE

• the loop is started if it's not already running.

This method is used by "ua_request".

It is suggested to use this method only if you are also using a callback in your call. Assuming that @callback contains a callback or not, you might want to call this method like this:

   $obj->may_start_loop(%args) if @callback;

ua_request

   $obj->ua_request($method, %args);

This is a wrapper around different $method methods available in Mojo::UserAgent. For example, this call:

   $obj->ua_request(get => ua_args => \@parameters);

translates into this:

   $obj->ua->get(@parameters);

If a "callback" is available (see "has_callback"), it is appended to the @parameters unless the last item is a sub reference itself. In either cases, Mojo::IOLoop is started unless it's already running.

Returns whatever the call to Mojo::UserAgent returns.

The recognised keys in %args are the following:

start_loop

in case there is a callback, this flag tells ua_request to start the Mojo::IOLoop if it's not already running. Defaults to what set in accessor "start_loop".

ua_args

the argument list for Mojo::UserAgent. This might be extended if it does not contain a callback but the object "has_callback".

SEE ALSO

Bot::ChatBots, Bot::ChatBots::Role::Sender.

AUTHOR

Flavio Poletti <polettix@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 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