/ 
overload-reify-0.07
River stage zero No dependents
/ overload::reify

NAME

overload::reify - Provide named methods for inherited overloaded operators

VERSION

version 0.07

SYNOPSIS

{ package Parent;
  use overload
    '+=' => 'plus_equals',
    '++' => sub { ... };

  # ...

  sub plus_equals { ... }
}

{ package Child1;

  use Parent;

  use overload::reify;

  # this creates new methods:
  #
  #  operator_increment()
  #    performs the ++ operation
  #
  #  operator_add_assign()
  #    comparable to plus_equals(), but modifying
  #    it won't modify plus_equals

}

{ package Child2;

  use Parent;

  # don't create methods for overloads with method names
  use overload::reify { -methods => 0 };

  # this creates new methods:
  #
  #  operator_increment()
  #    performs the ++ operation
}

DESCRIPTION

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 code reference, e.g.

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

In the latter case, the overloaded subroutine cannot be modified 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 for overloaded operators into a package's symbol table. The method names are constructed by concatenating a prefix (provided by the -prefix option) and a standardized operator name (see "method_names"). An existing method with the same name will be quietly replaced, unless the "-redefine" option is true.

For operators overloaded with a method name which is different from the new method name, a wrapper which calls the original method by its name is installed. If the original and new method names are the same, nothing is installed.

For operators overloaded with a code reference, an alias to the code reference is installed.

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.

-redefine

A boolean which if true will cause an exception to be thrown if installing the new method would replace an existing one of the same name in the package specified by "-into". Defaults to false.

-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_.

METHODS

tag_to_ops

@ops = overload::reify->tag_to_ops( $tag );

Return a list of operators correspond to the passed tag. A tag is a string which is either

  • an operator, e.g. '++'; or

  • a string (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.

method_names

# from the command line:
perl -Ilib -MData::Dumper -Moverload::reify \
   -e 'print Dumper overload::reify->method_names()'

# in code
$hashref = overload::reify->method_names( ?@ops, ?\%options );

This class method returns the mapping between operators and generated method names. Supplied operators are first run through "tag_to_ops". If no operators are passed, a map for all of the supported ones is returned.

The map is returned a hashref whose keys are operators and whose values are the names of generated methods. The available options are:

-prefix

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

SEE ALSO

Class::Method::Modfiers, Moo, Moose.

CONTRIBUTORS

Thanks to

  • MSTROUT for the suggestion to house this code in its own module and for the module name.

  • HAARG for reviewing an initial version of this code.

AUTHOR

Diab Jerius <djerius@cpan.org>

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.