overload::reify

This pragma creates named methods for inherited operator overloads. The
child may then modify them using such packages as Moo, Moose, or
Class::Method::Modifers.

  Background

When a package overloads an operator it provides either a method name or
a coderef, e.g.

  overload
    '++' => 'plus_plus',
    '--' => sub { ..., }

In the latter case, the overloaded subroutine cannot be modfied via
e.g., the around subroutine in Class::Method::Modifiers (or Moo or
Moose) as it has no named symbol table entry.

overload::reify installs named methods in a package's symbol table for
overloaded operators. The methods for operators which already utilize a
method name are wrappers which call the original methods by name. For
operators using coderefs, the generated methods alias the coderefs. A
mapping of operators to method names is available via the "method_names"
method.

By default named methods are constructed for *all* overloaded operators,
regardless of how they are implemented (providing the child class a
uniform naming scheme). If this is not desired, set the "-methods"
option to false.

  Usage

The pragma is invoked with the following template:

  use overload::reify @operators, ?\%options;

where @operators is a list of strings, each of which may contain:

*   an operator to be considered, e.g. '++';

*   a tag (in the form ":"*class*) representing a class of operators. A
    class may be any of the keys accepted by the overload pragma, as
    well as the special class "all", which consists of all operators.

*   the token "-not", indicating that the next operator is to be
    excluded from consideration. If "-not" is the first element in the
    list of operators, the list is pre-seeded with all of the operators.

and %options is a hash with one or more of the following keys:

"-into"
    The package into which the methods will be installed. This defaults
    to the calling package.

"-methods"
    A boolean indicating whether or not wrappers will be generated for
    overloaded operators with named methods. This defaults to *true*.

"-prefix"
    The prefix for the names of the generated method names. It defaults
    to "operator_".

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Makefile.PL
  make
  make test
  make install

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Smithsonian Astrophysical
Observatory.

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