/
S12-objects.pod
2346 lines (1757 loc) · 95.2 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 AUTHORS
Larry Wall <larry@wall.org>
=head1 VERSION
Created: 27 Oct 2004
Last Modified: 12 Jul 2010
Version: 107
=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 C<Mu> support a fairly
standard class-based model.
There are two basic class declaration syntaxes:
class Foo; # rest of file is class definition
has $.foo;
class Bar { has $.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).
If the class body begins with a statement whose main operator is a
single C<< prefix:<...> >> (yada) listop, the class name is introduced
without a definition, and a second declaration of that class in the
same scope does not complain about redefinition. (Statement modifiers
are allowed on such a C<...> operator.) Thus you may
forward-declare your classes:
class A {...} # introduce A as a class name without definition
class B {...} # introduce B as a class name without definition
my A $root .= new(:a(B));
class A {
has B $.a;
}
class B {
has A $.b;
}
As this example demonstrates, this allows for mutually recursive class
definitions (though, of course, it can't allow recursive inheritance).
It is also possible to extend classes via the C<augment> declarator,
but that is considered somewhat antisocial and should not be used
for forward declarations.
[Conjecture: we may also allow the C<proto> and C<multi> declarator modifiers
on class definitions to explicitly declare classes with multiple bodies participating in
a single definition intentionally.]
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 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.
You can force interpretation of a name as a class or type name using
the C<::> prefix. In an rvalue context the C<::> prefix is a no-op,
but in a declarational context, it binds a new type name within the
declaration's scope along with anything else being declared by the declaration.
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 by use of the C<also> declarator:
class Dog {
also is Mammal;
also does Pet;
...
}
(However, the C<also> declarator is primarily intended for use
in roles, to distinguish class traits that might not be properly
understood as generic when placed in the role header, which tends to
communicate the false impression that the trait in question is to be
applied directly to the role rather than to the composed class.)
Every object (including any class-based 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" or "generic" object, or just
"type object". Perl 6 doesn't really have any classes named C<Class>.
Types of all kinds are instead named via these undefined type objects,
which are considered to have exactly the same type as an instantiated
version of themsleves. But such type objects are inert, and do not
manage the state of class instances.
The actual object that manages instances 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 type object, the latter of which points to the
object representing the class via C<HOW>. The type object
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.
Class declarations (in particular, role composition) are strictly
compile time statements. In particular, if a class declaration appears
inside a nested scope, the class declaration is constrained to compose
in exactly the same way on any possible execution. All named roles and
superclasses must be bound as non-rebindable readonly values; any
parameters to traits will be evaluated only in a non-cloning context.
Names bound by the class declaration are made non-rebindable and read
only so they may be used as superclasses.
In an anonymous class declaration, C<::> by itself may represent the
anonymous class name if desired:
class {...} # ok
class is Mammal {...} # WRONG
class :: is Mammal {...} # ok
class { is Mammal; ...} # also ok
=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) { ... }
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<!>:
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.)
Unlike with most other declarations, C<method> declarations do not
default to C<our> semantics, or even C<my> semantics, but rather
C<has> semantics. So instead of installing a symbol into a lexical
or package symbol table, they merely install a public or private
method in the current class or role via calls to its metaobject.
(Likewise for C<submethod> declarations--see L</Submethods> below.)
Use of an explicit C<has> declarator has no effect on the declaration.
You may install additional aliases to the method in the lexical scope
using C<my> or in the current package using C<our>. These aliases
are named with C<&foo> notation and return a C<Routine> object that
may be called as a subroutine, in which case you must supply the
expected invocant as the first argument.
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 C<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
As an aid to catching Perl 5 brainos, this quoted form always requires
a parenthesized argument list to distinguish it from code that looks
like a Perl 5 concatenation.
Within an interpolation, the double-quoted form may not contain
whitespace. This does what the user expects in the common case of
a quoted string ending with a period:
say "Foo = $foo.";
If you really want to call a method with whitespace, you may work
around this restriction with a closure interpolation:
say "Foo = {$foo."a method"()}"; # OK
[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 an iterable object it is expanded out recursively until C<Callable>
candidates are found. The call fails if it hits a candidate that is
not C<Callable>, C<Iterable>, or C<List>.
Another form of indirection relies on the fact that operators are named
using a variant on pair 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
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() (unspace form)
Note that the named method call forms are special and do not use the dot
form of postfix. If you attempt to use the postfix operator form, it
will assume you want to call the method with no arguments and then call
the result of I<that>:
.doit.() # okay, no arguments *twice*, same as .doit().()
.doit\ .() # okay, no arguments *twice*, same as .doit.().() (unspace form)
However, you can turn any of the named 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)
In particular, this allows us to pass a final closure in addition to the
"normal" arguments:
.doit: { $^a <=> $^b } # okay
.doit(): { $^a <=> $^b } # okay
.doit(1,2,3): { $^a <=> $^b } # okay
Normally a space is required after the colon to disambiguate what
follows from from a pair that extends the previous name. However,
names may not be extended with the C<:{}> pair notation, and therefore
it is allowed to drop the space after the colon if the first argument
to the method is a closure. Hence, any of the above may be written
without the space after the colon:
.doit:{ $^a <=> $^b } # okay
.doit():{ $^a <=> $^b } # okay
.doit(1,2,3):{ $^a <=> $^b } # okay
These are parsed as there were a space there, so the argument list may
continue if the closure is followed by a comma.
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
Since the colon does not require a space in this case, and it looks
slightly odd there anyway, it may be clearer to omit the space to make
the method calls on the right look more like they attach to the term
on the left in one cascade of method calls:
@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 type object 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 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<Mu> 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.
As with the normal method call forms, only dotless parentheses may contain arguments.
If you use the C<.()> form it will perform an extra level of indirection after
the method call:
self.foo(1,2,3); # a regular method call
self.foo.(1,2,3); # self.foo().(1,2,3), call .() on closure returned by .foo
$.foo(1,2,3); # calls self.foo under $ context
$.foo.(1,2,3); # $.foo().(1,2,3), call .() on closure returned by .foo
&.foo(1,2,3); # calls self.foo under & context
&.foo.(1,2,3); # &.foo().(1,2,3), call .() on closure returned by .foo
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>. The closure
actually defines the body of an anonymous method, so C<self> is available
with whatever attributes are constructed by that point in time (including
all parent attributes). The initializers are run in order of declaration
within the class, so a given initializer may refer back to an attribute
defined in a preceding C<has> declaration.
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<Mu>. 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, ...});
However, the normal way to create a candidate to bless is by calling
C<CREATE> (which by default creates an opaque object):
$object = $class.bless($class.CREATE(), k1 => $v1, k2 => $v2, ...)
$object = $class.bless($class.CREATE(), :k1($v1), :k2($v2), ...) # same
Alternatively, you can pass C<Whatever> and have C<bless> call CREATE
for you.
$object = $class.bless(*, k1 => $v1, k2 => $v2, ...)
In addition to the candidate positional argument, C<bless> also
allows one or more positional arguments representing autovivifying
type objects. Such an object looks like a type name followed by a
hash subscript (see "Autovivifying objects" below). These are used
to initialize superclasses.
Other than the candidate object and any autovivifying type objects,
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 possibilities 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<Mu>,
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 type objects passed to bless, that type object'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 type objects that need special handling. (It is
allowed to pass type objects 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> type object 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 is copy, $legs is copy) {
$!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;
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 Nil
$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. (If you were already on the last call of the
candidate list, no candidates are thrown away, only the list. So
you can't accidentally throw away the wrong list by running off the
end, since the candidate list is ordinarily not thrown away by the
dispatcher until after the last call.)
Since it's possible to be dispatching within more than one candidate
list at a time, these control flow calls are defined to apply only to
the dynamically innermost dispatcher. If, for instance, you have a
single dispatch to a C<proto> method that then calls into a multiple dispatch on the C<multi>
methods within a class, C<nextsame> within one of those C<multi>s would go to the next best C<multi>
method within the class, not the next method candidate in the original
single dispatch. This is not a bad limitation, since dispatch loops
are dynamically scoped; to get to the outermost lists you can "pop"
unwanted candidate lists using C<lastcall>:
lastcall; nextsame; # call next in grandparent dispatcher loop
[Conjecture: if necessary, C<lastcall> could have an argument
or invocant to specify which kind of a dispatch loop we think
we're throwing away, in case we're not sure about our context.
This confusion could arise since we use C<nextsame> semantics at
least three different ways: single dispatch, multiple dispatch,
and routine wrapper dispatch.]
=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 C<Parcel> or C<List> of C<Parcel>
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);
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>, and there is a single C<proto> that manages them.
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