TITLE

Synopsis 12: Objects

AUTHORS

    Larry Wall <larry@wall.org>

VERSION

    Created: 27 Oct 2004

    Last Modified: 29 Jun 2009
    Version: 86

Overview

This synopsis summarizes Apocalypse 12, which discusses object-oriented programming.

Classes

From t/spec/S12-class/basic.t lines 13–48 (no results): (skip)

A class is a module declared with the 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 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 ... 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 roles when you simply want to factor out common code.

Perl 6 supports multiple inheritance, anonymous classes, and autoboxing.

From t/spec/S12-class/anonymous.t lines 5–48 (no results): (skip)

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 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 :: prefix. In an rvalue context the :: 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.

From t/spec/S12-class/literal.t lines 7–25 (no results): (skip)

Without a my or other scoping declarator, a bare class declarator declares an our declarator, that is, a name within the current package. Since class files begin parsing in the 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 our class or just class. To declare a lexically scoped class, use my class. Class names are always searched for from innermost scopes to outermost. As with an initial ::, the presence of a :: 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 is:

    class MyStruct is rw {...}

An "isa" is just a trait that happens to be another class:

From t/spec/S12-class/inheritance.t lines 7–133 (no results): (skip)

From t/spec/S12-class/basic.t lines 49–105 (no results): (skip)

    class Dog is Mammal {...}

MI is specified with multiple is modifiers:

    class Dog is Mammal is Pet {...}

Roles use does instead of 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-based object) delegates to an instance of its metaclass. You can get at the metaclass of any object via the 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 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 HOW syntax. So when you say "Dog", you're referring to both a package and a type object, the latter of which points to the object representing the class via 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 .defined method.

The notation ^Dog is syntactic sugar for Dog.HOW(), so ^ 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 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.

In an anonymous class declaration, :: 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

Methods

Methods are routines declared in a class with the 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 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 ::?CLASS even in anonymous classes or roles.)

From t/spec/S12-attributes/recursive.t lines 46–75 (no results): (skip)

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 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 !:

From t/spec/S12-methods/private.t lines 6–43 (no results): (skip)

    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 ! in place of the . character. See below.)

Unlike with most other declarations, method declarations do not default to our semantics, or even my semantics, but rather 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 submethod declarations--see "Submethods" below.)

Use of an explicit has declarator has no effect on the declaration. You may install additional aliases to the method in the lexical scope using my or in the current package using our. These aliases are named with &foo notation and return a 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:

From t/spec/S12-methods/instance.t lines 13–127 (no results): (skip)

    $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 IO class defines method close () is export, which puts a multi sub close (IO) in scope by default. Thus if the $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 $_:

    .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.

From t/spec/S12-methods/indirect_notation.t lines 57–75 (no results): (skip)

From t/spec/S12-methods/calling_syntax.t lines 34–48 (no results): (skip)

    $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

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 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 . concatenation, it cannot be parsed as a method call at all; instead it fails at compile time because standard Perl 6 has a pseudo 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 Callable object (usually of type 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 method declarator on an anonymous method has the primary effect of making the declaration of the invocant optional. (It also makes it an official Routine that can be returned from, just as if you'd used sub to declare it.)

Instead of a scalar variable, an array variable may also be used:

    $obj.@candidates(1,2,3)

From t/spec/S12-methods/indirect_notation.t lines 76–104 (no results): (skip)

As with the scalar variant, string method names are not allowed, only 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 nextwith or nextsame (see "Calling sets of methods" below).

Note also that the

    $obj.$candidates(1,2,3)

form may dispatch to a list of candidates if $candidates is either a list or a special Code object representing a partial dispatch to a list of candidates. If $candidates (or any element of @candidates) is a List or Array object it is expanded out recursively until Callable candidates are found. The call fails if it hits a candidate that is neither 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:

From t/spec/S12-methods/indirect_notation.t lines 105–120 (no results): (skip)

    $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:

From t/spec/S12-class/attributes.t lines 7–92 (no results): (skip)

    $!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":

From t/spec/S12-methods/syntax.t lines 6–28 (no results): (skip)

    .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 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 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:

From t/spec/S12-methods/syntax.t lines 29–44 (no results): (skip)

    @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 is rw. You can use an argumentless rw method anywhere you can use a variable, including in temp and let statements. (In fact, you can use an 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 Array, Hash or Code object bound to the variable:

    $elems = @array.elems;
    @keys  = %hash.keys;
    $sig   = &sub.signature;

Use the prefix VAR macro on a scalar variable to get at its underlying Scalar object:

    if VAR($scalar).readonly {...}

VAR is a no-op on a non-scalar variables and values:

    VAR(1);     # 1
    VAR(@x);    # @x

There's also a corresponding postfix:<.VAR> macro that can be used as if it were a method:

    if $scalar.VAR.readonly {...}

(But since it's a macro, VAR is not dispatched as a real method. To dispatch to a real .VAR method, use the indirect $obj."VAR" form.)

You can also get at the container through the appropriate symbol table:

    if MY::<$scalar>.readonly {...}

Class methods

From t/spec/S12-class/inheritance-class-methods.t lines 6–19 (no results): (skip)

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 "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:

From t/spec/S12-attributes/class2.t lines 55–79 (no results): (skip)

    our $count;
    method ^count { return $count }

Such a metaclass method is always delegated to the HOW object just as methods like .does are, so it's possible to call this as Dog.count or $dog.count. However, best practice is probably to call such a class method as Dog.^count or $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.

From t/spec/S12-attributes/class2.t lines 12–54 (no results): (skip)

Submethods

From t/spec/S12-methods/submethods.t lines 12–125 (no results): (skip)

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 Object class already supplies a default BUILD and new.)

Attributes

From t/spec/S12-attributes/augment-and-initialization.t lines 7–48 (no results): (skip)

From t/spec/S12-attributes/recursive.t lines 13–30 (no results): (skip)

From t/spec/S12-attributes/instance.t lines 88–126 (no results): (skip)

From t/spec/S12-attributes/instance.t lines 192–510 (no results): (skip)

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 my, use 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.

From t/spec/S12-attributes/instance.t lines 15–31 (no results): (skip)

From t/spec/S12-attributes/instance.t lines 67–87 (no results): (skip)

        has $!brain;

The "true name" of the private variable always has the exclamation, but much like with our variables, you may declare a lexically scoped alias to the private variable by saying:

        has $brain;     # also declares $!brain;

As with the ! 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 ! form. If you declare with the ! form, you must use that form consistently everywhere. If you declare with the . form, you also get the private ! form as a non-virtual name for the actual storage location, and you may use either ! or . form anywhere within the class, even if the class is reopened. Outside the class you must use the public . 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 rw trait causes the generated accessor to be declared rw, making it an lvalue method. The default is a read-only accessor.

From t/spec/S12-attributes/instance.t lines 44–66 (no results): (skip)

If you declare the class as rw, then all the class's attributes default to rw, much like a C struct.

From t/spec/S12-class/rw.t lines 7–30 (no results): (skip)

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 dot declaration also declares a corresponding private 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 $!foo should generally be restricted to submethods. Ordinary methods should stick to the $.foo form.

In fact, within submethods, use of the $.foo form on attributes that are available as $!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 $.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 BUILDALL call's the parent classes' BUILD routines first). If you attempt to get around this by declaring BUILD as a method rather than a submethod, that will also be flagged as a dire (but suppressible) compile-time warning. (It is possible to define an inheritable 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 submethod to method.)

Because $.foo, @.foo, %.foo, &.foo are just shorthands of self.foo with different contexts, the class does not need to declare any of those as an attribute -- a 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 .() 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:

From t/spec/S12-attributes/defaults.t lines 7–21 (no results): (skip)

From t/spec/S12-attributes/instance.t lines 32–43 (no results): (skip)

    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 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 BUILD only if the attribute is not otherwise initialized in either the signature or the body of the BUILD. The closure actually defines the body of an anonymous method, so 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 has declaration.

From t/spec/S12-attributes/defaults.t lines 22–103 (no results): (skip)