NAME

    Syntax::Keyword::Match - a match/case syntax for perl

SYNOPSIS

       use v5.14;
       use Syntax::Keyword::Match;
    
       my $n = ...;
    
       match($n : ==) {
          case(1) { say "It's one" }
          case(2) { say "It's two" }
          case(3) { say "It's three" }
          default { say "It's something else" }
       }

DESCRIPTION

    This module provides a syntax plugin that implements a control-flow
    block called match/case, which executes at most one of a choice of
    different blocks depending on the value of its controlling expression.

    This is similar to C's switch/case syntax (copied into many other
    languages), or syntax provided by Switch::Plain.

    This is an initial, experimental implementation. Furthermore, it is
    built as a non-trivial example use-case on top of XS::Parse::Keyword,
    which is also experimental. No API or compatbility guarantees are made
    at this time.

KEYWORDS

 match

       match( EXPR : OP ) {
          ...
       }

    A match statement provides the controlling expression, comparison
    operator, and sequence of case statements for a match operation. The
    expression is evaluated to yield a scalar value, which is then
    compared, using the comparison operator, against each of the case
    labels in the order they are written, topmost first. If a match is
    found then the body of the labelled block is executed. If no label
    matches but a default block is present, that will be executed instead.
    After a single inner block has been executed, no further tests are
    performed and execution continues from the statement following the
    match statement.

    The braces following the match block must only contain case or default
    statements. Arbitrary code is not supported here.

    Even though a match statement is a full statement and not an
    expression, it can still yield a value if it appears as the final
    statment in its containing sub or do block. For example:

       my $result = do {
          match( $topic : == ) {
             case(1) { ... }
          }
       };

  Comparison Operators

    The comparison operator must be either eq (to compare cases as strings)
    or == (to compare them as numbers), or =~ (to compare cases using
    regexps).

    On Perl versions 5.32 onwards, the isa operator is also supported,
    allowing dispatch based on what type of object the controlling
    expression gives.

       match( $obj : isa ) {
          case(A::Package)       { ... }
          case(Another::Package) { ... }
       }

    Remember that comparisons are made in the order they are written, from
    the top downwards. Therefore, if you list a derived class as well as a
    base class, make sure to put the derived class before the base class,
    or instances of that type will also match the base class case block and
    the derived one will never match.

       class TheBase {}
       class Derived extends TheBase {}
    
       match( $obj : isa ) {
          case(TheBase) { ... }
          case(Derived) {
             # This case will never match as the one above will always happen first
          }
       }

 case

       case(VAL) { STATEMENTS... }

    A case statement must only appear inside the braces of a match. It
    provides a block of code to run if the controlling expression's value
    matches the value given in the case statement, according to the
    comparison operator.

    If the value is a non-constant expression, such as a variable or
    function call, it will be evaluated as part of performing the
    comparison every time the match statement is executed. For best
    performance it is advised to extract values that won't need computing
    again into a variable that can be calculated just once at program
    startup; for example:

       my $condition = a_function("with", "arguments");
    
       match( $var : eq ) {
          case($condition) { ... }
          ...
       }

 default

    A default statement must only appear inside the braces of a match. If
    present, it must be the final choice, and there must only be one of
    them. It provides a block of code to run if the controlling
    expression's value did not match any of the given case labels.

TODO

    This is clearly an early experimental work. There are many features to
    add, and design decisions to make. Rather than attempt to list them all
    here it would be best to check the RT bug queue at

    https://rt.cpan.org/Dist/Display.html?Name=Syntax-Keyword-Match

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

