use Util::Any (KIND)

 use Util::Any -list, -hash;

Give list of kinds of modules. All functions in modules are exported.

use Util::Any KIND => [FUNCTIONS], ...;

 use Util::Any -list => ['uniq'], -hash => ['lock_keys'];

Give hash whose key is kind and value is function names as array ref. Selected functions are exported.

you can write it as hash ref.

 use Util::Any {-list => ['uniq'], -hash => ['lock_keys']};

use Util::Any ..., {OPTION => VALUE};

prefix => 1

add kind prefix to function name.

 use Util::Any -list, {prefix => 1};
 
 list_uniq(1,2,3,4,5); # it is List::More::Utils's uniq function
    

module_prefix => 1

see "PREFIX FOR EACH MODULE". Uti::Any itself doesn't have such a definition.

smart_rename => 1

see "SMART RENAME FOR EACH KIND".

plugin => 'lazy' / 'eager' / 0 (default is 'lazy')

If utility module based on Util::Any has plugin, Its plugins are loaded when related kind is specified(if kind name matches module name). If you want to load all plugin on using module, give 'eager' to this option. If you don't want to use plugin, set 0.

 use Util::Yours -kind, .... {plugin => 'eager'}; # all plugins are loaded
 use Util::Yours -kind, .... {plugin => 0};       # disable plugin feature.
 use Util::Yours -kind;                           # is equal {plugin => 'lazy'}
    

Relation of kind name and plugin name is the following.

for example, If you have the following modules.

 Util::Yours::Plugin::Date
 Util::Yours::Plugin::DateTime
 Util::Yours::Plugin::Net
 Util::Yours::Plugin::Net::Amazon
 Util::Yours::Plugin::Net::Twitter
    

the following code:

 use Util::Yours -date; # Plugin::Date is loaded
 use Util::Yours -datetime; # Plugin::DateTime is loaded
 use Util::Yours -net; # Plugin::Net is loaded
 use Util::Yours -net_amazon; # Plugin::Net::Amazon is loaded
 use Util::Yours -net_all; # Plugin::Net and Plugin::Net::* is loaded
    

"_all" is special keyword. see "NOTE ABOUT all KEYWORD".

debug => 1/2

Util::Any doesn't say anything when loading module fails. If you pass debug value, warn or die.

 use Util::Any -list, {debug => 1}; # warn
 use Util::Any -list, {debug => 2}; # die
    

-data

from Scalar::Util (1.19)

 blessed
 dualvar
 isvstring
 isweak
 looks_like_number
 openhandle
 readonly
 refaddr
 reftype
 set_prototype
 tainted
 weaken

-hash

 hash_seed
 lock_hash
 lock_keys
 lock_value
 unlock_hash
 unlock_keys
 unlock_value

-list

 first
 max
 maxstr
 min
 minstr
 reduce
 shuffle
 sum

from List::MoreUtils (0.21)

 after
 after_incl
 all
 any
 apply
 before
 before_incl
 each_array
 each_arrayref
 false
 first_index
 first_value
 firstidx
 firstval
 indexes
 insert_after
 insert_after_string
 last_index
 last_value
 lastidx
 lastval
 mesh
 minmax
 natatime
 none
 notall
 pairwise
 part
 true
 uniq
 zip

from List::Pairwise (0.29)

 mapp
 grepp
 firstp
 lastp
 map_pairwise
 grep_pairwise
 first_pairwise
 last_pairwise
 pair

-string

 crunch
 define
 equndef
 fullchomp
 hascontent
 htmlesc
 neundef
 nospace
 randcrypt
 randword
 trim
 unquote

from String::CamelCase (0.01)

 camelize
 decamelize
 wordsplit

-debug

 Dumper

use module with 'all' cannot take its arguments

 use Util::Any -all; # or 'all', ':all'

This cannot take sequential arguments for "all". For example;

 NG: use Util::Any -all => ['shuffle'];

When sequential arguments is kind's, it's ok.

 use Util::Any -all, -list => ['unique'];

-plugin_module_all cannot take its arguments

 use Util::Yours -plugin_name_all;

This cannot take sequential arguments for it. For example:

 NG: use Util::Yours -plugin_name_all => ['some_function'];

$Utils STRUCTURE

 $Utils => {
    # simply put module names
    -kind1 => [qw/Module1 Module2 ..../],
    -# Module name and its prefix
    -kind2 => [ [Module1 => 'module_prefix'], ... ],
    # limit functions to be exported
    -kind3 => [ [Module1, 'module_prefix', [qw/func1 func2/] ], ... ],
    # as same as above except not specify modul prefix
    -kind4 => [ [Module1, '', [qw/func1 func2/] ], ... ],
 };

Key must be lower character.

 NG $Utils = { LIST => [qw/List::Util/]};
 OK $Utils = { list => [qw/List::Util/]};
 OK $Utils = { -list => [qw/List::Util/]};
 OK $Utils = { ':list' => [qw/List::Util/]};

"all" cannot be used for key.

 NG $Utils = { all    => [qw/List::Util/]};
 NG $Utils = { -all   => [qw/List::Util/]};
 NG $Utils = { ':all' => [qw/List::Util/]};

Value is array ref which contained scalar or array ref.

Scalar is module name. Array ref is module name and its prefix.

 $Utils = { list => ['List::Utils'] };
 $Utils = { list => [['List::Utils', 'prefix_']] };

see "PREFIX FOR EACH MODULE"

PREFIX FOR EACH MODULE

 use base qw/Util::Any/;
 
 our $Utils = {
      list => [['List::Util' => 'lu_'], ['List::MoreUtils' => 'lmu_']]
 };

In your code;

 use Util::Yours qw/list/, {module_prefix => 1};

SMART RENAME FOR EACH KIND

 our $Utils = {
   utf8 => [['utf8', '',
             {
              is_utf8   => 'is_utf8',
              upgrade   => 'utf8_upgrade',
              downgrade => 'downgrade',
             }
            ]],
 };

In this definition, use "prefix =" 1> is not good idea. If you use it:

 is_utf8      => utf8_is_utf8
 utf8_upgrade => utf8_utf8_upgrade
 downgrade    => utf8_downgrade

That's too bad. If you use "smart_rename =" 1> instead:

 is_utf8      => is_utf8
 utf8_upgrade => utf8_upgrade
 downgrade    => utf8_downgrade

rename rule is represented in _create_smart_rename in Util::Any.

CHANGE smart_rename BEHAVIOUR

OTHER WAY TO EXPORT FUNCTIONS

Util::Any automatically export functions from modules' @EXPORT and @EXPORT_OK. In some cases, it is not good idea like Data::Dumper's Dumper and "DumperX". These 2 functions are same feature.

So you can limit functions to be exported.

 our $Utils = {
      -debug => [
                ['Data::Dumper', '',
                ['Dumper']], # only Dumper method is exported.
               ],
 };

or

 our $Utils = {
      -debug => [
                ['Data::Dumper', '',
                 { -select => ['Dumper'] }, # only Dumper method is exported.
                ]
               ],
 };

SELECT FUNCTIONS EXCEPT

Inverse of -select option. Cannot use this option with -select.

 our $Utils = {
      -debug => [
                ['Data::Dumper', '',
                 { -except => ['DumperX'] }, # export functions except DumperX
                ]
               ],
 };

RENAME FUNCTIONS

To rename function name, write original function name as hash key and renamed name as hash value. this definition is prior to -select/-except.

In the following example, 'min' is not in -select list, but can be exported.

 our $Utils = {
      -list  => [[
                  'List::Util', '',
                  {
                   'first' => 'list_first', # first as list_first
                   'sum'   => 'lsum',       # sum   as lsum
                   'min'   => 'lmin',       # min   as lmin
                   -select => ['first', 'sum', 'shuffle'],
                  }
               ]]
  };

USE Sub::Exporter's GENERATOR WAY

It's somewhat complicate, I just show you code.

Your utility class:

  package SubExporterGenerator;
  
  use strict;
  use Util::Any -Base;
  
  our $Utils =
    {
     -test => [[
               'List::Util', '',
               { min => \&build_min_reformatter,}
              ]]
    };
  
  sub build_min_reformatter {
    my ($pkg, $class, $name, @option) = @_;
    no strict 'refs';
    my $code = do { no strict 'refs'; \&{$class . '::' . $name}};
    sub {
      my @args = @_;
      $code->(@args, $option[0]->{under} || ());
    }
  }

Your script using your utility class:

 package main;
 
 use strict;
 use lib qw(lib t/lib);
 use SubExporterGenerator -test => [
       min => {-as => "min_under_20", under => 20},
       min => {-as => "min_under_5" , under => 5},
     ];
 
 print min_under_20(100,25,30); # 20
 print min_under_20(100,10,30); # 10
 print min_under_20(100,25,30); # 5
 print min_under_20(100,1,30);  # 1

If you don't specify "-as", exported function as "min". But, of course, the following doesn't work.

 use SubExporterGenerator -test => [
       min => {under => 20},
       min => {under => 5},
     ];

Util::Any try to export duplicate function "min", one of both should fail.

GIVE DEFAULT ARGUMENTS TO CODE GENERATOR

You may want to give default arguments to all code generators in same kind. For example, if you create shortcut to use Number::Format, you may want to give common arguments with creating instance.

 -number => [
    [ 'Number::Format' => {
        'round' => sub {
            my($pkg, $class, $func, $args, $default_args) = @_;
            my $n = 'Number::Format'->new(%$default_args);
            sub { $n->round(@_); }
        },
        'number_format' => sub {
            my($pkg, $class, $func, $args, $default_args) = @_;
            my $n = 'Number::Format'->new(%$default_args, %$args);
            sub { $n->format_number(@_); }
        }
      }
    ];

And write as the following:

 use Util::Yours -number => [-args => {thousands_sep => "_", int_curr_symbol => '\'} ];
 
 print number_format(100000); # 100_000
 print number_price(100000);  # \100_000

thousands_sep and int_curr_symbol are given to all of -number kind of function.

DO SOMETHING WITHOUT EXPORTING ANYTHING

 -strict => [
    [ 'strict' => {
        '.' => sub {
           strict->import();
           warnings->import();
        },
      }
    ];

This definition works like as pragma.

 use Util::Yours -strict;

function name '.' is special. This name is not exported and only execute the code in the definition.

ADD DEFAULT ARGUMENT FOR EXPORTING

 package You::Utils -Base;
 # ....
 sub _default_kinds { '-list', '-string' }

This means '-list' and '-string' arguments are given as default exporting arguments. So, these are same.

 use Your::Utils;

is equal to

 use Your::Utils -list, -string;

If you want to disable default kinds.

 use Your::Utils -list => [], -string;

ADD PLUGGABLE FEATURE FOR YOUR MODULE

 package Util::Yours;
 use Util::Any -Base, -Pluggable;

And write plugin as the following:

  package Util::Yours::Plugin::Net;
  
  sub utils {
    # This structure is as same as $Utils.
    return {
        # kind name and plugin name should be same.
        -net => [
                  [
                   'Net::Amazon', '',
                   {
                    amazon => sub {
                      my ($pkg, $class, $func, $args) = @_;
                      my $amazon = Net::Amazon->new(token => $args->{token});
                      sub { $amazon }
                    },
                   }
                  ]
                ]
       };
  }
  
  1;

And you can use it as the following.

  use Util::Yours -net => [amazon => {token => "your_token"}];
  
  my $amazon = amazon; # get Net::Amazon object;

Util::Any can merge definition in plugins. If same kind is in several plugins, it works. But same kind and same function name is defined, one of them doesn't work.

WORKING WITH EXPORTER-LIKE MODULES

CPAN has some modules to export functions. Util::Any can work with some of such modules, Exporter, Exporter::Simple and Sub::Exporter. (note that: Perl6::Export::Attrs is not supported after version 0.25 and the above) If you want to use other modules, please inform me or implement import method by yourself.

If you want to use module mentioned above, you have to change the way to inherit these modules.

DIFFERENCE between 'all' and '-all' or ':all'

If your utility module which inherited Util::Any has utility functions and export them by Exporter-like module, behaviour of 'all' and '-all' or ':all' is a bit different.

 'all' ... export all utilities defined in your package's $Utils variables.
 '-all' or ':all' ... export all utilities including functions in your util module itself.

ALTERNATIVE INHERITING

Normally, you use;

 package YourUtils;
 
 use Util::Any -Base; # or "use base qw/Util::Any/;"

But, if you want to use Exporter, Exporter::Simple or Perl6::Export::Attrs. write as the following, instead.

 # if you want to use Exporter
 use Util::Any -Exporter;
 # if you want to use Exporter::Simple
 use Util::Any -ExporterSimple;
 # if you want to use Sub::Exporter
 use Util::Any -SubExporter;

That's all. Note that don't use base the above modules in your utility module.

There is one notice to use Sub::Exporter.

 Sub::Exporter::setup_exporter
       ({
           as => 'do_import', # name is important
           exports => [...],
           groups  => { ... },
       });

You must pass "as" option to setup_exporter and its value must be "do_import". If you want to change this name, do the following.

 Sub::Exporter::setup_exporter
       ({
           as => $YourUtils::SubExporterImport = '__do_import',
           exports => [...],
           groups  => { ... },
       });