TITLE

Synopsis 12: Objects

AUTHOR

Larry Wall <larry@wall.org>

VERSION

  Maintainer: Larry Wall <larry@wall.org>
  Date: 27 Oct 2004
  Last Modified: 23 Feb 2008
  Number: 12
  Version: 58

Overview

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

Classes

From t/spec/S12-class/basic.t lines 13–40 (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.

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. Alternately, you can define a local class or type variable using the :: type sigil. In an rvalue context the :: prefix is a no-op, but in a declarational context, it binds a new type name within its declared scope.

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/basic.t lines 41–67 (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 object) delegates to an instance of its metaclass. You can get at the metaclass of any object via the HOW method. A "class" object is just considered an "empty" instance in Perl 6, more properly called a "prototype" object, or just "protoobject". The actual class object is the metaclass object pointed to by the HOW syntax. So when you say "Dog", you're referring to both a package and a protoobject, that latter of which points to the actual object representing the class via HOW. The protoobject differs from an instance object not by having a different type but rather in the extent to which it is defined. Some objects may tell you that they are defined, while others may tell you that they are undefined. That's up to the object, and depends on how the metaclass chooses to dispatch the .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.

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/oo/attributes/recursive.t lines 55–92 (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 my:

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

    my method think (Brain $self: $thought)

(Such methods are completely invisible to ordinary method calls, and are in fact called with a different syntax that uses ! in place of the . character. See below.)

To call an ordinary method with ordinary method-dispatch semantics, use either the dot notation or indirect object notation:

From t/oo/methods/instance.t lines 13–91 (13 √, 6 ×): (skip)

    $obj.doit(1,2,3)
    doit $obj: 1,2,3

If the method was not found, it will fall back to a subroutine call instead, with the invocant becoming the first positional argument.

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 11–50 (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.

    $obj."$methodname"(1,2,3)   # use contents of $methodname as method name
    $obj.'$methodname'(1,2,3)   # no interpolation; call method with $ in name!

    $obj!"$methodname"          # indirect call to private method name

[Note: to help catch the mistaken use of 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 if 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 Code object, 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)

As with the scalar variant, each array element must be a Code object, but the list is treated as a list of candidates to call. Note also that the

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

form may dispatch to a list of candidates if $candidates is a special Code object representing a partial dispatch to a list of candidates.

Another form of indirection relies on the fact that operators are named using a variant on hash subscript notation, which gives you these forms:

    $x.infix:{$op}($y)
    $x.prefix:{$op}
    $x.postfix:{$op}

Generally you see these with the literal angle bracket form of subscript:

    $a.infix:<*>($b)      # equivalent to $a * $b
    $a.prefix:<++>        # equivalent to ++$a
    $a.postfix:<++>       # equivalent to $a++

If you omit the syntactic category, the call will be dispatched according to the number of arguments either as "prefix" or as "infix":

    $a.:<+>($b)           # equivalent to $a + $b
    $a.:<++>              # equivalent to ++$a
    $a.:<!>               # equivalent to !$a
    @a.:<[*]>             # equivalent to [*] @a

But it's probably better to spell out the syntactic category when the actual operator is not obvious:

    $x.infix:{$op}($y)
    $x.prefix:{$op}

You must use a special syntax to call a private method:

    $mybrain!think($pinky)
    self!think($pinky)

For a call on your own private method, you may also use the attribute-ish form:

    $!think($pinky)     # short for $(self!think($pinky))

Parentheses (or a colon) are required on the dot/bang notations if there are any arguments (not counting adverbial arguments). There may be no space between the method name and the left parenthesis unless you use the dot form of parentheses or otherwise make use of "unspace":

    .doit       # okay, no arguments
    .doit()     # okay, no arguments
    .doit ()    # ILLEGAL (two terms in a row)
    .doit.()    # okay, no arguments, same as .doit()
    .doit\ ()   # okay, no arguments, same as .doit() (unspace form)
    .doit\ .()  # okay, no arguments, same as .doit.() (unspace form)

However, you can turn any of the legal forms above into a list operator by appending a colon:

    .doit: 1,2,3        # okay, three arguments
    .doit(1): 2,3       # okay, one argument plus list
    .doit (): 1,2,3     # ILLEGAL (two terms in a row)
    .doit.(1): 2,3      # okay, same as .doit(1,2,3)
    .doit\ .(1,2): 3    # okay, same as .doit(1,2,3)

In particular, this allows us to pass a closure in addition to the "normal" arguments:

    .doit: { $^a <=> $^b }              # okay
    .doit(): { $^a <=> $^b }            # okay
    .doit(1,2,3): { $^a <=> $^b }       # okay

In case of ambiguity between indirect object notation and dot form, the nearest thing wins:

    dothis $obj.dothat: 1,2,3

means

    dothis ($obj.dothat(1,2,3))

and you must say

    dothis ($obj.dothat): 1,2,3

or

    $obj.dothat.dothis: 1,2,3

if you mean the other thing.

Also note that if any term in a list is a bare closure or pointy sub, it will be considered to be the final argument of its list unless the closure's right curly is followed immediately by comma or colon. In particular, a method call does *not* extend the list, so you can say:

    @list.grep: { $_ % 2 }.map: { $_ - 1 }.say

and that will be taken as equivalent to

    @list.grep({ $_ % 2 }).map({ $_ - 1 }).say

Methods (and subs) may be declared as lvalues with 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–12 (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 protoobject 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:

    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/oo/attributes/class.t lines 12–47 (5 √, 12 ×): (skip)

Submethods

From t/oo/submethods.t lines 12–122 (24 √, 2 ×): (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/oo/attributes/array.t lines 3–21 (1 √, 0 ×): (skip)

From t/oo/attributes/recursive.t lines 13–36 (6 √, 0 ×): (skip)

From t/oo/attributes/instance.t lines 87–127 (9 √, 2 ×): (skip)

From t/oo/attributes/attribute_initialization.t lines 7–48 (8 √, 0 ×): (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/oo/attributes/instance.t lines 16–31 (3 √, 2 ×): (skip)

From t/oo/attributes/instance.t lines 68–86 (2 √, 2 ×): (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/oo/attributes/instance.t lines 45–67 (4 √, 4 ×): (skip)

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

From t/oo/attributes/is_rw_on_class.t lines 7–29 (2 √, 1 ×): (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.

The dot form can take an argument list as well. These are all equivalent:

    self.foo(1,2,3);    # a regular method call
    self.foo.(1,2,3);   # ditto
    $.foo(1,2,3);       # calls self.foo under $ context
    $.foo.(1,2,3);      # ditto
    @.foo(1,2,3);       # calls self.foo under @ context
    @.foo.(1,2,3);      # ditto

Pseudo-assignment to an attribute declaration specifies the default value. The value on the right is treated as an implicit closure and evaluated at object build time, that is, when the object is being constructed, not when class is being composed. To refer to a value computed at compilation or composition time, you can either use a temporary or a temporal block of some sort:

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

From t/oo/attributes/instance.t lines 32–44 (3 √, 1 ×): (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.

From t/oo/attributes/defaults.t lines 22–102 (5 √, 16 ×): (skip)

Class attributes are declared with either my or our. The only difference from ordinary my or our variables is that an accessor is generated according to the secondary sigil:

From t/oo/attributes/recursive.t lines 37–54 (1 √, 1 ×): (skip)

From t/oo/attributes/class.t lines 11–47 (5 √, 12 ×): (skip)