view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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.

README  view on Meta::CPAN

      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.