Skip to content

HTTPS clone URL

Subversion checkout URL

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