NAME

Sub::Exporter::ForMethods - helper routines for using Sub::Exporter to build methods

VERSION

version 0.100054

SYNOPSIS

In an exporting library:

  package Method::Builder;

  use Sub::Exporter::ForMethods qw(method_installer);

  use Sub::Exporter -setup => {
    exports   => [ method => \'_method_generator' ],
    installer => method_installer,
  };

  sub _method_generator {
    my ($self, $name, $arg, $col) = @_;
    return sub { ... };
  };

In an importing library:

  package Vehicle::Autobot;
  use Method::Builder method => { -as => 'transform' };

DESCRIPTION

The synopsis section, above, looks almost indistinguishable from any other use of Sub::Exporter, apart from the use of method_installer. It is nearly indistinguishable in behavior, too. The only change is that subroutines exported from Method::Builder into named slots in Vehicle::Autobot will be wrapped in a subroutine called Vehicle::Autobot::transform. This will insert a named frame into stack traces to aid in debugging.

More importantly (for the author, anyway), they will not be removed by namespace::autoclean. This makes the following code work:

  package MyLibrary;

  use Math::Trig qw(tan);         # uses Exporter.pm
  use String::Truncate qw(trunc); # uses Sub::Exporter's defaults

  use Sub::Exporter::ForMethods qw(method_installer);
  use Mixin::Linewise { installer => method_installer }, qw(read_file);

  use namespace::autoclean;

  ...

  1;

After MyLibrary is compiled, namespace::autoclean will remove tan and trunc as foreign contaminants, but will leave read_file in place. It will also remove method_installer, an added win.

PERL VERSION SUPPORT

This module has a long-term perl support period. That means it will not require a version of perl released fewer than five years ago.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

EXPORTS

Sub::Exporter::ForMethods offers only one routine for export, and it may also be called by its full package name:

method_installer

  my $installer = method_installer(\%arg);

This routine returns an installer suitable for use as the installer argument to Sub::Exporter. It updates the \@to_export argument to wrap all code that will be installed by name in a named subroutine, then passes control to the default Sub::Exporter installer.

The only argument to method_installer is an optional hashref which may contain a single entry for rebless. If the value for rebless is true, when a blessed subroutine is wrapped, the wrapper will be blessed into the same package.

AUTHOR

Ricardo Signes <rjbs@cpan.org>

CONTRIBUTOR

Ricardo Signes <rjbs@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Ricardo Signes.

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