Introducing Exporter::Almighty

Consider a simple module like this:

  package MyApp::Util::Maths;

  use strict;
  use warnings;

  use constant PI => 3.14159265358979;
  use constant EULER => 2.71828182845905;

  use base 'Exporter';

  our @EXPORT_OK = qw( PI EULER add );
  our %EXPORT_TAGS = (
    arithmetic => [qw( add )],
    numbers => [qw( PI EULER )],
    all => @EXPORT_OK,
  );

  sub add {
    my ( $x, $y ) = @_;
    return $x + $y;
  }

  1;

You might use it like:

  use MyApp::Util::Maths qw( PI add );

  my $pi_plus_one = add( PI, 1 );

Exporter::Almighty is a module designed to reduce boilerplate in your utils-like modules, and increase their functionality.

The initial module can be rewritten as:

  package MyApp::Util::Maths;

  use Exporter::Almighty -setup => {
    const => {
      numbers => {
        PI => 3.14159265358979,
        EULER => 2.71828182845905,
      },
    },
    tag => {
      arithmetic => ['add'],
    },
  };

  sub add {
    my ( $x, $y ) = @_;
    return $x + $y;
  }

  1;

Exporter::Almighty sets up your exporting automatically (but using Exporter::Tiny instead of Exporter), and calls use strict and use warnings on your behalf.

Exporter::Almighty creates your constants for you, so you don’t need to duplicate your list of constants anywhere.

A bonus for your caller is that they can do:

  use MyApp::Util::Maths qw( $PI $EULER );

To import read-only $PI and $EULER variables instead of traditional constants.

Your caller can also import things lexically:

  my $pi_plus_one = do {
    use MyApp::Util::Maths -lexical, qw( add $PI );
    add( $PI, 1 );
  };

 # add() and $PI are not defined outside the above block

Your caller can also rename any imported functions:

  use MyApp::Util::Maths 'add' => { -as => 'sum_of' };

Exporter::Almighty has integrations with Type::Tiny making it easy to define and export Type::Tiny type constraints as part of your module. For example:

  package MyApp::Util::Maths;

  use Exporter::Almighty -setup => {
    const => { ... },
    tag => { ... },
    type => { 'Types::Standard' => ['Int', 'Num'] },
    class => ['Calc' => { class => 'MyApp::Calculator' }],
  };

  ...;

  1;

Now people can import the Int and Num type constraints from your module:

  use MyApp::Util::Maths qw( Int );

They can even import a is_Int function:

  use MyApp::Util::Maths qw( is_Int );

You’ve also defined a Calc class type constraint which can be used like this:

  has calculator => (
    is => 'ro',
    isa => Calc,
    default => sub { Calc->new },
  );

Exporter::Almighty makes defining enum-like data types easy:

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

  package Story::Character {
    use Moo;
    use My::Properties -lexical, '+Status';
    use experimental 'signatures';

    has status => (
      is => 'ro',
      isa => Status,
      default => STATUS_ALIVE,
    );

    sub meet ( $self, $other ) {

      if ( $self->status eq STATUS_ALIVE
      and $other->status eq STATUS_UNDEAD ) {
        print "Help!\n";
      }

      return $self;
    }
  }

Next time you’re writing a module that needs to export things, consider Exporter::Almighty. It could make things very easy for you, while adding a bunch of useful features for your caller.