NAME

Exporter::Handy::Util - Routines useful when exporting symbols thru Exporter and friends

VERSION

version 1.000004

SYNOPSIS

Define a module with exports

  package My::Utils;
  use Exporter::Handy -exporter_setup => 1;

  export(qw( foo $x @STUFF -strict_and_warnings ), ':baz' => ['foo'] );

  sub foo { ... }

  sub strict_and_warnings {
    strict->import;
    warnings->import;
  }

Create a new module which exports all that, and more

  package My::MoreUtils;
  use My::Utils -exporter_setup => 1;
  sub util_fn3 : Export(:baz) { ... }

Use the module

  use My::MoreUtils qw( -strict_and_warnings :baz @STUFF );
  # Use the exported things
  push @STUFF, foo(), util_fn3();

DESCRIPTION

This module is currently EXPERIMENTAL. You are advised to restrain from using it.

You have been warned.

FUNCTIONS

cxtags

Same as xtags() described below, except that this one assumes {sig => ':'} as part of the options.

Hence, this one is more suitable to be used in conjunction with Exporter::Extensible and descendants, such as Exporter::Handy, like below:

    use Exporter::Handy::Util qw(cxtags);
    use Exporter::Handy -exporter_setup => 1

    export(
        foo
        goo
        cxtags (
          bar => [qw( $bozo @baza boom )],
          util => {
            io   => [qw(slurp)],
            text => [qw(ltrim rtrim trim)],
          },
        )
    );

which is the same as:

    use Exporter::Handy -exporter_setup => 1

    export(
        foo
        goo
        ':bar'       => [qw( $bozo @baza boom )],
        ':util_io'   => [qw(slurp)],
        ':util_text' => [qw(ltrim rtrim trim)],
    );

xtags

Build one or more export tags suitable for Exporter and friends, such as: Exporter::Extensible, Exporter::Handy, Exporter::Tiny, Exporter::Shiny, Exporter::Almighty, ...

Compared to cxtags() described above, this one does not prefix tag keys by a colon (':').

Hence it's quite suitable for populating %EXPORT_TAGS, recognized by Exporter and many others, such as: Exporter::Tiny, Exporter::Shiny, Exporter::Almighty, ...

Note that although Exporter::Extensible and Exporter::Handy do recognize %EXPORT_TAGS, their preferred API involves a call to the export() function, which requires a colon (:) prefix for tag names... See cxtags() that does just that.

    use Exporter::Handy::Util qw(xtags);
    use parent Exporter;

    our %EXPORT_TAGS = (
      xtags (
        bar => [qw( $bozo @baza boom )],
        util => {
          io   => [qw(slurp)],
          text => [qw(ltrim rtrim trim)],
        },
      )
    );

is the same as:

    use parent Exporter;

    our %EXPORT_TAGS = (
        bar => [qw( $bozo @baza boom )],
        util_io   => [qw(slurp)],
        util_text => [qw(ltrim rtrim trim)],
    );

expand_xtags

Expand tags in a manner compatible with Exporter and friends, such as: Exporter::Extensible, Exporter::Handy, Exporter::Tiny, Exporter::Shiny, Exporter::Almighty, ...

    use Exporter::Handy::Util qw(expand_xtags);

    our @EXPORT = qw( slurp uniq );
    our %EXPORT_TAGS = (
      file    => [qw( slurp spew )],
      io      => [qw( :file open4 ) ],
      list    => [qw( uniq zip )],
      default => \@EXPORT,
    );
    say expand_xtags(\%EXPORT_TAGS, qw(file) );                  # prints: file
    say expand_xtags(\%EXPORT_TAGS, qw(:file open4) );           # prints: slurp, spew, open4

    say expand_xtags(\%EXPORT_TAGS, @EXPORT_TAGS{qw(io list)} ); # prints: slurp, spew, open4, uniq, zip

    our @EXPORT_OK = expand_xtags(\%EXPORT_TAGS, values %EXPORT_TAGS);
    @EXPORT_OK     = expand_xtags(\%EXPORT_TAGS, { keys => \'*' });

AUTHORS

Tabulo[n] <dev@tabulo.net>

LEGAL

This software is copyright (c) 2023 by Tabulo[n].

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

cpanm Exporter::Handy

perl -MCPAN -e shell
install Exporter::Handy