TITLE

Synopsis 13: Overloading

AUTHORS

    Larry Wall <larry@wall.org>

VERSION

    Created: 2 Nov 2004

    Last Modified: 25 Oct 2010
    Version: 15

Overview

This synopsis discusses those portions of Apocalypse 12 that ought to have been in Apocalypse 13.

Multiple dispatch

The overloading mechanism of Perl 5 has been superseded by Perl 6's multiple dispatch mechanism. Nearly all internal functions are defined as multi subs or multi methods on generic types. Built-in operators are merely oddly named functions with an alternate call syntax. All you have to do to overload them is to define your own multi subs and methods that operate on arguments with more specific types.

For unary operators, this makes little effective difference, but for binary operators, multiple dispatch fixes the Perl 5 problem of paying attention only to the type of the left argument. Since both argument types are used in deciding which routine to call, there is no longer any trickery involving swapping the arguments to use the right argument's type instead of the left one. And there's no longer any need to examine a special flag to see if the arguments were reversed.

For much more about multiple dispatch, see S12.

Syntax

There is no longer any special use overload syntax separate from the declarations of the multi routines themselves. To overload an existing built-in sub, say something like:

    multi sub uc (TurkishStr $s) {...}

A multi is automatically exported if governed by a proto that is exported. It may also be explicitly exported:

    multi sub uc (TurkishStr $s) is exported {...}

Now if you call uc() on any Turkish string, it will call your function rather than the built-in one.

The types of the parameters are included in the longname of any multi sub or method. So if you want to overload string concatenation for Arabic strings so you can handle various ligatures, you can say:

    multi sub infix:<~>(ArabicStr $s1, ArabicStr $s2) {...}
    multi sub infix:<~>(Str $s1, ArabicStr $s2) {...}
    multi sub infix:<~>(ArabicStr $s1, Str $s2) {...}

The use overload syntax had one benefit over Perl 6's syntax in that it was easy to alias several different operators to the same service routine. This can easily be handled with Perl 6's aliasing:

    multi sub unimpl (MyFoo $x, MyFoo $y) { upchuck(); }
    &infix:<+> ::= &unimpl;
    &infix:<-> ::= &unimpl;
    &infix:<*> ::= &unimpl;
    &infix:</> ::= &unimpl;

That's one solution, but often your alternatives all have the same name, and vary instead in their signature. Some operators are commutative, or can otherwise take their arguments in more than one order. Perl allows you to declare multiple signatures for a given body, and these will be pattern matched as if you had declared separate multi entries. If you say:

    multi sub infix:<+> (Us $us, Them $them) |
                        (Them $them, Us $us) { myadd($us,$them) }

that's equivalent to:

    multi sub infix:<+> (Us $us, Them $them) { myadd($us,$them) }
    multi sub infix:<+> (Them $them, Us $us) { myadd($us,$them) }

except that there really is only one body. If you declared a state variable within the body, for instance, there would only be one of them.

A multi is in effect only within the scope in which it is defined or imported. Generally you want to put your multi subs into a package that will be imported wherever they are needed.

When you use the multiple signature syntax, the alternate signatures are not required to all bind the same set of formal variable names, nor are all parameters of a given name required to bind with the same type. Unbound parameters will be born with an undefined value (even if they have a default). For any parameter that occurs in multiple signatures with non-identical nominal types, the actual lexical variable will declared with a nominal type of Mu, and if unbound, will contain Mu. To catch parameter name typos, the compiler may warn about unused parameters.

Conjectural: If the first parameter to a multi signature is followed by an invocant colon, that signature represents two signatures, one for an ordinary method definition, and one for the corresponding multi definition that has a comma instead of the colon. This form is legal only where the standard method definition would be legal, and only if any declared type of the first parameter is consistent with $?CLASS.

Fallbacks

Dispatch is based on a routine's signature declaration without regard to whether the routine is defined yet. If an attempt is made to dispatch to a declared but undefined routine, Perl will redispatch to an AUTODEF submethod [conjectural] as appropriate to define the routine. This provides a run-time mechanism for fallbacks. By default, these declarations are taken at face value and do not specify any underlying semantics. As such, they're a "shallow" interpretation.

[Note: the following section on "is deep" may no longer be necessary given the way metaoperators are now constructed.]

However, sometimes you want to specify a "deep" interpretation of your operators. That is, you're specifying the abstract operation, which may be used by various shallow operators. Any deep multi declarations will be "amplified" into all the shallow operators that can be logically based on it. If you say:

    multi sub infix:<%> (Us $us, Them $them) is deep { mymod($us,$them) }

then

    multi sub infix:<%=> (Us $us, Them $them) { $us = $us % $them }

is also generated for you (unless you define it yourself). The mappings of magical names to sub definitions is controlled by the %?DEEPMAGIC compiler hash. Pragmas can influence the contents of this hash over a lexical scope, so you could have different policies on magical autogeneration. The default mappings correspond to the standard fallback mappings of Perl 5 overloading.

These deep mappings are mainly intended for infix operators that would have difficulty naming all their variants. Prefix operators tend to be simpler; note in particular that

    multi prefix:<~> is deep {...}

is better written:

    method Stringy {...}

(see below).

Type Casting

A class may define methods that allow it to respond as if it were a routine, array, or hash. The long forms are as follows:

    method postcircumfix:<( )> ($capture) {...}
    method postcircumfix:<[ ]> (**@slice) {...}
    method postcircumfix:<{ }> (**@slice) {...}

Those are a bit unwieldy, so you may also use these short forms:

    method &.( $capture ) {...}
    method @.[ **@slice ] {...}
    method %.{ **@slice } {...}

The sigil-dot sequence in these short forms autogenerates the corresponding public operators, in exactly the same way that the sigil-dot in:

    has $.action;
    has @.sequence;
    has %.mapping;

autogenerates public accessor methods.

And because it uses the same method-autogeneration mechanism, the specific sigil used to specify a short-form postcircumfix operator doesn't actually matter...as long as it's followed by a dot and the bracket pair containing the signature. (Though it's probably kinder to future readers of your code to stick with the "natural" sigil for each type of bracket.)

Note that the angle bracket subscripting form .<a b c> automatically translates itself into a call to .{'a','b','c'} , so defining methods for angles is basically useless.

The expected semantics of &.() is that of a type coercion which may or may not create a new object. So if you say:

    $fido = Dog.new($spot)

it certainly creates a new Dog object. But if you say:

    $fido = Dog($spot)

it might call Dog.new, or it might pull a Dog with Spot's identity from the dog cache, or it might do absolutely nothing if $spot already knows how to be a Dog. As a fallback, if no method responds to a coercion request, the class will be asked to attempt to do Dog.new($spot) instead.

It is also possible (and often preferable) to specify coercions from the other end, that is, for a class to specify how to coerce one of its values to some other class. If you define a method whose name is a declared type, it is taken as a coercion to that type:

    method Str { self.makestringval() }

As with all methods, you can also export the corresponding multi:

    multi method Str is export { self.makestringval() }

in which case you can use both calling forms:

    $x.Str
    Str($x)

If the source class and the destination class both specify a coercion routine, the ambiguity is settled by the ordinary rules of dispatch. That is, $x.Str will always prefer the method form and Str($x) will always prefer the functional form.

Note that, because the name of an anonymous class is unknown, coercion to an anonymous class can only be specified by the destination class:

    $someclass = generate_class();
    $someclass($x);

cpanm Perl6::Doc

perl -MCPAN -e shell
install Perl6::Doc