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.

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

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.

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:

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 by use of the also declarator:

class Dog {
also is Mammal;
also does Pet;
...
}

(However, the 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 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.

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, :: by itself may represent the anonymous class name if desired:

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

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

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

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

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

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

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

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:

Normally a space is required after the colon to disambiguate what follows from a pair that extends the previous name. However, names may not be extended with the :{} 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:

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

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:

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.

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

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.

If you declare the class as rw, then all the class's attributes default to 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 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:

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:

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.

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:

All classes inherit a default new constructor from Mu. It expects all arguments to be named parameters initializing attributes of the same name. You may write your own 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 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 CREATE (which by default creates an opaque object):

Alternatively, you can pass Whatever and have bless call CREATE for you.

$object = $class.bless(*, k1 => $v1, k2 => $v2, ...)

In addition to the candidate positional argument, 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 bless must be named arguments, not positional. Hence, the main purpose of custom constructors is to turn positional arguments into named arguments for bless. The 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 .clone instead of .bless if that's what you mean.

Any named arguments to bless are automatically passed to the CREATE and BUILD routines. If you wish to pass special options to the CREATE routine (such as an alternate representation), call CREATE yourself and then pass the resulting candidate to .bless:

For the built-in default CREATE method, P6opaque is the default representation. Other possibilities are P6hash, P5hash, P5array, PyDict, Cstruct, etc.

The bless function automatically calls all appropriate BUILD routines by calling the BUILDALL routine for the current class, which initializes the object in least-derived to most-derived order. DESTROY and DESTROYALL work the same way, only in reverse.

The default BUILD and BUILDALL are inherited from Mu, so you need to write initialization routines only if you wish to modify the default behavior. The bless function automatically passes the appropriate argument list to the 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 BUILD. For the final BUILD of the current object, all the arguments to bless are passed to the 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.)

Here we are using an autovivifying Animal type object to specify what the arguments to Animal's BUILD routine should look like. (It does not actually autovivify an 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 BUILD submethod to control initialization. If you name an attribute as a parameter, that attribute is initialized directly, so

Whether you write your own BUILD or not, at the end of the BUILD, any default attribute values are implicitly copied into any attributes that haven't otherwise been initialized. Note that the default BUILD will only initialize public attributes; you must write your own BUILD (as above) in order to present private attributes as part of your initialization API.

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:

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:

Any method can defer to the next candidate method in the list by the special functions callsame, callwith, nextsame, and 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 . and .?, the return value is the 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 .* and .+ is a list of 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, 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 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 proto method that then calls into a multiple dispatch on the multi methods within a class, nextsame within one of those multis would go to the next best 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 lastcall:

lastcall; nextsame; # call next in grandparent dispatcher loop

[Conjecture: if necessary, 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 nextsame semantics at least three different ways: single dispatch, multiple dispatch, and routine wrapper 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 @object. Each such return value is a Parcel or List of 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.

The "long name" of a subroutine or method includes the type signature of its invocant arguments. The "short name" doesn't.

If you put multi in front of any sub declaration, it allows multiple long names to share a short name, provided all of them are declared multi, or there is a single prior or outer proto in the same file that causes all unmarked subs to default to multi in that lexical scope. If a sub is not marked with multi and it is not governed within that same file by a proto of the same short name, it is considered unique, an only sub. (An imported proto can function as such a governing declaration.)

For method declaratoins, the proto, multi, and only declarations work similarly but not identically. The explicit declarations work the same, except that calculation of of governance and candidate sets proceeds via the inheritance tree rather than via lexical scoping. The other difference is that a proto method of a given short name forcing all unmarked method declarations to assume multi in all subclasses regardless of which file they are declared in, unless explicitly overridden via only method.

An 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 (lexical scope or class), and it hides any outer subs (or less-derived methods) of the same short name. It is illegal for a multi or proto declaration to share the same scope with an only declaration of the same short name.

Since they come from a different file, the default proto declarations provided by Perl from the setting scope do not automatically set the defaults in the user's scope unless explicitly imported, so a sub declaration there that happens to be the same as a setting proto is considered only unless explicitly marked multi. (This allows us to add new proto declarations in the setting without breaking the user's old code.) In the absence of such an explicit sub declaration, however, the proto from the innermost outer lexical scope is used by the compiler in the analysis of any calls to that short name. (Since only list operators may be post-declared, as soon as the compiler sees a non-listop operator it is free to apply the setting's proto since any user-defined only version of it must of necessity be declared or imported earlier in the user's file or not at all.)

A proto always functions as a dispatcher around any multis declared after it in the same scope, More specifically, it is the generic prototype of a dispatcher, which must be instantiated anew in each scope that has a different candidate list. (This works much like type punning from roles to classes. Or you can think of this dispatcher as a currying of the proto's code with the candidate list appropriate to the scope.) For the sake of discussion, let us say that there is a declarator equivalent to only that is instead spelled dispatch. Generally a user never writes a dispatch sub (it might not even be allowed); a dispatch is always instantiated from the governing proto. A new dispatch sub or method is autogenerated in any scope that contains multi declarations. Since dispatch is nearly identical to only, saying &foo always refers to the innermost visible dispatch or only sub, never to a proto or multi. Likewise, $obj.can('foo') will return the most-derived dispatch or only method.

Within its scope, the signature of a proto also nails down the presumed order and naming of positional parameters, so that any call to that short name with named arguments in that scope can presume to rearrange those arguments into positional parameters based on that information. (Unrecognized names remain named arguments.) Any other type information or traits attached to the proto may also be passed along to the routines within its scope, so a proto definition can be used to factor out common traits. This is particularly useful for establishing grammatical categories in a grammar by declaring a prototoken or protorule. (Perl 6's grammar does this, for instance.)

You can have multiple multi variables of the same name in the same scope, and they all share the same storage location and type. These are declared by one proto declaration at the top, in which case you may leave the multi implicit on the rest of the declarations in the same scope. You might do this when you suspect you'll have multiple declarations of the same variable name (such code might be produced by a macro or by a code generator, for instance) and you wish to suppress any possible warnings about redefinition.

In contrast, multi routines can have only one instance of the long name in any namespace, and that instance hides any outer (or less-derived) routines with the same long name. It does not hide any routines with the same short name but a different long name. In other words, multis with the same short name can come from several different namespaces provided their long names differ and their short names aren't hidden by an only or proto declaration in some intermediate scope.

When you call a routine with a particular short name, if there are multiple visible long names, they are all considered candidates. They are sorted into an order according to how close the run-time types of the arguments match up with the declared types of the parameters of each candidate. The best candidate is called, unless there's a tie, in which case the tied candidates are redispatched using any additional tiebreaker strategies (see below). For the purpose of this nominal typing, no constrained type is considered to be a type name; instead the constrained type is unwound into its base type plus constraint. Only the base type upon which the constrained type is based is considered for the nominal type match (along with the fact that it is constrained). That is, if you have a parameter:

Any constrained type is considered to have a base type that is "epsilon" narrower than the corresponding unconstrained type. The compile-time topological sort takes into account the presence of at least one constraint, but nothing about the number or nature of any additional constraints. If we think of Int' as any constrained version of Int, then Int' is always tighter nominally than Int. (Int' is a meta-notation, not Perl 6 syntax.)

The order in which candidates are considered is defined by a topological sort based on the "type narrowness" of each candidate's long name, where that in turn depends on the narrowness of each parameter that is participating. Identical types are considered tied. Parameters whose types are not comparable are also considered tied. A candidate is considered narrower than another candidate if at least one of its parameters is narrower and all the rest of its parameters are either narrower or tied. Also, if the signature has any additional required parameters not participating in the long name, the signature as a whole is considered epsilon tighter than any signature without extra parameters. In essence, the remaining arguments are added to the longname as if the user had declared a capture parameter to bind the rest of the arguments, and that capture parameter has a constraint that it must bind successfully to the additional required parameters. All such signatures within a given rank are considered equivalent, and subject to tiebreaker A below.

This defines the partial ordering of all the candidates. If the topological sort detects a circularity in the partial ordering, all candidates in the circle are considered tied. A warning will be issued at CHECK time if this is detected and there is no suitable tiebreaker that could break the tie.

There are two tiebreaking modes, in increasing order of desperation:

A) run-time constraint processing
B) use of a candidate marked with "is default"

In the absence of any constraints, ties in the nominal typing immediately failover to tiebreaker B; if not resolved by B, they warn at compile time about an ambiguous dispatch.

If there are any tied candidates with constraints, it follows from our definitions above that all of them are considered to be constrained. In the presence of longname parameters with constraints, or the implied constraint of extra required arguments, tiebreaker A is applied. Candidates which are tied nominally but have constraints are considered to be a completely different situation, insofar as it is assumed the user knows exactly why each candidate has the extra constraints it has. Thus, constrained signatures are considered to be much more like a switch defined by the user. So for tiebreaker A the candidates are simply called in the order they were declared, and the first one that successfully binds (and completes without calling nextsame or nextwith) is considered the winner, and all the other tied candidates are ignored. If all the constrained candidates fail, we throw out the rank of constrained variants and proceed to the next tighter rank, which may consist of the unconstrained variants without extra arguments.

For ranks that are not decided by constraint (tiebreaker A), tiebreaker B is used: only candidates marked with the default trait are considered, and the best matching default routine is used. If there are no default routines, or if two or more of the defaults are tied for best, the dispatch fails.

Ordinarily all the parameters of a multi sub are considered for dispatch. Here's a declaration for an integer range operator with two parameters in its long name:

multi sub infix:<..>(Int $min, Int $max) {...}

Sometimes you want to have parameters that aren't counted as part of the long name. For instance, if you want to allow an optional "step" parameter to your range operator, but not consider it for multi dispatch, then put a double semicolon instead of a comma before it:

multi sub infix:<..>(Int $min, Int $max;; Int $by = 1) {...}

The double semicolon, if any, determines the complete long name of a multi. (In the absence of that, a double semicolon is assumed after the last declared argument, but before any return signature.) Note that a call to the routine must still be compatible with subsequent arguments.

Note that the $by is not a required parameter, so doesn't impose the kind of constraint that allows tiebreaker A. If the default were omitted, it would be a required parameter, and subject to tiebreaker A. Likewise an ordinary named parameter does not participate as a tiebreaker, but you can mark named parameters as required to effectively make a switch based on named binding:

The first three are dispatched under tiebreaker A as a constrained rank. If none of them can match, the final one is dispatched as an unconstrained rank, since *%_ is not considered a required parameter.

If some of the constrained candidates come by import from other modules, they are all considered to be declared at the point of importation for purposes of tiebreaking; subsequent tiebreaking is provided by the original order in the used module.

[Conjecture: However, a given multi may advertise multiple long names, some of which are shorter than the complete long name. This is done by putting a semicolon after each advertised long name (replacing the comma, if present). A semicolon has the effect of inserting two candidates into the list. One of them is inserted with exactly the same types, as if the semicolon were a comma. The other is inserted as if all the types after the semicolon were of type Any, which puts it later in the list than the narrower actual candidate. This merely determines its sort order; the candidate uses its real type signature if the dispatcher gets to it after rejecting all earlier entries on the candidate list. If that set of delayed candidates also contains ties, then additional semicolons have the same effect within that sublist of ties. Note, however, that semicolon is a no-op if the types after it are all Any. (As a limiting case, putting a semicolon after every parameter produces dispatch semantics much like Common Lisp. And putting a semicolon after only the first argument is much like ordinary single-dispatch methods.) Note: This single-semicolon syntax is merely to be considered reserved until we understand the semantics of it, and more importantly, the pragamatics of it (that is, whether it has any valid use case). Until then only the double-semicolon form will be implemented in the standard language.]

A method or submethod doesn't ordinarily participate in any subroutine-dispatch process. However, they can be made to do so if prefixed with a my or our declarator.

The caller indicates whether to make a method call or subroutine call by the call syntax. The "dot" form and the indirect object form default to method calls. All other prefix calls default to subroutine calls. This applies to prefix unary operators as well:

!$obj; # same as $obj.prefix:<!>

A method call considers only methods (including multi-methods and submethods) from the class hierarchy of its invocant, and fails if none is found. The object in question is in charge of interpreting the meaning of the method name, so if the object is a foreign object, the name will be interpreted by that foreign runtime.

A subroutine call considers only visible subroutines (including submethods) of that name. The object itself has no say in the dispatch; the subroutine dispatcher considers only the types the arguments involved, along with the name. Hence foreign objects passed to subroutines are forced to follow Perl semantics (to the extent foreign types can be coerced into Perl types, otherwise they fail).

There is no fail-over either from subroutine to method dispatch or vice versa. However, you may use is export on a method definition to make it available also as a multi sub. As with indirect object syntax, the first argument is still always the invocant, but the export allows you to use a comma after the invocant instead of a colon, or to omit the colon entirely in the case of a method with no arguments other than the invocant. Many standard methods (such as IO::close and Array::push) are automatically exported to the CORE namespace by default. For other exported methods, you will not see the multi sub definition unless you use the class in your scope, which will import the proto (and associated multi subs) lexically, after which you can call it using normal subroutine call syntax.

In the absence of an explicit type on the method's invocant, the exported multi sub's first argument is implicitly constrained to match the class in which it was defined or composed, so for instance the multi version of close requires its first argument to be of type IO or one of its subclasses. If the invocant is explicitly typed, that will govern the type coverage of the corresponding multi's first argument, whether that is more specific or more general than the class's invocant would naturally be. (But be aware that if it's more specific than ::?CLASS, the binding may reject an otherwise valid single dispatch as well as a multi dispatch.) In any case, it does no good to overgeneralize the invocant if the routine itself cannot handle the broader type. In such a situation you must write a wrapper to coerce to the narrower type.

Multi submethods work just like multi methods except they are constrained to an exact type match on the invocant, just as ordinary submethods are.

Perl 6.0.0 is not required to support multiple dispatch on named parameters, only on positional parameters. Note however that any dispatcher derived from proto will map named arguments to known declared positional parameters and call the multi candidates with positionals for those arguments rather than named arguments.

Within a multiple dispatch, nextsame means to try the next best match, or next best default in case of tie.

Attributes are tied to a particular class definition, so a multi method can only directly access the attributes of a class it's defined within when the invocant is the "self" of that attribute. However, it may call the private attribute accessors from a different class if that other class has indicated that it trusts the class the multi method is defined in:

class MyClass {
trusts YourClass;
...
}

The trust really only applies to MyClass, not to possible subclasses thereof.

The syntax for calling back to MyClass is $obj!MyClass::meth(). Note that private attribute accessors are always invoked directly, never via a dispatcher, since there is never any question about which object is being referred to. Hence, the private accessor notation may be aggressively inlined for simple attributes, and no simpler notation is needed for accessing another object's private attributes.

The sub keyword is optional immediately after a proto, multi, or only keyword.

A proto declaration may not occur after a multi declaration in the same scope.

Delegation lets you pretend that some other object's methods are your own. Delegation is specified by a handles trait verb with an argument specifying one or more method names that the current object and the delegated object will have in common:

has $tail handles 'wag';

Since the method name (but nothing else) is known at class construction time, the following .wag method is autogenerated for you:

method wag (|$args) { $!tail.wag(|$args) }

You can specify multiple method names:

has $.legs handles <walk run lope shake lift>;

It's illegal to call the outer method unless the attribute has been initialized to an object of a type supporting the method, such as by:

has Tail $.tail handles 'wag' .= new(|%_);

Note that putting a Tail type on the attribute does not necessarily mean that the method is always delegated to the Tail class. The dispatch is still based on the run-time type of the object, not the declared type.

Any other kind of argument to handles is considered to be a smartmatch selector for method names. So you can say:

has $.fur is rw handles /^get_/;

If you say

has $.fur is rw handles Groomable;

then you get only those methods available via the Groomable role or class. To delegate everything, use the Whatever matcher:

has $the_real_me handles *;

Wildcard matches are evaluated only after it has been determined that there's no exact match to the method name anywhere. When you have multiple wildcard delegations to different objects, it's possible to have a conflict of method names. Wildcard method matches are evaluated in order, so the earliest one wins. (Non-wildcard method conflicts can be caught at class composition time.)

If, where you would ordinarily specify a string, you put a pair, then the pair maps the method name in this class to the method name in the other class. If you put a hash, each key/value pair is treated as such a mapping. Such mappings are not considered wildcards.

has $.fur handles { :shakefur<shake>, :scratch<get_fleas> };

You can do a wildcard renaming, but not with pairs. Instead do smartmatch with a substitution:

has $.fur handles (s/^furget_/get_/);

Ordinarily delegation is based on an attribute holding an object, but it can also be based on the return value of a method:

The type system of Perl consists of roles, classes, and subtypes. You can declare a subtype like this:

my subset Str_not2b of Str where /^[isnt|arent|amnot|aint]$/;

or this:

my Str subset Str_not2b where /^[isnt|arent|amnot|aint]$/;

An anonymous subtype looks like this:

Str where /^[isnt|arent|amnot|aint]$/;

A where clause implies future smartmatching of some kind: the as-yet unspecified object of the type on the left must match the selector on the right. Our example is roughly equivalent to this closure:

{ $_.does(Str) and $_ ~~ /^[isnt|arent|amnot|aint]$/; }

except that a subtype knows when to call itself.

A subtype is not a subclass. Subclasses add capabilities, whereas a subtype adds constraints (takes away capabilites). A subtype is primarily a handy way of sneaking smartmatching into multiple dispatch. Just as a role allows you to specify something more general than a class, a subtype allows you to specify something more specific than a class. A subtype specifies a subset of the values that the original type specified, which is why we use the subset keyword for it.

While subtypes are primarily intended for restricting parameter types for multiple dispatch, they also let you impose preconditions on assignment. If you declare any container with a subtype, Perl will check the constraint against any value you might try to bind or assign to the container.

For multi dispatch, a long name with a matching constraint is preferred over an equivalent one with no constraint. So the first mesg above is preferred if the constraint matches, and otherwise the second is preferred.

[Conjecture: This entire section is considered a guess at our post-6.0.0 direction. For 6.0.0 we will allow only a single constraint before the variable, and post constraints will all be considered "epsilon" narrower than the single type on the left. The single constraint on the left may, however, be a value like 0 or a named subset type. Such a named subset type may be predeclared with an arbitrarily complex where clause; for 6.0.0 any structure type information inferrable from the where clause will be ignored, and the declared subset type will simply be considered nominally derived from the of type mentioned in the same declaration.]

More generally, a parameter can have a set of constraints, and the set of constraints defines the formal type of the parameter, as visible to the signature. (No one constraint is privileged as the storage type of the actual argument, unless it is a native type.) All constraints are considered in type narrowness. That is, these are equivalently narrow:

Foo Bar @x
Bar Foo @x

The constraint implied by the sigil also counts as part of the official type. The sigil is actually a constraint on the container, so the actual type of the parameter above is something like:

Positional[subset :: of Any where Foo & Bar }]

Static where clauses also count as part of the official type. A where clause is considered static if it can be applied to the types to the left of it at compile time to produce a known finite set of values. For instance, a subset of an enum type is a static set of values. Hence

Day $d where 'Mon'..'Fri'

is considered equivalent to

subset Weekday of Day where 'Mon'..'Fri';
Weekday $d

Types mentioned in a dynamic where class are not considered part of the official type, except insofar as the type includes the notion: "is also constrained by a dynamic where clause", which narrows it by epsilon over the equivalent type without a where clause.

The set of constraints for a parameter creates a subset type that implies some set of allowed values for the parameter. The set of allowed values may or may not be determinable at compile time. When the set of allowed values is determinable at compile time, we call it a static subtype.

Type constraints that resolve to a static subtype (that is, with a fixed set of elements knowable (if not known) at compile time) are considered to be narrower than type constraints that involve run-time calculation, or are otherwise intractable at compile time. Note that all values such as 0 or "foo" are considered singleton static subtypes. Singleton values are considered narrower than a subtype with multiple values, even if the subtype contains the value in question. This is because, for enumerable types, type narrowness is defined by doing set theory on the set of enumerated values.

So assuming:

my enum Day ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'];
subset Weekday of Day where 'Mon' .. 'Fri'; # considered static
subset Today of Day where *.today;

The first where is considered dynamic not because of the nature of the comparisons but because Int is not finitely enumerable. Our Weekday subset type can calculate the set membership at compile time because it is based on the Day enum, and hence is considered static despite the use of a where. Had we based Weekday on Int it would have been considered dynamic. Note, however, that with "anded" constraints, any enum type governs looser types, so

Int Day $n where 1 <= * <= 5

is considered static, since Day is an enum, and cuts down the search space.

The basic principle we're trying to get at is this: in comparing two parameter types, the narrowness is determined by the subset relationships on the sets of possible values, not on the names of constraints, or the method by which those constraints are specified. For practical reasons, we limit our subset knowledge to what can be easily known at compile time, and consider the presence of one or more dynamic constraints to be epsilon narrower than the same set of possible values without a dynamic constraint.

As a first approximation for 6.0.0, subsets of enums are static, and other subsets are dynamic. We may refine this in subsequent versions of Perl.

An enumeration is a type that facilitates the use of a set of symbols to represent a set of constant values. Its most obvious use is the translation of those symbols to their corresponding values. Each enumeration association is a constant pair known as an enum, which is of type Enum. Each enum associates an enum key with an enum value. Semantically therefore, an enumeration operates like a constant hash, but since it uses a package Stash to hold the entries, it presents itself to the user's namespace as a typename package containing a set of constant declarations. That is,

enum E <a b c>;

is largely syntactic sugar for:

package E {
constant a = 0;
constant b = 1;
constant c = 2;
}

(However, the enum declaration supplies extra semantics.)

Such constant declarations allow the use of the declared names to stand in for the values where a value is desired. In addition, since a constant declaration introduces a name that behaves as a subtype matching a single value, the enum key can function as a typename in certain capacities where a typename is required. The name of the enumeration as a whole is also considered a typename, and may be used to represent the set of values. (Note that when we wish to verbally distinguish the enumeration as a whole from each individual enum pair, we use the long term "enumeration" for the former, despite the fact that it is declared using the enum keyword.)

In the enum declaration, the keys are specified as a parenthesized list, or an equivalent angle bracket list:

The values are generated implicitly by default, but may be also be specified explicitly. If the first value is unspecified, it defaults to 0. To specify the first value, use pair notation (see below).

If the declared enumeration typename begins with an uppercase letter, the enum values will be derived from Int or Str as appropriate. If the enumeration typename is lowercase, the enumeration is assumed to be representing a set of native values, so the default value type is int or buf.

The declared base type automatically distributes itself to the individual constant values. For non-native types, the enum objects are guaranteed only to be derived from and convertible to the specified type. The actual type of the enum object returned by using the symbol is the enumeration type itself.

The enumeration typename itself may be used as a coercion operator from either the key name or a value. First the argument is looked up as a key; if that is found, the enum object is returned. If the key name lookup fails, the value is looked up using an inverted mapping table (which might have dups if the mapping is not one-to-one):

An anonymous enum just makes sure each string turns into a pair with sequentially increasing values, so:

%e = enum < ook! ook. ook? >;

is equivalent to:

%e = ();
%e<ook!> = 0;
%e<ook.> = 1;
%e<ook?> = 2;

The return value of an anonymous enumeration is an EnumMap. The enum keyword is still a declarator here, so the list is evaluated at compile time. Use a coercion to EnumMap to get a run-time map.

The enumeration composer inspects list values for pairs, where the value of the pair sets the next value explicitly. Non-pairs ++ the previous value. (Str and buf types increment like Perl 5 strings.) Since the «...» quoter automatically recognizes pair syntax along with interpolations, we can simply say:

Note that enumeration declaration evaluates its list at compile time, so any interpolation into such a list may not depend on run-time values. Otherwise enums wouldn't be constants. (If this isn't what you want, try initializing an ordinary declaration using ::= to make a scoped readonly value.)

You may import enum types; only non-colliding symbols are imported. Colliding enum keys are hidden and must be disambiguated with the type name. Any attempt to use the ambiguous name will result in a fatal compilation error. (All colliding values are hidden, not just the new one, or the old one.) Any explicit sub or type definition hides all imported enum keys of the same name but will produce a warning unless is redefined is included.

Since non-native Enum values know their enumeration type, they may be used to name a desired property on the right side of a but or does. So these:

$x = "Today" but Tue;
$y does True;

expand to:

$x = "Today" but Day::Tue;
$y does Bool::True;

The but and does operators expect a role on their right side. An enum type is not in itself a role type; however, the but and does operators know that when a user supplies an enum type, it implies the generation of an anonymous mixin role that creates an appropriate accessor, read-write if an attribute is being created, and read-only otherwise. It depends on whether you mix in the whole or a specific enum or the whole enumeration:

Note that Bool and Taint are not role names themselves but imply roles, and the enum values are really subset types of Int, though the constant objects themselves know that they are of type Bool or Taint, and can therefore be used correctly in multimethod dispatch.

You can call the low-level .Bool coercion on any built-in type, because all built-in types do the Boolean role, which requires a .Bool method. Hence, there is a great difference between saying

$x does Boolean; # a no-op, since $x already does Boolean
$x does Bool; # create a $.Bool attribute, also does Boolean

Conditionals evaluate the truth of a boolean expression by testing the return value of .Bool like this:

$obj.Bool != 0

Never compare a value to "True". Just use it in a boolean context. Well, almost never...

If you wish to be explicit about a boolean context, use the high-level so function or ? prefix operator, which are underlying based on the .Bool method. Also, use these high level functions when you wish to autothread junctions, since .Bool forces collapse of a junction's wavefunction. (Similarly, .Str forces stringification of the entire junction, while prefix:<~> does not.)

Like other type names and constant names, enum keynames are parsed as standalone tokens representing scalar values, and don't look for any arguments. Unlike type names but like constant names, enum keynames return defined values. Also unlike types and unlike the enum type as a whole, individual keynames do not respond to .() unless you mix in Callable somehow. (That is, it makes no sense to coerce Wednesday to Tuesday by saying Tue($wed).) Enumerations may not be post-declared.

Since there is an enum OK, the function OK may only be called using parentheses, never in list operator form. (If there is a collision on two enum values that cancels them both, the function still may only be called with parentheses, since the enum key is "poisoned".)

Enumeration types (and perhaps certain other finite, enumerable types such as finite ranges) define a .pick method on the type object of that type. Hence:

my enum CoinFace <Heads Tails>;
CoinFace.pick

returns Heads or Tails with equal probability, and

Month.pick(*)

will return the months in random order. Presumably

StandardPlayingCards.pick(5)

might return a Royal Flush, but a Full House is much more likely. It can never return Five Aces, since the pick is done without replacement. (If it does return Five Aces, it's time to walk away. Or maybe run.)

To pick from the list of keynames or values, derive them via the .enums method described above.

By default, all classes in Perl are non-final, which means you can potentially derive from them. They are also open, which means you can add more methods to them, though you have to be explicit that that is what you're doing:

Otherwise you'll get a class redefinition error. (Also, to completely replace a definition, use "supersede" instead of "augment"...but don't do that, since the compiler may have already committed to optimizations based on the old definition.)

In order to discourage casual misuse of these declarators, they are not allowed on global classes unless you put a special declaration at the top:

use MONKEY_TYPING;

For optimization purposes, Perl 6 gives the top-level application the right to close and finalize classes by the use of oo, a pragma for selecting global semantics of the underlying object-oriented engine:

use oo :closed :final;

This merely changes the application's default to closed and final, which means that at the end of the main compilation (CHECK time) the optimizer is allowed to look for candidate classes to close or finalize. But anyone (including the main application) can request that any class stay open or nonfinal, and the class closer/finalizer must honor that.

use class :open<Mammal Insect> :nonfinal<Str>

These properties may also be specified on the class definition:

class Mammal is open {...}
class Insect is open {...}
class Str is nonfinal {...}

By default Perl 6 assumes that all objects have a representation of P6opaque. This may be overridden with a trait:

class Mammal is repr(P6Hash) {...}

Whether implicit or explicit, the representation is considered to be fixed for the class after declaration, and the optimizer is free to optimize based on this guarantee. It is illegal to create an object of the same type with any other representation. If you wish to allow objects to be created with run-time specified representations, you must specifically pessimize the class:

class Mammal is repr(*) {...}

An augment is allowed to do this as long as it is before the main CHECK time, at which point the compiler commits to its optimization strategies. Compilers are not required to support run-time pessimizations (though they may). Compilers may also generate both optimal and pessimal code paths and choose which to run based on run-time information, as long as correct semantics are maintained.

All non-native representations are required to support undefined type objects that may contain unthrown exceptions (Failure objects); while this can be implemented using an alternate representation, Perl 6 doesn't think of it that way. All normal objects in Perl 6 may be used as a specific object (proper noun) if they are defined, or as a generic object (common noun) whether or not they are defined. You get this representation polymorphism for free independently of the restriction above.

By default, all methods and submethods that do not declare an explicit *% parameter will get an implicit *%_ parameter declared for them whether they like it or not. In other words, all methods allow unexpected named arguments, so that nextsame semantics work consistently.

If you mark a class "is hidden", it hides the current class from "nextsame" semantics, and incidentally suppresses the autogeneration of *%_ parameters. Hidden classes may be visited as SUPER::, but not via "next".

A similar effect can be achieved from the derived class by saying hides Base instead of is Base.

Metamethods for objects are named with interrogative pronouns in uppercase:

WHAT the type object of the type, .Str returns MyClass()
WHICH the object's identity value
WHO the package supporting the object, stringifies to long name
WHERE the memory address of the object
HOW the metaclass object: "Higher Order Workings"
WHEN (reserved for events?)
WHY (reserved for documentation?)
WHENCE autovivification closure

These may be used either as methods or as unary operators:

$obj.WHAT # method form of P5's ref
WHAT $obj # unary form of P5's ref

These are all actually macros, not true operators or methods. If you get a foreign object from another language and need to call its .WHERE method, you can say:

$obj."WHERE"

And if you don't know the method name in advance, you'd be using the variable form anyway:

$obj.$somemeth

which also bypasses the macros.

For now Perl 6 reserves the right to change how all these macros and the corresponding ^ forms are defined in terms of each other. In particular, the .^ forms will automatically supply the invocant as the first argument to methods of the metaclass, while the other forms require you to pass this explicitly.

Note that WHAT.Str appends () to the name to indicate emptiness. Use .perl to get the bare name from a type object. Use one of .Stringy, prefix:<~>, or infix:<~> to get the Perl5ish semantics of returning the empty string (with a warning) on any type object. (There is no "undef", in Perl 6; type objects provide typed undefs instead.)

In general, use of these uppercased accessors in ordinary code should be a red flag that Something Very Strange is going on. (Hence the allcaps.) Most code should use Perl 6's operators that make use of this information implicitly. For instance, instead of

$obj.WHAT eq 'Dog()'
$x.WHICH === $y.WHICH
$obj.WHAT.bless(%args)

you usually just want:

$obj ~~ Dog
$x === $y
$obj.bless(%args)

Every class has a HOW function/method that lets you get at the class's metaobject, which lets you get at all the metadata properties for the class (or other metaobject protocol) implementing the objects of the class:

These are for the standard Perl 6 Meta-Object Protocol, but other MOPs may define other traits. The identifier should probably be accessed through the .WHO object in any case, which may have its own object methods depending on how type namespaces evolve over time. Which of these items are actually part of the .HOW object and which are delegated back to the package and prototype objects is up to the MOP. (Note also that anonymous classes may have anonymous packages and prototype objects, in which case stringification is not likely to produce something of interest to non-gurus.)

The .^parents method by default returns a flattened list of all parents out to (but not including) Cool or Any, sorted in MRO (dispatch) order. Other options are:

:local just returns the immediate parents
:local($n) return $n levels
:excl exclude Cool and Any (the default)
:all include Cool and Any
:tree the inheritance hierarchy as nested arrays

The .^methods method returns method-descriptors containing:

name the name of the method
signature the parameters of the method
as the coercion type of the method
proto whether this method governs a set of multi methods
do the method body

The .^methods method has a selector parameter that lets you specify whether you want to see a flattened or hierarchical view, whether you're interested in private methods, and so forth.

:local only methods defined in the current class
:local($n) out $n levels
:excl exclude Cool and Any (the default)
:all include Cool and Any
:tree methods by class structure (inheritance hierarchy)
:private include private methods

Note that, since introspection is primarily for use by the outside world (the class already knows its own structure, after all), a set of multi methods are presented to be a single proto method. You need to use .candidates on that to break it down further.

The .^attributes method returns a list of Attribute objects that have methods like these:

Note that an Attribute is not tied to a particular object of a type, but rather to the type itself. Which is why get_value and set_value need to receive the actual object as first positional parameter.

[Conjecture: if it's not feasible for a meta class or a representation to implement set_value and get_value, it may die with an helpful error message when these methods are called.]

set_value and get_value violate the privacy of attributes, and thus should be used with care, and at the user's own risk.

.^attributes also takes the parameters:

:local only methods defined in the current class
:local($n) out $n levels
:excl exclude Cool and Any (the default)
:all include Cool and Any
:tree attributes by class structure (inheritance hierarchy)

Strictly speaking, metamethods like .isa(), .does(), and .can() should be called through the meta object:

These, may, of course, be overridden in a subclass, so don't use the short form unless you wish to allow for overrides. In general, Any will delegate only those metamethods that read well when reasoning about an individual object. Infrastructural methods like .^methods and .^attributes are not delegated, so $obj.methods fails.

The smartmatch:

$obj ~~ Dog

actually calls:

$obj.HOW.does($obj, Dog)

which is true if $obj either "does" or "isa" Dog (or "isa" something that "does" Dog). If Dog is a subset, any additional where constraints must also evaluate true.

Unlike in Perl 5 where .can returns a single Code object, Perl 6's version of .^can returns a "WALK" iterator for a set of routines that match the name, including all autoloaded and wildcarded possibilities. In particular, .^can interrogates any class package's CANDO method for names that are to be considered autoloadable methods in the class, even if they haven't been declared yet. Role composition sometimes relies on this ability to determine whether a superclass supplies a method of a particular name if it's required and hasn't been supplied by the class or one of its roles.

The motivation for stopping at Cool and Any by default is that the first derivation from one of those is really what the user thinks of as the root class of the type hierarchy most of the time. Methods outside of that are really part of Perl 6's lexicon, recognizable across all types. Hence if you say, for exampe, $object.sort or $object.arctan, you're invoking well-known cultural concepts that tend to transcend the user's type hierarchy. When the user asks for $object.^methods, listing such methods by default is rather irritating.

Note that when we say "Cool and Any" above, we really mean those types as well as any types outside of them, such as Mu or Junction. But users should not generally be deriving from those types anyway.

The WHENCE property of an object is its autovivifying closure. Any undefined prototype object may carry such a closure that can lazily create an object of the appropriate type. When the closure is eventually evaluated it is expected to return an argument list corresponding to the arguments to a .bless call. For instance, a CANDO routine, instead of creating a Dog object directly, could instead return something like:

Dog but WHENCE({ :name<Fido> })

which runs the closure if the object ever needs to be autovivified. The closure can capture whatever initializers were available in the original lexical scope.

When the typename happens to be a role, autovivifying it involves attempting to create a punned class of the same name as the role. Whether this succeeds or not depends on whether the role is sufficiently complete to serve as a class on its own. Regardless of whether such an attempt would succeed, it is always perfectly fine to define a lazy type object for a role just as long as it's only ever used as an argument to bless, since bless will only be using its closure to construct the role's BUILD arguments in the context of the complete new class. (Of course, an inconsistent or incomplete class composition may subsequently fail, and in fact the incomplete role autovivification mentioned above is likely to be implemented by failing at the point of class composition.)

Note that when used as an argument to a method like bless, the type object is sufficiently lazy that autovivifying is done only by the appropriate BUILD routine. It does not waste energy creating a Dog object when that object's attributes would later have to be copied into the actual object. (On top of which, such an implementation would make it impossible to use type objects to initialize incomplete roles.)

The object autovivification syntax works only for literal named types, so any indirection must be written more explicitly: