1Syntax::Keyword::Match(U3s)er Contributed Perl DocumentatSiyonntax::Keyword::Match(3)
2
6 "Syntax::Keyword::Match" - a "match/case" syntax for perl
7
9 use v5.14;
10 use Syntax::Keyword::Match;
11 my $n = ...;
13 match($n : ==) {
15 case(1) { say "It's one" }
16 case(2) { say "It's two" }
17 case(3) { say "It's three" }
18 case(4), case(5)
19 { say "It's four or five" }
20 default { say "It's something else" }
21 }
22
24 This module provides a syntax plugin that implements a control-flow
25 block called "match/case", which executes at most one of a choice of
26 different blocks depending on the value of its controlling expression.
27 This is similar to C's "switch/case" syntax (copied into many other
29 languages), or syntax provided by Switch::Plain.
30 This is an initial, experimental implementation. Furthermore, it is
32 built as a non-trivial example use-case on top of XS::Parse::Keyword,
33 which is also experimental. No API or compatbility guarantees are made
34 at this time.
35
37 Some of the features of this module are currently marked as
38 experimental (even within the context that the module itself is
39 experimental). They will provoke warnings in the "experimental"
40 category, unless silenced.
41 use Syntax::Keyword::Match qw( match :experimental(dispatch) );
43 use Syntax::Keyword::Match qw( match :experimental ); # all of the above
45
47 match
48 match( EXPR : OP ) {
49 ...
50 }
51 A "match" statement provides the controlling expression, comparison
53 operator, and sequence of "case" statements for a match operation. The
54 expression is evaluated to yield a scalar value, which is then
55 compared, using the comparison operator, against each of the "case"
56 labels in the order they are written, topmost first. If a match is
57 found then the body of the labelled block is executed. If no label
58 matches but a "default" block is present, that will be executed
59 instead. After a single inner block has been executed, no further tests
60 are performed and execution continues from the statement following the
61 "match" statement.
62 The braces following the "match" block must only contain "case" or
64 "default" statements. Arbitrary code is not supported here.
65 Even though a "match" statement is a full statement and not an
67 expression, it can still yield a value if it appears as the final
68 statment in its containing "sub" or "do" block. For example:
69 my $result = do {
71 match( $topic : == ) {
72 case(1) { ... }
73 }
74 };
75 Comparison Operators
77 The comparison operator must be either "eq" (to compare cases as
79 strings) or "==" (to compare them as numbers), or "=~" (to compare
80 cases using regexps).
81 On Perl versions 5.32 onwards, the "isa" operator is also supported,
83 allowing dispatch based on what type of object the controlling
84 expression gives.
85 match( $obj : isa ) {
87 case(A::Package) { ... }
88 case(Another::Package) { ... }
89 }
90 Remember that comparisons are made in the order they are written, from
92 the top downwards. Therefore, if you list a derived class as well as a
93 base class, make sure to put the derived class before the base class,
94 or instances of that type will also match the base class "case" block
95 and the derived one will never match.
96 class TheBase {}
98 class Derived extends TheBase {}
99 match( $obj : isa ) {
101 case(TheBase) { ... }
102 case(Derived) {
103 # This case will never match as the one above will always happen first
104 }
105 }
106 Since version 0.08 the operator syntax is parsed using
108 XS::Parse::Infix, meaning that custom infix operators can be
109 recognised, even on versions of perl that do not support the full
110 "PL_infix_plugin" mechanism.
111 case
113 case(VAL) { STATEMENTS... }
114 case(VAL), case(VAL), ... { STATEMENTS... }
116 A "case" statement must only appear inside the braces of a "match". It
118 provides a block of code to run if the controlling expression's value
119 matches the value given in the "case" statement, according to the
120 comparison operator.
121 Multiple "case" statements are permitted for a single block. A value
123 matching any of them will run the code inside the block.
124 If the value is a non-constant expression, such as a variable or
126 function call, it will be evaluated as part of performing the
127 comparison every time the "match" statement is executed. For best
128 performance it is advised to extract values that won't need computing
129 again into a variable that can be calculated just once at program
130 startup; for example:
131 my $condition = a_function("with", "arguments");
133 match( $var : eq ) {
135 case($condition) { ... }
136 ...
137 }
138 The ":experimental(dispatch)" feature selects a more efficient handling
140 of sequences of multiple "case" blocks with constant expressions. This
141 handling is implemented with a custom operator that will entirely
142 confuse modules like "B::Deparse" or optree inspectors like coverage
143 tools so is not selected by default, but can be enabled for extra
144 performance in critical sections.
145 default
147 A "default" statement must only appear inside the braces of a "match".
148 If present, it must be the final choice, and there must only be one of
149 them. It provides a block of code to run if the controlling
150 expression's value did not match any of the given "case" labels.
151
153 As this syntax is fairly similar to a few other ideas, the following
154 comparisons may be useful.
155 Core perl's given/when syntax
157 Compared to core perl's "given/when" syntax (available with "use
158 feature 'switch'"), this syntax is initially visually very similar but
159 actually behaves very differently. Core's "given/when" uses the
160 smartmatch ("~~") operator for its comparisons, which is complex,
161 subtle, and hard to use correctly - doubly-so when comparisons against
162 values stored in variables rather than literal constants are involved.
163 It can be unpredictable whether string or numerical comparison are
164 being used, for example. By comparison, this module requires the
165 programmer to specify the comparison operator. The choice of string or
166 numerical comparison is given in the source code - there can be no
167 ambiguity.
168 Additionally, the "isa" operator is also permitted, which has no
170 equivalent ability in smartmatch.
171 Also, the "given/when" syntax permits mixed code within a "given" block
173 which is run unconditionally, or at least, until the first successful
174 "when" statement is encountered. The syntax provided by this module
175 requires that the only code inside a "match" block be a sequence of
176 "case" statements. No other code is permitted.
177 Switch::Plain
179 Like this module, Switch::Plain also provides a syntax where the
180 programmer specifies whether the comparison is made using stringy or
181 numerical semantics. "Switch::Plain" also permits additional
182 conditions to be placed on "case" blocks, whereas this module does not.
183 Additionally, the "isa" operator is also permitted, which has no
185 equivalent ability in "Switch::Plain".
186 C's switch/case
188 The C programming language provides a similar sort of syntax, using
189 keywords named "switch" and "case". One key difference between that and
190 the syntax provided for Perl by this module is that in C the "case"
191 labels really are just labels. The "switch" part of the statement
192 effectively acts as a sort of computed "goto". This often leads to bugs
193 caused by forgetting to put a "break" at the end of a sequence of
194 statements before the next "case" label; a situation called
195 "fallthrough". Such a mistake is impossible with this module, because
196 every "case" is provided by a block. Once execution has finished with
197 the block, the entire "match" statement is finished. There is no
198 possibility of accidental fallthrough.
199 C's syntax only permits compiletime constants for "case" labels,
201 whereas this module will also allow the result of any runtime
202 expression.
203 Code written in C will perform identically even if any of the "case"
205 labels and associated code are moved around into a different order. The
206 syntax provided by this module notionally performs all of its tests in
207 the order they are written in, and any changes of that order might
208 cause a different result.
209
211 This is clearly an early experimental work. There are many features to
212 add, and design decisions to make. Rather than attempt to list them all
213 here it would be best to check the RT bug queue at
214 <https://rt.cpan.org/Dist/Display.html?Name=Syntax-Keyword-Match>
216
218 Paul Evans <leonerd@leonerd.org.uk>
219perl v5.34.0 2021-10-27 Syntax::Keyword::Match(3)