NAME

Bot::ChatBots::Utils - Utility functions for Bot::ChatBots

SYNOPSIS

   use Bot::ChatBots qw< load_module resolve_module >;

   resolve_module('Duh');        # returns 'Bot::ChatBots::Duh'
   resolve_module('^Duh');       # returns 'Duh'
   resolve_module('+Duh');       # ditto, least surprise principle
   resolve_module('^Foo::Bar');  # returns 'Foo::Bar'
   resolve_module('Foo::Bar');   # returns 'Bot::ChatBots::Foo::Bar'
   resolve_module('::Foo::Bar'); # ditto, loud about needing prefix

   # transform $something using resolve_module, load it and return
   # the loaded class name
   load_module($something);

DESCRIPTION

This module provides a few utilities for ease your way while building stuff with Bot::ChatBots.

Nothing is exported by default.

FUNCTIONS

load_module

   my $module_name = load_module($module_name_spec);

Transforms the input $module_name_spec via "resolve_module", then loads the result using "use_module" in Module::Runtime and returns the loaded module name. This can be useful for doing things like this:

   # load Bot::ChatBots::Auth and create an instance
   my $auth = load_module('Auth')->new(users => {whitelist => {1 => 1}});

pipeline

   my $tube = pipeline($atube); # OR
      $tube = pipeline(@specifications); # OR
      $tube = pipeline(\%opts, @specifications); # OR
      $tube = pipeline(@specifications, \%opts);

Smart wrapper around "pipeline" in Data::Tubes.

If a single argument is provided and it is a sub reference, it is considered to be a tube itself and returned directly. In this case, no call to "pipeline" in Data::Tubes is done (and Data::Tubes is then not required).

In all other cases Data::Tubes is required as a dependency.

Arguments @specifications must be either tubes (i.e. sub references) or definitions that can be transformed into tubes (see Data::Tubes for the details). You can pass options with a hash reference either as the first or the last parameter.

One option that you can pass is prefix, which sets the prefix for automatic resolution of names. This resolution is done via "resolve_module" and does not rely upon Data::Tubes' own mechanism. These \%opts are anyway passed down to Data::Tubes if you want to set additional supported options. By default, %opts is considered an empty hash.

resolve_module

   my $module_name = resolve_module($spec); # OR
      $module_name = resolve_module($spec, $prefix);

Transform an input $spec string into a module name. Parameter $prefix is optional and defaults to Bot::ChatBots. The transformation rules are as follows:

    *

    if $spec starts with a caret ^ or a plus sign +, the $spec is returned after the initial character is removed. These two characters are aliased to cope with a long tradition of using + for this (although in other contexts + means add, which naturally translates into add a prefix in my very humble opinion), ELSE

    *

    $spec is pre-pended with :: (unless it already has them) and $prefix . $spec is returned. (You might want to explicitly put the :: in front of your sub-module name to document the fact that you actually want the prefix to be added, otherwise you can just let resolve_module put that for you).

The net result is that the $prefix is used in the default case (i.e. no initial special character), but you can start with :: if you want to document the prefixing or start with ^ (or +) if you want to skip prefixing. See "SYNOPSIS" for some examples.

SEE ALSO

Bot::ChatBots, Module::Runtime.

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.