/ 
Exporter-Almighty-0.001005
River stage zero No dependents
/ Exporter::Almighty

NAME

Exporter::Almighty - combining Exporter::Tiny with some other stuff for added power

SYNOPSIS

package Your::Package;

use v5.12;
use Exporter::Almighty -setup => {
  tag => {
    foo => [ 'foo1', 'foo2' ],
    bar => [ 'bar1' ],
  },
  const => {
    colours => { RED => 'red', BLUE => 'blue', GREEN => 'green' },
  },
  enum => {
    Status => [ 'dead', 'alive' ],
  },
  also => [
    'strict',
    'Scalar::Util' => [ 'refaddr' ],
    'warnings',
  ],
};

sub foo1 { ... }
sub foo2 { ... }
sub bar1 { ... }

1;

DESCRIPTION

This module aims to make building exporters easier. It is based on Exporter::Tiny, but helps you avoid manually setting @EXPORT_OK, %EXPORT_TAGS, etc.

Exporter::Almighty supports lexical exports, even on Perl versions as old as 5.12.

Exporter::Almighty indeed requires Perl 5.12, so it's strongly recommended you add use v5.12 (or higher) before use Exporter::Almighty so that your package can benefit from features which don't exist in legacy versions of Perl.

Setup Options

Exporter::Almighty's own setup happens through its import. A setup hashref is passed as per the example in the "SYNOPSIS". Each key in this hash is a setup option.

The names are all short, singular names, in case you forget whether to use tag or tags!

tag

This is a hashref where the keys are tag names and the values are arrayrefs of function names.

use Exporter::Almighty -setup => {
  tag => {
    foo => [ 'foo1', 'foo2' ],
    bar => [ 'bar1' ],
  }
};

A user of the package defined in the "SYNOPSIS" could import:

use Your::Package qw( foo1 foo2 bar1 );   # import functions by name
use Your::Package qw( :foo );             # import 'foo1' and 'foo2'
use Your::Package qw( -foo );             # same!

If you have a tag called default, that is special. It will be automatically exported if your caller doesn't provide an explicit list of things they want to import.

The following other tags also have special meanings: constants, types, assert, is, to, and all.

By convention, tags names should be snake_case.

const

Similar to tag this is a hashref where keys are tag names, but instead of the values being arrayrefs of function names, they are hashrefs which define constants.

use Exporter::Almighty -setup => {
  const => {
    colours => { RED => 'red', BLUE => 'blue', GREEN => 'green' },
  },
};

A user of the package defined in the "SYNOPSIS" could import:

use Your::Package qw( RED GREEN BLUE );   # import constants by name
use Your::Package qw( :colours );         # import 'colours' constants
use Your::Package qw( :constants );       # import ALL constants

By convention, the tag names should be snake_case, but constant names should be SHOUTING_SNAKE_CASE.

For every constant like RED, a readonly variable $RED is also created, making it easier to interpolate the constant into a string. These are not exported by default.

use Your::Package qw( $RED $GREEN $BLUE );  # import ro vars by name
use Your::Package qw( :ro_vars );           # import ALL ro vars

type

This is an arrayref of type libraries. Each library listed will be imported into your exporter, and then the types in it will be re-exported to the people who use your package. Each type library can optionally be followed by an arrayref of type names if you don't want to just import all types.

package Your::Package;

use Exporter::Almighty -setup => {
  tags => {
    foo => [ 'foo1', 'foo2' ],
  },
  type => [
    'Types::Standard',
    'Types::Common::String'  => [ 'NonEmptyStr' ],
    'Types::Common::Numeric' => [ 'PositiveInt', 'PositiveOrZeroInt' ],
  ],
};

sub foo1 { ... }
sub foo2 { ... }

...;

package main;

use Your::Package qw( -foo is_NonEmptyStr );

my $got = foo1();
if ( is_NonEmptyStr( $got ) ) {
  foo2();
}

If you re-export types like this, then your module will be "promoted" to being a subclass of Type::Library instead of Exporter::Tiny. (Type::Library is itself a subclass of Exporter::Tiny, so you don't miss out on any features.)

enum

This is a hashref where keys are enumerated type names, and the values are arrayrefs of strings.

use Exporter::Almighty -setup => {
  enum => {
    Status => [ 'dead', 'alive' ],
  },
};

A user of the package defined in the "SYNOPSIS" could import:

use Your::Package qw(
  Status
  is_Status
  assert_Status
  to_Status
  STATUS_ALIVE
  STATUS_DEAD
);
use Your::Package qw( +Status );  # shortcut for the above

The Status function exported by the above will return a Type::Tiny::Enum object.

The :types, :is, :assert, :to, and :constants tags will also automatically include the relevent exports.

If you export any enums then your module will be "promoted" from being an Exporter::Tiny to being a Type::Library.

By convention, enum types should be UpperCamelCase.

class

This is an arrayref of class names.

use Exporter::Almighty -setup => {
  class => [
    'HTTP::Tiny',
    'LWP::UserAgent',
  ],
};

People can import:

use Your::Package qw( +HTTPTiny +LWPUserAgent );

unless ( is_HTTPTiny($x) or is_LWPUserAgent($x) ) {
  $x = HTTPTiny->new();
}

These create Type::Tiny::Class type constraints similar to how enum works. It will similarly promote your exporter to a Type::Library.

Notice that the new method will be proxied through to the underlying class, so these can also work as useful aliases for long class names.

use Exporter::Almighty -setup => {
  class => [
    'ShortName' => { class => 'Very::Long::Class::Name' },
    'TinyName'  => { class => 'An::Even::Longer::Class::Name' },
  ],
};

Exporter::Almighty will attempt to pre-emptively load modules mentioned here, so you don't need to do it yourself. However if the modules don't exist, it won't complain.

role

This works the same as class, except for roles.

duck

This is a hashref where keys are "duck type" type names, and the values are arrayrefs of method names.

use Exporter::Almighty -setup => {
  duck => [
    'UserAgent' => [ 'head', 'get', 'post' ],
  ],
};

These create Type::Tiny::Duck type constraints similar to how enum works. It will similarly promote your exporter to be a Type::Library.

also

A list of other packages to also export to your caller. Each package name can optionally be followed by an arrayref of import arguments.

use Exporter::Almighty -setup => {
  also => [
    'strict',
    'Scalar::Util' => [ 'refaddr' ],
    'warnings',
  ],
};

Your caller isn't given any options allowing them to opt in or out of this, so it is recommended that this be used sparingly. strict, warnings, feature, experimental, and namespace::autoclean are good packages to consider listing here. Packages that export named functions are less good.

API

Instead of:

package Your::Package;
use Exporter::Almighty -setup => \%setup;

It is possible to do this at run-time:

Exporter::Almighty->setup_for( 'Your::Package', %setup );

This may allow slightly more flexibility in some cases.

Exporter::Almighty is also designed to be easily subclassable.

Exporter::Tiny features you get for free

Features for you

Exporter::Almighty will import strict and warnings into your package.

You can export package variables, though it's rarely a good idea:

package Your::Package;

use Exporter::Almighty -setup => {
  tag => { default => [ 'xxx', '$YYY' ] },
};

our $YYY = 42;

You can use generators:

package Your::Package;

use Exporter::Almighty -setup => {
  tag => { default => [ 'xxx' ] },
};

sub _generate_xxx {
  my ( $me, $name, $vals, $opts ) = @_;
  my $caller = $opts->{into};
  
  # Return the sub which will be installed into caller as 'xxx'.
  return sub {
  };
}

...;

package main;
use Your::Package 'xxx' => \%vals;

xxx( ... );

Features for your caller

Your caller can do lexical imports:

use Your::Package -lexical, qw( ... );

Your caller can rename imported functions:

use Your::Package foo => { -as => 'foofoo' };

And everything else described in Exporter::Tiny::Manual::Importing.

BUGS

Please report any bugs to https://github.com/tobyink/p5-exporter-almighty/issues.

SEE ALSO

Exporter::Tiny, Exporter::Shiny.

CXC::Exporter::Util was an inspiration for this module and the features overlap a bit.

AUTHOR

Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2023 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.