TITLE

Synopsis 12: Objects

AUTHORS

    Larry Wall <larry@wall.org>

VERSION

    Created: 27 Oct 2004

    Last Modified: 7 Mar 2010
    Version: 99

Overview

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

Classes

From t/spec/S12-class/lexical.t lines 12–20 (no results): (skip)

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 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 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 ... 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 augment declarator, but that is considered somewhat antisocial and should not be used for forward declarations.

[Conjecture: we may also allow the proto and multi modifiers 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.

From t/spec/S12-class/anonymous.t lines 5–73 (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.

From t/spec/S12-class/declaration-order.t lines 14–20 (no results): (skip)

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–27 (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–144 (no results): (skip)

From t/spec/S12-class/basic.t lines 49–120 (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–91 (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–137 (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:

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

    $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 49–67 (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

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:

From t/spec/S02-literals/misc-interpolation.t lines 96–113 (no results): (skip)

    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 68–96 (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 an iterable object it is expanded out recursively until Callable candidates are found. The call fails if it hits a candidate that is not Callable, Iterable, or List.

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 97–145 (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–94 (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.)

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

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–21 (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 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/class.t lines 55–115 (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/class.t lines 12–54 (no results): (skip)

Submethods

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

From t/spec/S14-roles/submethods.t lines 12–31 (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 Mu class already supplies a default BUILD and new.)

Attributes

From t/spec/S12-attributes/augment-and-initialization.t lines 7–50 (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 189–562 (no results): (skip)