-
Notifications
You must be signed in to change notification settings - Fork 36
/
S12-objects.pod
2107 lines (1559 loc) · 80.7 KB
/
S12-objects.pod
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=encoding utf8
=head1 TITLE
Synopsis 12: Objects
=head1 AUTHOR
Larry Wall <larry@wall.org>
=head1 VERSION
Maintainer: Larry Wall <larry@wall.org>
Date: 27 Oct 2004
Last Modified: 21 Jan 2009
Number: 12
Version: 68
=head1 Overview
This synopsis summarizes Apocalypse 12, which discusses object-oriented
programming.
=head1 Classes
A class is a module declared with the C<class> keyword. As with
modules, the public storage, interface, and name of the class is
represented by a package and its name, which is usually (but not
necessarily) a global name.
Taken as an object, a class represents all of the possible values of
its type, and the class object can thus be used as a proxy for any
"real" object of that type in calculating what a generic object of
that type can do. The class object is an Object, but it is not a
Class, because there is no mandatory Class class in Perl 6. We wish
to support both class-based and prototype-based OO programming.
So all metaprogramming is done through the current object's C<HOW>
object, which can delegate metaprogramming to any metamodel it likes.
However, by default, objects derived from Object support a fairly
standard class-based model.
There are two basic class declaration syntaxes:
class Foo; # rest of file is class definition
...
class Bar {...} # block is class definition
The first form is allowed only as the first declaration in a compilation
unit (that is, file or eval string).
In either case, the code represented by C<...> executes at compile
time as the body of a method of the metaclass, which is responsible
for interpreting the keywords of the class definition. (And since a
class is also a module, it also handles any module-oriented keywords.
You can export subs from a class at "use" time, for instance.)
A named class declaration can occur as part of an expression, just like
named subroutine declarations.
Classes are primarily for instance management, not code reuse.
Consider using C<roles> when you simply want to factor out
common code.
Perl 6 supports multiple inheritance, anonymous classes, and autoboxing.
All public method calls are "virtual" in the C++ sense. More
surprisingly, any class name mentioned in a method is also considered
virtual, that is, polymorphic on the actual type of the object.
You may derive from any built-in type, but the derivation of a low-level
type like C<int> may only add behaviors, not change the representation.
Use composition and/or delegation to change the representation.
Since there are no barewords in Perl 6, bare class names must be
predeclared. You can predeclare a stub class and fill it in later
just as you would a subroutine. Alternately, you can define a local
class or type variable using the C<::> type sigil. In an rvalue
context the C<::> prefix is a no-op, but in a declarational context,
it binds a new type name within its declared scope.
Without a C<my> or other scoping declarator, a bare C<class>
declarator declares an C<our> declarator, that is, a name within
the current package. Since class files begin parsing in the
C<GLOBAL> package, the first class declaration in the file installs
itself as a global name, and subsequent declarations then install
themselves into the current class rather than the global package.
Hence, to declare an inner class in the current package (or module, or
class), use C<our class> or just C<class>. To declare a lexically
scoped class, use C<my class>. Class names are always searched
for from innermost scopes to outermost. As with an initial C<::>,
the presence of a C<::> within the name does not imply globalness
(unlike in Perl 5). So the outward search can look in children
of the searched namespaces.
Class traits are set using C<is>:
class MyStruct is rw {...}
An "isa" is just a trait that happens to be another class:
class Dog is Mammal {...}
MI is specified with multiple C<is> modifiers:
class Dog is Mammal is Pet {...}
Roles use C<does> instead of C<is>:
class Dog is Mammal does Pet {...}
You may put these inside as well:
class Dog {
is Mammal;
does Pet;
...
}
Every object (including any class object) delegates to an instance of
its metaclass. You can get at the metaclass of any object via the
C<HOW> method, which returns an instance of the metaclass. A "class" object is just considered an "empty"
instance in Perl 6, more properly called a "prototype" object, or just
"protoobject".
The actual class object is the metaclass object pointed to by the
C<HOW> syntax. So when you say "C<Dog>", you're referring to both a
package and a protoobject, that latter of which points to the
actual object representing the class via C<HOW>. The protoobject
differs from an instance object not by having a different
type but rather in the extent to which it is defined. Some objects
may tell you that they are defined, while others may tell you that
they are undefined. That's up to the object, and depends on how the
metaclass chooses to dispatch the C<.defined> method.
The notation C<^Dog> is syntactic sugar for C<Dog.HOW()>, so C<^> can be
considered the "class" sigil when you want to talk about the current
metaclass instance.
Classes are open and non-final by default, but may easily be closed
or finalized not by themselves but by the entire application, provided
nobody issued an explicit compile-time request that the class stay open
or non-final. (Or a site policy could close any applications that use
the policy.) Platforms that do dynamic loading of sub-applications
probably don't want to close or finalize classes wholesale, however.
Roles take on some of the compile-time function of closed classes,
so you should probably use those instead anyway.
A private class can be declared using C<my>; most privacy issues are
handled with lexical scoping in Perl 6. The fact that importation
is lexical by default also means that any names your class imports
are also private by default.
=head1 Methods
Methods are routines declared in a class with the C<method> keyword:
method doit ($a, $b, $c) { ... }
method doit ($self: $a, $b, $c) { ... }
method doit (MyName $self: $a, $b, $c) { ... }
method doit (::?CLASS $self: $a, $b, $c) { ... }
Declaration of the invocant is optional. You may always access the
current invocant using the keyword C<self>. You need not declare the
invocant's type, since the lexical class of the invocant is known in any
event because methods must be declared in the class of the invocant,
though of course the actual (virtual) type may be a derived type of
the lexical type. You could declare a more restrictive type, but
that would probably be a bad thing for proper polymorphism. You may
explicitly type the invocant with the lexical type, but any check for
that will be optimized away. (The current lexically-determined class
may always be named as C<::?CLASS> even in anonymous classes or roles.)
To mark an explicit invocant, just put a colon after it:
method doit ($x: $a, $b, $c) { ... }
This is true also for multi methods:
multi method doit ($x: $a; $b; $c) { ... }
If you declare an explicit invocant for an Array type using an array variable,
you may use that directly in list context to produce its elements
method push3 (@x: $a, $b, $c) { ... any(@x) ... }
Note that the C<self> function is not context sensitive and thus always
returns the current object as a single item even in list context.
Hence if your current object happens to be an array but you did not
declare it with an explicit array variable, you need to explicitly
access the elements of the array somehow:
any(self) # WRONG
any(self[]) # okay
any(@(self)) # okay
any(@self) # WRONG unless you declared @self yourself
Private methods are declared using C<my>:
my method think (Brain $self: $thought)
(Such methods are completely invisible to ordinary method calls, and are
in fact called with a different syntax that uses C<!> in place of the C<.>
character. See below.)
To call an ordinary method with ordinary method-dispatch semantics,
use either the dot notation or indirect object notation:
$obj.doit(1,2,3)
doit $obj: 1,2,3
Indirect object notation now requires a colon after the invocant,
even if there are no arguments after the colon:
$handle.close;
close $handle:;
To reject method call and only consider subs, simply omit the colon
from the invocation line:
close($handle);
close $handle;
However, here the built-in B<IO> class defines C<method close () is export>,
which puts a C<multi sub close (IO)> in scope by default. Thus if the
C<$handle> evaluates to an IO object, then the two subroutine calls above
are still translated into method calls.
Dot notation can omit the invocant if it's in C<$_>:
.doit(1,2,3)
Note that there is no corresponding notation for private methods.
!doit(1,2,3) # WRONG, would be parsed as not(doit(1,2,3))
self!doit(1,2,3) # okay
There are several forms of indirection for the method name. You can
replace the identifier with a quoted string, and it will be evaluated
as a quote and then the result of that is used as the method name.
$obj."$methodname"(1,2,3) # use contents of $methodname as method name
$obj.'$methodname'(1,2,3) # no interpolation; call method with $ in name!
$obj!"$methodname" # indirect call to private method name
[Note: to help catch the mistaken use of C<< infix:<.> >> as a string
concatenation operator, Perl 6 will warn you about "useless use of
quotes" at compile time if the string inside quotes is an identifier.
(It does not warn about non-identifier strings, but such strings are
likely to produce missing method errors at run time in any case.)
Also, if there is whitespace around an intended C<.> concatenation,
it cannot be parsed as a method call at all; instead it fails at
compile time because standard Perl 6 has a pseudo C<< infix:<.> >> operator
that always fails at compile time.]
For situations where you already have a method located, you
can use a simple scalar variable in place of method name:
$methodobj = $foo ?? &bar !! &baz;
$obj.$methodobj(1,2,3)
or more succinctly but less readably:
$obj.$($foo ?? &bar !! &baz)(1,2,3)
The variable must contain a C<Callable> object (usually of type C<Code>), that is, a closure of some
sort. Regardless of whether the closure was defined as a method or
a sub or a block, the closure is called directly without any class
dispatch; from the closure's point of view, however, it is always
called as a method, with the object as its first argument, and the
rest of the arguments second, third, and so on. For instance, such
a closure may be used to abstract a "navigational" path through a
data structure without specifying the root of the path till later:
$locator = -> $root, $x, $y { $root.<foo>[$x]<bar>{$y}[3] }
$obj.$locator(42,"baz") # $obj<foo>[42]<bar><baz>[3]
$locator = { .<here> }
$obj.$locator # $obj<here>
As a convenient form of documentation, such a closure may also be written
in the form of an anonymous method:
$locator = method ($root: $x, $y) { $root.<foo>[$x]<bar>{$y}[3] }
$obj.$locator(42,"baz") # $obj<foo>[42]<bar><baz>[3]
$locator = method { self.<here> }
$obj.$locator # $obj<here>
Note however that, like any anonymous closure, an anonymous method
can only be dispatched to directly, like a sub. You may, of course,
bind an anonymous method to the name of a method in a class's public
interface, in which case it is no longer anonymous, and may be
dispatched to normally via the class. (And in fact, when the normal
method dispatcher is calling individual candidates in its candidate
list, it calls each candidate as a sub, not as a method, or you'd
end up with recursive dispatchers.) But fundamentally, there's
no such thing as a method closure. The C<method> declarator on an
anonymous method has the primary effect of making the declaration
of the invocant optional. (It also makes it an official C<Routine>
that can be returned from, just as if you'd used C<sub> to declare it.)
Instead of a scalar variable, an array variable may also be used:
$obj.@candidates(1,2,3)
As with the scalar variant, string method names are not allowed, only
C<Callable> objects, The list is treated as a list of candidates to
call. After the first successful call the rest of the candidates are
discarded. Failure of the current candidate is indicated by calling
C<nextwith> or C<nextsame> (see L</Calling sets of methods> below).
Note also that the
$obj.$candidates(1,2,3)
form may dispatch to a list of candidates if C<$candidates> is either
a list or a special C<Code> object representing a partial dispatch to a
list of candidates. If C<$candidates> (or any element of C<@candidates>)
is a List or Array object it is expanded out recursively until C<Callable>
candidates are found. The call fails if it hits a candidate that is
neither C<Callable> nor expandable.
Another form of indirection relies on the fact that operators are named
using a variant on hash subscript notation, which gives you these forms:
$x.infix:{$op}($y)
$x.prefix:{$op}
$x.postfix:{$op}
Generally you see these with the literal angle bracket form of subscript:
$a.infix:<*>($b) # equivalent to $a * $b
$a.prefix:<++> # equivalent to ++$a
$a.postfix:<++> # equivalent to $a++
If you omit the syntactic category, the call will be dispatched according
to the number of arguments either as "prefix" or as "infix":
$a.:<+>($b) # equivalent to $a + $b
$a.:<++> # equivalent to ++$a
$a.:<!> # equivalent to !$a
@a.:<[*]> # equivalent to [*] @a
But it's probably better to spell out the syntactic category when
the actual operator is not obvious:
$x.infix:{$op}($y)
$x.prefix:{$op}
You must use a special syntax to call a private method:
$mybrain!think($pinky)
self!think($pinky)
For a call on your own private method, you may also use the attribute-ish form:
$!think($pinky) # short for $(self!think($pinky))
Parentheses (or a colon) are required on the dot/bang notations if there
are any arguments (not counting adverbial arguments). There may be
no space between the method name and the left parenthesis unless you
use the dot form of parentheses or otherwise make use of "unspace":
.doit # okay, no arguments
.doit() # okay, no arguments
.doit () # ILLEGAL (two terms in a row)
.doit.() # okay, no arguments, same as .doit()
.doit\ () # okay, no arguments, same as .doit() (unspace form)
.doit\ .() # okay, no arguments, same as .doit.() (unspace form)
However, you can turn any of the legal forms above into a list
operator by appending a colon:
.doit: 1,2,3 # okay, three arguments
.doit(1): 2,3 # okay, one argument plus list
.doit (): 1,2,3 # ILLEGAL (two terms in a row)
.doit.(1): 2,3 # okay, same as .doit(1,2,3)
.doit\ .(1,2): 3 # okay, same as .doit(1,2,3)
In particular, this allows us to pass a closure in addition to the
"normal" arguments:
.doit: { $^a <=> $^b } # okay
.doit(): { $^a <=> $^b } # okay
.doit(1,2,3): { $^a <=> $^b } # okay
In case of ambiguity between indirect object notation and dot form,
the nearest thing wins:
dothis $obj.dothat: 1,2,3
means
dothis ($obj.dothat(1,2,3))
and you must say
dothis ($obj.dothat): 1,2,3
or
$obj.dothat.dothis: 1,2,3
if you mean the other thing.
Also note that if any term in a list is a bare closure or pointy
sub, it will be considered to be the final argument of its list
unless the closure's right curly is followed immediately by comma
or colon. In particular, a method call does *not* extend
the list, so you can say:
@list.grep: { $_ % 2 }.map: { $_ - 1 }.say
and that will be taken as equivalent to
@list.grep({ $_ % 2 }).map({ $_ - 1 }).say
Methods (and subs) may be declared as lvalues with C<is rw>. You can
use an argumentless C<rw> method anywhere you can use a variable,
including in C<temp> and C<let> statements. (In fact, you can use an
C<rw> method with arguments as a variable as long as the arguments are
used only to identify the actual value to change, and don't otherwise
have strange side effects that differ between rvalue and lvalue usage.
Setter methods that expect the new value as an argument do not fall
into the well-behaved category, however.)
Method calls on mutable scalars always go to the object contained in
the scalar (autoboxing value types as necessary):
$result = $object.doit();
$length = "mystring".codes;
Method calls on non-scalar variables just calls the C<Array>, C<Hash>
or C<Code> object bound to the variable:
$elems = @array.elems;
@keys = %hash.keys;
$sig = &sub.signature;
Use the prefix C<VAR> macro on a scalar variable to get at its
underlying C<Scalar> object:
if VAR($scalar).readonly {...}
C<VAR> is a no-op on a non-scalar variables and values:
VAR(1); # 1
VAR(@x); # @x
There's also a corresponding C<< postfix:<.VAR> >> macro that can be used
as if it were a method:
if $scalar.VAR.readonly {...}
(But since it's a macro, C<VAR> is not dispatched as a real method.
To dispatch to a real C<.VAR> method, use the indirect C<$obj."VAR">
form.)
You can also get at the container through the appropriate symbol table:
if MY::<$scalar>.readonly {...}
=head1 Class methods
Other OO languages give you the ability to declare "class" methods that either don't
need or actively prohibit calls on instances. Perl 6 gives you a choice.
If you declare an ordinary method, it can function as a "class" method when you
pass it a protoobject such as "C<Dog>" regardless of how defined the prototype
object is, as long as the method body doesn't try to access any information that
is undefined in the current instance.
Alternately, you can associate a class method with the current metaclass instance,
which as a singleton object knows your package, and can function as a more traditional
"class" method:
our $count;
method ^count { return $count }
Such a I<metaclass method> is always delegated to the C<HOW> object just as methods like
C<.does> are, so it's possible to call this as C<Dog.count> or C<$dog.count>.
However, best practice is probably to call such a class method as C<Dog.^count>
or C<$dog.^count> to make it clear that it's in its own namespace separate
from ordinary methods, and so that your class method cannot be accidentally
overridden by an ordinary method in a subclass--presuming you don't want to
allow for that possibility.
=head1 Submethods
Submethods are for declaring infrastructural methods that shouldn't
be inherited by subclasses, such as initializers:
submethod BUILD ($arg) {
$.attr = $arg;
}
Apart from the keyword, submethod declaration and call syntax is
identical to method syntax. You may mix methods and submethods of
the same name within the class hierarchy, but only the methods are
visible to derived classes via inheritance. A submethod is called
only when a method call is dispatched directly to the current class.
Conjecture: in order to catch spelling errors it is a compile-time
warning to define a submethod in any class that does not inherit the
corresponding method name from some base class. More importantly, this
would help safeguard Liskov substitutability. (But note that the
standard C<Object> class already supplies a default C<BUILD> and C<new>.)
=head1 Attributes
Attributes are stored in an opaque datatype, not in a hash. Not even
the class has to care how they're stored, since they're declared much like
ordinary variables. Instead of C<my>, use C<has>:
class Dog is Mammal {
has $.name = "fido";
has $.tail is rw;
has @.legs;
has $!brain;
...
}
Public attributes have a secondary sigil of "dot", indicating
the automatic generation of an accessor method of the same name.
Private attributes use an exclamation to indicate that no public accessor is
generated.
has $!brain;
The "true name" of the private variable always has the exclamation, but
much like with C<our> variables, you may declare a lexically scoped alias
to the private variable by saying:
has $brain; # also declares $!brain;
As with the C<!> declaration, no accessor is generated.
And any later references to the private variable within the same block
may either use or omit the exclamation, as you wish to emphasize or
ignore the privacy of the variable. Outside the block, you must use
the C<!> form. If you declare with the C<!> form, you must use that
form consistently everywhere. If you declare with the C<.> form, you
also get the private C<!> form as a non-virtual name for the actual
storage location, and you may use either C<!> or C<.> form anywhere
within the class, even if the class is reopened. Outside the class
you must use the public C<.> form, or rely on a method call (which
can be a private method call, but only for trusted classes).
For public attributes, some traits are copied to the accessor method.
The C<rw> trait causes the generated accessor to be declared C<rw>,
making it an lvalue method. The default is a read-only accessor.
If you declare the class as C<rw>, then all the class's attributes
default to C<rw>, much like a C struct.
You may write your own accessors to override any or all of the
autogenerated ones.
The attribute variables may be used within instance methods to refer
directly to the attribute values. Outside the instance methods, the
only access to attributes is through the accessors since an object has
to be specified. The dot form of attribute variables may be used in
derived classes because the dot form always implies a virtual accessor
call. Every I<dot> declaration also declares a corresponding private
I<exclamation> storage location, and the exclamation form may be used
only in the actual class, not in derived classes. Reference to the
internal storage location via C<$!foo> should generally be restricted
to submethods. Ordinary methods should stick to the C<$.foo> form.
In fact, within submethods, use of the C<$.foo> form on attributes
that are available as C<$!foo> (that is, that are declared directly
by this class) is illegal and produces a dire compile-time warning
(which may be suppressed). Within a submethod the C<$.foo> form may
only be used on attributes from parent classes, because only the parent
classes' part of the object is guaranteed to be in a consistent state
(because C<BUILDALL> call's the parent classes' C<BUILD> routines
first). If you attempt to get around this by declaring C<BUILD> as
a method rather than a submethod, that will also be flagged as a dire
(but suppressible) compile-time warning. (It is I<possible> to define
an inheritable C<BUILD> routine if you have access to all the metadata
for the current class, but it's not easy, and it certainly doesn't
happen by accident just because you change C<submethod> to C<method>.)
Because C<$.foo>, C<@.foo>, C<%.foo>, C<&.foo> are just shorthands of
C<self.foo> with different contexts, the class does not need to declare
any of those as an attribute -- a C<method foo> declaration can work
just as well.
The dot form can take an argument list as well. These are all equivalent:
self.foo(1,2,3); # a regular method call
self.foo.(1,2,3); # ditto
$.foo(1,2,3); # calls self.foo under $ context
$.foo.(1,2,3); # ditto
@.foo(1,2,3); # calls self.foo under @ context
@.foo.(1,2,3); # ditto
Pseudo-assignment to an attribute declaration specifies the default
value. The value on the right is treated as an implicit closure and
evaluated at object build time, that is, when the object is being
constructed, not when class is being composed. To refer to a value
computed at compilation or composition time, you can either use a
temporary or a temporal block of some sort:
has $.r = rand; # each object gets different random value
constant $random = rand;
has $.r = $random; # every object gets same value
has $.r = BEGIN { rand };
has $.r = INIT { rand };
has $.r = ENTER { rand };
has $.r = FIRST { rand };
has $.r = constant $myrand = rand;
When it is called at C<BUILD> time, the topic of the implicit closure
will be the attribute being initialized, while "self" refers to the
entire object being initialized. The closure will be called at the
end of the C<BUILD> only if the attribute is not otherwise initialized
in either the signature or the body of the C<BUILD>.
Class attributes are declared with either C<my> or C<our>. The only
difference from ordinary C<my> or C<our> variables is that an accessor
is generated according to the secondary sigil:
our $.count; # generates a public read-only .count accessor
our %!cache is rw; # generates no public accessor
my $.count; # generates a public read-only .count accessor
my %!cache is rw; # generates no public accessor
=head1 Construction and Initialization
All classes inherit a default C<new> constructor from C<Object>. It
expects all arguments to be named parameters initializing attributes of
the same name. You may write your own C<new> to override the default,
or write constructors with any other name you like. As in Perl 5,
a constructor is any routine that calls C<bless>. Unlike in Perl 5,
you call it as a method on the class object (though any object may be
used as a class object), passing the candidate as the first argument.
To bless a hash as in Perl 5, say:
$object = $class.bless({k1 => $v1, k2 => $v2, ...});
If the candidate is omitted, a candidate object is implicitly created in
the current class by calling C<CREATE>:
$object = $class.bless(k1 => $v1, k2 => $v2, ...)
$object = $class.bless(:k1($v1), :k2($v2), ...) # same
(The default C<CREATE> makes an opaque object.)
In addition to the candidate position argument, C<bless> also
allows one or more positional arguments representing autovivifying
protoobjects. Such an object looks like a prototype followed by a
hash subscript (see "Autovivifying objects" below). These are used
to initialize superclasses.
Other than the candidate object and any autovivifying protoobjects,
all arguments to C<bless> must be named arguments, not positional.
Hence, the main purpose of custom constructors is to turn positional
arguments into named arguments for C<bless>. The C<bless> method
allows an object to be used for its class invocant. (Your constructor
need not allow this). In any case, the object is not used as a prototype.
Use C<.clone> instead of C<.bless> if that's what you mean.
Any named arguments to C<bless> are automatically passed to the
C<CREATE> and C<BUILD> routines. If you wish to pass special options
to the C<CREATE> routine (such as an alternate representation),
call C<CREATE> yourself and then pass the resulting candidate to C<.bless>:
my $candidate = $class.CREATE(:repr<P6opaque>);
$object = $class.bless($candidate, :k1($v1), :k2($v2))
For the built-in default C<CREATE> method, C<P6opaque> is the default
representation. Other possiblilities are C<P6hash>, C<P5hash>,
C<P5array>, C<PyDict>, C<Cstruct>, etc.
The C<bless> function automatically calls all appropriate C<BUILD>
routines by calling the C<BUILDALL> routine for the current class,
which initializes the object in least-derived to most-derived order.
C<DESTROY> and C<DESTROYALL> work the same way, only in reverse.
The default C<BUILD> and C<BUILDALL> are inherited from C<Object>,
so you need to write initialization routines only if you wish to
modify the default behavior. The C<bless> function automatically
passes the appropriate argument list to the C<BUILD> of its various
parent classes. If the type of the parent class corresponds to one
of the protoobjects passed to bless, that protoobject's argument
list is used. Otherwise all the arguments to bless are passed to
the parent class's C<BUILD>. For the final C<BUILD> of the current
object, all the arguments to C<bless> are passed to the C<BUILD>, so
it can deal with any protoobjects that need special handling. (It is
allowed to pass protoobjects that don't correspond to any parent class.)
class Dog is Animal {...}
my $pet = Dog.new( :name<Fido>, Animal{ :blood<warm>, :legs(4) } );
Here we are using an autovivifying C<Animal> protoobject to specify what
the arguments to C<Animal>'s C<BUILD> routine should look like. (It does
not actually autovivify an C<Animal> apart from the one being created.)
You can clone an object, changing some of the attributes:
$newdog = $olddog.clone(:trick<RollOver>);
You can write your own C<BUILD> submethod to control initialization.
If you name an attribute as a parameter, that attribute is initialized
directly, so
submethod BUILD ($!tail, $!legs) {}
is equivalent to
submethod BUILD ($tail, $legs) {
$!tail = $tail;
$!legs = $legs;
}
Whether you write your own C<BUILD> or not, at the end of the C<BUILD>,
any default attribute values are implicitly copied into any attributes
that haven't otherwise been initialized.
=head1 Mutating methods
You can call an in-place mutator method like this:
@array .= sort;
If there is a C<self:sort> operator defined, that will be used. Otherwise
one will be autogenerated from the ordinary C<sort> operator, on the
order of:
@array = @array.sort;
One handy place for an in-place mutator is to call a constructor on a
variable of a known type:
my Dog $spot .= new(:tail<LONG> :legs<SHORT>);
=head1 Calling sets of methods
For any method name, there may be some number of candidate methods
that could handle the request: typically, inherited methods or
multi variants. The ordinary "dot" operator dispatches
to a method in the standard fashion. There are also "dot" variants
that call some number of methods with the same name:
$object.meth(@args) # calls one method or dies
$object.?meth(@args) # calls method if there is one, otherwise undef
$object.*meth(@args) # calls all methods (0 or more)
$object.+meth(@args) # calls all methods (1 or more)
The method name may be quoted when disambiguation is needed:
$object."+meth"(@args)
$object.'VAR'(@args)
As with ordinary calls, the identifier supplying the literal method
name may be replaced with an interpolated quote to specify the method
name indirectly. It may also be replaced with an array to specify
the exact list of candidates to be considered:
my @candidates := $object.WALK(:name<foo>, :breadth, :omit($?CLASS));
$object.*@candidates(@args);
The C<WALK> method takes these arguments:
:canonical # canonical dispatch order
:ascendant # most-derived first, like destruction order
:descendant # least-derived first, like construction order
:preorder # like Perl 5 dispatch
:breadth # like multi dispatch
:super # only immediate parent classes
:name<name> # only classes containing named method declaration
:omit(Selector) # only classes that don't match selector
:include(Selector) # only classes that match selector
Any method can defer to the next candidate method in the list by
the special functions C<callsame>, C<callwith>, C<nextsame>, and
C<nextwith>. The "same" variants reuse the original argument list
passed to the current method, whereas the "with" variants allow a
new argument list to be substituted for the rest of the candidates.
The "call" variants dispatch to the rest of the candidates and return
their values to the current method for subsequent processing, whereas
while the "next" variants don't return, but merely defer to the rest
of the candidate list:
callsame; # call with the original arguments (return here)
callwith(); # call with no arguments (return here)
callwith(1,2,3); # call with a new set of arguments (return here)
nextsame; # redispatch with the original arguments (no return)
nextwith(); # redispatch with no arguments (no return)
nextwith(1,2,3); # redispatch with a new set of arguments (no return)
For dispatches using C<.> and C<.?>, the return value is the
C<Capture> returned by the first method completed without deferring.
(Such a return value may in fact be failure, but it still counts as a
successful call from the standpoint of the dispatcher.) Likewise the
return value of C<.*> and C<.+> is a list of C<Captures> returned by
those methods that ran to completion without deferring to next method.
It is also possible to trim the candidate list so that the current
call is considered the final candidate. (This is implicitly the case
already for the dispatch variants that want a single successful call.)
For the multiple call variants, C<lastcall> will cause the dispatcher
to throw away the rest of the candidate list, and the subsequent
return from the current method will produce the final C<Capture>
in the returned list.
=head1 Parallel dispatch
Any of the method call forms may be turned into a hyperoperator by
treating the method call as a postfix:
@object».meth(@args) # calls one method on each
@object».?meth(@args) # calls method if there is one on each
@object».*meth(@args) # calls all methods (0 or more) on each
@object».+meth(@args) # calls all methods (1 or more) on each
@object».=meth(@args) # calls mutator method on each
@object»!meth(@args) # calls private method on each
The return value is a list with exactly the same number of elements
as C<@object>. Each such return value is a Capture or List of Captures
as specified above for the non-hyper "dot" variants.
Hyperoperators treat a junction as a scalar value, so saying:
$junction».meth(@args);
is just like:
$junction.meth(@args);
To hyperoperate over the values of a junction you have to explicitly
pull out the values:
$junction.values».meth(@args);
As with other forms of method call, the "meth" above may be replaced
with a quoted string or variable to do various forms of indirection.
Note that, as with any hyper operator, the methods may be evaluated
in any order (although the method results are always returned in the
same order as the list of invocants). Use an explicit loop if you
want to do something with ordered side effects, such as I/O.
=head1 Multisubs and Multimethods
The "long name" of a subroutine or method includes the type signature
of its invocant arguments. The "short name" doesn't. If you put
C<multi> in front of any sub (or method) declaration, it allows
multiple long names to share a short name, provided all of them are
declared C<multi>. (Putting C<proto> on the first such declaration has
the same effect, but usually you want to put the C<multi> explicitly
anyway for documentation.) If a sub (or method) is not marked
with C<multi> and it is not within the package or lexical scope of
a C<proto> of the same short name, it is considered unique, an I<only>
sub. You may mark a sub explicitly as C<only> if you're worried it
might be within the scope of a C<proto>, and you want to suppress
any other declarations within this scope. An C<only> sub (or method)
doesn't share with anything outside of it or declared prior to it.
Only one such sub (or method) can inhabit a given namespace, and it
hides any outer subs (or less-derived methods) of the same short name.
The default C<proto> declarations provided by Perl from the global
scope are I<not> automatically propagated to the user's scope
unless explicitly imported, so a C<sub> declaration there that
happens to be the same as a global multi is considered C<only> unless
explicitly marked C<multi>. In the absence of such an explicit C<sub>
declaration, however, the global proto is used by the compiler in
the analysis of any calls to that short name. (Since only list
operators may be post-declared, as soon as the compiler sees a
non-listop operator it is free to apply the global C<proto> since
any user-defined C<only> version of it must of necessity be declared
earlier in the user's lexical scope or not at all.)
A C<proto> may share dispatch with multis declared after it in the same scope,
but in that case it functions only as the final tie-breaker if the
inner multis can't decide among themselves what to do. (It may
then, of course, decide to redispatch outside of the current scope.)
Within its scope,
the signature of a C<proto> also nails down the presumed order
and naming of positional parameters, so that any multi call with named
arguments in that scope can presume to rearrange those arguments into
positional parameters based on that information. (Unrecognized names
remain named arguments.) Any other type information or traits attached
to the C<proto> are also shared by the routines within its scope,
so a C<proto> definition can be used to factor out common traits.
This is particularly useful for establishing grammatical categories
in a grammar by declaring a C<proto> C<token> or C<proto> C<rule>. (Perl 6's
grammar does this, for instance.)
You can have multiple C<multi> variables of the same name in the
same scope, and they all share the same storage location and type.
Usually these are declared by one C<proto> declaration at the top,
and leaving the C<multi> implicit on the rest of the declarations.
You might do this when you suspect you'll have multiple declarations
of the same variable name (such code might be produced by a macro
or by a code generator, for instance) and you wish to suppress any
possible warnings about redefinition.
In contrast, C<multi> routines can have only one instance of the long
name in any namespace, and that instance hides any outer (or less-derived)
routines with the same long name. It does not hide any routines with
the same short name but a different long name. In other words, multis
with the same short name can come from several different namespaces
provided their long names differ and their short names aren't hidden
by an C<only> declaration in some intermediate scope.
When you call a routine with a particular short name, if there are
multiple visible long names, they are all considered candidates.
They are sorted into an order according to how close the run-time types
of the arguments match up with the declared types of the parameters of
each candidate. The best candidate is called, unless there's a tie,
in which case the tied candidates are redispatched using any additional
tiebreaker long names (see below).
If a tie still results, only candidates marked with the C<default> trait are
considered, and the best matching default routine is used. If there
are no default routines, or if the available defaults are also tied,
a final tie-breaking proto sub is called, if there is one (see above).
Otherwise the dispatch fails.
The order in which candidates are considered is defined by a
topological sort based on the "type narrowness" of each candidate's
long name, where that in turn depends on the narrowness of each
parameter that is participating. Identical types are considered tied.
Parameters whose types are not comparable are also considered tied.
A candidate is considered narrower than another candidate if at least
one of its parameters is narrower and all the rest of its parameters
are either narrower or tied. This defines the partial ordering of
all the candidates. If the topological sort detects a circularity in
the partial ordering, all candidates in the circle are considered tied.
A warning will be issued at C<CHECK> time if this is detected and there is
no default candidate to fall back to.
Ordinarily all the parameters of a multi sub are considered for dispatch.
Here's a declaration for an integer range operator with two parameters
in its long name:
multi sub infix:<..>(Int $min, Int $max) {...}
Sometimes you want to have parameters that aren't counted as part of the
long name. For instance, if you want to allow an optional "step" parameter
to your range operator, but not consider it for multi dispatch, then put a
double semicolon instead of a comma before it:
multi sub infix:<..>(Int $min, Int $max;; Int $by = 1) {...}
The double semicolon, if any, determines the complete long name of
a multi. (In the absence of that, a double semicolon is assumed
after the last declared argument, but before any return signature.)
Note that a call to the routine must still be compatible with
subsequent arguments.
[Conjecture: However, a given multi may advertise multiple long names,
some of which are shorter than the complete long name. This is done
by putting a semicolon after each advertised long name (replacing
the comma, if present). A semicolon has the effect of inserting two
candidates into the list. One of them is inserted with exactly the
same types, as if the semicolon were a comma. The other is inserted
as if all the types after the semicolon were of type Any, which puts
it later in the list than the narrower actual candidate. This merely
determines its sort order; the candidate uses its real type signature
if the dispatcher gets to it after rejecting all earlier entries on the
candidate list. If that set of delayed candidates also contains ties,
then additional semicolons have the same effect within that sublist
of ties. Note, however, that semicolon is a no-op if the types after
it are all C<Any>. (As a limiting case, putting a semicolon after
every parameter produces dispatch semantics much like Common Lisp.
And putting a semicolon after only the first argument is much like
ordinary single-dispatch methods.) Note: This single-semicolon syntax
is merely to be considered reserved until we understand the semantics
of it, and more importantly, the pragamatics of it (that is, whether
it has any valid use case). Until then only the double-semicolon
form will be implemented in the standard language.]
Within a class, C<multi submethod> is visible to both method-dispatch
and subroutine-dispatch. A C<multi method> never participates in the
subroutine-dispatch process. It is dispatched just like a normal
method, then the tie-breaking rules of the previous paragraph are applied.
That is, the shortest long name of a multi method includes I<only> the
single invocant, and any additional semicolons may only indicate long names
to be used as tiebreakers.
Conjecture: In order to specify dispatch that includes the return
type context, it is necessary to place the return type before the double
semicolon:
multi infix:<..>(Int $min, Int $max --> Iterator;; Int $by = 1) {...}
multi infix:<..>(Int $min, Int $max --> Selector;; Int $by = 1) {...}
Note that such a declaration might have to delay dispatch until the
actual desired type is known! (Generally, you might just consider
returning a flexible C<Range> object instead of an anonymous partial
dispatch that may or may not be resolved at compile time via type