This page was generated by Text::SmartLinks v0.01 at 2010-06-24 20:02:12 GMT.
(syn r31436)   [ Index of Synopses ]

TITLE

Synopsis 3: Perl 6 Operators

AUTHORS

    Luke Palmer <luke@luqui.org>
    Larry Wall <larry@wall.org>
    Darren Duncan <darren@darrenduncan.net>

VERSION

    Created: 8 Mar 2004
    Last Modified: 18 Jun 2010
    Version: 210

Overview

For a summary of the changes from Perl 5, see "Changes to Perl 5 operators".

Operator precedence

From t/spec/S03-operators/arith.t lines 46–313: (skip) -

 

From t/spec/S03-operators/precedence.t lines 5–198: (skip) -

 

Perl 6 has about the same number of precedence levels as Perl 5, but they're differently arranged in spots. Here we list the levels from "tightest" to "loosest", along with a few examples of each level:

    A  Level             Examples
    =  =====             ========
    N  Terms             42 3.14 "eek" qq["foo"] $x :!verbose @$array
    L  Method postfix    .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
    N  Autoincrement     ++ --
    R  Exponentiation    **
    L  Symbolic unary    ! + - ~ ? | || +^ ~^ ?^ ^
    L  Multiplicative    * / % +& +< +> ~& ~< ~> ?& div mod
    L  Additive          + - +| +^ ~| ~^ ?| ?^
    L  Replication       x xx
    X  Concatenation     ~
    X  Junctive and      &
    X  Junctive or       | ^
    L  Named unary       sleep abs sin temp let
    N  Structural infix  but does <=> leg cmp .. ..^ ^.. ^..^
    C  Chaining infix    != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv
    X  Tight and         &&
    X  Tight or          || ^^ // min max
    R  Conditional       ?? !! ff fff
    R  Item assignment   = := ::= => += -= **= xx= .=
    L  Loose unary       so not
    X  Comma operator    , :
    X  List infix        Z minmax X X~ X* Xeqv ... E
    R  List prefix       print push say die map substr ... [+] [*] any $ @
    X  Loose and         and andthen
    X  Loose or          or xor orelse
    X  Sequencer         <==, ==>, <<==, ==>>
    N  Terminator        ; {...}, unless, extra ), ], }

Using two ! symbols below generically to represent any pair of operators that have the same precedence, the associativities specified above for binary operators are interpreted as follows:

        Assoc     Meaning of $a ! $b ! $c
        =====     =========================
    L   left      ($a ! $b) ! $c
    R   right     $a ! ($b ! $c)
    N   non       ILLEGAL
    C   chain     ($a ! $b) and ($b ! $c)
    X   list      infix:<!>($a; $b; $c)

For unaries this is interpreted as:

        Assoc     Meaning of !$a!
        =====     =========================
    L   left      (!$a)!
    R   right     !($a!)
    N   non       ILLEGAL

(In standard Perl there are no unaries that can take advantage of associativity, since at each precedence level the standard operators are either consistently prefix or postfix.)

Note that list associativity (X) only works between identical operators. If two different list-associative operators have the same precedence, they are assumed to be non-associative with respect to each other, and parentheses must be used to disambiguate.

From t/spec/S03-operators/precedence.t lines 209–226: (skip) -

 

For example, the X cross operator and the Z zip operator both have a precedence of "list infix", but:

    @a X @b Z @c

is illegal and must be written as either of:

    (@a X @b) Z @c
    @a X (@b Z @c)

If the only implementation of a list-associative operator is binary, it will be treated as right associative.

The standard precedence levels attempt to be consistent in their associativity, but user-defined operators and precedence levels may mix right and left associative operators at the same precedence level. If two conflicting operators are used ambiguously in the same expression, the operators will be considered non-associative with respect to each other, and parentheses must be used to disambiguate.

If you don't see your favorite operator above, the following sections cover all the operators in precedence order. Basic operator descriptions are here; special topics are covered afterwards.

Term precedence

This isn't really a precedence level, but it's in here because no operator can have tighter precedence than a term. See S02 for longer descriptions of various terms. Here are some examples.

Method postfix precedence

All method postfixes start with a dot, though the dot is optional for subscripts. Since these are the tightest standard operator, you can often think of a series of method calls as a single term that merely expresses a complicated name.

See S12 for more discussion of single dispatch method calls.

Autoincrement precedence

From t/spec/S03-operators/increment.t lines 7–117: (skip) -

 

From t/spec/S03-operators/overflow.t lines 7–236: (skip) -

 

From t/spec/S03-operators/autoincrement.t lines 9–51: (skip) -

 

As in C, these operators increment or decrement the object in question either before or after the value is taken from the object, depending on whether it is put before or after. Also as in C, multiple references to a single mutating object in the same expression may result in undefined behavior unless some explicit sequencing operator is interposed. See "Sequence points".

As with all postfix operators in Perl 6, no space is allowed between a term and its postfix. See S02 for why, and for how to work around the restriction with an "unspace".

As mutating methods, all these operators dispatch to the type of the operand and return a result of the same type, but they are legal on value types only if the (immutable) value is stored in a mutable container. However, a bare undefined value (in a suitable Scalar container) is allowed to mutate itself into an Int in order to support the common idiom:

    say $x unless %seen{$x}++;

Increment of a Str (in a suitable container) works similarly to Perl 5, but is generalized slightly. A scan is made for the final alphanumeric sequence in the string that is not preceded by a '.' character. Unlike in Perl 5, this alphanumeric sequence need not be anchored to the beginning of the string, nor does it need to begin with an alphabetic character; the final sequence in the string matching <!after '.'> <rangechar>+ is incremented regardless of what comes before it.

From t/spec/S03-operators/autoincrement.t lines 52–177: (skip) -

 

From t/spec/S03-operators/autoincrement.t lines 178–196: (skip) -

 

The <rangechar> character class is defined as that subset of characters that Perl knows how to increment within a range, as defined below.

The additional matching behaviors provide two useful benefits: for its typical use of incrementing a filename, you don't have to worry about the path name or the extension:

    $file = "/tmp/pix000.jpg";
    $file++;            # /tmp/pix001.jpg, not /tmp/pix000.jph

Perhaps more to the point, if you happen to increment a string that ends with a decimal number, it's likely to do the right thing:

    $num = "123.456";
    $num++;             # 124.456, not 123.457

Character positions are incremented within their natural range for any Unicode range that is deemed to represent the digits 0..9 or that is deemed to be a complete cyclical alphabet for (one case of) a (Unicode) script. Only scripts that represent their alphabet in codepoints that form a cycle independent of other alphabets may be so used. (This specification defers to the users of such a script for determining the proper cycle of letters.) We arbitrarily define the ASCII alphabet not to intersect with other scripts that make use of characters in that range, but alphabets that intersperse ASCII letters are not allowed.

If the current character in a string position is the final character in such a range, it wraps to the first character of the range and sends a "carry" to the position left of it, and that position is then incremented in its own range. If and only if the leftmost position is exhausted in its range, an additional character of the same range is inserted to hold the carry in the same fashion as Perl 5, so incrementing '(zz99)' turns into '(aaa00)' and incrementing '(99zz)' turns into '(100aa)'.

The following Unicode ranges are some of the possible rangechar ranges. For alphabets we might have ranges like:

    A..Z        # ASCII uc
    a..z        # ASCII lc
    Α..Ω        # Greek uc
    α..ω        # Greek lc (presumably skipping C<U+03C2>, final sigma)
    א..ת        # Hebrew
      etc.      # (XXX out of my depth here)

For digits we have ranges like:

    0..9        # ASCII
    ٠..٩        # Arabic-Indic
    ०..९        # Devangari
    ০..৯        # Bengali
    ੦..੯        # Gurmukhi
    ૦..૯        # Gujarati
    ୦..୯        # Oriya
      etc.

Other non-script 0..9 ranges may also be incremented, such as

    ⁰..⁹        # superscripts (note, cycle includes latin-1 chars)
    ₀..₉        # subscripts
    ０..９      # fullwidth digits

Conjecturally, any common sequence may be treated as a cycle even if it does not represent 0..9:

    Ⅰ..Ⅻ        # clock roman numerals uc
    ⅰ..ⅻ        # clock roman numerals lc
    ①..⑳        # circled digits 1..20
    ⒜..⒵        # parenthesize lc
    ⚀..⚅        # die faces 1..6
    ❶..❿        # dingbat negative circled 1..10
      etc.

While it doesn't really make sense to "carry" such numbers when they reach the end of their cycle, treating such values as incrementable may be convenient for writing outlines and similar numbered bullet items. (Note that we can't just increment unrecognized characters, because we have to locate the string's final sequence of rangechars before knowing which portion of the string to increment. Note also that all character increments can be handled by lookup in a single table of successors since we've defined our ranges not to include overlapping cycles.)

Perl 6 also supports Str decrement with similar semantics, simply by running the cycles the other direction. However, leftmost characters are never removed, and the decrement fails when you reach a string like "aaa" or "000".

Increment and decrement on non-Str types are defined in terms of the .succ and .pred methods on the type of object in the Scalar container. More specifically,

    ++$var
    --$var

are equivalent to

    $var.=succ
    $var.=pred

If the type does not support these methods, the corresponding increment or decrement operation will fail. (The optimizer is allowed to assume that the ordinary increment and decrement operations on integers will not be overridden.)

Increment of a Bool (in a suitable container) turns it true. Decrement turns it false regardless of how many times it was previously incremented. This is useful if your %seen hash is actually a KeySet, in which case decrement actually deletes it from the KeySet.

Exponentiation precedence

Symbolic unary precedence

Multiplicative precedence

Any bit shift operator may be turned into a rotate operator with the :rotate adverb. If :rotate is specified, the concept of sign extension is meaningless, and you may not specify a :signed adverb.

Additive precedence

Replication

Concatenation

From t/spec/S03-operators/misc.t lines 17–19: (skip) -

 

From t/spec/S03-operators/misc.t lines 49–53: (skip) -

 

Junctive and (all) precedence

Junctive or (any) precedence

Named unary precedence

Functions of one argument

    sleep
    abs
    sin
    ...         # see S29 Functions

Note that, unlike in Perl 5, you must use the .meth forms to default to $_ in Perl 6.

There is no unary rand prefix in Perl 6, though there is a .rand method call and an argumentless rand term. There is no unary int prefix either; you must use a typecast to a type such as Int or int. (Typecasts require parentheses and may not be used as prefix operators.) In other words:

    my $i = int $x;   # ILLEGAL

From t/spec/S03-operators/precedence.t lines 199–208: (skip) -

 

is a syntax error (two terms in a row), because int is a type name now.

Nonchaining binary precedence

Chaining binary precedence

From t/spec/S03-operators/equality.t lines 10–42: (skip) -

 

From t/spec/S03-operators/relational.t lines 9–103: (skip) -

 

All operators on this precedence level may be chained; see "Chained comparisons". They all return a boolean value.

Tight and precedence

Tight or precedence

Conditional operator precedence

Adverbs

Operator adverbs are special-cased in the grammar, but give the appearance of being parsed as trailing unary operators at a pseudo-precedence level slightly tighter than item assignment. (They're not officially "postfix" operators because those require the absence of whitespace, and these allow whitespace. These adverbs insert themselves in the spot where the parser is expecting an infix operator, but the parser continues to look for an infix after parsing the adverb and applying it to the previous term.) Thus,

    $a < 1 and $b == 2 :carefully

does the == carefully, while

    $a < 1 && $b == 2 :carefully

does the && carefully because && is of tighter precedence than "comma". Use

    $a < 1 && ($b == 2 :carefully)

to apply the adverb to the == operator instead. We say that == is the "topmost" operator in the sense that it is at the top of the parse tree that the adverb could possibly apply to. (It could not apply outside the parens.) If you are unsure what the topmost operator is, just ask yourself which operator would be applied last. For instance, in

    +%hash{$key} :foo

The subscript happens first and the + operator happens last, so :foo would apply to that. Use

    +(%hash{$key} :foo)

to apply :foo to the subscripting operator instead.

Adverbs will generally attach the way you want when you say things like

    1 op $x+2 :mod($x)

The proposed internal testing syntax makes use of these precedence rules:

    $x eqv $y+2  :ok<$x is equivalent to $y+2>;

Here the adverb is considered to be modifying the eqv operator.

Item assignment precedence

From t/spec/S03-operators/binding-nested.t lines 5–342: (skip) -

 

From t/spec/S03-operators/binding-arrays.t lines 5–239: (skip) -

 

From t/spec/S03-operators/binding-attributes.t lines 4–82: (skip) -

 

From t/spec/S03-operators/binding-subs.t lines 7–115: (skip) -

 

From t/spec/S03-operators/binding-hashes.t lines 5–185: (skip) -

 

Loose unary precedence

From t/spec/S03-operators/so.t lines 5–24: (skip) -

 

From t/spec/S03-operators/not.t lines 5–38: (skip) -

 

Comma operator precedence

List infix precedence

List infixes all have list associativity, which means that identical infix operators work together in parallel rather than one after the other. Non-identical operators are considered non-associative and must be parenthesized for clarity.

Many of these operators return a list of Parcels, which depending on context may or may not flatten them all out into one flat list. The default is to flatten, but see the contextualizers below.

List prefix precedence

Loose and precedence

Loose or precedence

Terminator precedence

As with terms, terminators are not really a precedence level, but looser than the loosest precedence level. They all have the effect of terminating any operator precedence parsing and returning a complete expression to the main parser. They don't care what state the operator precedence parser is in. If the parser is currently expecting a term and the final operator in the expression can't deal with a nullterm, then it's a syntax error. (Notably, the comma operator and many prefix list operators can handle a nullterm.)

Changes to Perl 5 operators

From t/spec/S03-operators/scalar-assign.t lines 8–28: (skip) -

 

Several operators have been given new names to increase clarity and better Huffman-code the language, while others have changed precedence.

Junctive operators

From t/spec/S03-junctions/associative.t lines 16–39: (skip) -

 

From t/spec/S03-junctions/misc.t lines 20–157: (skip) -

 

From t/spec/S03-junctions/misc.t lines 158–163: (skip) -

 

From t/spec/S03-junctions/boolean-context.t lines 5–79: (skip) -

 

|, &, and ^ are no longer bitwise operators (see "Changes to Perl 5 operators") but now serve a much higher cause: they are now the junction constructors.

A junction is a single value that is equivalent to multiple values. They thread through operations, returning another junction representing the result:

From t/spec/S03-operators/misc.t lines 69–90: (skip) -

 

From t/spec/S03-junctions/misc.t lines 164–174: (skip) -

 

From t/spec/S03-junctions/misc.t lines 240–405: (skip) -

  
     (1|2|3) + 4;                            # 5|6|7
     (1|2) + (3&4);                          # (4|5) & (5|6)

As illustrated by the last example, when two junctions are applied through a single operator, the result is a junction representing the application of the operator to each possible combination of values.

Junctions come with the functional variants any, all, one, and none.

This opens doors for constructions like:

From t/spec/S03-junctions/misc.t lines 175–198: (skip) -

  
     unless $roll == any(1..6) { print "Invalid roll" }
     if $roll == 1|2|3 { print "Low roll" }

Junctions work through subscripting:

From t/spec/S03-junctions/misc.t lines 199–214: (skip) -

  
    doit() if @foo[any(1,2,3)]

Junctions are specifically unordered. So if you say

From t/spec/S03-junctions/misc.t lines 215–239: (skip) -

  
    foo() | bar() | baz() == 42

it indicates to the compiler that there is no coupling between the junctional arguments. They can be evaluated in any order or in parallel. They can short-circuit as soon as any of them return 42, and not run the others at all. Or if running in parallel, the first successful thread may terminate the other threads abruptly. In general you probably want to avoid code with side effects in junctions.

Use of negative operators with junctions is potentially problematic if autothreaded naively. However, by defining != and ne in terms of the negation metaoperator, we automatically get the "not raising" that is expected by an English speaker. That is

From t/spec/S03-junctions/autothreading.t lines 289–302: (skip) -

  
    if $a != 1 | 2 | 3 {...}

really means

    if $a ![==] 1 | 2 | 3 {...}

which the metaoperator rewrites to a higher-order function resembling something like:

    negate((* == *), $a, (1|2|3));

which ends up being equivalent to:

    if not $a == 1 | 2 | 3 {...}

which is the semantics an English speaker expects. However, it may well be better style to write the latter form yourself.

Junctive methods on arrays, lists, and sets work just like the corresponding list operators. However, junctive methods on a hash make a junction of only the hash's keys. Use the listop form (or an explicit .pairs) to make a junction of pairs.

Comparison semantics

From t/spec/S03-operators/equality.t lines 11–42: (skip) -

 

From t/spec/S03-operators/comparison-simple.t lines 8–44: (skip) -

 

From t/spec/S03-operators/comparison.t lines 13–57: (skip) -

 

Range and RangeIter semantics

The .. range operator has variants with ^ on either end to indicate exclusion of that endpoint from the range. It always produces a Range object. Range objects are immutable, and primarily used for matching intervals. 1..2 is the interval from 1 to 2 inclusive of the endpoints, whereas 1^..^2 excludes the endpoints but matches any real number in between.

From t/spec/S03-operators/range.t lines 36–204: (skip) -

 

For numeric arguments of differing type, ranges coerce to the wider type, so:

    1 .. 1.5

is taken to mean:

    1.0 .. 1.5

These coercions are defined by multi signatures. (Other types may have different coercion policies.) It is specifically illegal to use anything that does Iterable as implicitly numeric:

    0 ..^ 10  # 0 .. 9
    0 .. ^10  # ERROR

For ranges with other non-numeric types on the right, the right argument is coerced to the type of the left argument and treated as numeric. Hence, Array types in the second argument are assumed to be intended as numeric if the left argument is numeric:

    0 ..^ @x    # okay
    0 ..^ +@x   # same thing

Whatever types are also supported to represent -Inf/+Inf. If either endpoint is a WhateverCode, the range is curried into another WhateverCode.

For other types, ranges may be composed for any two arguments of the same type, if the type itself supports it. That is, in general, infix:<..>:(::T Any $x, T $y) is defined such that, if type T defines generic comparison (that is, by defining infix:<cmp> or equivalent), a range is constructed in that type. If T also defines .succ, then the range may be iterated. (Otherwise the range may only be used as an interval, and will return failure if asked for a RangeIter.) Note that it is not necessary to define a range multimethod in type T, since the generic routine can usually auto-generate the range for you.

Range objects support .min and .max methods representing their left and right arguments. The .bounds method returns both values as a two-element list representing the interval. Ranges are not autoreversing: 2..1 is always a null range. (The series operator ... can autoreverse, however. See below.)

Range objects support .excludes_min and .excludes_max methods representing the exclusion (has ^) or inclusion (no ^) of each endpoint in the Range.

    Range      | .min | .max | .excludes_min | .excludes_max
    -----------+------+------+-------------+------------
    1..10      | 1    | 10   | Bool::False   | Bool::False
    2.7..^9.3  | 2.7  | 9.3  | Bool::False   | Bool::True
    'a'^..'z'  | 'a'  | 'z'  | Bool::True    | Bool::False
    1^..^10    | 1    | 10   | Bool::True    | Bool::True

If used in a list context, a Range object returns an iterator that produces a series of values starting at the min and ending at the max. Either endpoint may be excluded using ^. Hence 1..2 produces (1,2) but 1^..^2 is equivalent to 2..1 and produces no values (Nil). To specify a series that counts down, use a reverse:

    reverse 1..2
    reverse 'a'..'z'

Alternately, for numeric sequences, you can use the series operator instead of the range operator:

    100,99,98 ... 0
    100 ... *-1, 0      # same thing

In other words, any Range used as a list assumes .succ semantics, never .pred semantics. No other increment is allowed; if you wish to increment a numeric sequence by some number other than 1, you must use the ... series operator. (The Range operator's :by adverb is hereby deprecated.)

    0 ... *+0.1, 100    # 0, 0.1, 0.2, 0.3 ... 100

A Range may be iterated only if the type in question supports the .succ method. If it does not, any attempt to iterate returns failure.

Smart matching against a Range object smartmatches the endpoints in the domain of the object being matched, so fractional numbers are not truncated before comparison to integer ranges:

    1.5 ~~ 1^..^2  # true, equivalent to 1 < 1.5 < 2
    2.1 ~~ 1..2    # false, equivalent to 1 <= 2.1 <= 2

If a * (see the "Whatever" type in S02) occurs on the right side of a range, it is taken to mean "positive infinity" in whatever typespace the range is operating, as inferred from the left operand. A * on the left means "negative infinity" for types that support negative values, and the first value in the typespace otherwise as inferred from the right operand. (A star on both sides is not allowed.)

    0..*        # 0 .. +Inf
    'a'..*      # 'a' le $_
    *..0        # -Inf .. 0
    *..*        # Illegal
    1.2.3..*    # Any version higher than 1.2.3.
    May..*      # May through December

An empty range cannot be iterated; it returns a Nil instead. An empty range still has a defined .min and .max, but one of the following is true: 1. The .min is greater than the .max. 2. The .min is equal to the .max and at least one of .excludes_min or .excludes_max is true. 3. Both .excludes_min and .excludes_max are true and .min and .max are consecutive values.

Ranges that are iterated transmute into the corresponding series operator, and hence use !after semantics to determine an end to the sequence.

Unary ranges

The unary ^ operator generates a range from 0 up to (but not including) its argument. So ^4 is short for 0..^4.

    for ^4 { say $_ } # 0, 1, 2, 3

If applied to a type name, it indicates the metaclass instance instead, so ^Moose is short for HOW(Moose) or Moose.HOW. It still kinda means "what is this thing's domain" in an abstract sort of way.

Auto-currying of ranges

[This section is conjectural, and may be ignored for 6.0.]

Since use of Range objects in item context is usually non-sensical, a Range object used as an operand for scalar operators will generally attempt to distribute the operator to its endpoints and return another suitably modified Range instead, much like a junction of two items, only with proper interval semantics. (Notable exceptions to this autothreading include infix:<~~>, which does smart matching, and prefix:<+> which returns the length of the range.) Therefore if you wish to write a slice using a length instead of an endpoint, you can say

    @foo[ start() + ^$len ]

which is short for:

    @foo[ start() + (0..^$len) ]

which is equivalent to something like:

    @foo[ list do { my $tmp = start(); $tmp ..^ $tmp+$len } ]

In other words, operators of numeric and other ordered types are generally overloaded to do something sensible on Range objects.

Chained comparisons

From t/spec/S02-literals/listquote.t lines 14–69: (skip) -

 

From t/spec/S03-operators/relational.t lines 104–141: (skip) -

 

Perl 6 supports the natural extension to the comparison operators, allowing multiple operands:

    if 1 < $a < 100 { say "Good, you picked a number *between* 1 and 100." }
    if 3 < $roll <= 6              { print "High roll" }
    if 1 <= $roll1 == $roll2 <= 6  { print "Doubles!" }

A chain of comparisons short-circuits if the first comparison fails:

From t/spec/S03-operators/short-circuit.t lines 150–178: (skip) -

  
    1 > 2 > die("this is never reached");

Each argument in the chain will evaluate at most once:

From t/spec/S03-operators/short-circuit.t lines 140–149: (skip) -

  
    1 > $x++ > 2    # $x increments exactly once

Note: any operator beginning with < must have whitespace in front of it, or it will be interpreted as a hash subscript instead.

Smart matching

Here is the table of smart matches for standard Perl 6 (that is, the dialect of Perl in effect at the start of your compilation unit). Smart matching is generally done on the current "topic", that is, on $_. In the table below, $_ represents the left side of the ~~ operator, or the argument to a given, or to any other topicalizer. X represents the pattern to be matched against on the right side of ~~, or after a when. (And, in fact, the ~~ operator works as a small topicalizer; that is, it binds $_ to the value of the left side for the evaluation of the right side. Use the underlying .ACCEPTS form to avoid this topicalization.)

The first section contains privileged syntax; if a match can be done via one of those entries, it will be. These special syntaxes are dispatched by their form rather than their type. Otherwise the rest of the table is used, and the match will be dispatched according to the normal method dispatch rules. The optimizer is allowed to assume that no additional match operators are defined after compile time, so if the pattern types are evident at compile time, the jump table can be optimized. However, the syntax of this part of the table is still somewhat privileged, insofar as the ~~ operator is one of the few operators in Perl that does not use multiple dispatch. Instead, type-based smart matches singly dispatch to an underlying method belonging to the X pattern object.

In other words, smart matches are dispatched first on the basis of the pattern's form or type (the X below), and then that pattern itself decides whether and how to pay attention to the type of the topic ($_). So the second column below is really the primary column. The Any entries in the first column indicate a pattern that either doesn't care about the type of the topic, or that picks that entry as a default because the more specific types listed above it didn't match.

    $_        X         Type of Match Implied   Match if (given $_)
    ======    =====     =====================   ===================
    Any       True      ~~ True                 (parsewarn)
    Any       False     ~~ False match          (parsewarn)
    Any       *         block signature match   block successfully binds to |$_
    Any       Callable:($)  item sub truth          X($_)

From t/spec/S03-smartmatch/any-callable.t lines 5–14: (skip) -

  
    Any       Callable:()   simple closure truth    X() (ignoring $_)

From t/spec/S03-smartmatch/any-callable.t lines 15–26: (skip) -

  
    Any       Bool      simple truth            X

From t/spec/S03-smartmatch/any-bool.t lines 5–19: (skip) -

  
    Any       Numeric   numeric equality        +$_ == X
    Any       Stringy   string equality         ~$_ eq X
    Any       Whatever  always matches          True
    Hash      Pair      test hash mapping       $_{X.key} ~~ X.value

From t/spec/S03-smartmatch/any-hash-pair.t lines 5–19: (skip) -

  
    Any       Pair      test object attribute   ?."{X.key}" === ?X.value (e.g. filetests)

From t/spec/S03-smartmatch/any-pair.t lines 5–35: (skip) -

  
    Set       Set       identical sets          $_ === X
    Hash      Set       hash keys same set      $_.keys === X
    Any       Set       force set comparison    Set($_) === X
    Array     Array     arrays are comparable   $_ «===» X (dwims * wildcards!)

From t/spec/S03-smartmatch/array-array.t lines 5–54: (skip) -

  
    Set       Array     array equiv to set      $_ === Set(X)
    Any       Array     lists are comparable    @$_ «===» X

From t/spec/S03-smartmatch/any-array.t lines 5–24: (skip) -

  
    Hash      Hash      hash keys same set      $_.keys === X.keys

From t/spec/S03-smartmatch/hash-hash.t lines 7–24: (skip) -

  
    Set       Hash      hash keys same set      $_ === X.keys
    Array     Hash      hash slice existence    X.{any @$_}:exists

From t/spec/S03-smartmatch/array-hash.t lines 5–20: (skip) -

  
    Regex     Hash      hash key grep           any(X.keys).match($_)

From t/spec/S03-smartmatch/regex-hash.t lines 5–16: (skip) -

  
    Scalar    Hash      hash entry existence    X.{$_}:exists

From t/spec/S03-smartmatch/scalar-hash.t lines 5–15: (skip) -

  
    Any       Hash      hash slice existence    X.{any @$_}:exists
    Str       Regex     string pattern match    .match(X)
    Hash      Regex     hash key "boolean grep" .any.match(X)
    Array     Regex     array "boolean grep"    .any.match(X)
    Any       Regex     pattern match           .match(X)
    Num       Range     in numeric range        X.min <= $_ <= X.max (mod ^'s)

From t/spec/S03-smartmatch/disorganized.t lines 31–152: (skip) -

  
    Str       Range     in string range         X.min le $_ le X.max (mod ^'s)
    Any       Range     in generic range        [!after] X.min,$_,X.max (etc.)
    Any       Type      type membership         $_.does(X)

From t/spec/S03-smartmatch/any-type.t lines 5–20: (skip) -

  
    Signature Signature sig compatibility       $_ is a subset of X      ???
    Callable  Signature sig compatibility       $_.sig is a subset of X  ???
    Capture   Signature parameters bindable     $_ could bind to X (doesn't!)
    Any       Signature parameters bindable     |$_ could bind to X (doesn't!)
    Signature Capture   parameters bindable     X could bind to $_
    Any       Any       scalars are identical   $_ === X

From t/spec/S03-smartmatch/any-any.t lines 5–18: (skip) -

 

The final rule is applied only if no other pattern type claims X.

All smartmatch types are "itemized"; both ~~ and given/when provide item contexts to their arguments, and autothread any junctive matches so that the eventual dispatch to .ACCEPTS never sees anything "plural". So both $_ and X above are potentially container objects that are treated as scalars. (You may hyperize ~~ explicitly, though. In this case all smartmatching is done using the type-based dispatch to .ACCEPTS, not the form-based dispatch at the front of the table.)

The exact form of the underlying type-based method dispatch is:

    X.ACCEPTS($_)

As a single dispatch call this pays attention only to the type of X initially. The ACCEPTS method interface is defined by the Pattern role. Any class composing the Pattern role may choose to provide a single ACCEPTS method to handle everything, which corresponds to those pattern types that have only one entry with an Any on the left above. Or the class may choose to provide multiple ACCEPTS multi-methods within the class, and these will then redispatch within the class based on the type of $_.

The smartmatch table is primarily intended to reflect forms and types that are recognized at compile time. To avoid an explosion of entries, the table assumes the following types will behave similarly:

    Actual type                 Use entries for
    ===========                 ===============
    Iterator Seq                Array
    KeySet KeyBag KeyHash       Hash
    named values created with
      Class, Enum, or Role,
      or generic type binding   Type
    Subst                       Regex
    Char Cat                    Str
    Int UInt etc.               Num
    Match                       Capture
    Byte                        Str or Int
    Buf                         Str or Array of Int

(Note, however, that these mappings can be overridden by explicit definition of the appropriate ACCEPTS methods. If the redefinition occurs at compile time prior to analysis of the smart match then the information is also available to the optimizer.)

A Buf type containing any bytes or integers outside the ASCII range may silently promote to a Str type for pattern matching if and only if its relationship to Unicode is clearly declared or typed. This type information might come from an input filehandle, or the Buf role may be a parametric type that allows you to instantiate buffers with various known encodings. In the absence of such typing information, you may still do pattern matching against the buffer, but (apart from assuming the lowest 7 bits represent ASCII) any attempt to treat the buffer as other than a sequence integers is erroneous, and warnings may be generously issued.

Matching against a Grammar treats the grammar as a typename, not as a grammar. You need to use the .parse or .parsefile methods to invoke a grammar.

Matching against a Signature does not actually bind any variables, but only tests to see if the signature could bind. To really bind to a signature, use the * pattern to delegate binding to the when statement's block instead. Matching against * is special in that it takes its truth from whether the subsequent block is bound against the topic, so you can do ordered signature matching:

    given $capture {
        when * -> Int $a, Str $b { ... }
        when * -> Str $a, Int $b { ... }
        when * -> $a, $b         { ... }
        when *                   { ... }
    }

This can be useful when the unordered semantics of multiple dispatch are insufficient for defining the "pecking order" of code. Note that you can bind to either a bare block or a pointy block. Binding to a bare block conveniently leaves the topic in $_, so the final form above is equivalent to a default. (Placeholder parameters may also be used in the bare block form, though of course their types cannot be specified that way.)

There is no pattern matching defined for the Any pattern, so if you find yourself in the situation of wanting a reversed smartmatch test with an Any on the right, you can almost always get it by explicit call to the underlying ACCEPTS method using $_ as the pattern. For example:

    $_      X    Type of Match Wanted   What to use on the right
    ======  ===  ====================   ========================
    Callable Any  item sub truth         .ACCEPTS(X) or .(X)
    Range   Any  in range               .ACCEPTS(X)
    Type    Any  type membership        .ACCEPTS(X) or .does(X)
    Regex   Any  pattern match          .ACCEPTS(X)
    etc.

Similar tricks will allow you to bend the default matching rules for composite objects as long as you start with a dotted method on $_:

    given $somethingordered {
        when .values.'[<=]'     { say "increasing" }
        when .values.'[>=]'     { say "decreasing" }
    }

In a pinch you can define a macro to do the "reversed when":

    my macro statement_control:<ACCEPTS> () { "when .ACCEPTS: " }
    given $pattern {
        ACCEPTS $a      { ... }
        ACCEPTS $b      { ... }
        ACCEPTS $c      { ... }
    }

Various proposed-but-deprecated smartmatch behaviors may be easily (and we hope, more readably) emulated as follows:

    $_      X      Type of Match Wanted   What to use on the right
    ======  ===    ====================   ========================
    Array   Num    array element truth    .[X]
    Array   Num    array contains number  *,X,*
    Array   Str    array contains string  *,X,*
    Array   Seq    array begins with seq  X,*
    Array   Seq    array contains seq     *,X,*
    Array   Seq    array ends with seq    *,X
    Hash    Str    hash element truth     .{X}
    Hash    Str    hash key existence     .{X}:exists
    Hash    Num    hash element truth     .{X}
    Hash    Num    hash key existence     .{X}:exists
    Buf     Int    buffer contains int    .match(X)
    Str     Char   string contains char   .match(X)
    Str     Str    string contains string .match(X)
    Array   Scalar array contains item    .any === X
    Str     Array  array contains string  X.any
    Num     Array  array contains number  X.any
    Scalar  Array  array contains object  X.any
    Hash    Array  hash slice exists      .{X.all}:exists .{X.any}:exists
    Set     Set    subset relation        .{X}:exists
    Set     Hash   subset relation        .{X}:exists
    Any     Set    subset relation        .Set.{X}:exists
    Any     Hash   subset relation        .Set.{X}:exists
    Any     Set    superset relation      X.{$_}:exists
    Any     Hash   superset relation      X.{$_}:exists
    Any     Set    sets intersect         .{X.any}:exists
    Set     Array  subset relation        X,*          # (conjectured)
    Array   Regex  match array as string  .Cat.match(X)  cat(@$_).match(X)

(Note that the .cat method and the Cat type coercion both take a single object, unlike the cat function which, as a list operator, takes a syntactic list (or multilist) and flattens it. All of these return a Cat object, however.)

Boolean expressions are those known to return a boolean value, such as comparisons, or the unary ? operator. They may reference $_ explicitly or implicitly. If they don't reference $_ at all, that's okay too--in that case you're just using the switch structure as a more readable alternative to a string of elsifs. Note, however, that this means you can't write:

    given $boolean {
        when True  {...}
        when False {...}
    }

because it will always choose the True case. Instead use something like a conditional context uses internally:

    given $boolean {
        when .Bool == 1 {...}
        when .Bool == 0 {...}
    }

Better, just use an if statement. In any case, if you try to smartmatch with ~~ or when, it will recognize True or False syntactically and warn you that it won't do what you expect. The compiler is also allowed to warn about any other boolean construct that does not test $_, to the extent it can detect that.

In a similar vein, any function (such as grep) that takes a Matcher will not accept an argument of type Bool, since that almost always indicates a programming error. (One may always use * to match anything, if that's what you really want. Or use a closure that returns a constant boolean value.)

Note also that regex matching does not return a Bool, but merely a Match object that can be used as a boolean value. Use an explicit ? or true to force a Bool value if desired.

The primary use of the ~~ operator is to return a boolean value in a boolean context. However, for certain operands such as regular expressions, use of the operator within item or list context transfers the context to that operand, so that, for instance, a regular expression can return a list of matched substrings, as in Perl 5. This is done by returning an object that can return a list in list context, or that can return a boolean in a boolean context. In the case regex matching the Match object is a kind of Capture, which has these capabilities.

For the purpose of smartmatching, all Set and Bag values are considered to be of type KeyHash, that is, Hash containers where the keys represent the unique objects and the values represent the replication count of those unique keys. (Obviously, a Set can have only 0 or 1 replication because of the guarantee of uniqueness).

The Cat type allows you to have an infinitely extensible string. You can match an array or iterator by feeding it to a Cat, which is essentially a Str interface over an iterator of some sort. Then a Regex can be used against it as if it were an ordinary string. The Regex engine can ask the string if it has more characters, and the string will extend itself if possible from its underlying iterator. (Note that such strings have an indefinite number of characters, so if you use .* in your pattern, or if you ask the string how many characters it has in it, or if you even print the whole string, it may be feel compelled to slurp in the rest of the string, which may or may not be expeditious.)

The cat operator takes a (potentially lazy) list and returns a Cat object. In string context this coerces each of its elements to strings lazily, and behaves as a string of indeterminate length. You can search a gather like this:

    my $lazystr := cat gather for @foo { take .bar }
    $lazystr ~~ /pattern/;

The Cat interface allows the regex to match element boundaries with the <,> assertion, and the StrPos objects returned by the match can be broken down into elements index and position within that list element. If the underlying data structure is a mutable array, changes to the array (such as by shift or pop) are tracked by the Cat so that the element numbers remain correct. Strings, arrays, lists, sequences, captures, and tree nodes can all be pattern matched by regexes or by signatures more or less interchangeably.

Invocant marker

An appended : marks the invocant when using the indirect-object syntax for Perl 6 method calls. The following two statements are equivalent:

    $hacker.feed('Pizza and cola');
    feed $hacker: 'Pizza and cola';

A colon may also be used on an ordinary method call to indicate that it should be parsed as a list operator:

    $hacker.feed: 'Pizza and cola';

This colon is a separate token. A colon prefixing an adverb is not a separate token. Therefore, under the longest-token rule,

    $hacker.feed:xxx('Pizza and cola');

is tokenized as an adverb applying to the method as its "toplevel preceding operator":

    $hacker.feed :xxx('Pizza and cola');

not as an xxx sub in the argument list of .feed:

    $hacker.feed: xxx('Pizza and cola');  # wrong

If you want both meanings of colon in order to supply both an adverb and some positional arguments, you have to put the colon twice:

    $hacker.feed: :xxx('Pizza and cola'), 1,2,3;

(For similar reasons it's required to put whitespace after the colon of a label.)

Note in particular that because of adverbial precedence:

    1 + $hacker.feed :xxx('Pizza and cola');

will apply the :xxx adverb to the + operator, not the method call. This is not likely to succeed.

From t/spec/S03-operators/adverbial-modifiers.t lines 7–303: (skip) -

 

Feed operators

From t/spec/S03-operators/feed.t lines 6–137: (skip) -

 

The new operators ==> and <== are akin to UNIX pipes, but work with functions or statements that accept and return lists. Since these lists are composed of discrete objects and not liquids, we call these feed operators rather than pipes. For example,

     @result = map { floor($^x / 2) },
                 grep { /^ \d+ $/ },
                   @data;

can also now be written with rightward feeds as:

     @data ==> grep { /^ \d+ $/ }
           ==> map { floor($^x / 2) }
           ==> @result;

or with leftward feeds as:

     @result <== map { floor($^x / 2) }
             <== grep { /^ \d+ $/ }
             <== @data;

Either form more clearly indicates the flow of data. See S06 for more of the (less-than-obvious) details on these two operators.

Meta operators

Perl 6's operators have been greatly regularized, for instance, by consistently prefixing numeric, stringwise, and boolean operators with +, ~ and ? respectively to indicate whether the bitwise operation is done on a number, a string, or a single bit. But that's just a naming convention, and if you wanted to add a new bitwise ¬ operator, you'd have to add the +¬, ~¬, and ?¬ operators yourself. Similarly, the carets that exclude the endpoints on ranges are there by convention only.

In contrast to that, Perl 6 has eight standard metaoperators for turning a given existing operator into a related operator that is more powerful (or at least differently powerful). These differ from a mere naming convention in that Perl automatically generates these new operators from user-defined operators as well as from builtins. In fact, you're not generally supposed to define the individual metaoperations--their semantics are supposed to be self-evident by the transformation of the base operator. In other words, these metaoperators are really just shorthand for higher-order functions (functions that take other functions as arguments).

Constructs containing metaoperators are considered "metatokens", by which we mean that they are not subject to ordinary longest-token matching rules, although their components are. Like ordinary tokens, however, metatokens do not allow whitespace between their subparts.

Assignment operators

From t/spec/S03-operators/autovivification.t lines 4–100: (skip) -

 

Assignment operators are already familiar to C and Perl programmers. (Though the .= operator now means to call a mutating method on the object on the left, and ~= is string concatenation.) Most non-relational infix operators may be turned into their corresponding assignment operator by suffixing with =. The limitation is actually based on whether the left side can function both as an rvalue and an lvalue by the usual correspondence:

    A op= B;

From t/spec/S03-operators/inplace.t lines 5–49: (skip) -

  
    A = A op B;

Existing forms ending in = may not be modified with this metaoperator.

Regardless of the precedence of the base operator, the precedence of any assignment operator is forced to be the same as that of ordinary assignment. If the base operator is tighter than comma, the expression is parsed as item assignment. If the base operator is the same or looser than comma, the expression is parsed as a list assignment:

    $a += 1, $b += 2    # two separate item assignments
    @foo ,= 1,2,3       # same as push(@foo,1,2,3)

From t/spec/S03-operators/assign.t lines 699–762: (skip) -

  
    @foo Z= 1,2,3       # same as @foo = @foo Z 1,2,3

Note that metaassignment to a list does not automatically distribute the right argument over the assigned list unless the base operator does (as in the Z case above). Hence if you want to say:

    ($a,$b,$c) += 1;    # ILLEGAL

you must instead use a hyperoperator (see below):

    ($a,$b,$c) »+=» 1;  # add one to each of three variables

If you apply an assignment operator to a container containing a type object (which is undefined), it is assumed that you are implementing some kind of notional "reduction" to an accumulator variable. To that end, the operation is defined in terms of the corresponding reduction operator, where the type object autovivifies to the operator's identify value. So if you say:

From t/spec/S03-operators/autovivification.t lines 101–141: (skip) -

  
    $x -= 1;

it is more or less equivalent to:

    $x = [-]() unless defined $x;  # 0 for [-]()
    $x = $x - 1;

and $x ends up with -1 in it, as expected.

Hence you may correctly write:

    my Num $prod;
    for @factors -> $f {
        $prod *= $f;
    }

While this may seem marginally useful in the scalar variable case, it's much more important for it to work this way when the modified location may have only just been created by autovivification. In other words, if you write:

    %prod{$key} *= $f

you need not worry about whether the hash element exists yet. If it does not, it will simply be initialized with the value of $f.

Negated relational operators

From t/spec/S03-operators/equality.t lines 43–60: (skip) -

 

Any infix relational operator returning type Bool may be transformed into its negative by prefixing with !. A couple of these have traditional shortcuts:

    Full form   Shortcut
    ---------   --------
    !==         !=
    !eq         ne

but most of them do not:

    !~~
    !<
    !>=
    !ge
    !===
    !eqv
    !=:=

To avoid visual confusion with the !! operator, you may not modify any operator already beginning with !.

The precedence of any negated operator is the same as the base operator.

The operator

    !%

is specially allowed for testing even divisibility by an integer.

From t/spec/S03-metaops/not.t lines 52–69: (skip) -

 

Note that logical operators such as || and ^^ do not return a Bool, but rather one of the operands.

Reversed operators

Any infix operator may be called with its two arguments reversed by prefixing with R. For instance, to do reversed comparisons:

    Rcmp
    Rleg
    R<=>

The precedence of any reversed operator is the same as the base operator. The associativity is not reversed, so

    [R-] 1,2,3   # produces 2 from 3 - (2 - 1)

To get the other effect in a reduce, reverse the list:

    [-] reverse 1,2,3  # produces 0

Hyper operators

From t/spec/S03-metaops/hyper.t lines 13–690: (skip) -