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.

cpanm overload::reify

perl -MCPAN -e shell
install overload::reify