Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 214 lines (148 sloc) 7.737 kB
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line t…
Darren_Duncan authored
1
68d062f Move synopses to their new home.
pmichaud authored
2 =encoding utf8
3
4 =head1 TITLE
5
6 Synopsis 13: Overloading
7
04840a3 [Spec] treat all authors equally
lwall authored
8 =head1 AUTHORS
68d062f Move synopses to their new home.
pmichaud authored
9
04840a3 [Spec] treat all authors equally
lwall authored
10 Larry Wall <larry@wall.org>
68d062f Move synopses to their new home.
pmichaud authored
11
12 =head1 VERSION
13
04840a3 [Spec] treat all authors equally
lwall authored
14 Created: 2 Nov 2004
15
ea9fd14 @TimToady imported multis automatically re-export
TimToady authored
16 Last Modified: 17 Jan 2012
17 Version: 17
68d062f Move synopses to their new home.
pmichaud authored
18
19 =head1 Overview
20
21 This synopsis discusses those portions of Apocalypse 12 that ought to have
22 been in Apocalypse 13.
23
24 =head1 Multiple dispatch
25
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
26 The overloading mechanism of Perl 5 has been superseded by Perl 6's
68d062f Move synopses to their new home.
pmichaud authored
27 multiple dispatch mechanism. Nearly all internal functions
28 are defined as C<multi> subs or C<multi> methods on generic types.
29 Built-in operators are merely oddly named functions with an alternate
30 call syntax. All you have to do to overload them is to define your
31 own C<multi> subs and methods that operate on arguments with more
32 specific types.
33
34 For unary operators, this makes little effective difference, but for
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
35 binary operators, multiple dispatch fixes the Perl 5 problem of paying
68d062f Move synopses to their new home.
pmichaud authored
36 attention only to the type of the left argument. Since both argument
37 types are used in deciding which routine to call, there is no longer
38 any trickery involving swapping the arguments to use the right argument's
39 type instead of the left one. And there's no longer any need to
40 examine a special flag to see if the arguments were reversed.
41
42 For much more about multiple dispatch, see S12.
43
44 =head1 Syntax
45
46 There is no longer any special C<use overload> syntax separate from the
47 declarations of the C<multi> routines themselves. To overload an
48 existing built-in sub, say something like:
49
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
50 multi sub uc (TurkishStr $s) {...}
68d062f Move synopses to their new home.
pmichaud authored
51
60aef3a @TimToady Adjust proto semantics to address various concerns
TimToady authored
52 A C<multi> is automatically exported if governed by a proto that is exported.
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
53 It may also be explicitly exported:
54
55 multi sub uc (TurkishStr $s) is exported {...}
56
57 Now if you call C<uc()> on any Turkish string, it will call your
58 function rather than the built-in one.
68d062f Move synopses to their new home.
pmichaud authored
59
ea9fd14 @TimToady imported multis automatically re-export
TimToady authored
60 If you import a multi into a UNIT scope, it is automatically re-exported.
61
68d062f Move synopses to their new home.
pmichaud authored
62 The types of the parameters are included in the I<longname> of any C<multi>
63 sub or method. So if you want to overload string concatenation for Arabic
64 strings so you can handle various ligatures, you can say:
65
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
66 multi sub infix:<~>(ArabicStr $s1, ArabicStr $s2) {...}
67 multi sub infix:<~>(Str $s1, ArabicStr $s2) {...}
68 multi sub infix:<~>(ArabicStr $s1, Str $s2) {...}
68d062f Move synopses to their new home.
pmichaud authored
69
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
70 The C<use overload> syntax had one benefit over Perl 6's syntax in that
68d062f Move synopses to their new home.
pmichaud authored
71 it was easy to alias several different operators to the same service
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
72 routine. This can easily be handled with Perl 6's aliasing:
68d062f Move synopses to their new home.
pmichaud authored
73
74 multi sub unimpl (MyFoo $x, MyFoo $y) { upchuck(); }
75 &infix:<+> ::= &unimpl;
76 &infix:<-> ::= &unimpl;
77 &infix:<*> ::= &unimpl;
78 &infix:</> ::= &unimpl;
79
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
80 A C<multi> is in effect only within the scope in which it is defined or
81 imported. Generally you want to put your C<multi> subs into a package
afbd198 [Spec] get rid of some fossil uses of * spotted by masak++
lwall authored
82 that will be imported wherever they are needed.
68d062f Move synopses to their new home.
pmichaud authored
83
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
84 Conjectural: If the first parameter to a C<multi> signature is followed
68d062f Move synopses to their new home.
pmichaud authored
85 by an invocant colon, that signature represents two signatures, one
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
86 for an ordinary method definition, and one for the corresponding C<multi>
68d062f Move synopses to their new home.
pmichaud authored
87 definition that has a comma instead of the colon. This form is legal
88 only where the standard method definition would be legal, and only
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
89 if any declared type of the first parameter is consistent with C<$?CLASS>.
68d062f Move synopses to their new home.
pmichaud authored
90
91 =head1 Fallbacks
92
93 Dispatch is based on a routine's signature declaration without regard
94 to whether the routine is defined yet. If an attempt is made to
95 dispatch to a declared but undefined routine, Perl will redispatch
96 to an C<AUTODEF> submethod [conjectural] as appropriate to define the routine. This provides
97 a run-time mechanism for fallbacks. By default, these declarations
98 are taken at face value and do not specify any underlying semantics.
99 As such, they're a "shallow" interpretation.
100
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
101 [Note: the following section on "is deep" may no longer be necessary given
102 the way metaoperators are now constructed.]
103
68d062f Move synopses to their new home.
pmichaud authored
104 However, sometimes you want to specify a "deep" interpretation of
105 your operators. That is, you're specifying the abstract operation,
106 which may be used by various shallow operators. Any deep multi
107 declarations will be "amplified" into all the shallow operators that
108 can be logically based on it. If you say:
109
110 multi sub infix:<%> (Us $us, Them $them) is deep { mymod($us,$them) }
111
112 then
113
114 multi sub infix:<%=> (Us $us, Them $them) { $us = $us % $them }
115
116 is also generated for you (unless you define it yourself).
117 The mappings of magical names to sub definitions is controlled by the
118 C<%?DEEPMAGIC> compiler hash. Pragmas can influence the contents of
119 this hash over a lexical scope, so you could have different policies
120 on magical autogeneration. The default mappings correspond to the
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
121 standard fallback mappings of Perl 5 overloading.
68d062f Move synopses to their new home.
pmichaud authored
122
123 These deep mappings are mainly intended for infix operators that would have
124 difficulty naming all their variants. Prefix operators tend to be simpler;
125 note in particular that
126
127 multi prefix:<~> is deep {...}
128
129 is better written:
130
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
131 method Stringy {...}
68d062f Move synopses to their new home.
pmichaud authored
132
133 (see below).
134
135 =head1 Type Casting
136
137 A class may define methods that allow it to respond as if it were a
138 routine, array, or hash. The long forms are as follows:
139
4fe1480 @sorear Respec postcircumfix:<( )> to take arguments directly
sorear authored
140 method postcircumfix:<( )> (|capture) {...}
5d67a32 [S13] *@@ ---> **@
lwall authored
141 method postcircumfix:<[ ]> (**@slice) {...}
142 method postcircumfix:<{ }> (**@slice) {...}
68d062f Move synopses to their new home.
pmichaud authored
143
144 Those are a bit unwieldy, so you may also use these short forms:
145
4fe1480 @sorear Respec postcircumfix:<( )> to take arguments directly
sorear authored
146 method &.( |capture ) {...}
5d67a32 [S13] *@@ ---> **@
lwall authored
147 method @.[ **@slice ] {...}
148 method %.{ **@slice } {...}
68d062f Move synopses to their new home.
pmichaud authored
149
150 The sigil-dot sequence in these short forms autogenerates the
151 corresponding public operators, in exactly the same way that
152 the sigil-dot in:
153
154 has $.action;
155 has @.sequence;
156 has %.mapping;
157
158 autogenerates public accessor methods.
159
160 And because it uses the same method-autogeneration mechanism, the
161 specific sigil used to specify a short-form postcircumfix operator
162 doesn't actually matter...as long as it's followed by a dot and the
163 bracket pair containing the signature. (Though it's probably kinder
164 to future readers of your code to stick with the "natural" sigil
165 for each type of bracket.)
166
167 Note that the angle bracket subscripting form C<< .<a b c> >>
168 automatically translates itself into a call to C< .{'a','b','c'} >,
169 so defining methods for angles is basically useless.
170
171 The expected semantics of C<&.()> is that of a type coercion which may
172 or may not create a new object. So if you say:
173
174 $fido = Dog.new($spot)
175
176 it certainly creates a new C<Dog> object. But if you say:
177
178 $fido = Dog($spot)
179
180 it might call C<Dog.new>, or it might pull a C<Dog> with Spot's
181 identity from the dog cache, or it might do absolutely nothing if
182 C<$spot> already knows how to be a C<Dog>. As a fallback, if no
183 method responds to a coercion request, the class will be asked to attempt to
184 do C<Dog.new($spot)> instead.
185
186 It is also possible (and often preferable) to specify coercions from
187 the other end, that is, for a class to specify how to coerce one of
188 its values to some other class. If you define a method whose name
189 is a declared type, it is taken as a coercion to that type:
190
191 method Str { self.makestringval() }
192
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
193 As with all methods, you can also export the corresponding C<multi>:
68d062f Move synopses to their new home.
pmichaud authored
194
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
195 multi method Str is export { self.makestringval() }
68d062f Move synopses to their new home.
pmichaud authored
196
197 in which case you can use both calling forms:
198
199 $x.Str
200 Str($x)
201
202 If the source class and the destination class both specify a
203 coercion routine, the ambiguity is settled by the ordinary rules
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
204 of dispatch. That is, C<$x.Str> will always prefer the method form
205 and C<Str($x)> will always prefer the functional form.
68d062f Move synopses to their new home.
pmichaud authored
206
207 Note that, because the name of an anonymous class is unknown, coercion to
208 an anonymous class can only be specified by the destination class:
209
210 $someclass = generate_class();
211 $someclass($x);
212
213 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.