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