Debian Codegraph @

upstream/fedora-44/man1/perlop.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLOP 1"
61 .TH PERLOP 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlop \- Perl expressions: operators, precedence, string literals
68 .IX Xref "operator"
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 In Perl, the operator determines what operation is performed,
72 independent of the type of the operands. For example \f(CW\*(C`$x\ +\ $y\*(C'\fR
73 is always a numeric addition, and if \f(CW$x\fR or \f(CW$y\fR do not contain
74 numbers, an attempt is made to convert them to numbers first.
75 .PP
76 This is in contrast to many other dynamic languages, where the
77 operation is determined by the type of the first argument. It also
78 means that Perl has two versions of some operators, one for numeric
79 and one for string comparison. For example \f(CW\*(C`$x\ ==\ $y\*(C'\fR compares
80 two numbers for equality, and \f(CW\*(C`$x\ eq\ $y\*(C'\fR compares two strings.
81 .PP
82 There are a few exceptions though: The operator \f(CW\*(C`x\*(C'\fR can be either string
83 repetition or list repetition, depending on the type of the left
84 operand, and \f(CW\*(C`&\*(C'\fR, \f(CW\*(C`|\*(C'\fR, \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`~\*(C'\fR can be either string or numeric bit
85 operations.
86 .SS "Operator Precedence and Associativity"
87 .IX Xref "operator, precedence precedence associativity"
88 .IX Subsection "Operator Precedence and Associativity"
89 Operator precedence and associativity work in Perl more or less like
90 they do in mathematics.
91 .PP
92 \&\fIOperator precedence\fR means some operators group more tightly than others.
93 For example, in \f(CW\*(C`2 + 4 * 5\*(C'\fR, the multiplication has higher precedence, so \f(CW\*(C`4
94 * 5\*(C'\fR is grouped together as the right\-hand operand of the addition, rather
95 than \f(CW\*(C`2 + 4\*(C'\fR being grouped together as the left\-hand operand of the
96 multiplication. It is as if the expression were written \f(CW\*(C`2 + (4 * 5)\*(C'\fR, not
97 \&\f(CW\*(C`(2 + 4) * 5\*(C'\fR. So the expression yields \f(CW\*(C`2 + 20 == 22\*(C'\fR, rather than
98 \&\f(CW\*(C`6 * 5 == 30\*(C'\fR.
99 .PP
100 \&\fIOperator associativity\fR defines what happens if a sequence of the same
101 operators is used one after another:
102 usually that they will be grouped at the left
103 or the right. For example, in \f(CW\*(C`9 \- 3 \- 2\*(C'\fR, subtraction is left associative,
104 so \f(CW\*(C`9 \- 3\*(C'\fR is grouped together as the left\-hand operand of the second
105 subtraction, rather than \f(CW\*(C`3 \- 2\*(C'\fR being grouped together as the right\-hand
106 operand of the first subtraction. It is as if the expression were written
107 \&\f(CW\*(C`(9 \- 3) \- 2\*(C'\fR, not \f(CW\*(C`9 \- (3 \- 2)\*(C'\fR. So the expression yields \f(CW\*(C`6 \- 2 == 4\*(C'\fR,
108 rather than \f(CW\*(C`9 \- 1 == 8\*(C'\fR.
109 .PP
110 For simple operators that evaluate all their operands and then combine the
111 values in some way, precedence and associativity (and parentheses) imply some
112 ordering requirements on those combining operations. For example, in \f(CW2 + 4 *
113 5\fR, the grouping implied by precedence means that the multiplication of 4 and
114 5 must be performed before the addition of 2 and 20, simply because the result
115 of that multiplication is required as one of the operands of the addition. But
116 the order of operations is not fully determined by this: in \f(CW\*(C`2 * 2 + 4 * 5\*(C'\fR
117 both multiplications must be performed before the addition, but the grouping
118 does not say anything about the order in which the two multiplications are
119 performed. In fact Perl has a general rule that the operands of an operator
120 are evaluated in left\-to\-right order. A few operators such as \f(CW\*(C`&&=\*(C'\fR have
121 special evaluation rules that can result in an operand not being evaluated at
122 all; in general, the top\-level operator in an expression has control of
123 operand evaluation.
124 .PP
125 Some comparison operators, as their associativity, \fIchain\fR with some
126 operators of the same precedence (but never with operators of different
127 precedence). This chaining means that each comparison is performed
128 on the two arguments surrounding it, with each interior argument taking
129 part in two comparisons, and the comparison results are implicitly ANDed.
130 Thus \f(CW"$x\ <\ $y\ <=\ $z"\fR behaves exactly like \f(CW"$x\ <\ $y\ &&\ $y\ <=\ $z"\fR, assuming that \f(CW"$y"\fR is as simple a scalar as
131 it looks. The ANDing short\-circuits just like \f(CW"&&"\fR does, stopping
132 the sequence of comparisons as soon as one yields false.
133 .PP
134 In a chained comparison, each argument expression is evaluated at most
135 once, even if it takes part in two comparisons, but the result of the
136 evaluation is fetched for each comparison. (It is not evaluated
137 at all if the short\-circuiting means that it\*(Aqs not required for any
138 comparisons.) This matters if the computation of an interior argument
139 is expensive or non\-deterministic. For example,
140 .PP
141 .Vb 1
142 \& if ($x < expensive_sub() <= $z) { ...
143 .Ve
144 .PP
145 is not entirely like
146 .PP
147 .Vb 1
148 \& if ($x < expensive_sub() && expensive_sub() <= $z) { ...
149 .Ve
150 .PP
151 but instead closer to
152 .PP
153 .Vb 2
154 \& my $tmp = expensive_sub();
155 \& if ($x < $tmp && $tmp <= $z) { ...
156 .Ve
157 .PP
158 in that the subroutine is only called once. However, it\*(Aqs not exactly
159 like this latter code either, because the chained comparison doesn\*(Aqt
160 actually involve any temporary variable (named or otherwise): there is
161 no assignment. This doesn\*(Aqt make much difference where the expression
162 is a call to an ordinary subroutine, but matters more with an lvalue
163 subroutine, or if the argument expression yields some unusual kind of
164 scalar by other means. For example, if the argument expression yields
165 a tied scalar, then the expression is evaluated to produce that scalar
166 at most once, but the value of that scalar may be fetched up to twice,
167 once for each comparison in which it is actually used.
168 .PP
169 In this example, the expression is evaluated only once, and the tied
170 scalar (the result of the expression) is fetched for each comparison that
171 uses it.
172 .PP
173 .Vb 1
174 \& if ($x < $tied_scalar < $z) { ...
175 .Ve
176 .PP
177 In the next example, the expression is evaluated only once, and the tied
178 scalar is fetched once as part of the operation within the expression.
179 The result of that operation is fetched for each comparison, which
180 normally doesn\*(Aqt matter unless that expression result is also magical due
181 to operator overloading.
182 .PP
183 .Vb 1
184 \& if ($x < $tied_scalar + 42 < $z) { ...
185 .Ve
186 .PP
187 Some operators are instead non\-associative, meaning that it is a syntax
188 error to use a sequence of those operators of the same precedence.
189 For example, \f(CW"$x\ ..\ $y\ ..\ $z"\fR is an error.
190 .PP
191 Perl operators have the following associativity and precedence,
192 listed from highest precedence to lowest. Operators borrowed from
193 C keep the same precedence relationship with each other, even where
194 C\*(Aqs precedence is slightly screwy. (This makes learning Perl easier
195 for C folks.) With very few exceptions, these all operate on scalar
196 values only, not array values.
197 .PP
198 .Vb 10
199 \& left terms and list operators (leftward)
200 \& left \->
201 \& nonassoc ++ \-\-
202 \& right **
203 \& right ! ~ ~. \e and unary + and \-
204 \& left =~ !~
205 \& left * / % x
206 \& left + \- .
207 \& left << >>
208 \& nonassoc named unary operators
209 \& nonassoc isa
210 \& chained < > <= >= lt gt le ge
211 \& chain/na == != eq ne <=> cmp ~~
212 \& left & &.
213 \& left | |. ^ ^.
214 \& left &&
215 \& left || ^^ //
216 \& nonassoc .. ...
217 \& right ?:
218 \& right = += \-= *= etc. goto last next redo dump
219 \& left , =>
220 \& nonassoc list operators (rightward)
221 \& right not
222 \& left and
223 \& left or xor
224 .Ve
225 .PP
226 The following sections cover these operators in detail. Each section
227 covers all the operators for a single precedence level. The sections
228 are ordered highest precedence first, same as in the table above.
229 .PP
230 Many operators can be overloaded for objects. See overload.
231 .SS "Terms and List Operators (Leftward)"
232 .IX Xref "list operator operator, list term"
233 .IX Subsection "Terms and List Operators (Leftward)"
234 A TERM has the highest precedence in Perl. They include variables,
235 quote and quote\-like operators, any expression in parentheses,
236 and any function whose arguments are parenthesized. Actually, there
237 aren\*(Aqt really functions in this sense, just list operators and unary
238 operators behaving as functions because you put parentheses around
239 the arguments. These are all documented in perlfunc.
240 .PP
241 If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
242 is followed by a left parenthesis as the next token, the operator and
243 arguments within parentheses are taken to be of highest precedence,
244 just like a normal function call.
245 .PP
246 In the absence of parentheses, the precedence of list operators such as
247 \&\f(CW\*(C`print\*(C'\fR, \f(CW\*(C`sort\*(C'\fR, or \f(CW\*(C`chmod\*(C'\fR is either very high or very low depending on
248 whether you are looking at the left side or the right side of the operator.
249 For example, in
250 .PP
251 .Vb 2
252 \& @ary = (1, 3, sort 4, 2);
253 \& print @ary; # prints 1324
254 .Ve
255 .PP
256 the commas on the right of the \f(CW\*(C`sort\*(C'\fR are evaluated before the \f(CW\*(C`sort\*(C'\fR,
257 but the commas on the left are evaluated after. In other words,
258 list operators tend to gobble up all arguments that follow, and
259 then act like a simple TERM with regard to the preceding expression.
260 Be careful with parentheses:
261 .PP
262 .Vb 3
263 \& # These evaluate exit before doing the print:
264 \& print($foo, exit); # Obviously not what you want.
265 \& print $foo, exit; # Nor is this.
266 \&
267 \& # These do the print before evaluating exit:
268 \& (print $foo), exit; # This is what you want.
269 \& print($foo), exit; # Or this.
270 \& print ($foo), exit; # Or even this.
271 .Ve
272 .PP
273 Also note that
274 .PP
275 .Vb 1
276 \& print ($foo & 255) + 1, "\en";
277 .Ve
278 .PP
279 probably doesn\*(Aqt do what you expect at first glance. The parentheses
280 enclose the argument list for \f(CW\*(C`print\*(C'\fR which is evaluated (printing
281 the result of \f(CW\*(C`$foo\ &\ 255\*(C'\fR). Then one is added to the return value
282 of \f(CW\*(C`print\*(C'\fR (usually 1). The result is something like this:
283 .PP
284 .Vb 1
285 \& 1 + 1, "\en"; # Obviously not what you meant.
286 .Ve
287 .PP
288 To do what you meant properly, you must write:
289 .PP
290 .Vb 1
291 \& print(($foo & 255) + 1, "\en");
292 .Ve
293 .PP
294 See "Named Unary Operators" for more discussion of this.
295 .PP
296 Also parsed as terms are the \f(CW\*(C`do\ {}\*(C'\fR and \f(CW\*(C`eval\ {}\*(C'\fR constructs, as
297 well as subroutine and method calls, and the anonymous
298 constructors \f(CW\*(C`[]\*(C'\fR and \f(CW\*(C`{}\*(C'\fR.
299 .PP
300 See also "Quote and Quote\-like Operators" below,
301 as well as "I/O Operators".
302 .SS "The Arrow Operator"
303 .IX Xref "arrow dereference ->"
304 .IX Subsection "The Arrow Operator"
305 "\f(CW\*(C`\->\*(C'\fR" is an infix dereference operator, just as it is in C
306 and C++. If the right side is one of a \f(CW\*(C`[...]\*(C'\fR, \f(CW\*(C`{...}\*(C'\fR, or a
307 \&\f(CW\*(C`(...)\*(C'\fR subscript, then the left side must be either a hard or
308 symbolic reference to an array, a hash, or a subroutine respectively.
309 (Or technically speaking, a location capable of holding a hard
310 reference, if it\*(Aqs an array or hash reference being used for
311 assignment.) See perlreftut and perlref.
312 .PP
313 Otherwise, the right side is a method name or a simple scalar
314 variable containing either the method name or a subroutine reference,
315 and (if it is a method name) the left side must be either an object (a
316 blessed reference) or a class name (that is, a package name). See
317 perlobj.
318 .PP
319 The right side may also be the name of a subroutine, prefixed with the \f(CW\*(C`&\*(C'\fR
320 sigil. This creates what looks like a lexical method invocation, where the
321 method subroutine is resolved lexically instead of by name by a search within
322 the packages of the object\*(Aqs class. This resolution happens entirely at
323 compile\-time, and performs the same as a regular subroutine call at runtime.
324 .PP
325 The dereferencing cases (as opposed to method\-calling cases) are
326 somewhat extended by the \f(CW\*(C`postderef\*(C'\fR feature. For the
327 details of that feature, consult "Postfix Dereference Syntax" in perlref.
328 .SS "Auto\-increment and Auto\-decrement"
329 .IX Xref "increment auto-increment ++ decrement auto-decrement --"
330 .IX Subsection "Auto-increment and Auto-decrement"
331 \&\f(CW"++"\fR and \f(CW"\-\-"\fR work as in C. That is, if placed before a variable,
332 they increment or decrement the variable by one before returning the
333 value, and if placed after, increment or decrement after returning the
334 value.
335 .PP
336 .Vb 3
337 \& $i = 0; $j = 0;
338 \& print $i++; # prints 0
339 \& print ++$j; # prints 1
340 .Ve
341 .PP
342 Note that just as in C, Perl doesn\*(Aqt define \fBwhen\fR the variable is
343 incremented or decremented. You just know it will be done sometime
344 before or after the value is returned. This also means that modifying
345 a variable twice in the same statement will lead to undefined behavior.
346 Avoid statements like:
347 .PP
348 .Vb 2
349 \& $i = $i ++;
350 \& print ++ $i + $i ++;
351 .Ve
352 .PP
353 Perl will not guarantee what the result of the above statements is.
354 .PP
355 The auto\-increment operator has a little extra builtin magic to it. If
356 you increment a variable that is numeric, or that has ever been used in
357 a numeric context, you get a normal increment. If, however, the
358 variable has been used in only string contexts since it was set, and
359 has a value that is not the empty string and matches the pattern
360 \&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the increment is done as a string, preserving each
361 character within its range, with carry:
362 .PP
363 .Vb 4
364 \& print ++($foo = "99"); # prints "100"
365 \& print ++($foo = "a0"); # prints "a1"
366 \& print ++($foo = "Az"); # prints "Ba"
367 \& print ++($foo = "zz"); # prints "aaa"
368 .Ve
369 .PP
370 \&\f(CW\*(C`undef\*(C'\fR is always treated as numeric, and in particular is changed
371 to \f(CW0\fR before incrementing (so that a post\-increment of an undef value
372 will return \f(CW0\fR rather than \f(CW\*(C`undef\*(C'\fR).
373 .PP
374 The auto\-decrement operator is not magical.
375 .SS Exponentiation
376 .IX Xref "** exponentiation power"
377 .IX Subsection "Exponentiation"
378 Binary \f(CW"**"\fR is the exponentiation operator. It binds even more
379 tightly than unary minus, so \f(CW\*(C`\-2**4\*(C'\fR is \f(CW\*(C`\-(2**4)\*(C'\fR, not \f(CW\*(C`(\-2)**4\*(C'\fR.
380 (This is
381 implemented using C\*(Aqs \f(CWpow(3)\fR function, which actually works on doubles
382 internally.)
383 .PP
384 Note that certain exponentiation expressions are ill\-defined:
385 these include \f(CW\*(C`0**0\*(C'\fR, \f(CW\*(C`1**Inf\*(C'\fR, and \f(CW\*(C`Inf**0\*(C'\fR. Do not expect
386 any particular results from these special cases, the results
387 are platform\-dependent.
388 .SS "Symbolic Unary Operators"
389 .IX Xref "unary operator operator, unary"
390 .IX Subsection "Symbolic Unary Operators"
391 Unary \f(CW"!"\fR performs logical negation, that is, "not". See also
392 \&\f(CW\*(C`not\*(C'\fR for a lower precedence version of this.
393 .IX Xref "!"
394 .PP
395 Unary \f(CW"\-"\fR performs arithmetic negation if the operand is numeric,
396 including any string that looks like a number. If the operand is
397 an identifier, a string consisting of a minus sign concatenated
398 with the identifier is returned. Otherwise, if the string starts
399 with a plus or minus, a string starting with the opposite sign is
400 returned. One effect of these rules is that \f(CW\*(C`\-bareword\*(C'\fR is equivalent
401 to the string \f(CW"\-bareword"\fR. If, however, the string begins with a
402 non\-alphabetic character (excluding \f(CW"+"\fR or \f(CW"\-"\fR), Perl will attempt
403 to convert
404 the string to a numeric, and the arithmetic negation is performed. If the
405 string cannot be cleanly converted to a numeric, Perl will give the warning
406 \&\fBArgument "the string" isn\*(Aqt numeric in negation (\-) at ...\fR.
407 .IX Xref "- negation, arithmetic"
408 .PP
409 Unary \f(CW"~"\fR performs bitwise negation, that is, 1\*(Aqs complement. For
410 example, \f(CW\*(C`0666\ &\ ~027\*(C'\fR is 0640. (See also "Integer Arithmetic" and
411 "Bitwise String Operators".) Note that the width of the result is
412 platform\-dependent: \f(CW\*(C`~0\*(C'\fR is 32 bits wide on a 32\-bit platform, but 64
413 bits wide on a 64\-bit platform, so if you are expecting a certain bit
414 width, remember to use the \f(CW"&"\fR operator to mask off the excess bits.
415 .IX Xref "~ negation, binary"
416 .PP
417 Starting in Perl 5.28, it is a fatal error to try to complement a string
418 containing a character with an ordinal value above 255.
419 .PP
420 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or \f(CW\*(C`use v5.28\*(C'\fR, then unary
421 \&\f(CW"~"\fR always treats its argument as a number, and an
422 alternate form of the operator, \f(CW"~."\fR, always treats its argument as a
423 string. So \f(CW\*(C`~0\*(C'\fR and \f(CW\*(C`~"0"\*(C'\fR will both give 2**32\-1 on 32\-bit platforms,
424 whereas \f(CW\*(C`~.0\*(C'\fR and \f(CW\*(C`~."0"\*(C'\fR will both yield \f(CW"\exff"\fR. Until Perl 5.28,
425 this feature produced a warning in the \f(CW"experimental::bitwise"\fR category.
426 .PP
427 Unary \f(CW"+"\fR has no effect whatsoever, even on strings. It is useful
428 syntactically for separating a function name from a parenthesized expression
429 that would otherwise be interpreted as the complete list of function
430 arguments. (See examples above under "Terms and List Operators (Leftward)".)
431 .IX Xref "+"
432 .PP
433 Unary \f(CW"\e"\fR creates references. If its operand is a single sigilled
434 thing, it creates a reference to that object. If its operand is a
435 parenthesised list, then it creates references to the things mentioned
436 in the list. Otherwise it puts its operand in list context, and creates
437 a list of references to the scalars in the list provided by the operand.
438 See perlreftut
439 and perlref. Do not confuse this behavior with the behavior of
440 backslash within a string, although both forms do convey the notion
441 of protecting the next thing from interpolation.
442 .IX Xref "\\ reference backslash"
443 .SS "Binding Operators"
444 .IX Xref "binding operator, binding =~ !~"
445 .IX Subsection "Binding Operators"
446 Binary \f(CW"=~"\fR binds a scalar expression to a pattern match. Certain operations
447 search or modify the string \f(CW$_\fR by default. This operator makes that kind
448 of operation work on some other string. The right argument is a search
449 pattern, substitution, or transliteration. The left argument is what is
450 supposed to be searched, substituted, or transliterated instead of the default
451 \&\f(CW$_\fR. When used in scalar context, the return value generally indicates the
452 success of the operation. The exceptions are substitution (\f(CW\*(C`s///\*(C'\fR)
453 and transliteration (\f(CW\*(C`y///\*(C'\fR) with the \f(CW\*(C`/r\*(C'\fR (non\-destructive) option,
454 which cause the \fBr\fReturn value to be the result of the substitution.
455 Behavior in list context depends on the particular operator.
456 See "Regexp Quote\-Like Operators" for details and perlretut for
457 examples using these operators.
458 .PP
459 If the right argument is an expression rather than a search pattern,
460 substitution, or transliteration, it is interpreted as a search pattern at run
461 time. Note that this means that its
462 contents will be interpolated twice, so
463 .PP
464 .Vb 1
465 \& \*(Aq\e\e\*(Aq =~ q\*(Aq\e\e\*(Aq;
466 .Ve
467 .PP
468 is not ok, as the regex engine will end up trying to compile the
469 pattern \f(CW\*(C`\e\*(C'\fR, which it will consider a syntax error.
470 .PP
471 Binary \f(CW"!~"\fR is just like \f(CW"=~"\fR except the return value is negated in
472 the logical sense.
473 .PP
474 Binary \f(CW"!~"\fR with a non\-destructive substitution (\f(CW\*(C`s///r\*(C'\fR) or transliteration
475 (\f(CW\*(C`y///r\*(C'\fR) is a syntax error.
476 .SS "Multiplicative Operators"
477 .IX Xref "operator, multiplicative"
478 .IX Subsection "Multiplicative Operators"
479 Binary \f(CW"*"\fR multiplies two numbers.
480 .IX Xref "*"
481 .PP
482 Binary \f(CW"/"\fR divides two numbers.
483 .IX Xref "slash"
484 .PP
485 Binary \f(CW"%"\fR is the modulo operator, which computes the division
486 remainder of its first argument with respect to its second argument.
487 Given integer
488 operands \f(CW$m\fR and \f(CW$n\fR: If \f(CW$n\fR is positive, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is
489 \&\f(CW$m\fR minus the largest multiple of \f(CW$n\fR less than or equal to
490 \&\f(CW$m\fR. If \f(CW$n\fR is negative, then \f(CW\*(C`$m\ %\ $n\*(C'\fR is \f(CW$m\fR minus the
491 smallest multiple of \f(CW$n\fR that is not less than \f(CW$m\fR (that is, the
492 result will be less than or equal to zero). If the operands
493 \&\f(CW$m\fR and \f(CW$n\fR are floating point values and the absolute value of
494 \&\f(CW$n\fR (that is \f(CWabs($n)\fR) is less than \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, only
495 the integer portion of \f(CW$m\fR and \f(CW$n\fR will be used in the operation
496 (Note: here \f(CW\*(C`UV_MAX\*(C'\fR means the maximum of the unsigned integer type).
497 If the absolute value of the right operand (\f(CWabs($n)\fR) is greater than
498 or equal to \f(CW\*(C`(UV_MAX\ +\ 1)\*(C'\fR, \f(CW"%"\fR computes the floating\-point remainder
499 \&\f(CW$r\fR in the equation \f(CW\*(C`($r\ =\ $m\ \-\ $i*$n)\*(C'\fR where \f(CW$i\fR is a certain
500 integer that makes \f(CW$r\fR have the same sign as the right operand
501 \&\f(CW$n\fR (\fBnot\fR as the left operand \f(CW$m\fR like C function \f(CWfmod()\fR)
502 and the absolute value less than that of \f(CW$n\fR.
503 Note that when \f(CW\*(C`use\ integer\*(C'\fR is in scope, \f(CW"%"\fR gives you direct access
504 to the modulo operator as implemented by your C compiler. This
505 operator is not as well defined for negative operands, but it will
506 execute faster.
507 .IX Xref "% remainder modulo mod"
508 .PP
509 Binary \f(CW\*(C`x\*(C'\fR is the repetition operator. In scalar context, or if the
510 left operand is neither enclosed in parentheses nor a \f(CW\*(C`qw//\*(C'\fR list,
511 it performs a string repetition. In that case it supplies scalar
512 context to the left operand, and returns a string consisting of the
513 left operand string repeated the number of times specified by the right
514 operand. If the \f(CW\*(C`x\*(C'\fR is in list context, and the left operand is either
515 enclosed in parentheses or a \f(CW\*(C`qw//\*(C'\fR list, it performs a list repetition.
516 In that case it supplies list context to the left operand, and returns
517 a list consisting of the left operand list repeated the number of times
518 specified by the right operand.
519 If the right operand is zero or negative (raising a warning on
520 negative), it returns an empty string
521 or an empty list, depending on the context.
522 .IX Xref "x"
523 .PP
524 .Vb 1
525 \& print \*(Aq\-\*(Aq x 80; # print row of dashes
526 \&
527 \& print "\et" x ($tab/8), \*(Aq \*(Aq x ($tab%8); # tab over
528 \&
529 \& @ones = (1) x 80; # a list of 80 1\*(Aqs
530 \& @ones = (5) x @ones; # set all elements to 5
531 .Ve
532 .SS "Additive Operators"
533 .IX Xref "operator, additive"
534 .IX Subsection "Additive Operators"
535 Binary \f(CW"+"\fR returns the sum of two numbers.
536 .IX Xref "+"
537 .PP
538 Binary \f(CW"\-"\fR returns the difference of two numbers.
539 .IX Xref "-"
540 .PP
541 Binary \f(CW"."\fR concatenates two strings.
542 .IX Xref "string, concatenation concatenation cat concat concatenate ."
543 .SS "Shift Operators"
544 .IX Xref "shift operator operator, shift << >> right shift left shift bitwise shift shl shr shift, right shift, left"
545 .IX Subsection "Shift Operators"
546 Binary \f(CW"<<"\fR returns the value of its left argument shifted left by the
547 number of bits specified by the right argument. Arguments should be
548 integers. (See also "Integer Arithmetic".)
549 .PP
550 Binary \f(CW">>"\fR returns the value of its left argument shifted right by
551 the number of bits specified by the right argument. Arguments should
552 be integers. (See also "Integer Arithmetic".)
553 .PP
554 If \f(CW\*(C`use\ integer\*(C'\fR (see "Integer Arithmetic") is in force then
555 signed C integers are used (\fIarithmetic shift\fR), otherwise unsigned C
556 integers are used (\fIlogical shift\fR), even for negative shiftees.
557 In arithmetic right shift the sign bit is replicated on the left,
558 in logical shift zero bits come in from the left.
559 .PP
560 Either way, the implementation isn\*(Aqt going to generate results larger
561 than the size of the integer type Perl was built with (32 bits or 64 bits).
562 .PP
563 Shifting by a negative number of bits means the reverse shift: left
564 shift becomes right shift, right shift becomes left shift. This is
565 unlike in C, where negative shift is undefined.
566 .PP
567 Shifting by a value greater than or equal to integer size (in bits)
568 results in zero (all bits fall off), except that under \f(CW\*(C`use\ integer\*(C'\fR
569 right shifting a negative value by such an amount results in \-1.
570 This is unlike in C, where shifting by too many bits is undefined.
571 .PP
572 If you get tired of being subject to your platform\*(Aqs native integers,
573 the \f(CW\*(C`use\ bigint\*(C'\fR pragma neatly sidesteps the issue altogether:
574 .PP
575 .Vb 5
576 \& print 20 << 20; # 20971520
577 \& print 20 << 32; # 0 with 32\-bit integer,
578 \& # 85899345920 with 64\-bit integer
579 \& use bigint;
580 \& print 20 << 100; # 25353012004564588029934064107520
581 .Ve
582 .SS "Named Unary Operators"
583 .IX Xref "operator, named unary"
584 .IX Subsection "Named Unary Operators"
585 The various named unary operators are treated as functions with one
586 argument, with optional parentheses.
587 .PP
588 If any list operator (\f(CWprint()\fR, etc.) or any unary operator (\f(CWchdir()\fR, etc.)
589 is followed by a left parenthesis as the next token, the operator and
590 arguments within parentheses are taken to be of highest precedence,
591 just like a normal function call. For example,
592 because named unary operators are higher precedence than \f(CW\*(C`||\*(C'\fR:
593 .PP
594 .Vb 4
595 \& chdir $foo || die; # (chdir $foo) || die
596 \& chdir($foo) || die; # (chdir $foo) || die
597 \& chdir ($foo) || die; # (chdir $foo) || die
598 \& chdir +($foo) || die; # (chdir $foo) || die
599 .Ve
600 .PP
601 but, because \f(CW"*"\fR is higher precedence than named operators:
602 .PP
603 .Vb 4
604 \& chdir $foo * 20; # chdir ($foo * 20)
605 \& chdir($foo) * 20; # (chdir $foo) * 20
606 \& chdir ($foo) * 20; # (chdir $foo) * 20
607 \& chdir +($foo) * 20; # chdir ($foo * 20)
608 \&
609 \& rand 10 * 20; # rand (10 * 20)
610 \& rand(10) * 20; # (rand 10) * 20
611 \& rand (10) * 20; # (rand 10) * 20
612 \& rand +(10) * 20; # rand (10 * 20)
613 .Ve
614 .PP
615 Regarding precedence, the filetest operators, like \f(CW\*(C`\-f\*(C'\fR, \f(CW\*(C`\-M\*(C'\fR, etc. are
616 treated like named unary operators, but they don\*(Aqt follow this functional
617 parenthesis rule. That means, for example, that \f(CW\*(C`\-f($file).".bak"\*(C'\fR is
618 equivalent to \f(CW\*(C`\-f\ "$file.bak"\*(C'\fR.
619 .IX Xref "-X filetest operator, filetest"
620 .PP
621 See also "Terms and List Operators (Leftward)".
622 .SS "Class Instance Operator"
623 .IX Xref "isa operator"
624 .IX Subsection "Class Instance Operator"
625 Binary \f(CW\*(C`isa\*(C'\fR evaluates to true when the left argument is an object instance of
626 the class (or a subclass derived from that class) given by the right argument.
627 If the left argument is not defined, not a blessed object instance, and does
628 not derive from the class given by the right argument, the operator evaluates
629 as false. The right argument may give the class either as a bareword or a
630 scalar expression that yields a string class name:
631 .PP
632 .Vb 1
633 \& if ( $obj isa Some::Class ) { ... }
634 \&
635 \& if ( $obj isa "Different::Class" ) { ... }
636 \& if ( $obj isa $name_of_class ) { ... }
637 .Ve
638 .PP
639 This feature is available from Perl 5.31.6 onwards when enabled by
640 \&\f(CW\*(C`use feature \*(Aqisa\*(Aq\*(C'\fR. This feature is enabled automatically by a
641 \&\f(CW\*(C`use v5.36\*(C'\fR (or higher) declaration in the current scope.
642 .SS "Relational Operators"
643 .IX Xref "relational operator operator, relational"
644 .IX Subsection "Relational Operators"
645 Perl operators that return true or false generally return values
646 that can be safely used as numbers. For example, the relational
647 operators in this section and the equality operators in the next
648 one return \f(CW1\fR for true and a special version of the defined empty
649 string, \f(CW""\fR, which counts as a zero but is exempt from warnings
650 about improper numeric conversions, just as \f(CW"0\ but\ true"\fR is.
651 .PP
652 Binary \f(CW"<"\fR returns true if the left argument is numerically less than
653 the right argument.
654 .IX Xref "<"
655 .PP
656 Binary \f(CW">"\fR returns true if the left argument is numerically greater
657 than the right argument.
658 .IX Xref ">"
659 .PP
660 Binary \f(CW"<="\fR returns true if the left argument is numerically less than
661 or equal to the right argument.
662 .IX Xref "<="
663 .PP
664 Binary \f(CW">="\fR returns true if the left argument is numerically greater
665 than or equal to the right argument.
666 .IX Xref ">="
667 .PP
668 Binary \f(CW"lt"\fR returns true if the left argument is stringwise less than
669 the right argument.
670 .IX Xref "lt"
671 .PP
672 Binary \f(CW"gt"\fR returns true if the left argument is stringwise greater
673 than the right argument.
674 .IX Xref "gt"
675 .PP
676 Binary \f(CW"le"\fR returns true if the left argument is stringwise less than
677 or equal to the right argument.
678 .IX Xref "le"
679 .PP
680 Binary \f(CW"ge"\fR returns true if the left argument is stringwise greater
681 than or equal to the right argument.
682 .IX Xref "ge"
683 .PP
684 A sequence of relational operators, such as \f(CW"$x\ <\ $y\ <=\ $z"\fR, performs chained comparisons, in the manner described above in
685 the section "Operator Precedence and Associativity".
686 Beware that they do not chain with equality operators, which have lower
687 precedence.
688 .PP
689 \&\f(CW"lt"\fR, \f(CW"le"\fR, \f(CW"ge"\fR, \f(CW"gt"\fR, and \f(CW"cmp"\fR (this last is described
690 in the next section) use the collation (sort)
691 order specified by the current \f(CW\*(C`LC_COLLATE\*(C'\fR locale if a \f(CW\*(C`use\ locale\*(C'\fR form that includes collation is in effect. See perllocale.
692 Depending on the capabilities of the platform, these can give reasonable
693 results with Unicode, but the standard \f(CW\*(C`Unicode::Collate\*(C'\fR and
694 \&\f(CW\*(C`Unicode::Collate::Locale\*(C'\fR modules offer much more powerful
695 solutions to collation issues.
696 .PP
697 For case\-insensitive comparisons, look at the "fc" in perlfunc case\-folding
698 function, available in Perl v5.16 or later:
699 .PP
700 .Vb 1
701 \& if ( fc($x) eq fc($y) ) { ... }
702 .Ve
703 .SS "Equality Operators"
704 .IX Xref "equality equal equals operator, equality"
705 .IX Subsection "Equality Operators"
706 Binary \f(CW"=="\fR returns true if the left argument is numerically equal to
707 the right argument.
708 .IX Xref "=="
709 .PP
710 Binary \f(CW"!="\fR returns true if the left argument is numerically not equal
711 to the right argument.
712 .IX Xref "!="
713 .PP
714 Binary \f(CW"eq"\fR returns true if the left argument is stringwise equal to
715 the right argument.
716 .IX Xref "eq"
717 .PP
718 Binary \f(CW"ne"\fR returns true if the left argument is stringwise not equal
719 to the right argument.
720 .IX Xref "ne"
721 .PP
722 A sequence of the above equality operators, such as \f(CW"$x\ ==\ $y\ ==\ $z"\fR, performs chained comparisons, in the manner described above in
723 the section "Operator Precedence and Associativity".
724 Beware that they do not chain with relational operators, which have
725 higher precedence.
726 .PP
727 Binary \f(CW"<=>"\fR returns \-1, 0, or 1 depending on whether the left
728 argument is numerically less than, equal to, or greater than the right
729 argument. If your platform supports \f(CW\*(C`NaN\*(C'\fR\*(Aqs (not\-a\-numbers) as numeric
730 values, using them with \f(CW"<=>"\fR returns undef. \f(CW\*(C`NaN\*(C'\fR is not
731 \&\f(CW"<"\fR, \f(CW"=="\fR, \f(CW">"\fR, \f(CW"<="\fR or \f(CW">="\fR anything
732 (even \f(CW\*(C`NaN\*(C'\fR), so those 5 return false. \f(CW\*(C`NaN\ !=\ NaN\*(C'\fR returns
733 true, as does \f(CW\*(C`NaN\ !=\*(C'\fR\ \fIanything\ else\fR. If your platform doesn\*(Aqt
734 support \f(CW\*(C`NaN\*(C'\fR\*(Aqs then \f(CW\*(C`NaN\*(C'\fR is just a string with numeric value 0.
735 .IX Xref "<=> spaceship"
736 .PP
737 .Vb 2
738 \& $ perl \-le \*(Aq$x = "NaN"; print "No NaN support here" if $x == $x\*(Aq
739 \& $ perl \-le \*(Aq$x = "NaN"; print "NaN support here" if $x != $x\*(Aq
740 .Ve
741 .PP
742 (Note that the bigint, bigrat, and bignum pragmas all
743 support \f(CW"NaN"\fR.)
744 .PP
745 Binary \f(CW"cmp"\fR returns \-1, 0, or 1 depending on whether the left
746 argument is stringwise less than, equal to, or greater than the right
747 argument.
748 .PP
749 Here we can see the difference between \f(CW\*(C`<=>\*(C'\fR and \f(CW\*(C`cmp\*(C'\fR,
750 .PP
751 .Vb 2
752 \& print 10 <=> 2 #prints 1
753 \& print 10 cmp 2 #prints \-1
754 .Ve
755 .PP
756
757 (likewise between the relational operators that were described in the
758 previous section: \f(CW\*(C`gt\*(C'\fR and \f(CW\*(C`>\*(C'\fR, \f(CW\*(C`lt\*(C'\fR and
759 \&\f(CW\*(C`<\*(C'\fR, \fIetc\fR.)
760 .IX Xref "cmp"
761 .PP
762 Binary \f(CW"~~"\fR does a smartmatch between its arguments. Smart matching
763 is complicated enough to warrant
764 two subsections, starting just below.
765 .IX Xref "~~"
766 .PP
767 The two\-sided ordering operators \f(CW"<=>"\fR and \f(CW"cmp"\fR, and the
768 smartmatch operator \f(CW"~~"\fR, are non\-associative with respect to each
769 other and with respect to the equality operators of the same precedence.
770 .PP
771 \fISmartmatch Operator\fR
772 .IX Subsection "Smartmatch Operator"
773 .PP
774 The \f(CW\*(C`smartmatch\*(C'\fR feature is discouraged for new code and retained for
775 backward compatibility.
776 .PP
777 The smartmatch operator was introduced in 5.10.0 had significant
778 changes in 5.10.1. It is enabled by default and in all feature
779 bundles up to 5.40. To use smartmatch with a later feature bundle you
780 will need enable it explicitly:
781 .PP
782 .Vb 2
783 \& use v5.42;
784 \& use feature "smartmatch";
785 .Ve
786 .PP
787 Binary \f(CW\*(C`~~\*(C'\fR does a "smartmatch" between its arguments. This is mostly
788 used implicitly in the \f(CW\*(C`when\*(C'\fR construct described in perlsyn, although
789 not all \f(CW\*(C`when\*(C'\fR clauses call the smartmatch operator. Unique among all of
790 Perl\*(Aqs operators, the smartmatch operator can recurse.
791 .PP
792 It is also unique in that all other Perl operators impose a context
793 (usually string or numeric context) on their operands, autoconverting
794 those operands to those imposed contexts. In contrast, smartmatch
795 \&\fIinfers\fR contexts from the actual types of its operands and uses that
796 type information to select a suitable comparison mechanism.
797 .PP
798 The \f(CW\*(C`~~\*(C'\fR operator compares its operands "polymorphically", determining how
799 to compare them according to their actual types (numeric, string, array,
800 hash, etc.). Like the equality operators with which it shares the same
801 precedence, \f(CW\*(C`~~\*(C'\fR returns 1 for true and \f(CW""\fR for false. It is often best
802 read aloud as "in", "inside of", or "is contained in", because the left
803 operand is often looked for \fIinside\fR the right operand. That makes the
804 order of the operands to the smartmatch operand often opposite that of
805 the regular match operator. In other words, the "smaller" thing is usually
806 placed in the left operand and the larger one in the right.
807 .PP
808 The behavior of a smartmatch depends on what type of things its arguments
809 are, as determined by the following table. The first row of the table
810 whose types apply determines the smartmatch behavior. Because what
811 actually happens is mostly determined by the type of the second operand,
812 the table is sorted on the right operand instead of on the left.
813 .PP
814 .Vb 4
815 \& Left Right Description and pseudocode
816 \& ===============================================================
817 \& Any undef check whether Any is undefined
818 \& like: !defined Any
819 \&
820 \& Any Object invoke ~~ overloading on Object, or die
821 \&
822 \& Right operand is an ARRAY:
823 \&
824 \& Left Right Description and pseudocode
825 \& ===============================================================
826 \& ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
827 \& like: (ARRAY1[0] ~~ ARRAY2[0])
828 \& && (ARRAY1[1] ~~ ARRAY2[1]) && ...
829 \& HASH ARRAY any ARRAY elements exist as HASH keys
830 \& like: grep { exists HASH\->{$_} } ARRAY
831 \& Regexp ARRAY any ARRAY elements pattern match Regexp
832 \& like: grep { /Regexp/ } ARRAY
833 \& undef ARRAY undef in ARRAY
834 \& like: grep { !defined } ARRAY
835 \& Any ARRAY smartmatch each ARRAY element[3]
836 \& like: grep { Any ~~ $_ } ARRAY
837 \&
838 \& Right operand is a HASH:
839 \&
840 \& Left Right Description and pseudocode
841 \& ===============================================================
842 \& HASH1 HASH2 all same keys in both HASHes
843 \& like: keys HASH1 ==
844 \& grep { exists HASH2\->{$_} } keys HASH1
845 \& ARRAY HASH any ARRAY elements exist as HASH keys
846 \& like: grep { exists HASH\->{$_} } ARRAY
847 \& Regexp HASH any HASH keys pattern match Regexp
848 \& like: grep { /Regexp/ } keys HASH
849 \& undef HASH always false (undef cannot be a key)
850 \& like: 0 == 1
851 \& Any HASH HASH key existence
852 \& like: exists HASH\->{Any}
853 \&
854 \& Right operand is CODE:
855 \&
856 \& Left Right Description and pseudocode
857 \& ===============================================================
858 \& ARRAY CODE sub returns true on all ARRAY elements[1]
859 \& like: !grep { !CODE\->($_) } ARRAY
860 \& HASH CODE sub returns true on all HASH keys[1]
861 \& like: !grep { !CODE\->($_) } keys HASH
862 \& Any CODE sub passed Any returns true
863 \& like: CODE\->(Any)
864 \&
865 \& Right operand is a Regexp:
866 \&
867 \& Left Right Description and pseudocode
868 \& ===============================================================
869 \& ARRAY Regexp any ARRAY elements match Regexp
870 \& like: grep { /Regexp/ } ARRAY
871 \& HASH Regexp any HASH keys match Regexp
872 \& like: grep { /Regexp/ } keys HASH
873 \& Any Regexp pattern match
874 \& like: Any =~ /Regexp/
875 \&
876 \& Other:
877 \&
878 \& Left Right Description and pseudocode
879 \& ===============================================================
880 \& Object Any invoke ~~ overloading on Object,
881 \& or fall back to...
882 \&
883 \& Any Num numeric equality
884 \& like: Any == Num
885 \& Num nummy[4] numeric equality
886 \& like: Num == nummy
887 \& undef Any check whether undefined
888 \& like: !defined(Any)
889 \& Any Any string equality
890 \& like: Any eq Any
891 .Ve
892 .PP
893 Notes:
894 .IP "1. Empty hashes or arrays match." 4
895 .IX Item "1. Empty hashes or arrays match."
896 .PD 0
897 .IP "2. That is, each element smartmatches the element of the same index in the other array.[3]" 4
898 .IX Item "2. That is, each element smartmatches the element of the same index in the other array.[3]"
899 .IP "3. If a circular reference is found, fall back to referential equality." 4
900 .IX Item "3. If a circular reference is found, fall back to referential equality."
901 .IP "4. Either an actual number, or a string that looks like one." 4
902 .IX Item "4. Either an actual number, or a string that looks like one."
903 .PD
904 .PP
905 The smartmatch implicitly dereferences any non\-blessed hash or array
906 reference, so the \f(CW\*(C`\fR\f(CIHASH\fR\f(CW\*(C'\fR and \f(CW\*(C`\fR\f(CIARRAY\fR\f(CW\*(C'\fR entries apply in those cases.
907 For blessed references, the \f(CW\*(C`\fR\f(CIObject\fR\f(CW\*(C'\fR entries apply. Smartmatches
908 involving hashes only consider hash keys, never hash values.
909 .PP
910 The "like" code entry is not always an exact rendition. For example, the
911 smartmatch operator short\-circuits whenever possible, but \f(CW\*(C`grep\*(C'\fR does
912 not. Also, \f(CW\*(C`grep\*(C'\fR in scalar context returns the number of matches, but
913 \&\f(CW\*(C`~~\*(C'\fR returns only true or false.
914 .PP
915 Unlike most operators, the smartmatch operator knows to treat \f(CW\*(C`undef\*(C'\fR
916 specially:
917 .PP
918 .Vb 3
919 \& use v5.10.1;
920 \& @array = (1, 2, 3, undef, 4, 5);
921 \& say "some elements undefined" if undef ~~ @array;
922 .Ve
923 .PP
924 Each operand is considered in a modified scalar context, the modification
925 being that array and hash variables are passed by reference to the
926 operator, which implicitly dereferences them. Both elements
927 of each pair are the same:
928 .PP
929 .Vb 1
930 \& use v5.10.1;
931 \&
932 \& my %hash = (red => 1, blue => 2, green => 3,
933 \& orange => 4, yellow => 5, purple => 6,
934 \& black => 7, grey => 8, white => 9);
935 \&
936 \& my @array = qw(red blue green);
937 \&
938 \& say "some array elements in hash keys" if @array ~~ %hash;
939 \& say "some array elements in hash keys" if \e@array ~~ \e%hash;
940 \&
941 \& say "red in array" if "red" ~~ @array;
942 \& say "red in array" if "red" ~~ \e@array;
943 \&
944 \& say "some keys end in e" if /e$/ ~~ %hash;
945 \& say "some keys end in e" if /e$/ ~~ \e%hash;
946 .Ve
947 .PP
948 Two arrays smartmatch if each element in the first array smartmatches
949 (that is, is "in") the corresponding element in the second array,
950 recursively.
951 .PP
952 .Vb 6
953 \& use v5.10.1;
954 \& my @little = qw(red blue green);
955 \& my @bigger = ("red", "blue", [ "orange", "green" ] );
956 \& if (@little ~~ @bigger) { # true!
957 \& say "little is contained in bigger";
958 \& }
959 .Ve
960 .PP
961 Because the smartmatch operator recurses on nested arrays, this
962 will still report that "red" is in the array.
963 .PP
964 .Vb 4
965 \& use v5.10.1;
966 \& my @array = qw(red blue green);
967 \& my $nested_array = [[[[[[[ @array ]]]]]]];
968 \& say "red in array" if "red" ~~ $nested_array;
969 .Ve
970 .PP
971 If two arrays smartmatch each other, then they are deep
972 copies of each others\*(Aq values, as this example reports:
973 .PP
974 .Vb 3
975 \& use v5.12.0;
976 \& my @a = (0, 1, 2, [3, [4, 5], 6], 7);
977 \& my @b = (0, 1, 2, [3, [4, 5], 6], 7);
978 \&
979 \& if (@a ~~ @b && @b ~~ @a) {
980 \& say "a and b are deep copies of each other";
981 \& }
982 \& elsif (@a ~~ @b) {
983 \& say "a smartmatches in b";
984 \& }
985 \& elsif (@b ~~ @a) {
986 \& say "b smartmatches in a";
987 \& }
988 \& else {
989 \& say "a and b don\*(Aqt smartmatch each other at all";
990 \& }
991 .Ve
992 .PP
993 If you were to set \f(CW\*(C`$b[3]\ =\ 4\*(C'\fR, then instead of reporting that "a and b
994 are deep copies of each other", it now reports that \f(CW"b smartmatches in a"\fR.
995 That\*(Aqs because the corresponding position in \f(CW@a\fR contains an array that
996 (eventually) has a 4 in it.
997 .PP
998 Smartmatching one hash against another reports whether both contain the
999 same keys, no more and no less. This could be used to see whether two
1000 records have the same field names, without caring what values those fields
1001 might have. For example:
1002 .PP
1003 .Vb 3
1004 \& use v5.10.1;
1005 \& sub make_dogtag {
1006 \& state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
1007 \&
1008 \& my ($class, $init_fields) = @_;
1009 \&
1010 \& die "Must supply (only) name, rank, and serial number"
1011 \& unless $init_fields ~~ $REQUIRED_FIELDS;
1012 \&
1013 \& ...
1014 \& }
1015 .Ve
1016 .PP
1017 However, this only does what you mean if \f(CW$init_fields\fR is indeed a hash
1018 reference. The condition \f(CW\*(C`$init_fields ~~ $REQUIRED_FIELDS\*(C'\fR also allows the
1019 strings \f(CW"name"\fR, \f(CW"rank"\fR, \f(CW"serial_num"\fR as well as any array reference
1020 that contains \f(CW"name"\fR or \f(CW"rank"\fR or \f(CW"serial_num"\fR anywhere to pass
1021 through.
1022 .PP
1023 The smartmatch operator is most often used as the implicit operator of a
1024 \&\f(CW\*(C`when\*(C'\fR clause. See the section on "Switch Statements" in perlsyn.
1025 .PP
1026 \fISmartmatching of Objects\fR
1027 .IX Subsection "Smartmatching of Objects"
1028 .PP
1029 To avoid relying on an object\*(Aqs underlying representation, if the
1030 smartmatch\*(Aqs right operand is an object that doesn\*(Aqt overload \f(CW\*(C`~~\*(C'\fR,
1031 it raises the exception "\f(CW\*(C`Smartmatching a non\-overloaded object
1032 breaks encapsulation\*(C'\fR". That\*(Aqs because one has no business digging
1033 around to see whether something is "in" an object. These are all
1034 illegal on objects without a \f(CW\*(C`~~\*(C'\fR overload:
1035 .PP
1036 .Vb 3
1037 \& %hash ~~ $object
1038 \& 42 ~~ $object
1039 \& "fred" ~~ $object
1040 .Ve
1041 .PP
1042 However, you can change the way an object is smartmatched by overloading
1043 the \f(CW\*(C`~~\*(C'\fR operator. This is allowed to
1044 extend the usual smartmatch semantics.
1045 For objects that do have an \f(CW\*(C`~~\*(C'\fR overload, see overload.
1046 .PP
1047 Using an object as the left operand is allowed, although not very useful.
1048 Smartmatching rules take precedence over overloading, so even if the
1049 object in the left operand has smartmatch overloading, this will be
1050 ignored. A left operand that is a non\-overloaded object falls back on a
1051 string or numeric comparison of whatever the \f(CW\*(C`ref\*(C'\fR operator returns. That
1052 means that
1053 .PP
1054 .Vb 1
1055 \& $object ~~ X
1056 .Ve
1057 .PP
1058 does \fInot\fR invoke the overload method with \f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR as an argument.
1059 Instead the above table is consulted as normal, and based on the type of
1060 \&\f(CW\*(C`\fR\f(CIX\fR\f(CW\*(C'\fR, overloading may or may not be invoked. For simple strings or
1061 numbers, "in" becomes equivalent to this:
1062 .PP
1063 .Vb 2
1064 \& $object ~~ $number ref($object) == $number
1065 \& $object ~~ $string ref($object) eq $string
1066 .Ve
1067 .PP
1068 For example, this reports that the handle smells IOish
1069 (but please don\*(Aqt really do this!):
1070 .PP
1071 .Vb 5
1072 \& use IO::Handle;
1073 \& my $fh = IO::Handle\->new();
1074 \& if ($fh ~~ /\ebIO\eb/) {
1075 \& say "handle smells IOish";
1076 \& }
1077 .Ve
1078 .PP
1079 That\*(Aqs because it treats \f(CW$fh\fR as a string like
1080 \&\f(CW"IO::Handle=GLOB(0x8039e0)"\fR, then pattern matches against that.
1081 .SS "Bitwise And"
1082 .IX Xref "operator, bitwise, and bitwise and &"
1083 .IX Subsection "Bitwise And"
1084 Binary \f(CW"&"\fR returns its operands ANDed together bit by bit. Although no
1085 warning is currently raised, the result is not well defined when this operation
1086 is performed on operands that aren\*(Aqt either numbers (see
1087 "Integer Arithmetic") nor bitstrings (see "Bitwise String Operators").
1088 .PP
1089 Note that \f(CW"&"\fR has lower priority than relational operators, so for example
1090 the parentheses are essential in a test like
1091 .PP
1092 .Vb 1
1093 \& print "Even\en" if ($x & 1) == 0;
1094 .Ve
1095 .PP
1096 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
1097 \&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
1098 Before Perl 5.28 this feature produced a warning in the
1099 \&\f(CW"experimental::bitwise"\fR category.
1100 .SS "Bitwise Or and Exclusive Or"
1101 .IX Xref "operator, bitwise, or bitwise or | operator, bitwise, xor bitwise xor ^"
1102 .IX Subsection "Bitwise Or and Exclusive Or"
1103 Binary \f(CW"|"\fR returns its operands ORed together bit by bit. If both
1104 corresponding bits are 0, the resulting bit is 0; if either is 1, the result is
1105 1.
1106 .PP
1107 Binary \f(CW"^"\fR returns its operands XORed together bit by bit. If both
1108 corresponding bits are 0 or both are 1, the resulting bit is 0; if just
1109 one is 1, the result is 1.
1110 .PP
1111 Although no warning is currently raised, the results are not well
1112 defined when these operations are performed on operands that aren\*(Aqt either
1113 numbers (see "Integer Arithmetic") nor bitstrings (see "Bitwise String
1114 Operators").
1115 .PP
1116 Note that \f(CW"|"\fR and \f(CW"^"\fR have lower priority than relational operators, so
1117 for example the parentheses are essential in a test like
1118 .PP
1119 .Vb 1
1120 \& print "false\en" if (8 | 2) != 10;
1121 .Ve
1122 .PP
1123 If the "bitwise" feature is enabled via \f(CW\*(C`use\ feature\ \*(Aqbitwise\*(Aq\*(C'\fR or
1124 \&\f(CW\*(C`use v5.28\*(C'\fR, then this operator always treats its operands as numbers.
1125 Before Perl 5.28. this feature produced a warning in the
1126 \&\f(CW"experimental::bitwise"\fR category.
1127 .SS "C\-style Logical And"
1128 .IX Xref "&& logical and operator, logical, and"
1129 .IX Subsection "C-style Logical And"
1130 Binary \f(CW"&&"\fR performs a short\-circuit logical AND operation. That is,
1131 if the left operand is false, the right operand is not even evaluated.
1132 Scalar or list context propagates down to the right operand if it
1133 is evaluated.
1134 .PP
1135 \&\f(CW\*(C`&&\*(C'\fR returns the last value evaluated (unlike C\*(Aqs \f(CW\*(C`&&\*(C'\fR, which returns
1136 0 or 1).
1137 .PP
1138 As an alternative to \f(CW\*(C`&&\*(C'\fR when used for control flow, Perl provides the
1139 \&\f(CW\*(C`and\*(C'\fR operator (see below).
1140 The short\-circuit behavior is identical. The precedence of \f(CW"and"\fR is
1141 much lower, however, so that you can safely use it after a list operator
1142 without the need for parentheses.
1143 .SS "C\-style Logical Or, Xor, and Defined Or"
1144 .IX Xref "|| operator, logical, or ^^ operator, logical, xor operator, logical, defined-or"
1145 .IX Subsection "C-style Logical Or, Xor, and Defined Or"
1146 Binary \f(CW"||"\fR performs a short\-circuit logical OR operation. That is,
1147 if the left operand is true, the right operand is not even evaluated.
1148 Scalar or list context propagates down to the right operand if it
1149 does get evaluated.
1150 .PP
1151 As an alternative to \f(CW\*(C`||\*(C'\fR when used for control flow, Perl provides the
1152 \&\f(CW\*(C`or\*(C'\fR operator (see below).
1153 The short\-circuit behavior is identical. The precedence of \f(CW"or"\fR is
1154 much lower, however, so that you can safely use it after a list operator
1155 without the need for parentheses:
1156 .PP
1157 .Vb 2
1158 \& unlink "alpha", "beta", "gamma"
1159 \& or gripe(), next LINE;
1160 .Ve
1161 .PP
1162 With the C\-style operator that would have been written like this:
1163 .PP
1164 .Vb 2
1165 \& unlink("alpha", "beta", "gamma")
1166 \& || (gripe(), next LINE);
1167 .Ve
1168 .PP
1169 It would be even more readable to write that this way:
1170 .PP
1171 .Vb 4
1172 \& unless(unlink("alpha", "beta", "gamma")) {
1173 \& gripe();
1174 \& next LINE;
1175 \& }
1176 .Ve
1177 .PP
1178 Using \f(CW"or"\fR for assignment is unlikely to do what you want; see below.
1179 .PP
1180 Binary \f(CW"^^"\fR performs a logical XOR operation. Both operands are
1181 evaluated and the result is true only if exactly one of the operands is true.
1182 Scalar or list context propagates down to the right operand.
1183 .PP
1184 Although it has no direct equivalent in C, Perl\*(Aqs \f(CW\*(C`//\*(C'\fR operator is related
1185 to its C\-style "or". In fact, it\*(Aqs exactly the same as \f(CW\*(C`||\*(C'\fR, except that it
1186 tests the left hand side\*(Aqs definedness instead of its truth. Thus,
1187 \&\f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR returns the value of \f(CW\*(C`EXPR1\*(C'\fR if it\*(Aqs defined,
1188 otherwise, the value of \f(CW\*(C`EXPR2\*(C'\fR is returned.
1189 (\f(CW\*(C`EXPR1\*(C'\fR is evaluated in scalar context, \f(CW\*(C`EXPR2\*(C'\fR
1190 in the context of \f(CW\*(C`//\*(C'\fR itself). Usually,
1191 this is the same result as \f(CW\*(C`defined(EXPR1)\ ?\ EXPR1\ :\ EXPR2\*(C'\fR (except that
1192 the ternary\-operator form can be used as a lvalue, while \f(CW\*(C`EXPR1\ //\ EXPR2\*(C'\fR
1193 cannot). This is very useful for
1194 providing default values for variables. If you actually want to test if
1195 at least one of \f(CW$x\fR and \f(CW$y\fR is defined, use \f(CW\*(C`defined($x\ //\ $y)\*(C'\fR.
1196 .PP
1197 The \f(CW\*(C`||\*(C'\fR, \f(CW\*(C`^^\*(C'\fR and \f(CW\*(C`//\*(C'\fR operators return the last value evaluated
1198 (unlike C\*(Aqs \f(CW\*(C`||\*(C'\fR which returns 0 or 1). Thus, a reasonably
1199 portable way to find out the home directory might be:
1200 .PP
1201 .Vb 4
1202 \& $home = $ENV{HOME}
1203 \& // $ENV{LOGDIR}
1204 \& // (getpwuid($<))[7]
1205 \& // die "You\*(Aqre homeless!\en";
1206 .Ve
1207 .PP
1208 In particular, this means that you shouldn\*(Aqt use this
1209 for selecting between two aggregates for assignment:
1210 .PP
1211 .Vb 3
1212 \& @a = @b || @c; # This doesn\*(Aqt do the right thing
1213 \& @a = scalar(@b) || @c; # because it really means this.
1214 \& @a = @b ? @b : @c; # This works fine, though.
1215 .Ve
1216 .SS "Range Operators"
1217 .IX Xref "operator, range range .. ..."
1218 .IX Subsection "Range Operators"
1219 Binary \f(CW".."\fR is the range operator, which is really two different
1220 operators depending on the context. In list context, it returns a
1221 list of values counting (up by ones) from the left value to the right
1222 value. If the left value is greater than the right value then it
1223 returns the empty list. The range operator is useful for writing
1224 \&\f(CW\*(C`foreach\ (1..10)\*(C'\fR loops and for doing slice operations on arrays.
1225 No temporary array is created when the range operator is used as the
1226 expression in \f(CW\*(C`foreach\*(C'\fR loops.
1227 .PP
1228 The range operator also works on strings, using the magical
1229 auto\-increment, see below.
1230 .PP
1231 In scalar context, \f(CW".."\fR returns a boolean value. The operator is
1232 bistable, like a flip\-flop, and emulates the line\-range (comma)
1233 operator of \fBsed\fR, \fBawk\fR, and various editors. Each \f(CW".."\fR operator
1234 maintains its own boolean state, even across calls to a subroutine
1235 that contains it. It is false as long as its left operand is false.
1236 Once the left operand is true, the range operator stays true until the
1237 right operand is true, \fIAFTER\fR which the range operator becomes false
1238 again. It doesn\*(Aqt become false till the next time the range operator
1239 is evaluated. It can test the right operand and become false on the
1240 same evaluation it became true (as in \fBawk\fR), but it still returns
1241 true once. If you don\*(Aqt want it to test the right operand until the
1242 next evaluation, as in \fBsed\fR, just use three dots (\f(CW"..."\fR) instead of
1243 two. In all other regards, \f(CW"..."\fR behaves just like \f(CW".."\fR does.
1244 .PP
1245 The right operand is not evaluated while the operator is in the
1246 "false" state, and the left operand is not evaluated while the
1247 operator is in the "true" state. The precedence is a little lower
1248 than || and &&. The value returned is either the empty string for
1249 false, or a sequence number (beginning with 1) for true. The sequence
1250 number is reset for each range encountered. The final sequence number
1251 in a range has the string \f(CW"E0"\fR appended to it, which doesn\*(Aqt affect
1252 its numeric value, but gives you something to search for if you want
1253 to exclude the endpoint. You can exclude the beginning point by
1254 waiting for the sequence number to be greater than 1.
1255 .PP
1256 If either operand of scalar \f(CW".."\fR is a constant expression,
1257 that operand is considered true if it is equal (\f(CW\*(C`==\*(C'\fR) to the current
1258 input line number (the \f(CW$.\fR variable).
1259 .PP
1260 To be pedantic, the comparison is actually \f(CW\*(C`int(EXPR)\ ==\ int(EXPR)\*(C'\fR,
1261 but that is only an issue if you use a floating point expression; when
1262 implicitly using \f(CW$.\fR as described in the previous paragraph, the
1263 comparison is \f(CW\*(C`int(EXPR)\ ==\ int($.)\*(C'\fR which is only an issue when \f(CW$.\fR
1264 is set to a floating point value and you are not reading from a file.
1265 Furthermore, \f(CW"span"\ ..\ "spat"\fR or \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will not do what
1266 you want in scalar context because each of the operands are evaluated
1267 using their integer representation.
1268 .PP
1269 Examples:
1270 .PP
1271 As a scalar operator:
1272 .PP
1273 .Vb 2
1274 \& if (101 .. 200) { print; } # print 2nd hundred lines, short for
1275 \& # if ($. == 101 .. $. == 200) { print; }
1276 \&
1277 \& next LINE if 1 .. /^$/; # skip header lines, short for
1278 \& # next LINE if $. == 1 .. /^$/;
1279 \& # (typically in a loop labeled LINE)
1280 \&
1281 \& s/^/> / if /^$/ .. eof(); # quote body
1282 \&
1283 \& # parse mail messages
1284 \& while (<>) {
1285 \& $in_header = 1 .. /^$/;
1286 \& $in_body = /^$/ .. eof;
1287 \& if ($in_header) {
1288 \& # do something
1289 \& } else { # in body
1290 \& # do something else
1291 \& }
1292 \& } continue {
1293 \& close ARGV if eof; # reset $. each file
1294 \& }
1295 .Ve
1296 .PP
1297 Here\*(Aqs a simple example to illustrate the difference between
1298 the two range operators:
1299 .PP
1300 .Vb 4
1301 \& @lines = (" \- Foo",
1302 \& "01 \- Bar",
1303 \& "1 \- Baz",
1304 \& " \- Quux");
1305 \&
1306 \& foreach (@lines) {
1307 \& if (/0/ .. /1/) {
1308 \& print "$_\en";
1309 \& }
1310 \& }
1311 .Ve
1312 .PP
1313 This program will print only the line containing "Bar". If
1314 the range operator is changed to \f(CW\*(C`...\*(C'\fR, it will also print the
1315 "Baz" line.
1316 .PP
1317 And now some examples as a list operator:
1318 .PP
1319 .Vb 3
1320 \& for (101 .. 200) { print } # print $_ 100 times
1321 \& @foo = @foo[0 .. $#foo]; # an expensive no\-op
1322 \& @foo = @foo[$#foo\-4 .. $#foo]; # slice last 5 items
1323 .Ve
1324 .PP
1325 Because each operand is evaluated in integer form, \f(CW\*(C`2.18\ ..\ 3.14\*(C'\fR will
1326 return two elements in list context.
1327 .PP
1328 .Vb 1
1329 \& @list = (2.18 .. 3.14); # same as @list = (2 .. 3);
1330 .Ve
1331 .PP
1332 The range operator in list context can make use of the magical
1333 auto\-increment algorithm if both operands are strings, subject to the
1334 following rules:
1335 .IP \(bu 4
1336 With one exception (below), if both strings look like numbers to Perl,
1337 the magic increment will not be applied, and the strings will be treated
1338 as numbers (more specifically, integers) instead.
1339 .Sp
1340 For example, \f(CW"\-2".."2"\fR is the same as \f(CW\-2..2\fR, and
1341 \&\f(CW"2.18".."3.14"\fR produces \f(CW\*(C`2, 3\*(C'\fR.
1342 .IP \(bu 4
1343 The exception to the above rule is when the left\-hand string begins with
1344 \&\f(CW0\fR and is longer than one character, in this case the magic increment
1345 \&\fIwill\fR be applied, even though strings like \f(CW"01"\fR would normally look
1346 like a number to Perl.
1347 .Sp
1348 For example, \f(CW"01".."04"\fR produces \f(CW"01", "02", "03", "04"\fR, and
1349 \&\f(CW"00".."\-1"\fR produces \f(CW"00"\fR through \f(CW"99"\fR \- this may seem
1350 surprising, but see the following rules for why it works this way.
1351 To get dates with leading zeros, you can say:
1352 .Sp
1353 .Vb 2
1354 \& @z2 = ("01" .. "31");
1355 \& print $z2[$mday];
1356 .Ve
1357 .Sp
1358 If you want to force strings to be interpreted as numbers, you could say
1359 .Sp
1360 .Vb 1
1361 \& @numbers = ( 0+$first .. 0+$last );
1362 .Ve
1363 .Sp
1364 \&\fBNote:\fR In Perl versions 5.30 and below, \fIany\fR string on the left\-hand
1365 side beginning with \f(CW"0"\fR, including the string \f(CW"0"\fR itself, would
1366 cause the magic string increment behavior. This means that on these Perl
1367 versions, \f(CW"0".."\-1"\fR would produce \f(CW"0"\fR through \f(CW"99"\fR, which was
1368 inconsistent with \f(CW\*(C`0..\-1\*(C'\fR, which produces the empty list. This also means
1369 that \f(CW"0".."9"\fR now produces a list of integers instead of a list of
1370 strings.
1371 .IP \(bu 4
1372 If the initial value specified isn\*(Aqt part of a magical increment
1373 sequence (that is, a non\-empty string matching \f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR),
1374 only the initial value will be returned.
1375 .Sp
1376 For example, \f(CW"ax".."az"\fR produces \f(CW"ax", "ay", "az"\fR, but
1377 \&\f(CW"*x".."az"\fR produces only \f(CW"*x"\fR.
1378 .IP \(bu 4
1379 For other initial values that are strings that do follow the rules of the
1380 magical increment, the corresponding sequence will be returned.
1381 .Sp
1382 For example, you can say
1383 .Sp
1384 .Vb 1
1385 \& @alphabet = ("A" .. "Z");
1386 .Ve
1387 .Sp
1388 to get all normal letters of the English alphabet, or
1389 .Sp
1390 .Vb 1
1391 \& $hexdigit = (0 .. 9, "a" .. "f")[$num & 15];
1392 .Ve
1393 .Sp
1394 to get a hexadecimal digit.
1395 .IP \(bu 4
1396 If the final value specified is not in the sequence that the magical
1397 increment would produce, the sequence goes until the next value would
1398 be longer than the final value specified. If the length of the final
1399 string is shorter than the first, the empty list is returned.
1400 .Sp
1401 For example, \f(CW"a".."\-\-"\fR is the same as \f(CW"a".."zz"\fR, \f(CW"0".."xx"\fR
1402 produces \f(CW"0"\fR through \f(CW"99"\fR, and \f(CW"aaa".."\-\-"\fR returns the empty
1403 list.
1404 .PP
1405 As of Perl 5.26, the list\-context range operator on strings works as expected
1406 in the scope of \f(CW"use\ feature\ \*(Aqunicode_strings"\fR. In previous versions, and outside the scope of
1407 that feature, it exhibits "The "Unicode Bug"" in perlunicode: its behavior
1408 depends on the internal encoding of the range endpoint.
1409 .PP
1410 Because the magical increment only works on non\-empty strings matching
1411 \&\f(CW\*(C`/^[a\-zA\-Z]*[0\-9]*\ez/\*(C'\fR, the following will only return an alpha:
1412 .PP
1413 .Vb 2
1414 \& use charnames "greek";
1415 \& my @greek_small = ("\eN{alpha}" .. "\eN{omega}");
1416 .Ve
1417 .PP
1418 To get the 25 traditional lowercase Greek letters, including both sigmas,
1419 you could use this instead:
1420 .PP
1421 .Vb 5
1422 \& use charnames "greek";
1423 \& my @greek_small = map { chr } ( ord("\eN{alpha}")
1424 \& ..
1425 \& ord("\eN{omega}")
1426 \& );
1427 .Ve
1428 .PP
1429 However, because there are \fImany\fR other lowercase Greek characters than
1430 just those, to match lowercase Greek characters in a regular expression,
1431 you could use the pattern \f(CW\*(C`/(?:(?=\ep{Greek})\ep{Lower})+/\*(C'\fR (or the
1432 experimental feature \f(CW\*(C`/(?[\ \ep{Greek}\ &\ \ep{Lower}\ ])+/\*(C'\fR).
1433 .SS "Conditional Operator"
1434 .IX Xref "operator, conditional operator, ternary ternary ?:"
1435 .IX Subsection "Conditional Operator"
1436 Ternary \f(CW"?:"\fR is the conditional operator, just as in C. It works much
1437 like an if\-then\-else. If the argument before the \f(CW\*(C`?\*(C'\fR is true, the
1438 argument before the \f(CW\*(C`:\*(C'\fR is returned, otherwise the argument after the
1439 \&\f(CW\*(C`:\*(C'\fR is returned. For example:
1440 .PP
1441 .Vb 2
1442 \& printf "I have %d dog%s.\en", $n,
1443 \& ($n == 1) ? "" : "s";
1444 .Ve
1445 .PP
1446 Scalar or list context propagates downward into the 2nd
1447 or 3rd argument, whichever is selected.
1448 .PP
1449 .Vb 3
1450 \& $x = $ok ? $y : $z; # get a scalar
1451 \& @x = $ok ? @y : @z; # get an array
1452 \& $x = $ok ? @y : @z; # oops, that\*(Aqs just a count!
1453 .Ve
1454 .PP
1455 The operator may be assigned to if both the 2nd and 3rd arguments are
1456 legal lvalues (meaning that you can assign to them):
1457 .PP
1458 .Vb 1
1459 \& ($x_or_y ? $x : $y) = $z;
1460 .Ve
1461 .PP
1462 Because this operator produces an assignable result, using assignments
1463 without parentheses will get you in trouble. For example, this:
1464 .PP
1465 .Vb 1
1466 \& $x % 2 ? $x += 10 : $x += 2
1467 .Ve
1468 .PP
1469 Really means this:
1470 .PP
1471 .Vb 1
1472 \& (($x % 2) ? ($x += 10) : $x) += 2
1473 .Ve
1474 .PP
1475 Rather than this:
1476 .PP
1477 .Vb 1
1478 \& ($x % 2) ? ($x += 10) : ($x += 2)
1479 .Ve
1480 .PP
1481 That should probably be written more simply as:
1482 .PP
1483 .Vb 1
1484 \& $x += ($x % 2) ? 10 : 2;
1485 .Ve
1486 .SS "Assignment Operators"
1487 .IX Xref "assignment operator, assignment = **= += *= &= <<= &&= -= = |= >>= ||= = .= %= ^= x= &.= |.= ^.= ^^="
1488 .IX Subsection "Assignment Operators"
1489 \&\f(CW"="\fR is the ordinary assignment operator.
1490 .PP
1491 Assignment operators work as in C. That is,
1492 .PP
1493 .Vb 1
1494 \& $x += 2;
1495 .Ve
1496 .PP
1497 is equivalent to
1498 .PP
1499 .Vb 1
1500 \& $x = $x + 2;
1501 .Ve
1502 .PP
1503 although without duplicating any side effects that dereferencing the lvalue
1504 might trigger, such as from \f(CWtie()\fR. Other assignment operators work similarly.
1505 The following are recognized:
1506 .PP
1507 .Vb 4
1508 \& **= += *= &= &.= <<= &&=
1509 \& \-= /= |= |.= >>= ||=
1510 \& .= %= ^= ^.= //=
1511 \& x= ^^=
1512 .Ve
1513 .PP
1514 Although these are grouped by family, they all have the precedence
1515 of assignment. These combined assignment operators can only operate on
1516 scalars, whereas the ordinary assignment operator can assign to arrays,
1517 hashes, lists and even references. (See "Context"
1518 and "List value constructors" in perldata, and "Assigning to
1519 References" in perlref.)
1520 .PP
1521 Unlike in C, the scalar assignment operator produces a valid lvalue.
1522 Modifying an assignment is equivalent to doing the assignment and
1523 then modifying the variable that was assigned to. This is useful
1524 for modifying a copy of something, like this:
1525 .PP
1526 .Vb 1
1527 \& ($tmp = $global) =~ tr/13579/24680/;
1528 .Ve
1529 .PP
1530 Although as of 5.14, that can be also be accomplished this way:
1531 .PP
1532 .Vb 2
1533 \& use v5.14;
1534 \& $tmp = ($global =~ tr/13579/24680/r);
1535 .Ve
1536 .PP
1537 Likewise,
1538 .PP
1539 .Vb 1
1540 \& ($x += 2) *= 3;
1541 .Ve
1542 .PP
1543 is equivalent to
1544 .PP
1545 .Vb 2
1546 \& $x += 2;
1547 \& $x *= 3;
1548 .Ve
1549 .PP
1550 Similarly, a list assignment in list context produces the list of
1551 lvalues assigned to, and a list assignment in scalar context returns
1552 the number of elements produced by the expression on the right hand
1553 side of the assignment.
1554 .PP
1555 The three dotted bitwise assignment operators (\f(CW\*(C`&.=\*(C'\fR \f(CW\*(C`|.=\*(C'\fR \f(CW\*(C`^.=\*(C'\fR) are new in
1556 Perl 5.22. See "Bitwise String Operators".
1557 .SS "Comma Operator"
1558 .IX Xref "comma operator, comma ,"
1559 .IX Subsection "Comma Operator"
1560 Binary \f(CW","\fR is the comma operator. In scalar context it evaluates
1561 its left argument, throws that value away, then evaluates its right
1562 argument and returns that value. This is just like C\*(Aqs comma operator.
1563 .PP
1564 In list context, it\*(Aqs just the list argument separator, and inserts
1565 both its arguments into the list. These arguments are also evaluated
1566 from left to right.
1567 .PP
1568 The \f(CW\*(C`=>\*(C'\fR operator (sometimes pronounced "fat comma") is a synonym
1569 for the comma except that it causes a
1570 word on its left to be interpreted as a string if it begins with a letter
1571 or underscore and is composed only of letters, digits and underscores.
1572 This includes operands that might otherwise be interpreted as operators,
1573 constants, single number v\-strings or function calls. If in doubt about
1574 this behavior, the left operand can be quoted explicitly.
1575 .PP
1576 Otherwise, the \f(CW\*(C`=>\*(C'\fR operator behaves exactly as the comma operator
1577 or list argument separator, according to context.
1578 .PP
1579 For example:
1580 .PP
1581 .Vb 1
1582 \& use constant FOO => "something";
1583 \&
1584 \& my %h = ( FOO => 23 );
1585 .Ve
1586 .PP
1587 is equivalent to:
1588 .PP
1589 .Vb 1
1590 \& my %h = ("FOO", 23);
1591 .Ve
1592 .PP
1593 It is \fINOT\fR:
1594 .PP
1595 .Vb 1
1596 \& my %h = ("something", 23);
1597 .Ve
1598 .PP
1599 The \f(CW\*(C`=>\*(C'\fR operator is helpful in documenting the correspondence
1600 between keys and values in hashes, and other paired elements in lists.
1601 .PP
1602 .Vb 2
1603 \& %hash = ( $key => $value );
1604 \& login( $username => $password );
1605 .Ve
1606 .PP
1607 The special quoting behavior ignores precedence, and hence may apply to
1608 \&\fIpart\fR of the left operand:
1609 .PP
1610 .Vb 1
1611 \& print time.shift => "bbb";
1612 .Ve
1613 .PP
1614 That example prints something like \f(CW"1314363215shiftbbb"\fR, because the
1615 \&\f(CW\*(C`=>\*(C'\fR implicitly quotes the \f(CW\*(C`shift\*(C'\fR immediately on its left, ignoring
1616 the fact that \f(CW\*(C`time.shift\*(C'\fR is the entire left operand.
1617 .SS "List Operators (Rightward)"
1618 .IX Xref "operator, list, rightward list operator"
1619 .IX Subsection "List Operators (Rightward)"
1620 On the right side of a list operator, the comma has very low precedence,
1621 such that it controls all comma\-separated expressions found there.
1622 The only operators with lower precedence are the logical operators
1623 \&\f(CW"and"\fR, \f(CW"or"\fR, and \f(CW"not"\fR, which may be used to evaluate calls to list
1624 operators without the need for parentheses:
1625 .PP
1626 .Vb 2
1627 \& open HANDLE, "< :encoding(UTF\-8)", "filename"
1628 \& or die "Can\*(Aqt open: $!\en";
1629 .Ve
1630 .PP
1631 However, some people find that code harder to read than writing
1632 it with parentheses:
1633 .PP
1634 .Vb 2
1635 \& open(HANDLE, "< :encoding(UTF\-8)", "filename")
1636 \& or die "Can\*(Aqt open: $!\en";
1637 .Ve
1638 .PP
1639 in which case you might as well just use the more customary \f(CW"||"\fR operator:
1640 .PP
1641 .Vb 2
1642 \& open(HANDLE, "< :encoding(UTF\-8)", "filename")
1643 \& || die "Can\*(Aqt open: $!\en";
1644 .Ve
1645 .PP
1646 See also discussion of list operators in "Terms and List Operators (Leftward)".
1647 .SS "Logical Not"
1648 .IX Xref "operator, logical, not not"
1649 .IX Subsection "Logical Not"
1650 Unary \f(CW"not"\fR returns the logical negation of the expression to its right.
1651 It\*(Aqs the equivalent of \f(CW"!"\fR except for the very low precedence.
1652 .SS "Logical And"
1653 .IX Xref "operator, logical, and and"
1654 .IX Subsection "Logical And"
1655 Binary \f(CW"and"\fR returns the logical conjunction of the two surrounding
1656 expressions. It\*(Aqs equivalent to \f(CW\*(C`&&\*(C'\fR except for the very low
1657 precedence. This means that it short\-circuits: the right
1658 expression is evaluated only if the left expression is true.
1659 .SS "Logical or and Exclusive Or"
1660 .IX Xref "operator, logical, or or operator, logical, xor operator, logical, exclusive or xor"
1661 .IX Subsection "Logical or and Exclusive Or"
1662 There is no low precedence operator for defined\-OR.
1663 .PP
1664 Binary \f(CW"or"\fR returns the logical inclusive disjunction of the two
1665 surrounding expressions. It\*(Aqs equivalent to \f(CW\*(C`||\*(C'\fR except for it having
1666 very low precedence. This makes it useful for control flow:
1667 .PP
1668 .Vb 1
1669 \& print FH $data or die "Can\*(Aqt write to FH: $!";
1670 .Ve
1671 .PP
1672 This means that it short\-circuits: the right expression is evaluated
1673 only if the left expression is false. Due to its precedence, you must
1674 be careful to avoid using it as replacement for the \f(CW\*(C`||\*(C'\fR operator.
1675 It usually works out better for flow control than in assignments:
1676 .PP
1677 .Vb 3
1678 \& $x = $y or $z; # bug: this is wrong
1679 \& ($x = $y) or $z; # really means this
1680 \& $x = $y || $z; # better written this way
1681 .Ve
1682 .PP
1683 However, when it\*(Aqs a list\-context assignment and you\*(Aqre trying to use
1684 \&\f(CW\*(C`||\*(C'\fR for control flow, you probably need \f(CW"or"\fR so that the assignment
1685 takes higher precedence.
1686 .PP
1687 .Vb 2
1688 \& @info = stat($file) || die; # oops, scalar sense of stat!
1689 \& @info = stat($file) or die; # better, now @info gets its due
1690 .Ve
1691 .PP
1692 Then again, you could always use parentheses.
1693 .PP
1694 Binary \f(CW"xor"\fR returns the logical exclusive disjunction of the two
1695 surrounding expressions. That means it returns \f(CW\*(C`true\*(C'\fR if either, but
1696 not both, are true. It\*(Aqs equivalent to \f(CW\*(C`^^\*(C'\fR except for it having very
1697 low precedence. It cannot short\-circuit (of course). It tends to be
1698 used to verify that two mutually\-exclusive conditions are actually
1699 mutually exclusive. For example, in Perl\*(Aqs test suite, we might want to
1700 test that a regular expression pattern can\*(Aqt both match and not match,
1701 for otherwise it would be a bug in our pattern matching code.
1702 .PP
1703 .Vb 1
1704 \& ($x =~ qr/$pat/ xor $x !~ qr/$pat/) or die;
1705 .Ve
1706 .SS "C Operators Missing From Perl"
1707 .IX Xref "operator, missing from perl & * typecasting (TYPE)"
1708 .IX Subsection "C Operators Missing From Perl"
1709 Here is what C has that Perl doesn\*(Aqt:
1710 .IP "unary &" 8
1711 .IX Item "unary &"
1712 Address\-of operator. (But see the \f(CW"\e"\fR operator for taking a reference.)
1713 .IP "unary *" 8
1714 .IX Item "unary *"
1715 Dereference\-address operator. (Perl\*(Aqs prefix dereferencing
1716 operators are typed: \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR, \f(CW\*(C`%\*(C'\fR, and \f(CW\*(C`&\*(C'\fR.)
1717 .IP (TYPE) 8
1718 .IX Item "(TYPE)"
1719 Type\-casting operator.
1720 .SS "Quote and Quote\-like Operators"
1721 .IX Xref "operator, quote operator, quote-like q qq qx qw m qr s tr \\*(Aq \\*(Aq\\*(Aq "" """" \\` \\`\\` << escape sequence escape"
1722 .IX Subsection "Quote and Quote-like Operators"
1723 While we usually think of quotes as literal values, in Perl they
1724 function as operators, providing various kinds of interpolating and
1725 pattern matching capabilities. Perl provides customary quote characters
1726 for these behaviors, but also provides a way for you to choose your
1727 quote character for any of them. In the following table, a \f(CW\*(C`{}\*(C'\fR represents
1728 any pair of delimiters you choose.
1729 .PP
1730 .Vb 11
1731 \& Customary Generic Meaning Interpolates
1732 \& \*(Aq\*(Aq q{} Literal no
1733 \& "" qq{} Literal yes
1734 \& \`\` qx{} Command yes*
1735 \& qw{} Word list no
1736 \& // m{} Pattern match yes*
1737 \& qr{} Pattern yes*
1738 \& s{}{} Substitution yes*
1739 \& tr{}{} Transliteration no (but see below)
1740 \& y{}{} Transliteration no (but see below)
1741 \& <<EOF here\-doc yes*
1742 \&
1743 \& * unless the delimiter is \*(Aq\*(Aq.
1744 .Ve
1745 .PP
1746 Non\-bracketing delimiters use the same character fore and aft, but the four
1747 sorts of ASCII brackets (round, angle, square, curly) all nest, which means
1748 that
1749 .PP
1750 .Vb 1
1751 \& q{foo{bar}baz}
1752 .Ve
1753 .PP
1754 is the same as
1755 .PP
1756 .Vb 1
1757 \& \*(Aqfoo{bar}baz\*(Aq
1758 .Ve
1759 .PP
1760 Note, however, that this does not always work for quoting Perl code:
1761 .PP
1762 .Vb 1
1763 \& $s = q{ if ($x eq "}") ... }; # WRONG
1764 .Ve
1765 .PP
1766 is a syntax error. The \f(CW\*(C`Text::Balanced\*(C'\fR module (standard as of v5.8,
1767 and from CPAN before then) is able to do this properly.
1768 .PP
1769 If the \f(CW\*(C`extra_paired_delimiters\*(C'\fR feature is enabled, then Perl will
1770 additionally recognise a variety of Unicode characters as being paired. For
1771 a full list, see the "List of Extra Paired Delimiters" at the end of this
1772 document.
1773 .PP
1774 There can (and in some cases, must) be whitespace between the operator
1775 and the quoting
1776 characters, except when \f(CW\*(C`#\*(C'\fR is being used as the quoting character.
1777 \&\f(CW\*(C`q#foo#\*(C'\fR is parsed as the string \f(CW\*(C`foo\*(C'\fR, while \f(CW\*(C`q\ #foo#\*(C'\fR is the
1778 operator \f(CW\*(C`q\*(C'\fR followed by a comment. Its argument will be taken
1779 from the next line. This allows you to write:
1780 .PP
1781 .Vb 2
1782 \& s {foo} # Replace foo
1783 \& {bar} # with bar.
1784 .Ve
1785 .PP
1786 The cases where whitespace must be used are when the quoting character
1787 is a word character (meaning it matches \f(CW\*(C`/\ew/\*(C'\fR):
1788 .PP
1789 .Vb 2
1790 \& q XfooX # Works: means the string \*(Aqfoo\*(Aq
1791 \& qXfooX # WRONG!
1792 .Ve
1793 .PP
1794 The following escape sequences are available in constructs that interpolate,
1795 and in transliterations whose delimiters aren\*(Aqt single quotes (\f(CW"\*(Aq"\fR).
1796 In all the ones with braces, any number of blanks and/or tabs adjoining
1797 and within the braces are allowed (and ignored).
1798 .IX Xref "\\t \\n \\r \\f \\b \\a \\e \\x \\0 \\c \\N \\N{} \\o{}"
1799 .PP
1800 .Vb 10
1801 \& Sequence Note Description
1802 \& \et tab (HT, TAB)
1803 \& \en newline (NL)
1804 \& \er return (CR)
1805 \& \ef form feed (FF)
1806 \& \eb backspace (BS)
1807 \& \ea alarm (bell) (BEL)
1808 \& \ee escape (ESC)
1809 \& \ex{263A} [1,8] hex char (example shown: SMILEY)
1810 \& \ex{ 263A } Same, but shows optional blanks inside and
1811 \& adjoining the braces
1812 \& \ex1b [2,8] restricted range hex char (example: ESC)
1813 \& \eN{name} [3] named Unicode character or character sequence
1814 \& \eN{U+263D} [4,8] Unicode character (example: FIRST QUARTER MOON)
1815 \& \ec[ [5] control char (example: chr(27))
1816 \& \eo{23072} [6,8] octal char (example: SMILEY)
1817 \& \e033 [7,8] restricted range octal char (example: ESC)
1818 .Ve
1819 .PP
1820 Note that any escape sequence using braces inside interpolated
1821 constructs may have optional blanks (tab or space characters) adjoining
1822 with and inside of the braces, as illustrated above by the second
1823 \&\f(CW\*(C`\ex{\ }\*(C'\fR example.
1824 .IP [1] 4
1825 .IX Item "[1]"
1826 The result is the character specified by the hexadecimal number between
1827 the braces. See "[8]" below for details on which character.
1828 .Sp
1829 Blanks (tab or space characters) may separate the number from either or
1830 both of the braces.
1831 .Sp
1832 Otherwise, only hexadecimal digits are valid between the braces. If an
1833 invalid character is encountered, a warning will be issued and the
1834 invalid character and all subsequent characters (valid or invalid)
1835 within the braces will be discarded.
1836 .Sp
1837 If there are no valid digits between the braces, the generated character is
1838 the NULL character (\f(CW\*(C`\ex{00}\*(C'\fR). However, an explicit empty brace (\f(CW\*(C`\ex{}\*(C'\fR)
1839 will not cause a warning (currently).
1840 .IP [2] 4
1841 .IX Item "[2]"
1842 The result is the character specified by the hexadecimal number in the range
1843 0x00 to 0xFF. See "[8]" below for details on which character.
1844 .Sp
1845 Only hexadecimal digits are valid following \f(CW\*(C`\ex\*(C'\fR. When \f(CW\*(C`\ex\*(C'\fR is followed
1846 by fewer than two valid digits, any valid digits will be zero\-padded. This
1847 means that \f(CW\*(C`\ex7\*(C'\fR will be interpreted as \f(CW\*(C`\ex07\*(C'\fR, and a lone \f(CW"\ex"\fR will be
1848 interpreted as \f(CW\*(C`\ex00\*(C'\fR. Except at the end of a string, having fewer than
1849 two valid digits will result in a warning. Note that although the warning
1850 says the illegal character is ignored, it is only ignored as part of the
1851 escape and will still be used as the subsequent character in the string.
1852 For example:
1853 .Sp
1854 .Vb 5
1855 \& Original Result Warns?
1856 \& "\ex7" "\ex07" no
1857 \& "\ex" "\ex00" no
1858 \& "\ex7q" "\ex07q" yes
1859 \& "\exq" "\ex00q" yes
1860 .Ve
1861 .IP [3] 4
1862 .IX Item "[3]"
1863 The result is the Unicode character or character sequence given by \fIname\fR.
1864 See charnames.
1865 .IP [4] 4
1866 .IX Item "[4]"
1867 \&\f(CW\*(C`\eN{U+\fR\f(CIhexadecimal\ number\fR\f(CW}\*(C'\fR means the Unicode character whose Unicode code
1868 point is \fIhexadecimal number\fR.
1869 .IP [5] 4
1870 .IX Item "[5]"
1871 The character following \f(CW\*(C`\ec\*(C'\fR is mapped to some other character as shown in the
1872 table:
1873 .Sp
1874 .Vb 10
1875 \& Sequence Value
1876 \& \ec@ chr(0)
1877 \& \ecA chr(1)
1878 \& \eca chr(1)
1879 \& \ecB chr(2)
1880 \& \ecb chr(2)
1881 \& ...
1882 \& \ecZ chr(26)
1883 \& \ecz chr(26)
1884 \& \ec[ chr(27)
1885 \& # See below for chr(28)
1886 \& \ec] chr(29)
1887 \& \ec^ chr(30)
1888 \& \ec_ chr(31)
1889 \& \ec? chr(127) # (on ASCII platforms; see below for link to
1890 \& # EBCDIC discussion)
1891 .Ve
1892 .Sp
1893 In other words, it\*(Aqs the character whose code point has had 64 xor\*(Aqd with
1894 its uppercase. \f(CW\*(C`\ec?\*(C'\fR is DELETE on ASCII platforms because
1895 \&\f(CW\*(C`ord("?")\ ^\ 64\*(C'\fR is 127, and
1896 \&\f(CW\*(C`\ec@\*(C'\fR is NULL because the ord of \f(CW"@"\fR is 64, so xor\*(Aqing 64 itself produces 0.
1897 .Sp
1898 Also, \f(CW\*(C`\ec\e\fR\f(CIX\fR\f(CW\*(C'\fR yields \f(CW\*(C`\ chr(28)\ .\ "\fR\f(CIX\fR\f(CW"\*(C'\fR for any \fIX\fR, but cannot come at the
1899 end of a string, because the backslash would be parsed as escaping the end
1900 quote.
1901 .Sp
1902 On ASCII platforms, the resulting characters from the list above are the
1903 complete set of ASCII controls. This isn\*(Aqt the case on EBCDIC platforms; see
1904 "OPERATOR DIFFERENCES" in perlebcdic for a full discussion of the
1905 differences between these for ASCII versus EBCDIC platforms.
1906 .Sp
1907 Use of any other character following the \f(CW"c"\fR besides those listed above is
1908 discouraged, and as of Perl v5.20, the only characters actually allowed
1909 are the printable ASCII ones, minus the left brace \f(CW"{"\fR. What happens
1910 for any of the allowed other characters is that the value is derived by
1911 xor\*(Aqing with the seventh bit, which is 64, and a warning raised if
1912 enabled. Using the non\-allowed characters generates a fatal error.
1913 .Sp
1914 To get platform independent controls, you can use \f(CW\*(C`\eN{...}\*(C'\fR.
1915 .IP [6] 4
1916 .IX Item "[6]"
1917 The result is the character specified by the octal number between the braces.
1918 See "[8]" below for details on which character.
1919 .Sp
1920 Blanks (tab or space characters) may separate the number from either or
1921 both of the braces.
1922 .Sp
1923 Otherwise, if a character that isn\*(Aqt an octal digit is encountered, a
1924 warning is raised, and the value is based on the octal digits before it,
1925 discarding it and all following characters up to the closing brace. It
1926 is a fatal error if there are no octal digits at all.
1927 .IP [7] 4
1928 .IX Item "[7]"
1929 The result is the character specified by the three\-digit octal number in the
1930 range 000 to 777 (but best to not use above 077, see next paragraph). See
1931 "[8]" below for details on which character.
1932 .Sp
1933 Some contexts allow 2 or even 1 digit, but any usage without exactly
1934 three digits, the first being a zero, may give unintended results. (For
1935 example, in a regular expression it may be confused with a backreference;
1936 see "Octal escapes" in perlrebackslash.) Starting in Perl 5.14, you may
1937 use \f(CW\*(C`\eo{}\*(C'\fR instead, which avoids all these problems. Otherwise, it is best to
1938 use this construct only for ordinals \f(CW\*(C`\e077\*(C'\fR and below, remembering to pad to
1939 the left with zeros to make three digits. For larger ordinals, either use
1940 \&\f(CW\*(C`\eo{}\*(C'\fR, or convert to something else, such as to hex and use \f(CW\*(C`\eN{U+}\*(C'\fR
1941 (which is portable between platforms with different character sets) or
1942 \&\f(CW\*(C`\ex{}\*(C'\fR instead.
1943 .IP [8] 4
1944 .IX Item "[8]"
1945 Several constructs above specify a character by a number. That number
1946 gives the character\*(Aqs position in the character set encoding (indexed from 0).
1947 This is called synonymously its ordinal, code position, or code point. Perl
1948 works on platforms that have a native encoding currently of either ASCII/Latin1
1949 or EBCDIC, each of which allow specification of 256 characters. In general, if
1950 the number is 255 (0xFF, 0377) or below, Perl interprets this in the platform\*(Aqs
1951 native encoding. If the number is 256 (0x100, 0400) or above, Perl interprets
1952 it as a Unicode code point and the result is the corresponding Unicode
1953 character. For example \f(CW\*(C`\ex{50}\*(C'\fR and \f(CW\*(C`\eo{120}\*(C'\fR both are the number 80 in
1954 decimal, which is less than 256, so the number is interpreted in the native
1955 character set encoding. In ASCII the character in the 80th position (indexed
1956 from 0) is the letter \f(CW"P"\fR, and in EBCDIC it is the ampersand symbol \f(CW"&"\fR.
1957 \&\f(CW\*(C`\ex{100}\*(C'\fR and \f(CW\*(C`\eo{400}\*(C'\fR are both 256 in decimal, so the number is interpreted
1958 as a Unicode code point no matter what the native encoding is. The name of the
1959 character in the 256th position (indexed by 0) in Unicode is
1960 \&\f(CW\*(C`LATIN CAPITAL LETTER A WITH MACRON\*(C'\fR.
1961 .Sp
1962 An exception to the above rule is that \f(CW\*(C`\eN{U+\fR\f(CIhex\ number\fR\f(CW}\*(C'\fR is
1963 always interpreted as a Unicode code point, so that \f(CW\*(C`\eN{U+0050}\*(C'\fR is \f(CW"P"\fR even
1964 on EBCDIC platforms.
1965 .PP
1966 \&\fBNOTE\fR: Unlike C and other languages, Perl has no \f(CW\*(C`\ev\*(C'\fR escape sequence for
1967 the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
1968 use \f(CW\*(C`\eN{VT}\*(C'\fR, \f(CW\*(C`\eck\*(C'\fR, \f(CW\*(C`\eN{U+0b}\*(C'\fR, or \f(CW\*(C`\ex0b\*(C'\fR. (\f(CW\*(C`\ev\*(C'\fR
1969 does have meaning in regular expression patterns in Perl, see perlre.)
1970 .PP
1971 The following escape sequences are available in constructs that interpolate,
1972 but not in transliterations.
1973 .IX Xref "\\l \\u \\L \\U \\E \\Q \\F"
1974 .PP
1975 .Vb 9
1976 \& \el lowercase next character only
1977 \& \eu titlecase (not uppercase!) next character only
1978 \& \eL lowercase all characters till \eE or end of string
1979 \& \eU uppercase all characters till \eE or end of string
1980 \& \eF foldcase all characters till \eE or end of string
1981 \& \eQ quote (disable) pattern metacharacters till \eE or
1982 \& end of string
1983 \& \eE end either case modification or quoted section
1984 \& (whichever was last seen)
1985 .Ve
1986 .PP
1987 See "quotemeta" in perlfunc for the exact definition of characters that
1988 are quoted by \f(CW\*(C`\eQ\*(C'\fR.
1989 .PP
1990 \&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, and \f(CW\*(C`\eQ\*(C'\fR can stack, in which case you need one
1991 \&\f(CW\*(C`\eE\*(C'\fR for each. For example:
1992 .PP
1993 .Vb 2
1994 \& say "This \eQquoting \eubusiness \eUhere isn\*(Aqt\eE done yet,\eE is it?";
1995 \& This quoting Business HERE ISN\*(AqT done yet, is it?
1996 .Ve
1997 .PP
1998 If a \f(CW\*(C`use\ locale\*(C'\fR form that includes \f(CW\*(C`LC_CTYPE\*(C'\fR is in effect (see
1999 perllocale), the case map used by \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is
2000 taken from the current locale. If Unicode (for example, \f(CW\*(C`\eN{}\*(C'\fR or code
2001 points of 0x100 or beyond) is being used, the case map used by \f(CW\*(C`\el\*(C'\fR,
2002 \&\f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, and \f(CW\*(C`\eU\*(C'\fR is as defined by Unicode. That means that
2003 case\-mapping a single character can sometimes produce a sequence of
2004 several characters.
2005 Under \f(CW\*(C`use\ locale\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR produces the same results as \f(CW\*(C`\eL\*(C'\fR
2006 for all locales but a UTF\-8 one, where it instead uses the Unicode
2007 definition.
2008 .PP
2009 All systems use the virtual \f(CW"\en"\fR to represent a line terminator,
2010 called a "newline". There is no such thing as an unvarying, physical
2011 newline character. It is only an illusion that the operating system,
2012 device drivers, C libraries, and Perl all conspire to preserve. Not all
2013 systems read \f(CW"\er"\fR as ASCII CR and \f(CW"\en"\fR as ASCII LF. For example,
2014 on the ancient Macs (pre\-MacOS X) of yesteryear, these used to be reversed,
2015 and on systems without a line terminator,
2016 printing \f(CW"\en"\fR might emit no actual data. In general, use \f(CW"\en"\fR when
2017 you mean a "newline" for your system, but use the literal ASCII when you
2018 need an exact character. For example, most networking protocols expect
2019 and prefer a CR+LF (\f(CW"\e015\e012"\fR or \f(CW"\ecM\ecJ"\fR) for line terminators,
2020 and although they often accept just \f(CW"\e012"\fR, they seldom tolerate just
2021 \&\f(CW"\e015"\fR. If you get in the habit of using \f(CW"\en"\fR for networking,
2022 you may be burned some day.
2023 .IX Xref "newline line terminator eol end of line \\n \\r \\r\\n"
2024 .PP
2025 For constructs that do interpolate, variables beginning with "\f(CW\*(C`$\*(C'\fR"
2026 or "\f(CW\*(C`@\*(C'\fR" are interpolated. Subscripted variables such as \f(CW$a[3]\fR or
2027 \&\f(CW\*(C`$href\->{key}[0]\*(C'\fR are also interpolated, as are array and hash slices.
2028 But method calls such as \f(CW\*(C`$obj\->meth\*(C'\fR are not.
2029 .PP
2030 Interpolating an array or slice interpolates the elements in order,
2031 separated by the value of \f(CW$"\fR, so is equivalent to interpolating
2032 \&\f(CW\*(C`join\ $",\ @array\*(C'\fR. "Punctuation" arrays such as \f(CW\*(C`@*\*(C'\fR are usually
2033 interpolated only if the name is enclosed in braces \f(CW\*(C`@{*}\*(C'\fR, but the
2034 arrays \f(CW@_\fR, \f(CW\*(C`@+\*(C'\fR, and \f(CW\*(C`@\-\*(C'\fR are interpolated even without braces.
2035 .PP
2036 For double\-quoted strings, the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after
2037 interpolation and escapes are processed.
2038 .PP
2039 .Vb 1
2040 \& "abc\eQfoo\etbar$s\eExyz"
2041 .Ve
2042 .PP
2043 is equivalent to
2044 .PP
2045 .Vb 1
2046 \& "abc" . quotemeta("foo\etbar$s") . "xyz"
2047 .Ve
2048 .PP
2049 For the pattern of regex operators (\f(CW\*(C`qr//\*(C'\fR, \f(CW\*(C`m//\*(C'\fR and \f(CW\*(C`s///\*(C'\fR),
2050 the quoting from \f(CW\*(C`\eQ\*(C'\fR is applied after interpolation is processed,
2051 but before escapes are processed. This allows the pattern to match
2052 literally (except for \f(CW\*(C`$\*(C'\fR and \f(CW\*(C`@\*(C'\fR). For example, the following matches:
2053 .PP
2054 .Vb 1
2055 \& \*(Aq\es\et\*(Aq =~ /\eQ\es\et/
2056 .Ve
2057 .PP
2058 Because \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR trigger interpolation, you\*(Aqll need to use something
2059 like \f(CW\*(C`/\eQuser\eE\e@\eQhost/\*(C'\fR to match them literally.
2060 .PP
2061 Patterns are subject to an additional level of interpretation as a
2062 regular expression. This is done as a second pass, after variables are
2063 interpolated, so that regular expressions may be incorporated into the
2064 pattern from the variables. If this is not what you want, use \f(CW\*(C`\eQ\*(C'\fR to
2065 interpolate a variable literally.
2066 .PP
2067 Apart from the behavior described above, Perl does not expand
2068 multiple levels of interpolation. In particular, contrary to the
2069 expectations of shell programmers, back\-quotes do \fINOT\fR interpolate
2070 within double quotes, nor do single quotes impede evaluation of
2071 variables when used within double quotes.
2072 .PP
2073 \fISimpler Quote\-Like Operators\fR
2074 .IX Xref "operator, quote-like"
2075 .IX Subsection "Simpler Quote-Like Operators"
2076 .ie n .IP """q/\fISTRING\fR/""" 4
2077 .el .IP \f(CWq/\fR\f(CISTRING\fR\f(CW/\fR 4
2078 .IX Xref "q quote, single \\*(Aq \\*(Aq\\*(Aq"
2079 .IX Item "q/STRING/"
2080 .PD 0
2081 .ie n .IP \*(Aq\fISTRING\fR\*(Aq 4
2082 .el .IP \f(CW\*(Aq\fR\f(CISTRING\fR\f(CW\*(Aq\fR 4
2083 .IX Item "'STRING'"
2084 .PD
2085 A single\-quoted, literal string. A backslash represents a backslash
2086 unless followed by the delimiter or another backslash, in which case
2087 the delimiter or backslash is interpolated.
2088 .Sp
2089 .Vb 3
2090 \& $foo = q!I said, "You said, \*(AqShe said it.\*(Aq"!;
2091 \& $bar = q(\*(AqThis is it.\*(Aq);
2092 \& $baz = \*(Aq\en\*(Aq; # a two\-character string
2093 .Ve
2094 .ie n .IP """qq/\fISTRING\fR/""" 4
2095 .el .IP \f(CWqq/\fR\f(CISTRING\fR\f(CW/\fR 4
2096 .IX Xref "qq quote, double "" """""
2097 .IX Item "qq/STRING/"
2098 .PD 0
2099 .ie n .IP """\fISTRING\fR""" 4
2100 .el .IP "\f(CW""\fR\f(CISTRING\fR\f(CW""\fR" 4
2101 .IX Item """STRING"""
2102 .PD
2103 A double\-quoted, interpolated string.
2104 .Sp
2105 .Vb 4
2106 \& $_ .= qq
2107 \& (*** The previous line contains the naughty word "$1".\en)
2108 \& if /\eb(tcl|java|python)\eb/i; # :\-)
2109 \& $baz = "\en"; # a one\-character string
2110 .Ve
2111 .ie n .IP """qx/\fISTRING\fR/""" 4
2112 .el .IP \f(CWqx/\fR\f(CISTRING\fR\f(CW/\fR 4
2113 .IX Xref "qx \\` \\`\\` backtick"
2114 .IX Item "qx/STRING/"
2115 .PD 0
2116 .ie n .IP \`\fISTRING\fR\` 4
2117 .el .IP \f(CW\`\fR\f(CISTRING\fR\f(CW\`\fR 4
2118 .IX Item "`STRING`"
2119 .PD
2120 A string which is (possibly) interpolated and then executed as a
2121 system command, via \fI/bin/sh\fR or its equivalent if required. Shell
2122 wildcards, pipes, and redirections will be honored. Similarly to
2123 \&\f(CW\*(C`system\*(C'\fR, if the string contains no shell metacharacters then it will
2124 be executed directly. The collected standard output of the command is
2125 returned; standard error is unaffected. In scalar context, it comes
2126 back as a single (potentially multi\-line) string, or \f(CW\*(C`undef\*(C'\fR if the
2127 shell (or command) could not be started. In list context, returns a
2128 list of lines (however you\*(Aqve defined lines with \f(CW$/\fR or
2129 \&\f(CW$INPUT_RECORD_SEPARATOR\fR), or an empty list if the shell (or command)
2130 could not be started.
2131 .Sp
2132 .Vb 1
2133 \& print qx/date/; # prints "Sun Jan 28 06:16:19 CST 2024"
2134 .Ve
2135 .Sp
2136 Because backticks do not affect standard error, use shell file descriptor
2137 syntax (assuming the shell supports this) if you care to address this.
2138 To capture a command\*(Aqs STDERR and STDOUT together:
2139 .Sp
2140 .Vb 1
2141 \& $output = \`cmd 2>&1\`;
2142 .Ve
2143 .Sp
2144 To capture a command\*(Aqs STDOUT but discard its STDERR:
2145 .Sp
2146 .Vb 1
2147 \& $output = \`cmd 2>/dev/null\`;
2148 .Ve
2149 .Sp
2150 To capture a command\*(Aqs STDERR but discard its STDOUT (ordering is
2151 important here):
2152 .Sp
2153 .Vb 1
2154 \& $output = \`cmd 2>&1 1>/dev/null\`;
2155 .Ve
2156 .Sp
2157 To exchange a command\*(Aqs STDOUT and STDERR in order to capture the STDERR
2158 but leave its STDOUT to come out the old STDERR:
2159 .Sp
2160 .Vb 1
2161 \& $output = \`cmd 3>&1 1>&2 2>&3 3>&\-\`;
2162 .Ve
2163 .Sp
2164 To read both a command\*(Aqs STDOUT and its STDERR separately, it\*(Aqs easiest
2165 to redirect them separately to files, and then read from those files
2166 when the program is done:
2167 .Sp
2168 .Vb 1
2169 \& system("program args 1>program.stdout 2>program.stderr");
2170 .Ve
2171 .Sp
2172 The STDIN filehandle used by the command is inherited from Perl\*(Aqs STDIN.
2173 For example:
2174 .Sp
2175 .Vb 3
2176 \& open(SPLAT, "stuff") || die "can\*(Aqt open stuff: $!";
2177 \& open(STDIN, "<&SPLAT") || die "can\*(Aqt dupe SPLAT: $!";
2178 \& print STDOUT \`sort\`;
2179 .Ve
2180 .Sp
2181 will print the sorted contents of the file named \fI"stuff"\fR.
2182 .Sp
2183 Using single\-quote as a delimiter protects the command from Perl\*(Aqs
2184 double\-quote interpolation, passing it on to the shell instead:
2185 .Sp
2186 .Vb 2
2187 \& $perl_info = qx(ps $$); # that\*(Aqs Perl\*(Aqs $$
2188 \& $shell_info = qx\*(Aqps $$\*(Aq; # that\*(Aqs the new shell\*(Aqs $$
2189 .Ve
2190 .Sp
2191 How that string gets evaluated is entirely subject to the command
2192 interpreter on your system. On most platforms, you will have to protect
2193 shell metacharacters if you want them treated literally. This is in
2194 practice difficult to do, as it\*(Aqs unclear how to escape which characters.
2195 See perlsec for a clean and safe example of a manual \f(CWfork()\fR and \f(CWexec()\fR
2196 to emulate backticks safely.
2197 .Sp
2198 On some platforms (notably DOS\-like ones), the shell may not be
2199 capable of dealing with multiline commands, so putting newlines in
2200 the string may not get you what you want. You may be able to evaluate
2201 multiple commands in a single line by separating them with the command
2202 separator character, if your shell supports that (for example, \f(CW\*(C`;\*(C'\fR on
2203 many Unix shells and \f(CW\*(C`&\*(C'\fR on the Windows NT \f(CW\*(C`cmd\*(C'\fR shell).
2204 .Sp
2205 Perl will attempt to flush all files opened for
2206 output before starting the child process, but this may not be supported
2207 on some platforms (see perlport). To be safe, you may need to set
2208 \&\f(CW$|\fR (\f(CW$AUTOFLUSH\fR in \f(CW\*(C`English\*(C'\fR) or call the \f(CWautoflush()\fR method of
2209 \&\f(CW\*(C`IO::Handle\*(C'\fR on any open handles.
2210 .Sp
2211 Beware that some command shells may place restrictions on the length
2212 of the command line. You must ensure your strings don\*(Aqt exceed this
2213 limit after any necessary interpolations. See the platform\-specific
2214 release notes for more details about your particular environment.
2215 .Sp
2216 Using this operator can lead to programs that are difficult to port,
2217 because the shell commands called vary between systems, and may in
2218 fact not be present at all. As one example, the \f(CW\*(C`type\*(C'\fR command under
2219 the POSIX shell is very different from the \f(CW\*(C`type\*(C'\fR command under DOS.
2220 That doesn\*(Aqt mean you should go out of your way to avoid backticks
2221 when they\*(Aqre the right way to get something done. Perl was made to be
2222 a glue language, and one of the things it glues together is commands.
2223 Just understand what you\*(Aqre getting yourself into.
2224 .Sp
2225 Like \f(CW\*(C`system\*(C'\fR, backticks put the child process exit code in \f(CW$?\fR.
2226 If you\*(Aqd like to manually inspect failure, you can check all possible
2227 failure modes by inspecting \f(CW$?\fR like this:
2228 .Sp
2229 .Vb 10
2230 \& if ($? == \-1) {
2231 \& print "failed to execute: $!\en";
2232 \& }
2233 \& elsif ($? & 127) {
2234 \& printf "child died with signal %d, %s coredump\en",
2235 \& ($? & 127), ($? & 128) ? \*(Aqwith\*(Aq : \*(Aqwithout\*(Aq;
2236 \& }
2237 \& else {
2238 \& printf "child exited with value %d\en", $? >> 8;
2239 \& }
2240 .Ve
2241 .Sp
2242 Use the open pragma to control the I/O layers used when reading the
2243 output of the command, for example:
2244 .Sp
2245 .Vb 2
2246 \& use open IN => ":encoding(UTF\-8)";
2247 \& my $x = \`cmd\-producing\-utf\-8\`;
2248 .Ve
2249 .Sp
2250 \&\f(CW\*(C`qx//\*(C'\fR can also be called like a function with "readpipe" in perlfunc.
2251 .Sp
2252 See "I/O Operators" for more discussion.
2253 .ie n .IP """qw/\fISTRING\fR/""" 4
2254 .el .IP \f(CWqw/\fR\f(CISTRING\fR\f(CW/\fR 4
2255 .IX Xref "qw quote, list quote, words"
2256 .IX Item "qw/STRING/"
2257 Evaluates to a list of the words extracted out of \fISTRING\fR, using embedded
2258 whitespace as the word delimiters. It can be understood as being roughly
2259 equivalent to:
2260 .Sp
2261 .Vb 1
2262 \& split(" ", q/STRING/);
2263 .Ve
2264 .Sp
2265 the differences being that it only splits on ASCII whitespace,
2266 generates a real list at compile time, and
2267 in scalar context it returns the last element in the list. So
2268 this expression:
2269 .Sp
2270 .Vb 1
2271 \& qw(foo bar baz)
2272 .Ve
2273 .Sp
2274 is semantically equivalent to the list:
2275 .Sp
2276 .Vb 1
2277 \& "foo", "bar", "baz"
2278 .Ve
2279 .Sp
2280 Some frequently seen examples:
2281 .Sp
2282 .Vb 2
2283 \& use POSIX qw( setlocale localeconv )
2284 \& @EXPORT = qw( foo bar baz );
2285 .Ve
2286 .Sp
2287 A common mistake is to try to separate the words with commas or to
2288 put comments into a multi\-line \f(CW\*(C`qw\*(C'\fR\-string. For this reason, the
2289 \&\f(CW\*(C`use\ warnings\*(C'\fR pragma and the \fB\-w\fR switch (that is, the \f(CW$^W\fR variable)
2290 produces warnings if the \fISTRING\fR contains the \f(CW","\fR or the \f(CW"#"\fR character.
2291 .PP
2292 \fIRegexp Quote\-Like Operators\fR
2293 .IX Xref "operator, regexp"
2294 .IX Subsection "Regexp Quote-Like Operators"
2295 .PP
2296 Here are the quote\-like operators that apply to pattern
2297 matching and related activities.
2298 .ie n .IP """qr/\fISTRING\fR/msixpodualn""" 8
2299 .el .IP \f(CWqr/\fR\f(CISTRING\fR\f(CW/msixpodualn\fR 8
2300 .IX Xref "qr i m o s x p"
2301 .IX Item "qr/STRING/msixpodualn"
2302 This operator quotes (and possibly compiles) its \fISTRING\fR as a regular
2303 expression. \fISTRING\fR is interpolated the same way as \fIPATTERN\fR
2304 in \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR. If \f(CW"\*(Aq"\fR is used as the delimiter, no variable
2305 interpolation is done. Returns a Perl value which may be used instead of the
2306 corresponding \f(CW\*(C`/\fR\f(CISTRING\fR\f(CW/msixpodualn\*(C'\fR expression. The returned value is a
2307 normalized version of the original pattern. It magically differs from
2308 a string containing the same characters: \f(CWref(qr/x/)\fR returns "Regexp";
2309 however, dereferencing it is not well defined (you currently get the
2310 normalized version of the original pattern, but this may change).
2311 .Sp
2312 For example,
2313 .Sp
2314 .Vb 3
2315 \& $rex = qr/my.STRING/is;
2316 \& print $rex; # prints (?si\-xm:my.STRING)
2317 \& s/$rex/foo/;
2318 .Ve
2319 .Sp
2320 is equivalent to
2321 .Sp
2322 .Vb 1
2323 \& s/my.STRING/foo/is;
2324 .Ve
2325 .Sp
2326 The result may be used as a subpattern in a match:
2327 .Sp
2328 .Vb 5
2329 \& $re = qr/$pattern/;
2330 \& $string =~ /foo${re}bar/; # can be interpolated in other
2331 \& # patterns
2332 \& $string =~ $re; # or used standalone
2333 \& $string =~ /$re/; # or this way
2334 .Ve
2335 .Sp
2336 Since Perl may compile the pattern at the moment of execution of the \f(CWqr()\fR
2337 operator, using \f(CWqr()\fR may have speed advantages in some situations,
2338 notably if the result of \f(CWqr()\fR is used standalone:
2339 .Sp
2340 .Vb 11
2341 \& sub match {
2342 \& my $patterns = shift;
2343 \& my @compiled = map qr/$_/i, @$patterns;
2344 \& grep {
2345 \& my $success = 0;
2346 \& foreach my $pat (@compiled) {
2347 \& $success = 1, last if /$pat/;
2348 \& }
2349 \& $success;
2350 \& } @_;
2351 \& }
2352 .Ve
2353 .Sp
2354 Precompilation of the pattern into an internal representation at
2355 the moment of \f(CWqr()\fR avoids the need to recompile the pattern every
2356 time a match \f(CW\*(C`/$pat/\*(C'\fR is attempted. (Perl has many other internal
2357 optimizations, but none would be triggered in the above example if
2358 we did not use \f(CWqr()\fR operator.)
2359 .Sp
2360 Options (specified by the following modifiers) are:
2361 .Sp
2362 .Vb 10
2363 \& m Treat string as multiple lines.
2364 \& s Treat string as single line. (Make . match a newline)
2365 \& i Do case\-insensitive pattern matching.
2366 \& x Use extended regular expressions; specifying two
2367 \& x\*(Aqs means \et and the SPACE character are ignored within
2368 \& square\-bracketed character classes
2369 \& p When matching preserve a copy of the matched string so
2370 \& that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
2371 \& defined (ignored starting in v5.20 as these are always
2372 \& defined starting in that release)
2373 \& o Compile pattern only once.
2374 \& a ASCII\-restrict: Use ASCII for \ed, \es, \ew and [[:posix:]]
2375 \& character classes; specifying two a\*(Aqs adds the further
2376 \& restriction that no ASCII character will match a
2377 \& non\-ASCII one under /i.
2378 \& l Use the current run\-time locale\*(Aqs rules.
2379 \& u Use Unicode rules.
2380 \& d Use Unicode or native charset, as in 5.12 and earlier.
2381 \& n Non\-capture mode. Don\*(Aqt let () fill in $1, $2, etc...
2382 .Ve
2383 .Sp
2384 If a precompiled pattern is embedded in a larger pattern then the effect
2385 of \f(CW"msixpluadn"\fR will be propagated appropriately. The effect that the
2386 \&\f(CW\*(C`/o\*(C'\fR modifier has is not propagated, being restricted to those patterns
2387 explicitly using it.
2388 .Sp
2389 The \f(CW\*(C`/a\*(C'\fR, \f(CW\*(C`/d\*(C'\fR, \f(CW\*(C`/l\*(C'\fR, and \f(CW\*(C`/u\*(C'\fR modifiers (added in Perl 5.14)
2390 control the character set rules, but \f(CW\*(C`/a\*(C'\fR is the only one you are likely
2391 to want to specify explicitly; the other three are selected
2392 automatically by various pragmas.
2393 .Sp
2394 See perlre for additional information on valid syntax for \fISTRING\fR, and
2395 for a detailed look at the semantics of regular expressions. In
2396 particular, all modifiers except the largely obsolete \f(CW\*(C`/o\*(C'\fR are further
2397 explained in "Modifiers" in perlre. \f(CW\*(C`/o\*(C'\fR is described in the next section.
2398 .ie n .IP """m/\fIPATTERN\fR/msixpodualngc""" 8
2399 .el .IP \f(CWm/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
2400 .IX Xref "m operator, match regexp, options regexp regex, options regex m s i x p o g c"
2401 .IX Item "m/PATTERN/msixpodualngc"
2402 .PD 0
2403 .ie n .IP """/\fIPATTERN\fR/msixpodualngc""" 8
2404 .el .IP \f(CW/\fR\f(CIPATTERN\fR\f(CW/msixpodualngc\fR 8
2405 .IX Item "/PATTERN/msixpodualngc"
2406 .PD
2407 Searches a string for a pattern match, and in scalar context returns
2408 true if it succeeds, false if it fails. If no string is specified
2409 via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR string is searched. (The
2410 string specified with \f(CW\*(C`=~\*(C'\fR need not be an lvalue\-\-it may be the
2411 result of an expression evaluation, but remember the \f(CW\*(C`=~\*(C'\fR binds
2412 rather tightly.) See also perlre.
2413 .Sp
2414 Options are as described in \f(CW\*(C`qr//\*(C'\fR above; in addition, the following match
2415 process modifiers are available:
2416 .Sp
2417 .Vb 3
2418 \& g Match globally, i.e., find all occurrences.
2419 \& c Do not reset search position on a failed match when /g is
2420 \& in effect.
2421 .Ve
2422 .Sp
2423 If \f(CW"/"\fR is the delimiter then the initial \f(CW\*(C`m\*(C'\fR is optional. With the \f(CW\*(C`m\*(C'\fR
2424 you can use any pair of non\-whitespace (ASCII) characters
2425 as delimiters. This is particularly useful for matching path names
2426 that contain \f(CW"/"\fR, to avoid LTS (leaning toothpick syndrome). If \f(CW"?"\fR is
2427 the delimiter, then a match\-only\-once rule applies,
2428 described in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR below. If \f(CW"\*(Aq"\fR (single quote) is the delimiter,
2429 no variable interpolation is performed on the \fIPATTERN\fR.
2430 When using a delimiter character valid in an identifier, whitespace is required
2431 after the \f(CW\*(C`m\*(C'\fR.
2432 .Sp
2433 \&\fIPATTERN\fR may contain variables, which will be interpolated
2434 every time the pattern search is evaluated, except
2435 for when the delimiter is a single quote. (Note that \f(CW$(\fR, \f(CW$)\fR, and
2436 \&\f(CW$|\fR are not interpolated because they look like end\-of\-string tests.)
2437 Perl will not recompile the pattern unless an interpolated
2438 variable that it contains changes. You can force Perl to skip the
2439 test and never recompile by adding a \f(CW\*(C`/o\*(C'\fR (which stands for "once")
2440 after the trailing delimiter.
2441 Once upon a time, Perl would recompile regular expressions
2442 unnecessarily, and this modifier was useful to tell it not to do so, in the
2443 interests of speed. But now, the only reasons to use \f(CW\*(C`/o\*(C'\fR are one of:
2444 .RS 8
2445 .IP 1. 4
2446 The variables are thousands of characters long and you know that they
2447 don\*(Aqt change, and you need to wring out the last little bit of speed by
2448 having Perl skip testing for that. (There is a maintenance penalty for
2449 doing this, as mentioning \f(CW\*(C`/o\*(C'\fR constitutes a promise that you won\*(Aqt
2450 change the variables in the pattern. If you do change them, Perl won\*(Aqt
2451 even notice.)
2452 .IP 2. 4
2453 you want the pattern to use the initial values of the variables
2454 regardless of whether they change or not. (But there are saner ways
2455 of accomplishing this than using \f(CW\*(C`/o\*(C'\fR.)
2456 .IP 3. 4
2457 If the pattern contains embedded code, such as
2458 .Sp
2459 .Vb 3
2460 \& use re \*(Aqeval\*(Aq;
2461 \& $code = \*(Aqfoo(?{ $x })\*(Aq;
2462 \& /$code/
2463 .Ve
2464 .Sp
2465 then perl will recompile each time, even though the pattern string hasn\*(Aqt
2466 changed, to ensure that the current value of \f(CW$x\fR is seen each time.
2467 Use \f(CW\*(C`/o\*(C'\fR if you want to avoid this.
2468 .RE
2469 .RS 8
2470 .Sp
2471 The bottom line is that using \f(CW\*(C`/o\*(C'\fR is almost never a good idea.
2472 .RE
2473 .ie n .IP "The empty pattern ""//""" 8
2474 .el .IP "The empty pattern \f(CW//\fR" 8
2475 .IX Item "The empty pattern //"
2476 If the \fIPATTERN\fR evaluates to the empty string, the last
2477 \&\fIsuccessfully\fR matched regular expression in the current dynamic
2478 scope is used instead (see also "Scoping Rules of Regex Variables" in perlvar).
2479 In this case, only the \f(CW\*(C`g\*(C'\fR and \f(CW\*(C`c\*(C'\fR flags on the empty pattern are
2480 honored; the other flags are taken from the original pattern. If no
2481 match has previously succeeded, this will (silently) act instead as a
2482 genuine empty pattern (which will always match). Using a user supplied
2483 string as a pattern has the risk that if the string is empty that it
2484 triggers the "last successful match" behavior, which can be very
2485 confusing. In such cases you are recommended to replace \f(CW\*(C`m/$pattern/\*(C'\fR
2486 with \f(CW\*(C`m/(?:$pattern)/\*(C'\fR to avoid this behavior.
2487 .Sp
2488 The last successful pattern may be accessed as a variable via
2489 \&\f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR. Matching against it, or the empty
2490 pattern should have the same effect, with the exception that when there
2491 is no last successful pattern the empty pattern will silently match,
2492 whereas using the \f(CW\*(C`${^LAST_SUCCESSFUL_PATTERN}\*(C'\fR variable will produce
2493 undefined warnings (if warnings are enabled). You can check
2494 \&\f(CWdefined(${^LAST_SUCCESSFUL_PATTERN})\fR to test if there is a "last
2495 successful match" in the current scope.
2496 .Sp
2497 Note that it\*(Aqs possible to confuse Perl into thinking \f(CW\*(C`//\*(C'\fR (the empty
2498 regex) is really \f(CW\*(C`//\*(C'\fR (the defined\-or operator). Perl is usually pretty
2499 good about this, but some pathological cases might trigger this, such as
2500 \&\f(CW\*(C`$x///\*(C'\fR (is that \f(CW\*(C`($x)\ /\ (//)\*(C'\fR or \f(CW\*(C`$x\ //\ /\*(C'\fR?) and \f(CW\*(C`print\ $fh\ //\*(C'\fR
2501 (\f(CW\*(C`print\ $fh(//\*(C'\fR or \f(CW\*(C`print($fh\ //\*(C'\fR?). In all of these examples, Perl
2502 will assume you meant defined\-or. If you meant the empty regex, just
2503 use parentheses or spaces to disambiguate, or even prefix the empty
2504 regex with an \f(CW\*(C`m\*(C'\fR (so \f(CW\*(C`//\*(C'\fR becomes \f(CW\*(C`m//\*(C'\fR).
2505 .IP "Matching in list context" 8
2506 .IX Item "Matching in list context"
2507 If the \f(CW\*(C`/g\*(C'\fR option is not used, \f(CW\*(C`m//\*(C'\fR in list context returns a
2508 list consisting of the subexpressions matched by the parentheses in the
2509 pattern, that is, (\f(CW$1\fR, \f(CW$2\fR, \f(CW$3\fR...) (Note that here \f(CW$1\fR etc. are
2510 also set). When there are no parentheses in the pattern, the return
2511 value is the list \f(CW\*(C`(1)\*(C'\fR for success.
2512 With or without parentheses, an empty list is returned upon failure.
2513 .Sp
2514 Examples:
2515 .Sp
2516 .Vb 2
2517 \& open(TTY, "+</dev/tty")
2518 \& || die "can\*(Aqt access /dev/tty: $!";
2519 \&
2520 \& <TTY> =~ /^y/i && foo(); # do foo if desired
2521 \&
2522 \& if (/Version: *([0\-9.]*)/) { $version = $1; }
2523 \&
2524 \& next if m#^/usr/spool/uucp#;
2525 \&
2526 \& # poor man\*(Aqs grep
2527 \& $arg = shift;
2528 \& while (<>) {
2529 \& print if /$arg/;
2530 \& }
2531 \& if (($F1, $F2, $Etc) = ($foo =~ /^(\eS+)\es+(\eS+)\es*(.*)/))
2532 .Ve
2533 .Sp
2534 This last example splits \f(CW$foo\fR into the first two words and the
2535 remainder of the line, and assigns those three fields to \f(CW$F1\fR, \f(CW$F2\fR, and
2536 \&\f(CW$Etc\fR. The conditional is true if any variables were assigned; that is,
2537 if the pattern matched.
2538 .Sp
2539 The \f(CW\*(C`/g\*(C'\fR modifier specifies global pattern matching\-\-that is,
2540 matching as many times as possible within the string. How it behaves
2541 depends on the context. In list context, it returns a list of the
2542 substrings matched by any capturing parentheses in the regular
2543 expression. If there are no parentheses, it returns a list of all
2544 the matched strings, as if there were parentheses around the whole
2545 pattern.
2546 .Sp
2547 In scalar context, each execution of \f(CW\*(C`m//g\*(C'\fR finds the next match,
2548 returning true if it matches, and false if there is no further match.
2549 The position after the last match can be read or set using the \f(CWpos()\fR
2550 function; see "pos" in perlfunc. A failed match normally resets the
2551 search position to the beginning of the string, but you can avoid that
2552 by adding the \f(CW\*(C`/c\*(C'\fR modifier (for example, \f(CW\*(C`m//gc\*(C'\fR). Modifying the target
2553 string also resets the search position.
2554 .ie n .IP """\eG \fIassertion\fR""" 8
2555 .el .IP "\f(CW\eG \fR\f(CIassertion\fR\f(CW\fR" 8
2556 .IX Item "G assertion"
2557 You can intermix \f(CW\*(C`m//g\*(C'\fR matches with \f(CW\*(C`m/\eG.../g\*(C'\fR, where \f(CW\*(C`\eG\*(C'\fR is a
2558 zero\-width assertion that matches the exact position where the
2559 previous \f(CW\*(C`m//g\*(C'\fR, if any, left off. Without the \f(CW\*(C`/g\*(C'\fR modifier, the
2560 \&\f(CW\*(C`\eG\*(C'\fR assertion still anchors at \f(CWpos()\fR as it was at the start of
2561 the operation (see "pos" in perlfunc), but the match is of course only
2562 attempted once. Using \f(CW\*(C`\eG\*(C'\fR without \f(CW\*(C`/g\*(C'\fR on a target string that has
2563 not previously had a \f(CW\*(C`/g\*(C'\fR match applied to it is the same as using
2564 the \f(CW\*(C`\eA\*(C'\fR assertion to match the beginning of the string. Note also
2565 that, currently, \f(CW\*(C`\eG\*(C'\fR is only properly supported when anchored at the
2566 very beginning of the pattern.
2567 .Sp
2568 Examples:
2569 .Sp
2570 .Vb 2
2571 \& # list context
2572 \& ($one,$five,$fifteen) = (\`uptime\` =~ /(\ed+\e.\ed+)/g);
2573 \&
2574 \& # scalar context
2575 \& local $/ = "";
2576 \& while ($paragraph = <>) {
2577 \& while ($paragraph =~ /\ep{Ll}[\*(Aq")]*[.!?]+[\*(Aq")]*\es/g) {
2578 \& $sentences++;
2579 \& }
2580 \& }
2581 \& say $sentences;
2582 .Ve
2583 .Sp
2584 Here\*(Aqs another way to check for sentences in a paragraph:
2585 .Sp
2586 .Vb 10
2587 \& my $sentence_rx = qr{
2588 \& (?: (?<= ^ ) | (?<= \es ) ) # after start\-of\-string or
2589 \& # whitespace
2590 \& \ep{Lu} # capital letter
2591 \& .*? # a bunch of anything
2592 \& (?<= \eS ) # that ends in non\-
2593 \& # whitespace
2594 \& (?<! \eb [DMS]r ) # but isn\*(Aqt a common abbr.
2595 \& (?<! \eb Mrs )
2596 \& (?<! \eb Sra )
2597 \& (?<! \eb St )
2598 \& [.?!] # followed by a sentence
2599 \& # ender
2600 \& (?= $ | \es ) # in front of end\-of\-string
2601 \& # or whitespace
2602 \& }sx;
2603 \& local $/ = "";
2604 \& while (my $paragraph = <>) {
2605 \& say "NEW PARAGRAPH";
2606 \& my $count = 0;
2607 \& while ($paragraph =~ /($sentence_rx)/g) {
2608 \& printf "\etgot sentence %d: <%s>\en", ++$count, $1;
2609 \& }
2610 \& }
2611 .Ve
2612 .Sp
2613 Here\*(Aqs how to use \f(CW\*(C`m//gc\*(C'\fR with \f(CW\*(C`\eG\*(C'\fR:
2614 .Sp
2615 .Vb 10
2616 \& $_ = "ppooqppqq";
2617 \& while ($i++ < 2) {
2618 \& print "1: \*(Aq";
2619 \& print $1 while /(o)/gc; print "\*(Aq, pos=", pos, "\en";
2620 \& print "2: \*(Aq";
2621 \& print $1 if /\eG(q)/gc; print "\*(Aq, pos=", pos, "\en";
2622 \& print "3: \*(Aq";
2623 \& print $1 while /(p)/gc; print "\*(Aq, pos=", pos, "\en";
2624 \& }
2625 \& print "Final: \*(Aq$1\*(Aq, pos=",pos,"\en" if /\eG(.)/;
2626 .Ve
2627 .Sp
2628 The last example should print:
2629 .Sp
2630 .Vb 7
2631 \& 1: \*(Aqoo\*(Aq, pos=4
2632 \& 2: \*(Aqq\*(Aq, pos=5
2633 \& 3: \*(Aqpp\*(Aq, pos=7
2634 \& 1: \*(Aq\*(Aq, pos=7
2635 \& 2: \*(Aqq\*(Aq, pos=8
2636 \& 3: \*(Aq\*(Aq, pos=8
2637 \& Final: \*(Aqq\*(Aq, pos=8
2638 .Ve
2639 .Sp
2640 Notice that the final match matched \f(CW\*(C`q\*(C'\fR instead of \f(CW\*(C`p\*(C'\fR, which a match
2641 without the \f(CW\*(C`\eG\*(C'\fR anchor would have done. Also note that the final match
2642 did not update \f(CW\*(C`pos\*(C'\fR. \f(CW\*(C`pos\*(C'\fR is only updated on a \f(CW\*(C`/g\*(C'\fR match. If the
2643 final match did indeed match \f(CW\*(C`p\*(C'\fR, it\*(Aqs a good bet that you\*(Aqre running an
2644 ancient (pre\-5.6.0) version of Perl.
2645 .Sp
2646 A useful idiom for \f(CW\*(C`lex\*(C'\fR\-like scanners is \f(CW\*(C`/\eG.../gc\*(C'\fR. You can
2647 combine several regexps like this to process a string part\-by\-part,
2648 doing different actions depending on which regexp matched. Each
2649 regexp tries to match where the previous one leaves off.
2650 .Sp
2651 .Vb 4
2652 \& $_ = <<\*(AqEOL\*(Aq;
2653 \& $url = URI::URL\->new( "http://example.com/" );
2654 \& die if $url eq "xXx";
2655 \& EOL
2656 \&
2657 \& LOOP: {
2658 \& print(" digits"), redo LOOP if /\eG\ed+\eb[,.;]?\es*/gc;
2659 \& print(" lowercase"), redo LOOP
2660 \& if /\eG\ep{Ll}+\eb[,.;]?\es*/gc;
2661 \& print(" UPPERCASE"), redo LOOP
2662 \& if /\eG\ep{Lu}+\eb[,.;]?\es*/gc;
2663 \& print(" Capitalized"), redo LOOP
2664 \& if /\eG\ep{Lu}\ep{Ll}+\eb[,.;]?\es*/gc;
2665 \& print(" MiXeD"), redo LOOP
2666 \& if /\eG\epL+\eb[,.;]?\es*/gc;
2667 \& print(" alphanumeric"), redo LOOP
2668 \& if /\eG[\ep{Alpha}\epN]+\eb[,.;]?\es*/gc;
2669 \& print(" line\-noise"), redo LOOP if /\eG\eW+/gc;
2670 \& print ". That\*(Aqs all!\en";
2671 \& }
2672 .Ve
2673 .Sp
2674 Here is the output (split into several lines):
2675 .Sp
2676 .Vb 4
2677 \& line\-noise lowercase line\-noise UPPERCASE line\-noise UPPERCASE
2678 \& line\-noise lowercase line\-noise lowercase line\-noise lowercase
2679 \& lowercase line\-noise lowercase lowercase line\-noise lowercase
2680 \& lowercase line\-noise MiXeD line\-noise. That\*(Aqs all!
2681 .Ve
2682 .ie n .IP """m?\fIPATTERN\fR?msixpodualngc""" 8
2683 .el .IP \f(CWm?\fR\f(CIPATTERN\fR\f(CW?msixpodualngc\fR 8
2684 .IX Xref "? operator, match-once"
2685 .IX Item "m?PATTERN?msixpodualngc"
2686 This is just like the \f(CW\*(C`m/\fR\f(CIPATTERN\fR\f(CW/\*(C'\fR search, except that it matches
2687 only once between calls to the \f(CWreset()\fR operator. This is a useful
2688 optimization when you want to see only the first occurrence of
2689 something in each file of a set of files, for instance. Only \f(CW\*(C`m??\*(C'\fR
2690 patterns local to the current package are reset.
2691 .Sp
2692 .Vb 7
2693 \& while (<>) {
2694 \& if (m?^$?) {
2695 \& # blank line between header and body
2696 \& }
2697 \& } continue {
2698 \& reset if eof; # clear m?? status for next file
2699 \& }
2700 .Ve
2701 .Sp
2702 Another example switched the first "latin1" encoding it finds
2703 to "utf8" in a pod file:
2704 .Sp
2705 .Vb 1
2706 \& s//utf8/ if m? ^ =encoding \eh+ \eK latin1 ?x;
2707 .Ve
2708 .Sp
2709 The match\-once behavior is controlled by the match delimiter being
2710 \&\f(CW\*(C`?\*(C'\fR; with any other delimiter this is the normal \f(CW\*(C`m//\*(C'\fR operator.
2711 .Sp
2712 In the past, the leading \f(CW\*(C`m\*(C'\fR in \f(CW\*(C`m?\fR\f(CIPATTERN\fR\f(CW?\*(C'\fR was optional, but omitting it
2713 would produce a deprecation warning. As of v5.22.0, omitting it produces a
2714 syntax error. If you encounter this construct in older code, you can just add
2715 \&\f(CW\*(C`m\*(C'\fR.
2716 .ie n .IP """s/\fIPATTERN\fR/\fIREPLACEMENT\fR/msixpodualngcer""" 8
2717 .el .IP \f(CWs/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/msixpodualngcer\fR 8
2718 .IX Xref "s substitute substitution replace regexp, replace regexp, substitute m s i x p o g c e r"
2719 .IX Item "s/PATTERN/REPLACEMENT/msixpodualngcer"
2720 Searches a string for a pattern, and if found, replaces that pattern
2721 with the replacement text and returns the number of substitutions
2722 made. Otherwise it returns false (a value that is both an empty string (\f(CW""\fR)
2723 and numeric zero (\f(CW0\fR) as described in "Relational Operators").
2724 .Sp
2725 If the \f(CW\*(C`/r\*(C'\fR (non\-destructive) option is used then it runs the
2726 substitution on a copy of the string and instead of returning the
2727 number of substitutions, it returns the copy whether or not a
2728 substitution occurred. The original string is never changed when
2729 \&\f(CW\*(C`/r\*(C'\fR is used. The copy will always be a plain string, even if the
2730 input is an object or a tied variable.
2731 .Sp
2732 If no string is specified via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the \f(CW$_\fR
2733 variable is searched and modified. Unless the \f(CW\*(C`/r\*(C'\fR option is used,
2734 the string specified must be a scalar variable, an array element, a
2735 hash element, or an assignment to one of those; that is, some sort of
2736 scalar lvalue.
2737 .Sp
2738 If the delimiter chosen is a single quote, no variable interpolation is
2739 done on either the \fIPATTERN\fR or the \fIREPLACEMENT\fR. Otherwise, if the
2740 \&\fIPATTERN\fR contains a \f(CW\*(C`$\*(C'\fR that looks like a variable rather than an
2741 end\-of\-string test, the variable will be interpolated into the pattern
2742 at run\-time. If you want the pattern compiled only once the first time
2743 the variable is interpolated, use the \f(CW\*(C`/o\*(C'\fR option. If the pattern
2744 evaluates to the empty string, the last successfully executed regular
2745 expression is used instead. See perlre for further explanation on these.
2746 .Sp
2747 Options are as with \f(CW\*(C`m//\*(C'\fR with the addition of the following replacement
2748 specific options:
2749 .Sp
2750 .Vb 5
2751 \& e Evaluate the right side as an expression.
2752 \& ee Evaluate the right side as a string then eval the
2753 \& result.
2754 \& r Return substitution and leave the original string
2755 \& untouched.
2756 .Ve
2757 .Sp
2758 Any non\-whitespace delimiter may replace the slashes. Add space after
2759 the \f(CW\*(C`s\*(C'\fR when using a character allowed in identifiers. If single quotes
2760 are used, no interpretation is done on the replacement string (the \f(CW\*(C`/e\*(C'\fR
2761 modifier overrides this, however). Note that Perl treats backticks
2762 as normal delimiters; the replacement text is not evaluated as a command.
2763 If the \fIPATTERN\fR is delimited by bracketing quotes, the \fIREPLACEMENT\fR has
2764 its own pair of quotes, which may or may not be bracketing quotes, for example,
2765 \&\f(CW\*(C`s(foo)(bar)\*(C'\fR or \f(CW\*(C`s<foo>/bar/\*(C'\fR. A \f(CW\*(C`/e\*(C'\fR will cause the
2766 replacement portion to be treated as a full\-fledged Perl expression
2767 and evaluated right then and there. It is, however, syntax checked at
2768 compile\-time. A second \f(CW\*(C`e\*(C'\fR modifier will cause the replacement portion
2769 to be \f(CW\*(C`eval\*(C'\fRed before being run as a Perl expression.
2770 .Sp
2771 Examples:
2772 .Sp
2773 .Vb 1
2774 \& s/\ebgreen\eb/mauve/g; # don\*(Aqt change wintergreen
2775 \&
2776 \& $path =~ s|/usr/bin|/usr/local/bin|;
2777 \&
2778 \& s/Login: $foo/Login: $bar/; # run\-time pattern
2779 \&
2780 \& ($foo = $bar) =~ s/this/that/; # copy first, then
2781 \& # change
2782 \& ($foo = "$bar") =~ s/this/that/; # convert to string,
2783 \& # copy, then change
2784 \& $foo = $bar =~ s/this/that/r; # Same as above using /r
2785 \& $foo = $bar =~ s/this/that/r
2786 \& =~ s/that/the other/r; # Chained substitutes
2787 \& # using /r
2788 \& @foo = map { s/this/that/r } @bar # /r is very useful in
2789 \& # maps
2790 \&
2791 \& $count = ($paragraph =~ s/Mister\eb/Mr./g); # get change\-cnt
2792 \&
2793 \& $_ = \*(Aqabc123xyz\*(Aq;
2794 \& s/\ed+/$&*2/e; # yields \*(Aqabc246xyz\*(Aq
2795 \& s/\ed+/sprintf("%5d",$&)/e; # yields \*(Aqabc 246xyz\*(Aq
2796 \& s/\ew/$& x 2/eg; # yields \*(Aqaabbcc 224466xxyyzz\*(Aq
2797 \&
2798 \& s/%(.)/$percent{$1}/g; # change percent escapes; no /e
2799 \& s/%(.)/$percent{$1} || $&/ge; # expr now, so /e
2800 \& s/^=(\ew+)/pod($1)/ge; # use function call
2801 \&
2802 \& $_ = \*(Aqabc123xyz\*(Aq;
2803 \& $x = s/abc/def/r; # $x is \*(Aqdef123xyz\*(Aq and
2804 \& # $_ remains \*(Aqabc123xyz\*(Aq.
2805 \&
2806 \& # expand variables in $_, but dynamics only, using
2807 \& # symbolic dereferencing
2808 \& s/\e$(\ew+)/${$1}/g;
2809 \&
2810 \& # Add one to the value of any numbers in the string
2811 \& s/(\ed+)/1 + $1/eg;
2812 \&
2813 \& # Titlecase words in the last 30 characters only (presuming
2814 \& # that the substring doesn\*(Aqt start in the middle of a word)
2815 \& substr($str, \-30) =~ s/\eb(\ep{Alpha})(\ep{Alpha}*)\eb/\eu$1\eL$2/g;
2816 \&
2817 \& # This will expand any embedded scalar variable
2818 \& # (including lexicals) in $_ : First $1 is interpolated
2819 \& # to the variable name, and then evaluated
2820 \& s/(\e$\ew+)/$1/eeg;
2821 \&
2822 \& # Delete (most) C comments.
2823 \& $program =~ s {
2824 \& /\e* # Match the opening delimiter.
2825 \& .*? # Match a minimal number of characters.
2826 \& \e*/ # Match the closing delimiter.
2827 \& } []gsx;
2828 \&
2829 \& s/^\es*(.*?)\es*$/$1/; # trim whitespace in $_,
2830 \& # expensively
2831 \&
2832 \& for ($variable) { # trim whitespace in $variable,
2833 \& # cheap
2834 \& s/^\es+//;
2835 \& s/\es+$//;
2836 \& }
2837 \&
2838 \& s/([^ ]*) *([^ ]*)/$2 $1/; # reverse 1st two fields
2839 \&
2840 \& $foo !~ s/A/a/g; # Lowercase all A\*(Aqs in $foo; return
2841 \& # 0 if any were found and changed;
2842 \& # otherwise return 1
2843 .Ve
2844 .Sp
2845 Note the use of \f(CW\*(C`$\*(C'\fR instead of \f(CW\*(C`\e\*(C'\fR in the last example. Unlike
2846 \&\fBsed\fR, we use the \e<\fIdigit\fR> form only in the left hand side.
2847 Anywhere else it\*(Aqs $<\fIdigit\fR>.
2848 .Sp
2849 Occasionally, you can\*(Aqt use just a \f(CW\*(C`/g\*(C'\fR to get all the changes
2850 to occur that you might want. Here are two common cases:
2851 .Sp
2852 .Vb 2
2853 \& # put commas in the right places in an integer
2854 \& 1 while s/(\ed)(\ed\ed\ed)(?!\ed)/$1,$2/g;
2855 \&
2856 \& # expand tabs to 8\-column spacing
2857 \& 1 while s/\et+/\*(Aq \*(Aq x (length($&)*8 \- length($\`)%8)/e;
2858 .Ve
2859 .Sp
2860 While \f(CW\*(C`s///\*(C'\fR accepts the \f(CW\*(C`/c\*(C'\fR flag, it has no effect beyond
2861 producing a warning if warnings are enabled.
2862 .IX Xref " c"
2863 .PP
2864 \fITransliteration Quote\-Like Operators\fR
2865 .IX Subsection "Transliteration Quote-Like Operators"
2866 .ie n .IP """tr/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
2867 .el .IP \f(CWtr/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
2868 .IX Xref "tr y transliterate c d s"
2869 .IX Item "tr/SEARCHLIST/REPLACEMENTLIST/cdsr"
2870 .PD 0
2871 .ie n .IP """y/\fISEARCHLIST\fR/\fIREPLACEMENTLIST\fR/cdsr""" 4
2872 .el .IP \f(CWy/\fR\f(CISEARCHLIST\fR\f(CW/\fR\f(CIREPLACEMENTLIST\fR\f(CW/cdsr\fR 4
2873 .IX Item "y/SEARCHLIST/REPLACEMENTLIST/cdsr"
2874 .PD
2875 These transliterate all occurrences of the characters found (or not found
2876 if the \f(CW\*(C`/c\*(C'\fR modifier is specified) in the search list with the
2877 positionally corresponding character in the replacement list, possibly
2878 deleting some, depending on the modifiers specified. Unless the \f(CW\*(C`/r\*(C'\fR
2879 flag is specified, they return the number of characters replaced or
2880 deleted. If no string is specified via the \f(CW\*(C`=~\*(C'\fR or \f(CW\*(C`!~\*(C'\fR operator, the
2881 \&\f(CW$_\fR string is transliterated.
2882 .Sp
2883 For \fBsed\fR devotees, \f(CW\*(C`y\*(C'\fR is provided as a synonym for \f(CW\*(C`tr\*(C'\fR.
2884 .Sp
2885 If the \f(CW\*(C`/r\*(C'\fR (non\-destructive) option is present, a new copy of the string
2886 is made and its characters transliterated, and this copy is returned,
2887 instead of a count, no matter whether it was modified or not: the
2888 original string is always left unchanged. The new copy is always a
2889 plain string, even if the input string is an object or a tied variable.
2890 .Sp
2891 Unless the \f(CW\*(C`/r\*(C'\fR option is used, the string specified with \f(CW\*(C`=~\*(C'\fR must be a
2892 scalar variable, an array element, a hash element, or an assignment to one
2893 of those; in other words, an lvalue.
2894 .Sp
2895 The characters delimiting \fISEARCHLIST\fR and \fIREPLACEMENTLIST\fR
2896 can be any printable character, not just forward slashes. If they
2897 are single quotes (\f(CW\*(C`tr\*(Aq\fR\f(CISEARCHLIST\fR\f(CW\*(Aq\fR\f(CIREPLACEMENTLIST\fR\f(CW\*(Aq\*(C'\fR), the only
2898 interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR; so hyphens are
2899 interpreted literally rather than specifying a character range.
2900 .Sp
2901 Otherwise, a character range may be specified with a hyphen, so
2902 \&\f(CW\*(C`tr/A\-J/0\-9/\*(C'\fR does the same replacement as
2903 \&\f(CW\*(C`tr/ACEGIBDFHJ/0246813579/\*(C'\fR.
2904 .Sp
2905 If the \fISEARCHLIST\fR is delimited by bracketing quotes, the
2906 \&\fIREPLACEMENTLIST\fR must have its own pair of quotes, which may or may
2907 not be bracketing quotes; for example, \f(CW\*(C`tr(aeiouy)(yuoiea)\*(C'\fR or
2908 \&\f(CW\*(C`tr[+\e\-*/]"ABCD"\*(C'\fR. This final example shows a way to visually clarify
2909 what is going on for people who are more familiar with regular
2910 expression patterns than with \f(CW\*(C`tr\*(C'\fR, and who may think forward slash
2911 delimiters imply that \f(CW\*(C`tr\*(C'\fR is more like a regular expression pattern
2912 than it actually is. (Another option might be to use \f(CW\*(C`tr[...][...]\*(C'\fR.)
2913 .Sp
2914 \&\f(CW\*(C`tr\*(C'\fR isn\*(Aqt fully like bracketed character classes, just
2915 (significantly) more like them than it is to full patterns. For
2916 example, characters appearing more than once in either list behave
2917 differently here than in patterns, and \f(CW\*(C`tr\*(C'\fR lists do not allow
2918 backslashed character classes such as \f(CW\*(C`\ed\*(C'\fR or \f(CW\*(C`\epL\*(C'\fR, nor variable
2919 interpolation, so \f(CW"$"\fR and \f(CW"@"\fR are always treated as literals.
2920 .Sp
2921 The allowed elements are literals plus \f(CW\*(C`\e\*(Aq\*(C'\fR (meaning a single quote).
2922 If the delimiters aren\*(Aqt single quotes, also allowed are any of the
2923 escape sequences accepted in double\-quoted strings. Escape sequence
2924 details are in the table near the beginning of this section.
2925 .Sp
2926 A hyphen at the beginning or end, or preceded by a backslash is also
2927 always considered a literal. Precede a delimiter character with a
2928 backslash to allow it.
2929 .Sp
2930 The \f(CW\*(C`tr\*(C'\fR operator is not equivalent to the \f(CW\*(C`\fR\f(CBtr\fR\f(CW\|(1)\*(C'\fR utility.
2931 \&\f(CW\*(C`tr[a\-z][A\-Z]\*(C'\fR will uppercase the 26 letters "a" through "z", but for
2932 case changing not confined to ASCII, use \f(CW\*(C`lc\*(C'\fR,
2933 \&\f(CW\*(C`uc\*(C'\fR, \f(CW\*(C`lcfirst\*(C'\fR,
2934 \&\f(CW\*(C`ucfirst\*(C'\fR (all documented in perlfunc), or the
2935 substitution operator
2936 \&\f(CW\*(C`s/\fR\f(CIPATTERN\fR\f(CW/\fR\f(CIREPLACEMENT\fR\f(CW/\*(C'\fR
2937 (with \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, and \f(CW\*(C`\el\*(C'\fR string\-interpolation escapes in the
2938 \&\fIREPLACEMENT\fR portion).
2939 .Sp
2940 Most ranges are unportable between character sets, but certain ones
2941 signal Perl to do special handling to make them portable. There are two
2942 classes of portable ranges. The first are any subsets of the ranges
2943 \&\f(CW\*(C`A\-Z\*(C'\fR, \f(CW\*(C`a\-z\*(C'\fR, and \f(CW\*(C`0\-9\*(C'\fR, when expressed as literal characters.
2944 .Sp
2945 .Vb 1
2946 \& tr/h\-k/H\-K/
2947 .Ve
2948 .Sp
2949 capitalizes the letters \f(CW"h"\fR, \f(CW"i"\fR, \f(CW"j"\fR, and \f(CW"k"\fR and nothing
2950 else, no matter what the platform\*(Aqs character set is. In contrast, all
2951 of
2952 .Sp
2953 .Vb 3
2954 \& tr/\ex68\-\ex6B/\ex48\-\ex4B/
2955 \& tr/h\-\ex6B/H\-\ex4B/
2956 \& tr/\ex68\-k/\ex48\-K/
2957 .Ve
2958 .Sp
2959 do the same capitalizations as the previous example when run on ASCII
2960 platforms, but something completely different on EBCDIC ones.
2961 .Sp
2962 The second class of portable ranges is invoked when one or both of the
2963 range\*(Aqs end points are expressed as \f(CW\*(C`\eN{...}\*(C'\fR
2964 .Sp
2965 .Vb 1
2966 \& $string =~ tr/\eN{U+20}\-\eN{U+7E}//d;
2967 .Ve
2968 .Sp
2969 removes from \f(CW$string\fR all the platform\*(Aqs characters which are
2970 equivalent to any of Unicode U+0020, U+0021, ... U+007D, U+007E. This
2971 is a portable range, and has the same effect on every platform it is
2972 run on. In this example, these are the ASCII
2973 printable characters. So after this is run, \f(CW$string\fR has only
2974 controls and characters which have no ASCII equivalents.
2975 .Sp
2976 But, even for portable ranges, it is not generally obvious what is
2977 included without having to look things up in the manual. A sound
2978 principle is to use only ranges that both begin from, and end at, either
2979 ASCII alphabetics of equal case (\f(CW\*(C`b\-e\*(C'\fR, \f(CW\*(C`B\-E\*(C'\fR), or digits (\f(CW\*(C`1\-4\*(C'\fR).
2980 Anything else is unclear (and unportable unless \f(CW\*(C`\eN{...}\*(C'\fR is used). If
2981 in doubt, spell out the character sets in full.
2982 .Sp
2983 Options:
2984 .Sp
2985 .Vb 5
2986 \& c Complement the SEARCHLIST.
2987 \& d Delete found but unreplaced characters.
2988 \& r Return the modified string instead of a count, and leave the
2989 \& original string untouched.
2990 \& s Squash duplicate replaced characters.
2991 .Ve
2992 .Sp
2993 If the \f(CW\*(C`/d\*(C'\fR modifier is specified, any characters specified by
2994 \&\fISEARCHLIST\fR not found in \fIREPLACEMENTLIST\fR are deleted. (Note that
2995 this is slightly more flexible than the behavior of some \fBtr\fR programs,
2996 which delete anything they find in the \fISEARCHLIST\fR, period.)
2997 .Sp
2998 If the \f(CW\*(C`/s\*(C'\fR modifier is specified, sequences of characters, all in a
2999 row, that were transliterated to the same character are squashed down to
3000 a single instance of that character.
3001 .Sp
3002 .Vb 2
3003 \& my $x = "aaabbbca";
3004 \& $x =~ tr/ab/dd/s; # $x now is "dcd"
3005 .Ve
3006 .Sp
3007 If the \f(CW\*(C`/d\*(C'\fR modifier is used, the \fIREPLACEMENTLIST\fR is always interpreted
3008 exactly as specified. Otherwise, if the \fIREPLACEMENTLIST\fR is shorter
3009 than the \fISEARCHLIST\fR, the final character, if any, is replicated until
3010 it is long enough. There won\*(Aqt be a final character if and only if the
3011 \&\fIREPLACEMENTLIST\fR is empty, in which case \fIREPLACEMENTLIST\fR is
3012 copied from \fISEARCHLIST\fR. An empty \fIREPLACEMENTLIST\fR is useful
3013 for counting characters in a class, or for squashing character sequences
3014 in a class.
3015 .Sp
3016 .Vb 4
3017 \& tr/abcd// tr/abcd/abcd/
3018 \& tr/abcd/AB/ tr/abcd/ABBB/
3019 \& tr/abcd//d s/[abcd]//g
3020 \& tr/abcd/AB/d (tr/ab/AB/ + s/[cd]//g) \- but run together
3021 .Ve
3022 .Sp
3023 If the \f(CW\*(C`/c\*(C'\fR modifier is specified, the characters to be transliterated
3024 are the ones NOT in \fISEARCHLIST\fR, that is, it is complemented. If
3025 \&\f(CW\*(C`/d\*(C'\fR and/or \f(CW\*(C`/s\*(C'\fR are also specified, they apply to the complemented
3026 \&\fISEARCHLIST\fR. Recall, that if \fIREPLACEMENTLIST\fR is empty (except
3027 under \f(CW\*(C`/d\*(C'\fR) a copy of \fISEARCHLIST\fR is used instead. That copy is made
3028 after complementing under \f(CW\*(C`/c\*(C'\fR. \fISEARCHLIST\fR is sorted by code point
3029 order after complementing, and any \fIREPLACEMENTLIST\fR is applied to
3030 that sorted result. This means that under \f(CW\*(C`/c\*(C'\fR, the order of the
3031 characters specified in \fISEARCHLIST\fR is irrelevant. This can
3032 lead to different results on EBCDIC systems if \fIREPLACEMENTLIST\fR
3033 contains more than one character, hence it is generally non\-portable to
3034 use \f(CW\*(C`/c\*(C'\fR with such a \fIREPLACEMENTLIST\fR.
3035 .Sp
3036 Another way of describing the operation is this:
3037 If \f(CW\*(C`/c\*(C'\fR is specified, the \fISEARCHLIST\fR is sorted by code point order,
3038 then complemented. If \fIREPLACEMENTLIST\fR is empty and \f(CW\*(C`/d\*(C'\fR is not
3039 specified, \fIREPLACEMENTLIST\fR is replaced by a copy of \fISEARCHLIST\fR (as
3040 modified under \f(CW\*(C`/c\*(C'\fR), and these potentially modified lists are used as
3041 the basis for what follows. Any character in the target string that
3042 isn\*(Aqt in \fISEARCHLIST\fR is passed through unchanged. Every other
3043 character in the target string is replaced by the character in
3044 \&\fIREPLACEMENTLIST\fR that positionally corresponds to its mate in
3045 \&\fISEARCHLIST\fR, except that under \f(CW\*(C`/s\*(C'\fR, the 2nd and following characters
3046 are squeezed out in a sequence of characters in a row that all translate
3047 to the same character. If \fISEARCHLIST\fR is longer than
3048 \&\fIREPLACEMENTLIST\fR, characters in the target string that match a
3049 character in \fISEARCHLIST\fR that doesn\*(Aqt have a correspondence in
3050 \&\fIREPLACEMENTLIST\fR are either deleted from the target string if \f(CW\*(C`/d\*(C'\fR is
3051 specified; or replaced by the final character in \fIREPLACEMENTLIST\fR if
3052 \&\f(CW\*(C`/d\*(C'\fR isn\*(Aqt specified.
3053 .Sp
3054 Some examples:
3055 .Sp
3056 .Vb 1
3057 \& $ARGV[1] =~ tr/A\-Z/a\-z/; # canonicalize to lower case ASCII
3058 \&
3059 \& $cnt = tr/*/*/; # count the stars in $_
3060 \& $cnt = tr/*//; # same thing
3061 \&
3062 \& $cnt = $sky =~ tr/*/*/; # count the stars in $sky
3063 \& $cnt = $sky =~ tr/*//; # same thing
3064 \&
3065 \& $cnt = $sky =~ tr/*//c; # count all the non\-stars in $sky
3066 \& $cnt = $sky =~ tr/*/*/c; # same, but transliterate each non\-star
3067 \& # into a star, leaving the already\-stars
3068 \& # alone. Afterwards, everything in
3069 \& # $sky is a star.
3070 \&
3071 \& $cnt = tr/0\-9//; # count the ASCII digits in $_
3072 \&
3073 \& tr/a\-zA\-Z//s; # bookkeeper \-> bokeper
3074 \& tr/o/o/s; # bookkeeper \-> bokkeeper
3075 \& tr/oe/oe/s; # bookkeeper \-> bokkeper
3076 \& tr/oe//s; # bookkeeper \-> bokkeper
3077 \& tr/oe/o/s; # bookkeeper \-> bokkopor
3078 \&
3079 \& ($HOST = $host) =~ tr/a\-z/A\-Z/;
3080 \& $HOST = $host =~ tr/a\-z/A\-Z/r; # same thing
3081 \&
3082 \& $HOST = $host =~ tr/a\-z/A\-Z/r # chained with s///r
3083 \& =~ s/:/ \-p/r;
3084 \&
3085 \& tr/a\-zA\-Z/ /cs; # change non\-alphas to single space
3086 \&
3087 \& @stripped = map tr/a\-zA\-Z/ /csr, @original;
3088 \& # /r with map
3089 \&
3090 \& tr [\e200\-\e377]
3091 \& [\e000\-\e177]; # wickedly delete 8th bit
3092 \&
3093 \& $foo !~ tr/A/a/ # transliterate all the A\*(Aqs in $foo to \*(Aqa\*(Aq,
3094 \& # return 0 if any were found and changed.
3095 \& # Otherwise return 1
3096 .Ve
3097 .Sp
3098 If multiple transliterations are given for a character, only the
3099 first one is used:
3100 .Sp
3101 .Vb 1
3102 \& tr/AAA/XYZ/
3103 .Ve
3104 .Sp
3105 will transliterate any A to X.
3106 .Sp
3107 Because the transliteration table is built at compile time, neither
3108 the \fISEARCHLIST\fR nor the \fIREPLACEMENTLIST\fR are subjected to double quote
3109 interpolation. That means that if you want to use variables, you
3110 must use an \f(CWeval()\fR:
3111 .Sp
3112 .Vb 2
3113 \& eval "tr/$oldlist/$newlist/";
3114 \& die $@ if $@;
3115 \&
3116 \& eval "tr/$oldlist/$newlist/, 1" or die $@;
3117 .Ve
3118 .PP
3119 \fIHere\-docs\fR
3120 .IX Xref "here-doc here-docs heredoc here-document <<"
3121 .IX Subsection "Here-docs"
3122 .ie n .IP """<<\fIEOT\fR""" 4
3123 .el .IP \f(CW<<\fR\f(CIEOT\fR\f(CW\fR 4
3124 .IX Item "<<EOT"
3125 .PD 0
3126 .ie n .IP """<<~\fIEOT\fR""" 4
3127 .el .IP \f(CW<<~\fR\f(CIEOT\fR\f(CW\fR 4
3128 .IX Item "<<~EOT"
3129 .PD
3130 A line\-oriented form of quoting is based on the shell "here\-document"
3131 syntax. Following a \f(CW\*(C`<<\*(C'\fR you specify a string to terminate
3132 the quoted material, and all lines following the current line down to
3133 the terminating string are the value of the item.
3134 .Sp
3135 An example is
3136 .Sp
3137 .Vb 5
3138 \& my $endng = <<WHIMPER;
3139 \& This is the way the text ends.
3140 \& This is the way the text ends.
3141 \& Not with a bang, but with a
3142 \& WHIMPER
3143 .Ve
3144 .Sp
3145 In this case, the terminator is an identifier, the word "WHIMPER". Most
3146 usually, people capitalize the identifier, just so it stands out, but
3147 this is just a convention that isn\*(Aqt necessary.
3148 .Sp
3149 The terminator may be enclosed in quotes, as detailed below, but without
3150 them, the text of the here\-doc acts exactly as if it were double\-quoted.
3151 .Sp
3152 .Vb 1
3153 \& my $person = \*(AqJohn\*(Aq;
3154 \&
3155 \& print uc <<EOT;
3156 \& Hello, $person!
3157 \& And the text goes on.
3158 \& EOT
3159 .Ve
3160 .Sp
3161 This yields:
3162 .Sp
3163 .Vb 2
3164 \& HELLO, JOHN!
3165 \& AND THE TEXT GOES ON.
3166 .Ve
3167 .Sp
3168 The parentheses in the \f(CW\*(C`uc\*(C'\fR function call don\*(Aqt have to be omitted:
3169 .Sp
3170 .Vb 4
3171 \& print uc(<<EOT);
3172 \& Hello, $person!
3173 \& And the text goes on.
3174 \& EOT
3175 \&
3176 \& HELLO, JOHN!
3177 \& AND THE TEXT GOES ON.
3178 .Ve
3179 .Sp
3180 And you can intermix a here\-document with other things:
3181 .Sp
3182 .Vb 4
3183 \& print <<EOT, "Followed by the next argument\en";
3184 \& Hello, $person!
3185 \& And the text goes on.
3186 \& EOT
3187 \&
3188 \& Hello, John!
3189 \& And the text goes on.
3190 \& Followed by the next argument
3191 .Ve
3192 .Sp
3193 And you can have multiple here\-documents:
3194 .Sp
3195 .Vb 6
3196 \& print <<EOT1, <<EOT2;
3197 \& Hello, $person!
3198 \& And the text goes on.
3199 \& EOT1
3200 \& Followed by the next argument
3201 \& EOT2
3202 \&
3203 \& Hello, John!
3204 \& And the text goes on.
3205 \& Followed by the next argument
3206 .Ve
3207 .Sp
3208 The terminator doesn\*(Aqt have to be a single word; it may also be some
3209 quoted text:
3210 .Sp
3211 .Vb 6
3212 \& my $pagliaci = << "La Commedia e finita!";
3213 \& A troupe comes to town to perform a play, a comedy. The lead actress
3214 \& and lead actor are in an unhappy marriage. On stage, he stabs her
3215 \& for real; then he stabs her lover who has rushed from the audience to
3216 \& defend her. Both die.
3217 \& La Commedia e finita!
3218 .Ve
3219 .Sp
3220 There may not be a space between the \f(CW\*(C`<<\*(C'\fR and the identifier unless
3221 the terminator is quoted, as demonstrated in the example just above.
3222 Quoting rules for the terminator are unrelated to Perl\*(Aqs quoting rules.
3223 Only \f(CW""\fR, \f(CW\*(Aq\*(Aq\fR, and \f(CW\`\`\fR can be used to quote it, NOT \f(CWq()\fR,
3224 \&\f(CWqq()\fR, and the like. The only interpolation is for backslashing the
3225 quoting character:
3226 .Sp
3227 .Vb 3
3228 \& print << "abc\e"def";
3229 \& testing...
3230 \& abc"def
3231 .Ve
3232 .Sp
3233 The terminating string must appear by itself (unquoted and with no
3234 surrounding whitespace) on the terminating line. Also, it cannot span
3235 multiple lines. The general rule is that the identifier must be a
3236 string literal. Stick with that, and you should be safe.
3237 .Sp
3238 Don\*(Aqt forget that you have to put a semicolon on the end to finish the
3239 statement, as Perl doesn\*(Aqt know you\*(Aqre not going to try to do this:
3240 .Sp
3241 .Vb 4
3242 \& print <<ABC
3243 \& 10
3244 \& ABC
3245 \& + 20;
3246 .Ve
3247 .Sp
3248 which prints \f(CW30\fR and no line terminator.
3249 .Sp
3250 If you want your here\-doc to not have a line terminator on the final
3251 line, use \f(CWchomp()\fR.
3252 .Sp
3253 .Vb 4
3254 \& chomp($string = <<\*(AqEND\*(Aq);
3255 \& This is the first line.
3256 \& This second line won\*(Aqt end in a \en.
3257 \& END
3258 .Ve
3259 .Sp
3260 If you use a here\-doc within a delimited construct, such as in \f(CW\*(C`s///eg\*(C'\fR,
3261 the quoted material must still come on the line following the
3262 \&\f(CW\*(C`<<TERMINATOR\*(C'\fR marker, which means it may be inside the delimited
3263 construct:
3264 .Sp
3265 .Vb 4
3266 \& s/this/<<E . \*(Aqthat\*(Aq
3267 \& the other
3268 \& E
3269 \& . \*(Aqmore \*(Aq/eg;
3270 .Ve
3271 .Sp
3272 (It works this way as of Perl 5.18. Historically, it was inconsistent, and
3273 you would have to write
3274 .Sp
3275 .Vb 4
3276 \& s/this/<<E . \*(Aqthat\*(Aq
3277 \& . \*(Aqmore \*(Aq/eg;
3278 \& the other
3279 \& E
3280 .Ve
3281 .Sp
3282 outside of string evals.)
3283 .Sp
3284 A problem with the Here\-doc syntax given so far is that it must be at the
3285 left margin of your program, messing up the indentation. Starting in
3286 Perl v5.26, the tilde \f(CW\*(C`~\*(C'\fR modifier allows you to indent your here\-docs
3287 to make the code more readable.
3288 .Sp
3289 .Vb 5
3290 \& if ($some_var) {
3291 \& print <<~EOF;
3292 \& This is a here\-doc
3293 \& EOF
3294 \& }
3295 .Ve
3296 .Sp
3297 This will print...
3298 .Sp
3299 .Vb 1
3300 \& This is a here\-doc
3301 .Ve
3302 .Sp
3303 \&...with no leading whitespace.
3304 .Sp
3305 The line containing the delimiter that marks the end of the here\-doc
3306 determines the indentation template for the whole thing. Compilation
3307 croaks if any non\-empty line inside the here\-doc does not begin with the
3308 precise indentation of the terminating line. (An empty line consists of
3309 the single character "\en".) For example, suppose the terminating line
3310 begins with a tab character followed by 4 space characters. Every
3311 non\-empty line in the here\-doc must begin with a tab followed by 4
3312 spaces. They are stripped from each line, and any leading white space
3313 remaining on a line serves as the indentation for that line. Currently,
3314 only the TAB and SPACE characters are treated as whitespace for this
3315 purpose. Tabs and spaces may be mixed, but are matched exactly; tabs
3316 remain tabs and are not expanded.
3317 .Sp
3318 Additional beginning whitespace (beyond what preceded the
3319 delimiter) will be preserved:
3320 .Sp
3321 .Vb 7
3322 \& print <<~EOF;
3323 \& This text is not indented
3324 \& This text is indented with two spaces
3325 \& This line is indented with two tabs, though those may
3326 \& have been converted to spaces by various filters by
3327 \& the time you read this.
3328 \& EOF
3329 .Ve
3330 .PP
3331 Quoting the delimiter
3332 .IX Subsection "Quoting the delimiter"
3333 .PP
3334 As mentioned above, the terminating string may be quoted. There are
3335 three types of quoting possible. The type used determines the treatment
3336 of the text.
3337 .IP "Double Quotes" 4
3338 .IX Item "Double Quotes"
3339 Double quotes surrounding the terminating word or string behave as if
3340 no quotes were there, namely the text will be interpolated using exactly
3341 the same rules as normal double quoted strings, as in all the examples
3342 above. So
3343 .Sp
3344 .Vb 1
3345 \& my $person = \*(AqJohn\*(Aq;
3346 \&
3347 \& print uc << "EOT";
3348 \& Hello, $person!
3349 \& And the text goes on.
3350 \& EOT
3351 .Ve
3352 .Sp
3353 yields:
3354 .Sp
3355 .Vb 2
3356 \& HELLO, JOHN!
3357 \& AND THE TEXT GOES ON.
3358 .Ve
3359 .Sp
3360 which is the same result as without quotes.
3361 .IP "Single Quotes" 4
3362 .IX Item "Single Quotes"
3363 If instead, single quotes are used, the text is treated literally, with
3364 no interpolation of its content.
3365 .Sp
3366 .Vb 5
3367 \& my $person = \*(AqJohn\*(Aq;
3368 \& print uc <<\*(AqEOT\*(Aq;
3369 \& Hello, $person!
3370 \& And the text goes on.
3371 \& EOT
3372 \&
3373 \& HELLO, $PERSON!
3374 \& AND THE TEXT GOES ON.
3375 .Ve
3376 .Sp
3377 The difference between a single\-quoted here\-doc and a single\-quoted
3378 string is that backslashes have no special meaning in a here\-doc, with
3379 \&\f(CW\*(C`\e\e\*(C'\fR being treated as two backslashes and not one as they would in
3380 every other quoting construct.
3381 .Sp
3382 Just as in the shell, a backslashed bareword following the \f(CW\*(C`<<\*(C'\fR
3383 means the same thing as a single\-quoted string does:
3384 .Sp
3385 .Vb 3
3386 \& $cost = <<\*(AqVISTA\*(Aq; # hasta la ...
3387 \& That\*(Aqll be $10 please, ma\*(Aqam.
3388 \& VISTA
3389 \&
3390 \& $cost = <<\eVISTA; # Same thing!
3391 \& That\*(Aqll be $10 please, ma\*(Aqam.
3392 \& VISTA
3393 .Ve
3394 .Sp
3395 These two forms are the only ways of quoting in Perl where there is no
3396 need to worry about escaping content, something that code generators can
3397 and do make good use of.
3398 .IP Backticks 4
3399 .IX Item "Backticks"
3400 Finally, if instead backticks are used to quote the terminating string,
3401 the content of the here doc is treated just as it would be if it were a
3402 string embedded in backticks. Thus the content is interpolated as
3403 though it were double quoted and then executed via the shell, with the
3404 results of the execution returned.
3405 .Sp
3406 .Vb 3
3407 \& print << \`EOC\`; # execute command and get results
3408 \& echo hi there
3409 \& EOC
3410 .Ve
3411 .PP
3412 \fIGory details of parsing quoted constructs\fR
3413 .IX Xref "quote, gory details"
3414 .IX Subsection "Gory details of parsing quoted constructs"
3415 .PP
3416 When presented with something that might have several different
3417 interpretations, Perl uses the \fBDWIM\fR (that\*(Aqs "Do What I Mean")
3418 principle to pick the most probable interpretation. This strategy
3419 is so successful that Perl programmers often do not suspect the
3420 ambiguity of what they write. But from time to time, Perl\*(Aqs
3421 notions differ substantially from what the author honestly meant.
3422 .PP
3423 This section hopes to clarify how Perl handles quoted constructs.
3424 Although the most common reason to learn this is to unravel labyrinthine
3425 regular expressions, because the initial steps of parsing are the
3426 same for all quoting operators, they are all discussed together.
3427 .PP
3428 The most important Perl parsing rule is the first one discussed
3429 below: when processing a quoted construct, Perl first finds the end
3430 of that construct, then interprets its contents. If you understand
3431 this rule, you may skip the rest of this section on the first
3432 reading. The other rules are likely to contradict the user\*(Aqs
3433 expectations much less frequently than this first one.
3434 .PP
3435 Some passes discussed below are performed concurrently, but because
3436 their results are the same, we consider them individually. For different
3437 quoting constructs, Perl performs different numbers of passes, from
3438 one to four, but these passes are always performed in the same order.
3439 .IP "Finding the end" 4
3440 .IX Item "Finding the end"
3441 The first pass is finding the end of the quoted construct. This results
3442 in saving to a safe location a copy of the text (between the starting
3443 and ending delimiters), normalized as necessary to avoid needing to know
3444 what the original delimiters were.
3445 .Sp
3446 If the construct is a here\-doc, the ending delimiter is a line
3447 that has a terminating string as the content. Therefore \f(CW\*(C`<<EOF\*(C'\fR is
3448 terminated by \f(CW\*(C`EOF\*(C'\fR immediately followed by \f(CW"\en"\fR and starting
3449 from the first column of the terminating line.
3450 When searching for the terminating line of a here\-doc, nothing
3451 is skipped. In other words, lines after the here\-doc syntax
3452 are compared with the terminating string line by line.
3453 .Sp
3454 For the constructs except here\-docs, single characters are used as starting
3455 and ending delimiters. If the starting delimiter is an opening punctuation
3456 (that is \f(CW\*(C`(\*(C'\fR, \f(CW\*(C`[\*(C'\fR, \f(CW\*(C`{\*(C'\fR, or \f(CW\*(C`<\*(C'\fR), the ending delimiter is the
3457 corresponding closing punctuation (that is \f(CW\*(C`)\*(C'\fR, \f(CW\*(C`]\*(C'\fR, \f(CW\*(C`}\*(C'\fR, or \f(CW\*(C`>\*(C'\fR).
3458 If the starting delimiter is an unpaired character like \f(CW\*(C`/\*(C'\fR or a closing
3459 punctuation, the ending delimiter is the same as the starting delimiter.
3460 Therefore a \f(CW\*(C`/\*(C'\fR terminates a \f(CW\*(C`qq//\*(C'\fR construct, while a \f(CW\*(C`]\*(C'\fR terminates
3461 both \f(CW\*(C`qq[]\*(C'\fR and \f(CW\*(C`qq]]\*(C'\fR constructs.
3462 .Sp
3463 When searching for single\-character delimiters, escaped delimiters
3464 and \f(CW\*(C`\e\e\*(C'\fR are skipped. For example, while searching for terminating \f(CW\*(C`/\*(C'\fR,
3465 combinations of \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e/\*(C'\fR are skipped. If the delimiters are
3466 bracketing, nested pairs are also skipped. For example, while searching
3467 for a closing \f(CW\*(C`]\*(C'\fR paired with the opening \f(CW\*(C`[\*(C'\fR, combinations of \f(CW\*(C`\e\e\*(C'\fR, \f(CW\*(C`\e]\*(C'\fR,
3468 and \f(CW\*(C`\e[\*(C'\fR are all skipped, and nested \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR are skipped as well.
3469 However, when backslashes are used as the delimiters (like \f(CW\*(C`qq\e\e\*(C'\fR and
3470 \&\f(CW\*(C`tr\e\e\e\*(C'\fR), nothing is skipped.
3471 During the search for the end, backslashes that escape delimiters or
3472 other backslashes are removed (exactly speaking, they are not copied to the
3473 safe location).
3474 .Sp
3475 For constructs with three\-part delimiters (\f(CW\*(C`s///\*(C'\fR, \f(CW\*(C`y///\*(C'\fR, and
3476 \&\f(CW\*(C`tr///\*(C'\fR), the search is repeated once more.
3477 If the first delimiter is not an opening punctuation, the three delimiters must
3478 be the same, such as \f(CW\*(C`s!!!\*(C'\fR and \f(CW\*(C`tr)))\*(C'\fR,
3479 in which case the second delimiter
3480 terminates the left part and starts the right part at once.
3481 If the left part is delimited by bracketing punctuation (that is \f(CW\*(C`()\*(C'\fR,
3482 \&\f(CW\*(C`[]\*(C'\fR, \f(CW\*(C`{}\*(C'\fR, or \f(CW\*(C`<>\*(C'\fR), the right part needs another pair of
3483 delimiters such as \f(CW\*(C`s(){}\*(C'\fR and \f(CW\*(C`tr[]//\*(C'\fR. In these cases, whitespace
3484 and comments are allowed between the two parts, although the comment must follow
3485 at least one whitespace character; otherwise a character expected as the
3486 start of the comment may be regarded as the starting delimiter of the right part.
3487 .Sp
3488 During this search no attention is paid to the semantics of the construct.
3489 Thus:
3490 .Sp
3491 .Vb 1
3492 \& "$hash{"$foo/$bar"}"
3493 .Ve
3494 .Sp
3495 or:
3496 .Sp
3497 .Vb 3
3498 \& m/
3499 \& bar # NOT a comment, this slash / terminated m//!
3500 \& /x
3501 .Ve
3502 .Sp
3503 do not form legal quoted expressions. The quoted part ends on the
3504 first \f(CW\*(C`"\*(C'\fR and \f(CW\*(C`/\*(C'\fR, and the rest happens to be a syntax error.
3505 Because the slash that terminated \f(CW\*(C`m//\*(C'\fR was followed by a \f(CW\*(C`SPACE\*(C'\fR,
3506 the example above is not \f(CW\*(C`m//x\*(C'\fR, but rather \f(CW\*(C`m//\*(C'\fR with no \f(CW\*(C`/x\*(C'\fR
3507 modifier. So the embedded \f(CW\*(C`#\*(C'\fR is interpreted as a literal \f(CW\*(C`#\*(C'\fR.
3508 .Sp
3509 Also no attention is paid to \f(CW\*(C`\ec\e\*(C'\fR (multichar control char syntax) during
3510 this search. Thus the second \f(CW\*(C`\e\*(C'\fR in \f(CW\*(C`qq/\ec\e/\*(C'\fR is interpreted as a part
3511 of \f(CW\*(C`\e/\*(C'\fR, and the following \f(CW\*(C`/\*(C'\fR is not recognized as a delimiter.
3512 Instead, use \f(CW\*(C`\e034\*(C'\fR or \f(CW\*(C`\ex1c\*(C'\fR at the end of quoted constructs.
3513 .IP Interpolation 4
3514 .IX Xref "interpolation"
3515 .IX Item "Interpolation"
3516 The next step is interpolation in the text obtained, which is now
3517 delimiter\-independent. There are multiple cases.
3518 .RS 4
3519 .ie n .IP """<<\*(AqEOF\*(Aq""" 4
3520 .el .IP \f(CW<<\*(AqEOF\*(Aq\fR 4
3521 .IX Item "<<'EOF'"
3522 No interpolation is performed.
3523 Note that the combination \f(CW\*(C`\e\e\*(C'\fR is left intact, since escaped delimiters
3524 are not available for here\-docs.
3525 .ie n .IP """m\*(Aq\*(Aq"", the pattern of ""s\*(Aq\*(Aq\*(Aq""" 4
3526 .el .IP "\f(CWm\*(Aq\*(Aq\fR, the pattern of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
3527 .IX Item "m'', the pattern of s'''"
3528 No interpolation is performed at this stage.
3529 Any backslashed sequences including \f(CW\*(C`\e\e\*(C'\fR are treated at the stage
3530 of "Parsing regular expressions".
3531 .ie n .IP "\*(Aq\*(Aq, ""q//"", ""tr\*(Aq\*(Aq\*(Aq"", ""y\*(Aq\*(Aq\*(Aq"", the replacement of ""s\*(Aq\*(Aq\*(Aq""" 4
3532 .el .IP "\f(CW\*(Aq\*(Aq\fR, \f(CWq//\fR, \f(CWtr\*(Aq\*(Aq\*(Aq\fR, \f(CWy\*(Aq\*(Aq\*(Aq\fR, the replacement of \f(CWs\*(Aq\*(Aq\*(Aq\fR" 4
3533 .IX Item "'', q//, tr''', y''', the replacement of s'''"
3534 The only interpolation is removal of \f(CW\*(C`\e\*(C'\fR from pairs of \f(CW\*(C`\e\e\*(C'\fR.
3535 Therefore \f(CW"\-"\fR in \f(CW\*(C`tr\*(Aq\*(Aq\*(Aq\*(C'\fR and \f(CW\*(C`y\*(Aq\*(Aq\*(Aq\*(C'\fR is treated literally
3536 as a hyphen and no character range is available.
3537 \&\f(CW\*(C`\e1\*(C'\fR in the replacement of \f(CW\*(C`s\*(Aq\*(Aq\*(Aq\*(C'\fR does not work as \f(CW$1\fR.
3538 .ie n .IP """tr///"", ""y///""" 4
3539 .el .IP "\f(CWtr///\fR, \f(CWy///\fR" 4
3540 .IX Item "tr///, y///"
3541 No variable interpolation occurs. String modifying combinations for
3542 case and quoting such as \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, and \f(CW\*(C`\eE\*(C'\fR are not recognized.
3543 The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
3544 characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are converted to appropriate literals.
3545 The character \f(CW"\-"\fR is treated specially and therefore \f(CW\*(C`\e\-\*(C'\fR is treated
3546 as a literal \f(CW"\-"\fR.
3547 .ie n .IP """"", \`\`, ""qq//"", ""qx//"", ""<file*glob>"", ""<<""EOF""""" 4
3548 .el .IP "\f(CW""""\fR, \f(CW\`\`\fR, \f(CWqq//\fR, \f(CWqx//\fR, \f(CW<file*glob>\fR, \f(CW<<""EOF""\fR" 4
3549 .IX Item """"", ``, qq//, qx//, <file*glob>, <<""EOF"""
3550 \&\f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR (possibly paired with \f(CW\*(C`\eE\*(C'\fR) are
3551 converted to corresponding Perl constructs. Thus, \f(CW"$foo\eQbaz$bar"\fR
3552 is converted to \f(CW\*(C`$foo\ .\ (quotemeta("baz"\ .\ $bar))\*(C'\fR internally.
3553 The other escape sequences such as \f(CW\*(C`\e200\*(C'\fR and \f(CW\*(C`\et\*(C'\fR and backslashed
3554 characters such as \f(CW\*(C`\e\e\*(C'\fR and \f(CW\*(C`\e\-\*(C'\fR are replaced with appropriate
3555 expansions.
3556 .Sp
3557 Let it be stressed that \fIwhatever falls between \fR\f(CI\*(C`\eQ\*(C'\fR\fI and \fR\f(CI\*(C`\eE\*(C'\fR
3558 is interpolated in the usual way. Something like \f(CW"\eQ\e\eE"\fR has
3559 no \f(CW\*(C`\eE\*(C'\fR inside. Instead, it has \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\e\e\*(C'\fR, and \f(CW\*(C`E\*(C'\fR, so the
3560 result is the same as for \f(CW"\e\e\e\eE"\fR. As a general rule, backslashes
3561 between \f(CW\*(C`\eQ\*(C'\fR and \f(CW\*(C`\eE\*(C'\fR may lead to counterintuitive results. So,
3562 \&\f(CW"\eQ\et\eE"\fR is converted to \f(CWquotemeta("\et")\fR, which is the same
3563 as \f(CW"\e\e\et"\fR (since TAB is not alphanumeric). Note also that:
3564 .Sp
3565 .Vb 2
3566 \& $str = \*(Aq\et\*(Aq;
3567 \& return "\eQ$str";
3568 .Ve
3569 .Sp
3570 may be closer to the conjectural \fIintention\fR of the writer of \f(CW"\eQ\et\eE"\fR.
3571 .Sp
3572 Interpolated scalars and arrays are converted internally to the \f(CW\*(C`join\*(C'\fR and
3573 \&\f(CW"."\fR catenation operations. Thus, \f(CW"$foo\ XXX\ \*(Aq@arr\*(Aq"\fR becomes:
3574 .Sp
3575 .Vb 1
3576 \& $foo . " XXX \*(Aq" . (join $", @arr) . "\*(Aq";
3577 .Ve
3578 .Sp
3579 All operations above are performed simultaneously, left to right.
3580 .Sp
3581 Because the result of \f(CW"\eQ\ \fR\f(CISTRING\fR\f(CW\ \eE"\fR has all metacharacters
3582 quoted, there is no way to insert a literal \f(CW\*(C`$\*(C'\fR or \f(CW\*(C`@\*(C'\fR inside a
3583 \&\f(CW\*(C`\eQ\eE\*(C'\fR pair. If protected by \f(CW\*(C`\e\*(C'\fR, \f(CW\*(C`$\*(C'\fR will be quoted to become
3584 \&\f(CW"\e\e\e$"\fR; if not, it is interpreted as the start of an interpolated
3585 scalar.
3586 .Sp
3587 Note also that the interpolation code needs to make a decision on
3588 where the interpolated scalar ends. For instance, whether
3589 \&\f(CW"a\ $x\ \->\ {c}"\fR really means:
3590 .Sp
3591 .Vb 1
3592 \& "a " . $x . " \-> {c}";
3593 .Ve
3594 .Sp
3595 or:
3596 .Sp
3597 .Vb 1
3598 \& "a " . $x \-> {c};
3599 .Ve
3600 .Sp
3601 Most of the time, the longest possible text that does not include
3602 spaces between components and which contains matching braces or
3603 brackets. because the outcome may be determined by voting based
3604 on heuristic estimators, the result is not strictly predictable.
3605 Fortunately, it\*(Aqs usually correct for ambiguous cases.
3606 .ie n .IP "The replacement of ""s///""" 4
3607 .el .IP "The replacement of \f(CWs///\fR" 4
3608 .IX Item "The replacement of s///"
3609 Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR and interpolation
3610 happens as with \f(CW\*(C`qq//\*(C'\fR constructs.
3611 .Sp
3612 It is at this step that \f(CW\*(C`\e1\*(C'\fR is begrudgingly converted to \f(CW$1\fR in
3613 the replacement text of \f(CW\*(C`s///\*(C'\fR, in order to correct the incorrigible
3614 \&\fIsed\fR hackers who haven\*(Aqt picked up the saner idiom yet. A warning
3615 is emitted if the \f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR command\-line flag
3616 (that is, the \f(CW$^W\fR variable) was set.
3617 .ie n .IP """RE"" in ""m?RE?"", ""/RE/"", ""m/RE/"", ""s/RE/foo/""," 4
3618 .el .IP "\f(CWRE\fR in \f(CWm?RE?\fR, \f(CW/RE/\fR, \f(CWm/RE/\fR, \f(CWs/RE/foo/\fR," 4
3619 .IX Item "RE in m?RE?, /RE/, m/RE/, s/RE/foo/,"
3620 Processing of \f(CW\*(C`\eQ\*(C'\fR, \f(CW\*(C`\eU\*(C'\fR, \f(CW\*(C`\eu\*(C'\fR, \f(CW\*(C`\eL\*(C'\fR, \f(CW\*(C`\el\*(C'\fR, \f(CW\*(C`\eF\*(C'\fR, \f(CW\*(C`\eE\*(C'\fR,
3621 and interpolation happens (almost) as with \f(CW\*(C`qq//\*(C'\fR constructs.
3622 .Sp
3623 Processing of \f(CW\*(C`\eN{...}\*(C'\fR is also done here, and compiled into an intermediate
3624 form for the regex compiler. (This is because, as mentioned below, the regex
3625 compilation may be done at execution time, and \f(CW\*(C`\eN{...}\*(C'\fR is a compile\-time
3626 construct.)
3627 .Sp
3628 However any other combinations of \f(CW\*(C`\e\*(C'\fR followed by a character
3629 are not substituted but only skipped, in order to parse them
3630 as regular expressions at the following step.
3631 As \f(CW\*(C`\ec\*(C'\fR is skipped at this step, \f(CW\*(C`@\*(C'\fR of \f(CW\*(C`\ec@\*(C'\fR in RE is possibly
3632 treated as an array symbol (for example \f(CW@foo\fR),
3633 even though the same text in \f(CW\*(C`qq//\*(C'\fR gives interpolation of \f(CW\*(C`\ec@\*(C'\fR.
3634 .Sp
3635 Code blocks such as \f(CW\*(C`(?{BLOCK})\*(C'\fR are handled by temporarily passing control
3636 back to the perl parser, in a similar way that an interpolated array
3637 subscript expression such as \f(CW"foo$array[1+f("[xyz")]bar"\fR would be.
3638 .Sp
3639 Moreover, inside \f(CW\*(C`(?{BLOCK})\*(C'\fR, \f(CW\*(C`(?#\ comment\ )\*(C'\fR, and
3640 a \f(CW\*(C`#\*(C'\fR\-comment in a \f(CW\*(C`/x\*(C'\fR\-regular expression, no processing is
3641 performed whatsoever. This is the first step at which the presence
3642 of the \f(CW\*(C`/x\*(C'\fR modifier is relevant.
3643 .Sp
3644 Interpolation in patterns has several quirks: \f(CW$|\fR, \f(CW$(\fR, \f(CW$)\fR, \f(CW\*(C`@+\*(C'\fR
3645 and \f(CW\*(C`@\-\*(C'\fR are not interpolated, and constructs \f(CW$var[SOMETHING]\fR are
3646 voted (by several different estimators) to be either an array element
3647 or \f(CW$var\fR followed by an RE alternative. This is where the notation
3648 \&\f(CW\*(C`${arr[$bar]}\*(C'\fR comes handy: \f(CW\*(C`/${arr[0\-9]}/\*(C'\fR is interpreted as
3649 array element \f(CW\-9\fR, not as a regular expression from the variable
3650 \&\f(CW$arr\fR followed by a digit, which would be the interpretation of
3651 \&\f(CW\*(C`/$arr[0\-9]/\*(C'\fR. Since voting among different estimators may occur,
3652 the result is not predictable.
3653 .Sp
3654 The lack of processing of \f(CW\*(C`\e\e\*(C'\fR creates specific restrictions on
3655 the post\-processed text. If the delimiter is \f(CW\*(C`/\*(C'\fR, one cannot get
3656 the combination \f(CW\*(C`\e/\*(C'\fR into the result of this step. \f(CW\*(C`/\*(C'\fR will
3657 finish the regular expression, \f(CW\*(C`\e/\*(C'\fR will be stripped to \f(CW\*(C`/\*(C'\fR on
3658 the previous step, and \f(CW\*(C`\e\e/\*(C'\fR will be left as is. Because \f(CW\*(C`/\*(C'\fR is
3659 equivalent to \f(CW\*(C`\e/\*(C'\fR inside a regular expression, this does not
3660 matter unless the delimiter happens to be character special to the
3661 RE engine, such as in \f(CW\*(C`s*foo*bar*\*(C'\fR, \f(CW\*(C`m[foo]\*(C'\fR, or \f(CW\*(C`m?foo?\*(C'\fR; or an
3662 alphanumeric char, as in:
3663 .Sp
3664 .Vb 1
3665 \& m m ^ a \es* b mmx;
3666 .Ve
3667 .Sp
3668 In the RE above, which is intentionally obfuscated for illustration, the
3669 delimiter is \f(CW\*(C`m\*(C'\fR, the modifier is \f(CW\*(C`mx\*(C'\fR, and after delimiter\-removal the
3670 RE is the same as for \f(CW\*(C`m/\ ^\ a\ \es*\ b\ /mx\*(C'\fR. There\*(Aqs more than one
3671 reason you\*(Aqre encouraged to restrict your delimiters to non\-alphanumeric,
3672 non\-whitespace choices.
3673 .RE
3674 .RS 4
3675 .Sp
3676 This step is the last one for all constructs except regular expressions,
3677 which are processed further.
3678 .RE
3679 .IP "Parsing regular expressions" 4
3680 .IX Xref "regexp, parse"
3681 .IX Item "Parsing regular expressions"
3682 Previous steps were performed during the compilation of Perl code,
3683 but this one happens at run time, although it may be optimized to
3684 be calculated at compile time if appropriate. After preprocessing
3685 described above, and possibly after evaluation if concatenation,
3686 joining, casing translation, or metaquoting are involved, the
3687 resulting \fIstring\fR is passed to the RE engine for compilation.
3688 .Sp
3689 Whatever happens in the RE engine might be better discussed in perlre,
3690 but for the sake of continuity, we shall do so here.
3691 .Sp
3692 This is another step where the presence of the \f(CW\*(C`/x\*(C'\fR modifier is
3693 relevant. The RE engine scans the string from left to right and
3694 converts it into a finite automaton.
3695 .Sp
3696 Backslashed characters are either replaced with corresponding
3697 literal strings (as with \f(CW\*(C`\e{\*(C'\fR), or else they generate special nodes
3698 in the finite automaton (as with \f(CW\*(C`\eb\*(C'\fR). Characters special to the
3699 RE engine (such as \f(CW\*(C`|\*(C'\fR) generate corresponding nodes or groups of
3700 nodes. \f(CW\*(C`(?#...)\*(C'\fR comments are ignored. All the rest is either
3701 converted to literal strings to match, or else is ignored (as is
3702 whitespace and \f(CW\*(C`#\*(C'\fR\-style comments if \f(CW\*(C`/x\*(C'\fR is present).
3703 .Sp
3704 Parsing of the bracketed character class construct, \f(CW\*(C`[...]\*(C'\fR, is
3705 rather different than the rule used for the rest of the pattern.
3706 The terminator of this construct is found using the same rules as
3707 for finding the terminator of a \f(CW\*(C`{}\*(C'\fR\-delimited construct, the only
3708 exception being that \f(CW\*(C`]\*(C'\fR immediately following \f(CW\*(C`[\*(C'\fR is treated as
3709 though preceded by a backslash.
3710 .Sp
3711 The terminator of runtime \f(CW\*(C`(?{...})\*(C'\fR is found by temporarily switching
3712 control to the perl parser, which should stop at the point where the
3713 logically balancing terminating \f(CW\*(C`}\*(C'\fR is found.
3714 .Sp
3715 It is possible to inspect both the string given to RE engine and the
3716 resulting finite automaton. See the arguments \f(CW\*(C`debug\*(C'\fR/\f(CW\*(C`debugcolor\*(C'\fR
3717 in the \f(CW\*(C`use\ re\*(C'\fR pragma, as well as Perl\*(Aqs \fB\-Dr\fR command\-line
3718 switch documented in "Command Switches" in perlrun.
3719 .IP "Optimization of regular expressions" 4
3720 .IX Xref "regexp, optimization"
3721 .IX Item "Optimization of regular expressions"
3722 This step is listed for completeness only. Since it does not change
3723 semantics, details of this step are not documented and are subject
3724 to change without notice. This step is performed over the finite
3725 automaton that was generated during the previous pass.
3726 .Sp
3727 It is at this stage that \f(CWsplit()\fR silently optimizes \f(CW\*(C`/^/\*(C'\fR to
3728 mean \f(CW\*(C`/^/m\*(C'\fR.
3729 .SS "I/O Operators"
3730 .IX Xref "operator, i o operator, io io while filehandle <> <<>> @ARGV diamond operator double diamond operator"
3731 .IX Subsection "I/O Operators"
3732 There are several I/O operators you should know about.
3733 .PP
3734 A string enclosed by backticks (grave accents) first undergoes
3735 double\-quote interpolation. It is then interpreted as an external
3736 command, and the output of that command is the value of the
3737 backtick string, like in a shell. In scalar context, a single string
3738 consisting of all output is returned. In list context, a list of
3739 values is returned, one per line of output. (You can set \f(CW$/\fR to use
3740 a different line terminator.) The command is executed each time the
3741 pseudo\-literal is evaluated. The status value of the command is
3742 returned in \f(CW$?\fR (see perlvar for the interpretation of \f(CW$?\fR).
3743 Unlike in \fBcsh\fR, no translation is done on the return data\-\-newlines
3744 remain newlines. Unlike in any of the shells, single quotes do not
3745 hide variable names in the command from interpretation. To pass a
3746 literal dollar\-sign through to the shell you need to hide it with a
3747 backslash. The generalized form of backticks is \f(CW\*(C`qx//\*(C'\fR, or you can
3748 call the "readpipe" in perlfunc function. (Because
3749 backticks always undergo shell expansion as well, see perlsec for
3750 security concerns.)
3751 .IX Xref "qx \\` \\`\\` backtick glob"
3752 .PP
3753 In scalar context, evaluating a filehandle in angle brackets yields
3754 the next line from that file (the newline, if any, included), or
3755 \&\f(CW\*(C`undef\*(C'\fR at end\-of\-file or on error. When \f(CW$/\fR is set to \f(CW\*(C`undef\*(C'\fR
3756 (sometimes known as file\-slurp mode) and the file is empty, it
3757 returns \f(CW\*(Aq\*(Aq\fR the first time, followed by \f(CW\*(C`undef\*(C'\fR subsequently.
3758 .PP
3759 Ordinarily you must assign the returned value to a variable, but
3760 there is one situation where an automatic assignment happens. If
3761 and only if the input symbol is the only thing inside the conditional
3762 of a \f(CW\*(C`while\*(C'\fR statement (even if disguised as a \f(CWfor(;;)\fR loop),
3763 the value is automatically assigned to the global variable \f(CW$_\fR,
3764 destroying whatever was there previously. (This may seem like an
3765 odd thing to you, but you\*(Aqll use the construct in almost every Perl
3766 script you write.) The \f(CW$_\fR variable is not implicitly localized.
3767 You\*(Aqll have to put a \f(CW\*(C`local\ $_;\*(C'\fR before the loop if you want that
3768 to happen. Furthermore, if the input symbol or an explicit assignment
3769 of the input symbol to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition,
3770 then the condition actually tests for definedness of the expression\*(Aqs
3771 value, not for its regular truth value.
3772 .PP
3773 Thus the following lines are equivalent:
3774 .PP
3775 .Vb 7
3776 \& while (defined($_ = <STDIN>)) { print; }
3777 \& while ($_ = <STDIN>) { print; }
3778 \& while (<STDIN>) { print; }
3779 \& for (;<STDIN>;) { print; }
3780 \& print while defined($_ = <STDIN>);
3781 \& print while ($_ = <STDIN>);
3782 \& print while <STDIN>;
3783 .Ve
3784 .PP
3785 This also behaves similarly, but assigns to a lexical variable
3786 instead of to \f(CW$_\fR:
3787 .PP
3788 .Vb 1
3789 \& while (my $line = <STDIN>) { print $line }
3790 .Ve
3791 .PP
3792 In these loop constructs, the assigned value (whether assignment
3793 is automatic or explicit) is then tested to see whether it is
3794 defined. The defined test avoids problems where the line has a string
3795 value that would be treated as false by Perl; for example a "" or
3796 a \f(CW"0"\fR with no trailing newline. If you really mean for such values
3797 to terminate the loop, they should be tested for explicitly:
3798 .PP
3799 .Vb 2
3800 \& while (($_ = <STDIN>) ne \*(Aq0\*(Aq) { ... }
3801 \& while (<STDIN>) { last unless $_; ... }
3802 .Ve
3803 .PP
3804 In other boolean contexts, \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR without an
3805 explicit \f(CW\*(C`defined\*(C'\fR test or comparison elicits a warning if the
3806 \&\f(CW\*(C`use\ warnings\*(C'\fR pragma or the \fB\-w\fR
3807 command\-line switch (the \f(CW$^W\fR variable) is in effect.
3808 .PP
3809 The filehandles STDIN, STDOUT, and STDERR are predefined. (The
3810 filehandles \f(CW\*(C`stdin\*(C'\fR, \f(CW\*(C`stdout\*(C'\fR, and \f(CW\*(C`stderr\*(C'\fR will also work except
3811 in packages, where they would be interpreted as local identifiers
3812 rather than global.) Additional filehandles may be created with
3813 the \f(CWopen()\fR function, amongst others. See perlopentut and
3814 "open" in perlfunc for details on this.
3815 .IX Xref "stdin stdout sterr"
3816 .PP
3817 If a \f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR is used in a context that is looking for
3818 a list, a list comprising all input lines is returned, one line per
3819 list element. It\*(Aqs easy to grow to a rather large data space this
3820 way, so use with care.
3821 .PP
3822 \&\f(CW\*(C`<\fR\f(CIFILEHANDLE\fR\f(CW>\*(C'\fR may also be spelled \f(CWreadline(*\fR\f(CIFILEHANDLE\fR\f(CW)\fR.
3823 See "readline" in perlfunc.
3824 .PP
3825 The null filehandle \f(CW\*(C`<>\*(C'\fR (sometimes called the diamond operator) is
3826 special: it can be used to emulate the
3827 behavior of \fBsed\fR and \fBawk\fR, and any other Unix filter program
3828 that takes a list of filenames, doing the same to each line
3829 of input from all of them. Input from \f(CW\*(C`<>\*(C'\fR comes either from
3830 standard input, or from each file listed on the command line. Here\*(Aqs
3831 how it works: the first time \f(CW\*(C`<>\*(C'\fR is evaluated, the \f(CW@ARGV\fR array is
3832 checked, and if it is empty, \f(CW$ARGV[0]\fR is set to \f(CW"\-"\fR, which when opened
3833 gives you standard input. The \f(CW@ARGV\fR array is then processed as a list
3834 of filenames. The loop
3835 .PP
3836 .Vb 3
3837 \& while (<>) {
3838 \& ... # code for each line
3839 \& }
3840 .Ve
3841 .PP
3842 is equivalent to the following Perl\-like pseudo code:
3843 .PP
3844 .Vb 7
3845 \& unshift(@ARGV, \*(Aq\-\*(Aq) unless @ARGV;
3846 \& while ($ARGV = shift) {
3847 \& open(ARGV, $ARGV);
3848 \& while (<ARGV>) {
3849 \& ... # code for each line
3850 \& }
3851 \& }
3852 .Ve
3853 .PP
3854 except that it isn\*(Aqt so cumbersome to say, and will actually work.
3855 It really does shift the \f(CW@ARGV\fR array and put the current filename
3856 into the \f(CW$ARGV\fR variable. It also uses filehandle \fIARGV\fR
3857 internally. \f(CW\*(C`<>\*(C'\fR is just a synonym for \f(CW\*(C`<ARGV>\*(C'\fR, which
3858 is magical. (The pseudo code above doesn\*(Aqt work because it treats
3859 \&\f(CW\*(C`<ARGV>\*(C'\fR as non\-magical.)
3860 .PP
3861 Since the null filehandle uses the two argument form of "open" in perlfunc
3862 it interprets special characters, so if you have a script like this:
3863 .PP
3864 .Vb 3
3865 \& while (<>) {
3866 \& print;
3867 \& }
3868 .Ve
3869 .PP
3870 and call it with \f(CW\*(C`perl\ dangerous.pl\ \*(Aqrm\ \-rfv\ *|\*(Aq\*(C'\fR, it actually opens a
3871 pipe, executes the \f(CW\*(C`rm\*(C'\fR command and reads \f(CW\*(C`rm\*(C'\fR\*(Aqs output from that pipe.
3872 If you want all items in \f(CW@ARGV\fR to be interpreted as file names, you
3873 can use the module \f(CW\*(C`ARGV::readonly\*(C'\fR from CPAN, or use the double
3874 diamond operator:
3875 .PP
3876 .Vb 3
3877 \& while (<<>>) {
3878 \& print;
3879 \& }
3880 .Ve
3881 .PP
3882 Using double angle brackets inside of a while causes the open to use the
3883 three argument form (with the second argument being \f(CW\*(C`<\*(C'\fR), so all
3884 arguments in \f(CW\*(C`ARGV\*(C'\fR are treated as literal filenames (including \f(CW"\-"\fR).
3885 (Note that for convenience, if you use \f(CW\*(C`<<>>\*(C'\fR and if \f(CW@ARGV\fR is
3886 empty, it will still read from the standard input.)
3887 .PP
3888 You can modify \f(CW@ARGV\fR before the first \f(CW\*(C`<>\*(C'\fR as long as the array ends up
3889 containing the list of filenames you really want. Line numbers (\f(CW$.\fR)
3890 continue as though the input were one big happy file. See the example
3891 in "eof" in perlfunc for how to reset line numbers on each file.
3892 .PP
3893 If you want to set \f(CW@ARGV\fR to your own list of files, go right ahead.
3894 This sets \f(CW@ARGV\fR to all plain text files if no \f(CW@ARGV\fR was given:
3895 .PP
3896 .Vb 1
3897 \& @ARGV = grep { \-f && \-T } glob(\*(Aq*\*(Aq) unless @ARGV;
3898 .Ve
3899 .PP
3900 You can even set them to pipe commands. For example, this automatically
3901 filters compressed arguments through \fBgzip\fR:
3902 .PP
3903 .Vb 1
3904 \& @ARGV = map { /\e.(gz|Z)$/ ? "gzip \-dc < $_ |" : $_ } @ARGV;
3905 .Ve
3906 .PP
3907 If you want to pass switches into your script, you can use one of the
3908 \&\f(CW\*(C`Getopts\*(C'\fR modules or put a loop on the front like this:
3909 .PP
3910 .Vb 7
3911 \& while ($_ = $ARGV[0], /^\-/) {
3912 \& shift;
3913 \& last if /^\-\-$/;
3914 \& if (/^\-D(.*)/) { $debug = $1 }
3915 \& if (/^\-v/) { $verbose++ }
3916 \& # ... # other switches
3917 \& }
3918 \&
3919 \& while (<>) {
3920 \& # ... # code for each line
3921 \& }
3922 .Ve
3923 .PP
3924 The \f(CW\*(C`<>\*(C'\fR symbol will return \f(CW\*(C`undef\*(C'\fR for end\-of\-file only once.
3925 If you call it again after this, it will assume you are processing another
3926 \&\f(CW@ARGV\fR list, and if you haven\*(Aqt set \f(CW@ARGV\fR, will read input from STDIN.
3927 .PP
3928 If what the angle brackets contain is a simple scalar variable (for example,
3929 \&\f(CW$foo\fR), then that variable contains the name of the
3930 filehandle to input from, or its typeglob, or a reference to the
3931 same. For example:
3932 .PP
3933 .Vb 2
3934 \& $fh = \e*STDIN;
3935 \& $line = <$fh>;
3936 .Ve
3937 .PP
3938 If what\*(Aqs within the angle brackets is neither a filehandle nor a simple
3939 scalar variable containing a filehandle name, typeglob, or typeglob
3940 reference, it is interpreted as a filename pattern to be globbed, and
3941 either a list of filenames or the next filename in the list is returned,
3942 depending on context. This distinction is determined on syntactic
3943 grounds alone. That means \f(CW\*(C`<$x>\*(C'\fR is always a \f(CWreadline()\fR from
3944 an indirect handle, but \f(CW\*(C`<$hash{key}>\*(C'\fR is always a \f(CWglob()\fR.
3945 That\*(Aqs because \f(CW$x\fR is a simple scalar variable, but \f(CW$hash{key}\fR is
3946 not\-\-it\*(Aqs a hash element. Even \f(CW\*(C`<$x >\*(C'\fR (note the extra space)
3947 is treated as \f(CW\*(C`glob("$x ")\*(C'\fR, not \f(CWreadline($x)\fR.
3948 .PP
3949 One level of double\-quote interpretation is done first, but you can\*(Aqt
3950 say \f(CW\*(C`<$foo>\*(C'\fR because that\*(Aqs an indirect filehandle as explained
3951 in the previous paragraph. (In older versions of Perl, programmers
3952 would insert curly brackets to force interpretation as a filename glob:
3953 \&\f(CW\*(C`<${foo}>\*(C'\fR. These days, it\*(Aqs considered cleaner to call the
3954 internal function directly as \f(CWglob($foo)\fR, which is probably the right
3955 way to have done it in the first place.) For example:
3956 .PP
3957 .Vb 3
3958 \& while (<*.c>) {
3959 \& chmod 0644, $_;
3960 \& }
3961 .Ve
3962 .PP
3963 is roughly equivalent to:
3964 .PP
3965 .Vb 5
3966 \& open(FOO, "echo *.c | tr \-s \*(Aq \et\er\ef\*(Aq \*(Aq\e\e012\e\e012\e\e012\e\e012\*(Aq|");
3967 \& while (<FOO>) {
3968 \& chomp;
3969 \& chmod 0644, $_;
3970 \& }
3971 .Ve
3972 .PP
3973 except that the globbing is actually done internally using the standard
3974 \&\f(CW\*(C`File::Glob\*(C'\fR extension. Of course, the shortest way to do the above is:
3975 .PP
3976 .Vb 1
3977 \& chmod 0644, <*.c>;
3978 .Ve
3979 .PP
3980 A (file)glob evaluates its (embedded) argument only when it is
3981 starting a new list. All values must be read before it will start
3982 over. In list context, this isn\*(Aqt important because you automatically
3983 get them all anyway. However, in scalar context the operator returns
3984 the next value each time it\*(Aqs called, or \f(CW\*(C`undef\*(C'\fR when the list has
3985 run out. As with filehandle reads, an automatic \f(CW\*(C`defined\*(C'\fR is
3986 generated when the glob occurs in the test part of a \f(CW\*(C`while\*(C'\fR,
3987 because legal glob returns (for example,
3988 a file called \fI0\fR) would otherwise
3989 terminate the loop. Again, \f(CW\*(C`undef\*(C'\fR is returned only once. So if
3990 you\*(Aqre expecting a single value from a glob, it is much better to
3991 say
3992 .PP
3993 .Vb 1
3994 \& ($file) = <blurch*>;
3995 .Ve
3996 .PP
3997 than
3998 .PP
3999 .Vb 1
4000 \& $file = <blurch*>;
4001 .Ve
4002 .PP
4003 because the latter will alternate between returning a filename and
4004 returning false.
4005 .PP
4006 If you\*(Aqre trying to do variable interpolation, it\*(Aqs definitely better
4007 to use the \f(CWglob()\fR function, because the older notation can cause people
4008 to become confused with the indirect filehandle notation.
4009 .PP
4010 .Vb 2
4011 \& @files = glob("$dir/*.[ch]");
4012 \& @files = glob($files[$i]);
4013 .Ve
4014 .PP
4015 If an angle\-bracket\-based globbing expression is used as the condition of
4016 a \f(CW\*(C`while\*(C'\fR or \f(CW\*(C`for\*(C'\fR loop, then it will be implicitly assigned to \f(CW$_\fR.
4017 If either a globbing expression or an explicit assignment of a globbing
4018 expression to a scalar is used as a \f(CW\*(C`while\*(C'\fR/\f(CW\*(C`for\*(C'\fR condition, then
4019 the condition actually tests for definedness of the expression\*(Aqs value,
4020 not for its regular truth value.
4021 .SS "Constant Folding"
4022 .IX Xref "constant folding folding"
4023 .IX Subsection "Constant Folding"
4024 Like C, Perl does a certain amount of expression evaluation at
4025 compile time whenever it determines that all arguments to an
4026 operator are static and have no side effects. In particular, string
4027 concatenation happens at compile time between literals that don\*(Aqt do
4028 variable substitution. Backslash interpolation also happens at
4029 compile time. You can say
4030 .PP
4031 .Vb 3
4032 \& \*(AqNow is the time for all\*(Aq
4033 \& . "\en"
4034 \& . \*(Aqgood men to come to.\*(Aq
4035 .Ve
4036 .PP
4037 and this all reduces to one string internally. Likewise, if
4038 you say
4039 .PP
4040 .Vb 3
4041 \& foreach $file (@filenames) {
4042 \& if (\-s $file > 5 + 100 * 2**16) { }
4043 \& }
4044 .Ve
4045 .PP
4046 the compiler precomputes the number which that expression
4047 represents so that the interpreter won\*(Aqt have to.
4048 .SS No\-ops
4049 .IX Xref "no-op nop"
4050 .IX Subsection "No-ops"
4051 Perl doesn\*(Aqt officially have a no\-op operator, but the bare constants
4052 \&\f(CW0\fR and \f(CW1\fR are special\-cased not to produce a warning in void
4053 context, so you can for example safely do
4054 .PP
4055 .Vb 1
4056 \& 1 while foo();
4057 .Ve
4058 .SS "Bitwise String Operators"
4059 .IX Xref "operator, bitwise, string &. |. ^. ~."
4060 .IX Subsection "Bitwise String Operators"
4061 Bitstrings of any size may be manipulated by the bitwise operators
4062 (\f(CW\*(C`~ | & ^\*(C'\fR).
4063 .PP
4064 If the operands to a binary bitwise op are strings of different
4065 sizes, \fB|\fR and \fB^\fR ops act as though the shorter operand had
4066 additional zero bits on the right, while the \fB&\fR op acts as though
4067 the longer operand was truncated to the length of the shorter.
4068 The granularity for such extension or truncation is one or more
4069 bytes.
4070 .PP
4071 .Vb 5
4072 \& # ASCII\-based examples
4073 \& print "j p \en" ^ " a h"; # prints "JAPH\en"
4074 \& print "JA" | " ph\en"; # prints "japh\en"
4075 \& print "japh\enJunk" & \*(Aq_\|_\|_\|_\|_\*(Aq; # prints "JAPH\en";
4076 \& print \*(Aqp N$\*(Aq ^ " E<H\en"; # prints "Perl\en";
4077 .Ve
4078 .PP
4079 If you are intending to manipulate bitstrings, be certain that
4080 you\*(Aqre supplying bitstrings: If an operand is a number, that will imply
4081 a \fBnumeric\fR bitwise operation. You may explicitly show which type of
4082 operation you intend by using \f(CW""\fR or \f(CW\*(C`0+\*(C'\fR, as in the examples below.
4083 .PP
4084 .Vb 4
4085 \& $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
4086 \& $foo = \*(Aq150\*(Aq | 105; # yields 255
4087 \& $foo = 150 | \*(Aq105\*(Aq; # yields 255
4088 \& $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq (under ASCII)
4089 \&
4090 \& $baz = 0+$foo & 0+$bar; # both ops explicitly numeric
4091 \& $biz = "$foo" ^ "$bar"; # both ops explicitly stringy
4092 .Ve
4093 .PP
4094 This somewhat unpredictable behavior can be avoided with the "bitwise"
4095 feature, new in Perl 5.22. You can enable it via \f(CWuse\ feature\ \*(Aqbitwise\*(Aq\fR or \f(CW\*(C`use v5.28\*(C'\fR. Before Perl 5.28, it used to emit a warning
4096 in the \f(CW"experimental::bitwise"\fR category. Under this feature, the four
4097 standard bitwise operators (\f(CW\*(C`~ | & ^\*(C'\fR) are always numeric. Adding a dot
4098 after each operator (\f(CW\*(C`~. |. &. ^.\*(C'\fR) forces it to treat its operands as
4099 strings:
4100 .PP
4101 .Vb 9
4102 \& use feature "bitwise";
4103 \& $foo = 150 | 105; # yields 255 (0x96 | 0x69 is 0xFF)
4104 \& $foo = \*(Aq150\*(Aq | 105; # yields 255
4105 \& $foo = 150 | \*(Aq105\*(Aq; # yields 255
4106 \& $foo = \*(Aq150\*(Aq | \*(Aq105\*(Aq; # yields 255
4107 \& $foo = 150 |. 105; # yields string \*(Aq155\*(Aq
4108 \& $foo = \*(Aq150\*(Aq |. 105; # yields string \*(Aq155\*(Aq
4109 \& $foo = 150 |.\*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq
4110 \& $foo = \*(Aq150\*(Aq |.\*(Aq105\*(Aq; # yields string \*(Aq155\*(Aq
4111 \&
4112 \& $baz = $foo & $bar; # both operands numeric
4113 \& $biz = $foo ^. $bar; # both operands stringy
4114 .Ve
4115 .PP
4116 The assignment variants of these operators (\f(CW\*(C`&= |= ^= &.= |.= ^.=\*(C'\fR)
4117 behave likewise under the feature.
4118 .PP
4119 It is a fatal error if an operand contains a character whose ordinal
4120 value is above 0xFF, and hence not expressible except in UTF\-8. The
4121 operation is performed on a non\-UTF\-8 copy for other operands encoded in
4122 UTF\-8. See "Byte and Character Semantics" in perlunicode.
4123 .PP
4124 See "vec" in perlfunc for information on how to manipulate individual bits
4125 in a bit vector.
4126 .SS "Integer Arithmetic"
4127 .IX Xref "integer"
4128 .IX Subsection "Integer Arithmetic"
4129 By default, Perl assumes that it must do most of its arithmetic in
4130 floating point. But by saying
4131 .PP
4132 .Vb 1
4133 \& use integer;
4134 .Ve
4135 .PP
4136 you may tell the compiler to use integer operations
4137 (see integer for a detailed explanation) from here to the end of
4138 the enclosing BLOCK. An inner BLOCK may countermand this by saying
4139 .PP
4140 .Vb 1
4141 \& no integer;
4142 .Ve
4143 .PP
4144 which lasts until the end of that BLOCK. Note that this doesn\*(Aqt
4145 mean everything is an integer, merely that Perl will use integer
4146 operations for arithmetic, comparison, and bitwise operators. For
4147 example, even under \f(CW\*(C`use\ integer\*(C'\fR, if you take the \f(CWsqrt(2)\fR, you\*(Aqll
4148 still get \f(CW1.4142135623731\fR or so.
4149 .PP
4150 Used on numbers, the bitwise operators (\f(CW\*(C`&\*(C'\fR \f(CW\*(C`|\*(C'\fR \f(CW\*(C`^\*(C'\fR \f(CW\*(C`~\*(C'\fR \f(CW\*(C`<<\*(C'\fR
4151 \&\f(CW\*(C`>>\*(C'\fR) always produce integral results. (But see also
4152 "Bitwise String Operators".) However, \f(CW\*(C`use\ integer\*(C'\fR still has meaning for
4153 them. By default, their results are interpreted as unsigned integers, but
4154 if \f(CW\*(C`use\ integer\*(C'\fR is in effect, their results are interpreted
4155 as signed integers. For example, \f(CW\*(C`~0\*(C'\fR usually evaluates to a large
4156 integral value. However, \f(CW\*(C`use\ integer;\ ~0\*(C'\fR is \f(CW\-1\fR on two\*(Aqs\-complement
4157 machines.
4158 .SS "Floating\-point Arithmetic"
4159 .IX Subsection "Floating-point Arithmetic"
4160
4161 .IX Xref "floating-point floating point float real"
4162 .PP
4163 While \f(CW\*(C`use\ integer\*(C'\fR provides integer\-only arithmetic, there is no
4164 analogous mechanism to provide automatic rounding or truncation to a
4165 certain number of decimal places. For rounding to a certain number
4166 of digits, \f(CWsprintf()\fR or \f(CWprintf()\fR is usually the easiest route.
4167 See perlfaq4.
4168 .PP
4169 Floating\-point numbers are only approximations to what a mathematician
4170 would call real numbers. There are infinitely more reals than floats,
4171 so some corners must be cut. For example:
4172 .PP
4173 .Vb 2
4174 \& printf "%.20g\en", 123456789123456789;
4175 \& # produces 123456789123456784
4176 .Ve
4177 .PP
4178 Testing for exact floating\-point equality or inequality is not a
4179 good idea. Here\*(Aqs a (relatively expensive) work\-around to compare
4180 whether two floating\-point numbers are equal to a particular number of
4181 decimal places. See Knuth, volume II, for a more robust treatment of
4182 this topic.
4183 .PP
4184 .Vb 7
4185 \& sub fp_equal {
4186 \& my ($X, $Y, $POINTS) = @_;
4187 \& my ($tX, $tY);
4188 \& $tX = sprintf("%.${POINTS}g", $X);
4189 \& $tY = sprintf("%.${POINTS}g", $Y);
4190 \& return $tX eq $tY;
4191 \& }
4192 .Ve
4193 .PP
4194 The POSIX module (part of the standard perl distribution) implements
4195 \&\f(CWceil()\fR, \f(CWfloor()\fR, and other mathematical and trigonometric functions.
4196 The \f(CW\*(C`Math::Complex\*(C'\fR module (part of the standard perl distribution)
4197 defines mathematical functions that work on both the reals and the
4198 imaginary numbers. \f(CW\*(C`Math::Complex\*(C'\fR is not as efficient as POSIX, but
4199 POSIX can\*(Aqt work with complex numbers.
4200 .PP
4201 Rounding in financial applications can have serious implications, and
4202 the rounding method used should be specified precisely. In these
4203 cases, it probably pays not to trust whichever system rounding is
4204 being used by Perl, but to instead implement the rounding function you
4205 need yourself.
4206 .SS "Bigger Numbers"
4207 .IX Xref "number, arbitrary precision"
4208 .IX Subsection "Bigger Numbers"
4209 The standard \f(CW\*(C`Math::BigInt\*(C'\fR, \f(CW\*(C`Math::BigRat\*(C'\fR, and
4210 \&\f(CW\*(C`Math::BigFloat\*(C'\fR modules,
4211 along with the \f(CW\*(C`bignum\*(C'\fR, \f(CW\*(C`bigint\*(C'\fR, and \f(CW\*(C`bigrat\*(C'\fR pragmas, provide
4212 variable\-precision arithmetic and overloaded operators, although
4213 they\*(Aqre currently pretty slow. At the cost of some space and
4214 considerable speed, they avoid the normal pitfalls associated with
4215 limited\-precision representations.
4216 .PP
4217 .Vb 5
4218 \& use 5.010;
4219 \& use bigint; # easy interface to Math::BigInt
4220 \& $x = 123456789123456789;
4221 \& say $x * $x;
4222 \& +15241578780673678515622620750190521
4223 .Ve
4224 .PP
4225 Or with rationals:
4226 .PP
4227 .Vb 8
4228 \& use 5.010;
4229 \& use bigrat;
4230 \& $x = 3/22;
4231 \& $y = 4/6;
4232 \& say "x/y is ", $x/$y;
4233 \& say "x*y is ", $x*$y;
4234 \& x/y is 9/44
4235 \& x*y is 1/11
4236 .Ve
4237 .PP
4238 Several modules let you calculate with unlimited or fixed precision
4239 (bound only by memory and CPU time). There
4240 are also some non\-standard modules that
4241 provide faster implementations via external C libraries.
4242 .PP
4243 Here is a short, but incomplete summary:
4244 .PP
4245 .Vb 10
4246 \& Math::String treat string sequences like numbers
4247 \& Math::FixedPrecision calculate with a fixed precision
4248 \& Math::Currency for currency calculations
4249 \& Bit::Vector manipulate bit vectors fast (uses C)
4250 \& Math::BigIntFast Bit::Vector wrapper for big numbers
4251 \& Math::Pari provides access to the Pari C library
4252 \& Math::Cephes uses the external Cephes C library (no
4253 \& big numbers)
4254 \& Math::Cephes::Fraction fractions via the Cephes library
4255 \& Math::GMP another one using an external C library
4256 \& Math::GMPz an alternative interface to libgmp\*(Aqs big ints
4257 \& Math::GMPq an interface to libgmp\*(Aqs fraction numbers
4258 \& Math::GMPf an interface to libgmp\*(Aqs floating point numbers
4259 .Ve
4260 .PP
4261 Choose wisely.
4262 .SS "C\-style Logical Or"
4263 .IX Subsection "C-style Logical Or"
4264 This section has been superceded by
4265 "C\-style Logical Or, Xor, and Defined Or". The heading is retained
4266 only to prevent breaking any pre\-existing links to it from outside.
4267 .SS "C\-style Logical Xor"
4268 .IX Subsection "C-style Logical Xor"
4269 This section has been superceded by
4270 "C\-style Logical Or, Xor, and Defined Or". The heading is retained
4271 only to prevent breaking any pre\-existing links to it from outside.
4272 .SS "Logical Defined\-Or"
4273 .IX Subsection "Logical Defined-Or"
4274 This section has been superceded by
4275 "C\-style Logical Or, Xor, and Defined Or". The heading is retained
4276 only to prevent breaking any pre\-existing links to it from outside.
4277 .SS "Quote\-Like Operators"
4278 .IX Subsection "Quote-Like Operators"
4279 This section has been replaced by "Simpler Quote\-Like Operators"
4280 .SS "Indented Here\-docs"
4281 .IX Subsection "Indented Here-docs"
4282 This section has been merged into "Here\-docs"
4283 .SH APPENDIX
4284 .IX Header "APPENDIX"
4285 .SS "List of Extra Paired Delimiters"
4286 .IX Subsection "List of Extra Paired Delimiters"
4287 The complete list of accepted paired delimiters as of Unicode 16.0 is:
4288 .PP
4289 .Vb 10
4290 \& ( ) U+0028, U+0029 LEFT/RIGHT PARENTHESIS
4291 \& < > U+003C, U+003E LESS\-THAN/GREATER\-THAN SIGN
4292 \& [ ] U+005B, U+005D LEFT/RIGHT SQUARE BRACKET
4293 \& { } U+007B, U+007D LEFT/RIGHT CURLY BRACKET
4294 \& « » U+00AB, U+00BB LEFT/RIGHT\-POINTING DOUBLE ANGLE QUOTATION MARK
4295 \& » « U+00BB, U+00AB RIGHT/LEFT\-POINTING DOUBLE ANGLE QUOTATION MARK
4296 \& ༺ ༻ U+0F3A, U+0F3B TIBETAN MARK GUG RTAGS GYON, TIBETAN MARK GUG
4297 \& RTAGS GYAS
4298 \& ༼ ༽ U+0F3C, U+0F3D TIBETAN MARK ANG KHANG GYON, TIBETAN MARK ANG
4299 \& KHANG GYAS
4300 \& ᚛ ᚜ U+169B, U+169C OGHAM FEATHER MARK, OGHAM REVERSED FEATHER MARK
4301 \& ‘ ’ U+2018, U+2019 LEFT/RIGHT SINGLE QUOTATION MARK
4302 \& ’ ‘ U+2019, U+2018 RIGHT/LEFT SINGLE QUOTATION MARK
4303 \& “ ” U+201C, U+201D LEFT/RIGHT DOUBLE QUOTATION MARK
4304 \& ” “ U+201D, U+201C RIGHT/LEFT DOUBLE QUOTATION MARK
4305 \& ‵ ′ U+2035, U+2032 REVERSED PRIME, PRIME
4306 \& ‶ ″ U+2036, U+2033 REVERSED DOUBLE PRIME, DOUBLE PRIME
4307 \& ‷ ‴ U+2037, U+2034 REVERSED TRIPLE PRIME, TRIPLE PRIME
4308 \& ‹ › U+2039, U+203A SINGLE LEFT/RIGHT\-POINTING ANGLE QUOTATION MARK
4309 \& › ‹ U+203A, U+2039 SINGLE RIGHT/LEFT\-POINTING ANGLE QUOTATION MARK
4310 \& ⁅ ⁆ U+2045, U+2046 LEFT/RIGHT SQUARE BRACKET WITH QUILL
4311 \& ⁍ ⁌ U+204D, U+204C BLACK RIGHT/LEFTWARDS BULLET
4312 \& ⁽ ⁾ U+207D, U+207E SUPERSCRIPT LEFT/RIGHT PARENTHESIS
4313 \& ₍ ₎ U+208D, U+208E SUBSCRIPT LEFT/RIGHT PARENTHESIS
4314 \& → ← U+2192, U+2190 RIGHT/LEFTWARDS ARROW
4315 \& ↛ ↚ U+219B, U+219A RIGHT/LEFTWARDS ARROW WITH STROKE
4316 \& ↝ ↜ U+219D, U+219C RIGHT/LEFTWARDS WAVE ARROW
4317 \& ↠ ↞ U+21A0, U+219E RIGHT/LEFTWARDS TWO HEADED ARROW
4318 \& ↣ ↢ U+21A3, U+21A2 RIGHT/LEFTWARDS ARROW WITH TAIL
4319 \& ↦ ↤ U+21A6, U+21A4 RIGHT/LEFTWARDS ARROW FROM BAR
4320 \& ↪ ↩ U+21AA, U+21A9 RIGHT/LEFTWARDS ARROW WITH HOOK
4321 \& ↬ ↫ U+21AC, U+21AB RIGHT/LEFTWARDS ARROW WITH LOOP
4322 \& ↱ ↰ U+21B1, U+21B0 UPWARDS ARROW WITH TIP RIGHT/LEFTWARDS
4323 \& ↳ ↲ U+21B3, U+21B2 DOWNWARDS ARROW WITH TIP RIGHT/LEFTWARDS
4324 \& ⇀ ↼ U+21C0, U+21BC RIGHT/LEFTWARDS HARPOON WITH BARB UPWARDS
4325 \& ⇁ ↽ U+21C1, U+21BD RIGHT/LEFTWARDS HARPOON WITH BARB DOWNWARDS
4326 \& ⇉ ⇇ U+21C9, U+21C7 RIGHT/LEFTWARDS PAIRED ARROWS
4327 \& ⇏ ⇍ U+21CF, U+21CD RIGHT/LEFTWARDS DOUBLE ARROW WITH STROKE
4328 \& ⇒ ⇐ U+21D2, U+21D0 RIGHT/LEFTWARDS DOUBLE ARROW
4329 \& ⇛ ⇚ U+21DB, U+21DA RIGHT/LEFTWARDS TRIPLE ARROW
4330 \& ⇝ ⇜ U+21DD, U+21DC RIGHT/LEFTWARDS SQUIGGLE ARROW
4331 \& ⇢ ⇠ U+21E2, U+21E0 RIGHT/LEFTWARDS DASHED ARROW
4332 \& ⇥ ⇤ U+21E5, U+21E4 RIGHT/LEFTWARDS ARROW TO BAR
4333 \& ⇨ ⇦ U+21E8, U+21E6 RIGHT/LEFTWARDS WHITE ARROW
4334 \& ⇴ ⬰ U+21F4, U+2B30 RIGHT/LEFT ARROW WITH SMALL CIRCLE
4335 \& ⇶ ⬱ U+21F6, U+2B31 THREE RIGHT/LEFTWARDS ARROWS
4336 \& ⇸ ⇷ U+21F8, U+21F7 RIGHT/LEFTWARDS ARROW WITH VERTICAL STROKE
4337 \& ⇻ ⇺ U+21FB, U+21FA RIGHT/LEFTWARDS ARROW WITH DOUBLE VERTICAL
4338 \& STROKE
4339 \& ⇾ ⇽ U+21FE, U+21FD RIGHT/LEFTWARDS OPEN\-HEADED ARROW
4340 \& ∈ ∋ U+2208, U+220B ELEMENT OF, CONTAINS AS MEMBER
4341 \& ∉ ∌ U+2209, U+220C NOT AN ELEMENT OF, DOES NOT CONTAIN AS MEMBER
4342 \& ∊ ∍ U+220A, U+220D SMALL ELEMENT OF, SMALL CONTAINS AS MEMBER
4343 \& ≤ ≥ U+2264, U+2265 LESS\-THAN/GREATER\-THAN OR EQUAL TO
4344 \& ≦ ≧ U+2266, U+2267 LESS\-THAN/GREATER\-THAN OVER EQUAL TO
4345 \& ≨ ≩ U+2268, U+2269 LESS\-THAN/GREATER\-THAN BUT NOT EQUAL TO
4346 \& ≪ ≫ U+226A, U+226B MUCH LESS\-THAN/GREATER\-THAN
4347 \& ≮ ≯ U+226E, U+226F NOT LESS\-THAN/GREATER\-THAN
4348 \& ≰ ≱ U+2270, U+2271 NEITHER LESS\-THAN/GREATER\-THAN NOR EQUAL TO
4349 \& ≲ ≳ U+2272, U+2273 LESS\-THAN/GREATER\-THAN OR EQUIVALENT TO
4350 \& ≴ ≵ U+2274, U+2275 NEITHER LESS\-THAN/GREATER\-THAN NOR EQUIVALENT TO
4351 \& ≺ ≻ U+227A, U+227B PRECEDES/SUCCEEDS
4352 \& ≼ ≽ U+227C, U+227D PRECEDES/SUCCEEDS OR EQUAL TO
4353 \& ≾ ≿ U+227E, U+227F PRECEDES/SUCCEEDS OR EQUIVALENT TO
4354 \& ⊀ ⊁ U+2280, U+2281 DOES NOT PRECEDE/SUCCEED
4355 \& ⊂ ⊃ U+2282, U+2283 SUBSET/SUPERSET OF
4356 \& ⊄ ⊅ U+2284, U+2285 NOT A SUBSET/SUPERSET OF
4357 \& ⊆ ⊇ U+2286, U+2287 SUBSET/SUPERSET OF OR EQUAL TO
4358 \& ⊈ ⊉ U+2288, U+2289 NEITHER A SUBSET/SUPERSET OF NOR EQUAL TO
4359 \& ⊊ ⊋ U+228A, U+228B SUBSET/SUPERSET OF WITH NOT EQUAL TO
4360 \& ⊣ ⊢ U+22A3, U+22A2 LEFT/RIGHT TACK
4361 \& ⊦ ⫞ U+22A6, U+2ADE ASSERTION, SHORT LEFT TACK
4362 \& ⊨ ⫤ U+22A8, U+2AE4 TRUE, VERTICAL BAR DOUBLE LEFT TURNSTILE
4363 \& ⊩ ⫣ U+22A9, U+2AE3 FORCES, DOUBLE VERTICAL BAR LEFT TURNSTILE
4364 \& ⊰ ⊱ U+22B0, U+22B1 PRECEDES/SUCCEEDS UNDER RELATION
4365 \& ⋐ ⋑ U+22D0, U+22D1 DOUBLE SUBSET/SUPERSET
4366 \& ⋖ ⋗ U+22D6, U+22D7 LESS\-THAN/GREATER\-THAN WITH DOT
4367 \& ⋘ ⋙ U+22D8, U+22D9 VERY MUCH LESS\-THAN/GREATER\-THAN
4368 \& ⋜ ⋝ U+22DC, U+22DD EQUAL TO OR LESS\-THAN/GREATER\-THAN
4369 \& ⋞ ⋟ U+22DE, U+22DF EQUAL TO OR PRECEDES/SUCCEEDS
4370 \& ⋠ ⋡ U+22E0, U+22E1 DOES NOT PRECEDE/SUCCEED OR EQUAL
4371 \& ⋦ ⋧ U+22E6, U+22E7 LESS\-THAN/GREATER\-THAN BUT NOT EQUIVALENT TO
4372 \& ⋨ ⋩ U+22E8, U+22E9 PRECEDES/SUCCEEDS BUT NOT EQUIVALENT TO
4373 \& ⋲ ⋺ U+22F2, U+22FA ELEMENT OF/CONTAINS WITH LONG HORIZONTAL STROKE
4374 \& ⋳ ⋻ U+22F3, U+22FB ELEMENT OF/CONTAINS WITH VERTICAL BAR AT END OF
4375 \& HORIZONTAL STROKE
4376 \& ⋴ ⋼ U+22F4, U+22FC SMALL ELEMENT OF/CONTAINS WITH VERTICAL BAR AT
4377 \& END OF HORIZONTAL STROKE
4378 \& ⋶ ⋽ U+22F6, U+22FD ELEMENT OF/CONTAINS WITH OVERBAR
4379 \& ⋷ ⋾ U+22F7, U+22FE SMALL ELEMENT OF/CONTAINS WITH OVERBAR
4380 \& ⌈ ⌉ U+2308, U+2309 LEFT/RIGHT CEILING
4381 \& ⌊ ⌋ U+230A, U+230B LEFT/RIGHT FLOOR
4382 \& ⌦ ⌫ U+2326, U+232B ERASE TO THE RIGHT/LEFT
4383 \& 〈 〉 U+2329, U+232A LEFT/RIGHT\-POINTING ANGLE BRACKET
4384 \& ⍈ ⍇ U+2348, U+2347 APL FUNCTIONAL SYMBOL QUAD RIGHT/LEFTWARDS ARROW
4385 \& ⏩ ⏪ U+23E9, U+23EA BLACK RIGHT/LEFT\-POINTING DOUBLE TRIANGLE
4386 \& ⏭ ⏮ U+23ED, U+23EE BLACK RIGHT/LEFT\-POINTING DOUBLE TRIANGLE WITH
4387 \& VERTICAL BAR
4388 \& ☛ ☚ U+261B, U+261A BLACK RIGHT/LEFT POINTING INDEX
4389 \& ☞ ☜ U+261E, U+261C WHITE RIGHT/LEFT POINTING INDEX
4390 \& ⚞ ⚟ U+269E, U+269F THREE LINES CONVERGING RIGHT/LEFT
4391 \& ❨ ❩ U+2768, U+2769 MEDIUM LEFT/RIGHT PARENTHESIS ORNAMENT
4392 \& ❪ ❫ U+276A, U+276B MEDIUM FLATTENED LEFT/RIGHT PARENTHESIS ORNAMENT
4393 \& ❬ ❭ U+276C, U+276D MEDIUM LEFT/RIGHT\-POINTING ANGLE BRACKET
4394 \& ORNAMENT
4395 \& ❮ ❯ U+276E, U+276F HEAVY LEFT/RIGHT\-POINTING ANGLE QUOTATION MARK
4396 \& ORNAMENT
4397 \& ❰ ❱ U+2770, U+2771 HEAVY LEFT/RIGHT\-POINTING ANGLE BRACKET ORNAMENT
4398 \& ❲ ❳ U+2772, U+2773 LIGHT LEFT/RIGHT TORTOISE SHELL BRACKET ORNAMENT
4399 \& ❴ ❵ U+2774, U+2775 MEDIUM LEFT/RIGHT CURLY BRACKET ORNAMENT
4400 \& ⟃ ⟄ U+27C3, U+27C4 OPEN SUBSET/SUPERSET
4401 \& ⟅ ⟆ U+27C5, U+27C6 LEFT/RIGHT S\-SHAPED BAG DELIMITER
4402 \& ⟈ ⟉ U+27C8, U+27C9 REVERSE SOLIDUS PRECEDING SUBSET, SUPERSET
4403 \& PRECEDING SOLIDUS
4404 \& ⟞ ⟝ U+27DE, U+27DD LONG LEFT/RIGHT TACK
4405 \& ⟦ ⟧ U+27E6, U+27E7 MATHEMATICAL LEFT/RIGHT WHITE SQUARE BRACKET
4406 \& ⟨ ⟩ U+27E8, U+27E9 MATHEMATICAL LEFT/RIGHT ANGLE BRACKET
4407 \& ⟪ ⟫ U+27EA, U+27EB MATHEMATICAL LEFT/RIGHT DOUBLE ANGLE BRACKET
4408 \& ⟬ ⟭ U+27EC, U+27ED MATHEMATICAL LEFT/RIGHT WHITE TORTOISE SHELL
4409 \& BRACKET
4410 \& ⟮ ⟯ U+27EE, U+27EF MATHEMATICAL LEFT/RIGHT FLATTENED PARENTHESIS
4411 \& ⟴ ⬲ U+27F4, U+2B32 RIGHT/LEFT ARROW WITH CIRCLED PLUS
4412 \& ⟶ ⟵ U+27F6, U+27F5 LONG RIGHT/LEFTWARDS ARROW
4413 \& ⟹ ⟸ U+27F9, U+27F8 LONG RIGHT/LEFTWARDS DOUBLE ARROW
4414 \& ⟼ ⟻ U+27FC, U+27FB LONG RIGHT/LEFTWARDS ARROW FROM BAR
4415 \& ⟾ ⟽ U+27FE, U+27FD LONG RIGHT/LEFTWARDS DOUBLE ARROW FROM BAR
4416 \& ⟿ ⬳ U+27FF, U+2B33 LONG RIGHT/LEFTWARDS SQUIGGLE ARROW
4417 \& ⤀ ⬴ U+2900, U+2B34 RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH VERTICAL
4418 \& STROKE
4419 \& ⤁ ⬵ U+2901, U+2B35 RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH DOUBLE
4420 \& VERTICAL STROKE
4421 \& ⤃ ⤂ U+2903, U+2902 RIGHT/LEFTWARDS DOUBLE ARROW WITH VERTICAL
4422 \& STROKE
4423 \& ⤅ ⬶ U+2905, U+2B36 RIGHT/LEFTWARDS TWO\-HEADED ARROW FROM BAR
4424 \& ⤇ ⤆ U+2907, U+2906 RIGHT/LEFTWARDS DOUBLE ARROW FROM BAR
4425 \& ⤍ ⤌ U+290D, U+290C RIGHT/LEFTWARDS DOUBLE DASH ARROW
4426 \& ⤏ ⤎ U+290F, U+290E RIGHT/LEFTWARDS TRIPLE DASH ARROW
4427 \& ⤐ ⬷ U+2910, U+2B37 RIGHT/LEFTWARDS TWO\-HEADED TRIPLE DASH ARROW
4428 \& ⤑ ⬸ U+2911, U+2B38 RIGHT/LEFTWARDS ARROW WITH DOTTED STEM
4429 \& ⤔ ⬹ U+2914, U+2B39 RIGHT/LEFTWARDS ARROW WITH TAIL WITH VERTICAL
4430 \& STROKE
4431 \& ⤕ ⬺ U+2915, U+2B3A RIGHT/LEFTWARDS ARROW WITH TAIL WITH DOUBLE
4432 \& VERTICAL STROKE
4433 \& ⤖ ⬻ U+2916, U+2B3B RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL
4434 \& ⤗ ⬼ U+2917, U+2B3C RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL WITH
4435 \& VERTICAL STROKE
4436 \& ⤘ ⬽ U+2918, U+2B3D RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TAIL WITH
4437 \& DOUBLE VERTICAL STROKE
4438 \& ⤚ ⤙ U+291A, U+2919 RIGHT/LEFTWARDS ARROW\-TAIL
4439 \& ⤜ ⤛ U+291C, U+291B RIGHT/LEFTWARDS DOUBLE ARROW\-TAIL
4440 \& ⤞ ⤝ U+291E, U+291D RIGHT/LEFTWARDS ARROW TO BLACK DIAMOND
4441 \& ⤠ ⤟ U+2920, U+291F RIGHT/LEFTWARDS ARROW FROM BAR TO BLACK DIAMOND
4442 \& ⤳ ⬿ U+2933, U+2B3F WAVE ARROW POINTING DIRECTLY RIGHT/LEFT
4443 \& ⤷ ⤶ U+2937, U+2936 ARROW POINTING DOWNWARDS THEN CURVING RIGHT/
4444 \& LEFTWARDS
4445 \& ⥅ ⥆ U+2945, U+2946 RIGHT/LEFTWARDS ARROW WITH PLUS BELOW
4446 \& ⥇ ⬾ U+2947, U+2B3E RIGHT/LEFTWARDS ARROW THROUGH X
4447 \& ⥓ ⥒ U+2953, U+2952 RIGHT/LEFTWARDS HARPOON WITH BARB UP TO BAR
4448 \& ⥗ ⥖ U+2957, U+2956 RIGHT/LEFTWARDS HARPOON WITH BARB DOWN TO BAR
4449 \& ⥛ ⥚ U+295B, U+295A RIGHT/LEFTWARDS HARPOON WITH BARB UP FROM BAR
4450 \& ⥟ ⥞ U+295F, U+295E RIGHT/LEFTWARDS HARPOON WITH BARB DOWN FROM BAR
4451 \& ⥤ ⥢ U+2964, U+2962 RIGHT/LEFTWARDS HARPOON WITH BARB UP ABOVE
4452 \& RIGHT/LEFTWARDS HARPOON WITH BARB DOWN
4453 \& ⥬ ⥪ U+296C, U+296A RIGHT/LEFTWARDS HARPOON WITH BARB UP ABOVE LONG
4454 \& DASH
4455 \& ⥭ ⥫ U+296D, U+296B RIGHT/LEFTWARDS HARPOON WITH BARB DOWN BELOW
4456 \& LONG DASH
4457 \& ⥱ ⭀ U+2971, U+2B40 EQUALS SIGN ABOVE RIGHT/LEFTWARDS ARROW
4458 \& ⥲ ⭁ U+2972, U+2B41 TILDE OPERATOR ABOVE RIGHTWARDS ARROW, REVERSE
4459 \& TILDE OPERATOR ABOVE LEFTWARDS ARROW
4460 \& ⥴ ⭋ U+2974, U+2B4B RIGHTWARDS ARROW ABOVE TILDE OPERATOR,
4461 \& LEFTWARDS ARROW ABOVE REVERSE TILDE OPERATOR
4462 \& ⥵ ⭂ U+2975, U+2B42 RIGHTWARDS ARROW ABOVE ALMOST EQUAL TO,
4463 \& LEFTWARDS ARROW ABOVE REVERSE ALMOST EQUAL TO
4464 \& ⥹ ⥻ U+2979, U+297B SUBSET/SUPERSET ABOVE RIGHT/LEFTWARDS ARROW
4465 \& ⦃ ⦄ U+2983, U+2984 LEFT/RIGHT WHITE CURLY BRACKET
4466 \& ⦅ ⦆ U+2985, U+2986 LEFT/RIGHT WHITE PARENTHESIS
4467 \& ⦇ ⦈ U+2987, U+2988 Z NOTATION LEFT/RIGHT IMAGE BRACKET
4468 \& ⦉ ⦊ U+2989, U+298A Z NOTATION LEFT/RIGHT BINDING BRACKET
4469 \& ⦋ ⦌ U+298B, U+298C LEFT/RIGHT SQUARE BRACKET WITH UNDERBAR
4470 \& ⦍ ⦐ U+298D, U+2990 LEFT/RIGHT SQUARE BRACKET WITH TICK IN TOP
4471 \& CORNER
4472 \& ⦏ ⦎ U+298F, U+298E LEFT/RIGHT SQUARE BRACKET WITH TICK IN BOTTOM
4473 \& CORNER
4474 \& ⦑ ⦒ U+2991, U+2992 LEFT/RIGHT ANGLE BRACKET WITH DOT
4475 \& ⦓ ⦔ U+2993, U+2994 LEFT/RIGHT ARC LESS\-THAN/GREATER\-THAN BRACKET
4476 \& ⦕ ⦖ U+2995, U+2996 DOUBLE LEFT/RIGHT ARC GREATER\-THAN/LESS\-THAN
4477 \& BRACKET
4478 \& ⦗ ⦘ U+2997, U+2998 LEFT/RIGHT BLACK TORTOISE SHELL BRACKET
4479 \& ⦨ ⦩ U+29A8, U+29A9 MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW
4480 \& POINTING UP AND RIGHT/LEFT
4481 \& ⦪ ⦫ U+29AA, U+29AB MEASURED ANGLE WITH OPEN ARM ENDING IN ARROW
4482 \& POINTING DOWN AND RIGHT/LEFT
4483 \& ⦳ ⦴ U+29B3, U+29B4 EMPTY SET WITH RIGHT/LEFT ARROW ABOVE
4484 \& ⧀ ⧁ U+29C0, U+29C1 CIRCLED LESS\-THAN/GREATER\-THAN
4485 \& ⧘ ⧙ U+29D8, U+29D9 LEFT/RIGHT WIGGLY FENCE
4486 \& ⧚ ⧛ U+29DA, U+29DB LEFT/RIGHT DOUBLE WIGGLY FENCE
4487 \& ⧼ ⧽ U+29FC, U+29FD LEFT/RIGHT\-POINTING CURVED ANGLE BRACKET
4488 \& ⩹ ⩺ U+2A79, U+2A7A LESS\-THAN/GREATER\-THAN WITH CIRCLE INSIDE
4489 \& ⩻ ⩼ U+2A7B, U+2A7C LESS\-THAN/GREATER\-THAN WITH QUESTION MARK ABOVE
4490 \& ⩽ ⩾ U+2A7D, U+2A7E LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO
4491 \& ⩿ ⪀ U+2A7F, U+2A80 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4492 \& DOT INSIDE
4493 \& ⪁ ⪂ U+2A81, U+2A82 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4494 \& DOT ABOVE
4495 \& ⪃ ⪄ U+2A83, U+2A84 LESS\-THAN/GREATER\-THAN OR SLANTED EQUAL TO WITH
4496 \& DOT ABOVE RIGHT/LEFT
4497 \& ⪅ ⪆ U+2A85, U+2A86 LESS\-THAN/GREATER\-THAN OR APPROXIMATE
4498 \& ⪇ ⪈ U+2A87, U+2A88 LESS\-THAN/GREATER\-THAN AND SINGLE\-LINE NOT
4499 \& EQUAL TO
4500 \& ⪉ ⪊ U+2A89, U+2A8A LESS\-THAN/GREATER\-THAN AND NOT APPROXIMATE
4501 \& ⪍ ⪎ U+2A8D, U+2A8E LESS\-THAN/GREATER\-THAN ABOVE SIMILAR OR EQUAL
4502 \& ⪕ ⪖ U+2A95, U+2A96 SLANTED EQUAL TO OR LESS\-THAN/GREATER\-THAN
4503 \& ⪗ ⪘ U+2A97, U+2A98 SLANTED EQUAL TO OR LESS\-THAN/GREATER\-THAN WITH
4504 \& DOT INSIDE
4505 \& ⪙ ⪚ U+2A99, U+2A9A DOUBLE\-LINE EQUAL TO OR LESS\-THAN/GREATER\-THAN
4506 \& ⪛ ⪜ U+2A9B, U+2A9C DOUBLE\-LINE SLANTED EQUAL TO OR LESS\-THAN/
4507 \& GREATER\-THAN
4508 \& ⪝ ⪞ U+2A9D, U+2A9E SIMILAR OR LESS\-THAN/GREATER\-THAN
4509 \& ⪟ ⪠ U+2A9F, U+2AA0 SIMILAR ABOVE LESS\-THAN/GREATER\-THAN ABOVE
4510 \& EQUALS SIGN
4511 \& ⪡ ⪢ U+2AA1, U+2AA2 DOUBLE NESTED LESS\-THAN/GREATER\-THAN
4512 \& ⪦ ⪧ U+2AA6, U+2AA7 LESS\-THAN/GREATER\-THAN CLOSED BY CURVE
4513 \& ⪨ ⪩ U+2AA8, U+2AA9 LESS\-THAN/GREATER\-THAN CLOSED BY CURVE ABOVE
4514 \& SLANTED EQUAL
4515 \& ⪪ ⪫ U+2AAA, U+2AAB SMALLER THAN/LARGER THAN
4516 \& ⪬ ⪭ U+2AAC, U+2AAD SMALLER THAN/LARGER THAN OR EQUAL TO
4517 \& ⪯ ⪰ U+2AAF, U+2AB0 PRECEDES/SUCCEEDS ABOVE SINGLE\-LINE EQUALS SIGN
4518 \& ⪱ ⪲ U+2AB1, U+2AB2 PRECEDES/SUCCEEDS ABOVE SINGLE\-LINE NOT EQUAL TO
4519 \& ⪳ ⪴ U+2AB3, U+2AB4 PRECEDES/SUCCEEDS ABOVE EQUALS SIGN
4520 \& ⪵ ⪶ U+2AB5, U+2AB6 PRECEDES/SUCCEEDS ABOVE NOT EQUAL TO
4521 \& ⪷ ⪸ U+2AB7, U+2AB8 PRECEDES/SUCCEEDS ABOVE ALMOST EQUAL TO
4522 \& ⪹ ⪺ U+2AB9, U+2ABA PRECEDES/SUCCEEDS ABOVE NOT ALMOST EQUAL TO
4523 \& ⪻ ⪼ U+2ABB, U+2ABC DOUBLE PRECEDES/SUCCEEDS
4524 \& ⪽ ⪾ U+2ABD, U+2ABE SUBSET/SUPERSET WITH DOT
4525 \& ⪿ ⫀ U+2ABF, U+2AC0 SUBSET/SUPERSET WITH PLUS SIGN BELOW
4526 \& ⫁ ⫂ U+2AC1, U+2AC2 SUBSET/SUPERSET WITH MULTIPLICATION SIGN BELOW
4527 \& ⫃ ⫄ U+2AC3, U+2AC4 SUBSET/SUPERSET OF OR EQUAL TO WITH DOT ABOVE
4528 \& ⫅ ⫆ U+2AC5, U+2AC6 SUBSET/SUPERSET OF ABOVE EQUALS SIGN
4529 \& ⫇ ⫈ U+2AC7, U+2AC8 SUBSET/SUPERSET OF ABOVE TILDE OPERATOR
4530 \& ⫉ ⫊ U+2AC9, U+2ACA SUBSET/SUPERSET OF ABOVE ALMOST EQUAL TO
4531 \& ⫋ ⫌ U+2ACB, U+2ACC SUBSET/SUPERSET OF ABOVE NOT EQUAL TO
4532 \& ⫏ ⫐ U+2ACF, U+2AD0 CLOSED SUBSET/SUPERSET
4533 \& ⫑ ⫒ U+2AD1, U+2AD2 CLOSED SUBSET/SUPERSET OR EQUAL TO
4534 \& ⫕ ⫖ U+2AD5, U+2AD6 SUBSET/SUPERSET ABOVE SUBSET/SUPERSET
4535 \& ⫥ ⊫ U+2AE5, U+22AB DOUBLE VERTICAL BAR DOUBLE LEFT/RIGHT TURNSTILE
4536 \& ⫷ ⫸ U+2AF7, U+2AF8 TRIPLE NESTED LESS\-THAN/GREATER\-THAN
4537 \& ⫹ ⫺ U+2AF9, U+2AFA DOUBLE\-LINE SLANTED LESS\-THAN/GREATER\-THAN OR
4538 \& EQUAL TO
4539 \& ⭆ ⭅ U+2B46, U+2B45 RIGHT/LEFTWARDS QUADRUPLE ARROW
4540 \& ⭇ ⭉ U+2B47, U+2B49 REVERSE TILDE OPERATOR ABOVE RIGHTWARDS ARROW,
4541 \& TILDE OPERATOR ABOVE LEFTWARDS ARROW
4542 \& ⭈ ⭊ U+2B48, U+2B4A RIGHTWARDS ARROW ABOVE REVERSE ALMOST EQUAL
4543 \& TO, LEFTWARDS ARROW ABOVE ALMOST EQUAL TO
4544 \& ⭌ ⥳ U+2B4C, U+2973 RIGHTWARDS ARROW ABOVE REVERSE TILDE OPERATOR,
4545 \& LEFTWARDS ARROW ABOVE TILDE OPERATOR
4546 \& ⭢ ⭠ U+2B62, U+2B60 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW
4547 \& ⭬ ⭪ U+2B6C, U+2B6A RIGHT/LEFTWARDS TRIANGLE\-HEADED DASHED ARROW
4548 \& ⭲ ⭰ U+2B72, U+2B70 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW TO BAR
4549 \& ⭼ ⭺ U+2B7C, U+2B7A RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4550 \& DOUBLE VERTICAL STROKE
4551 \& ⮆ ⮄ U+2B86, U+2B84 RIGHT/LEFTWARDS TRIANGLE\-HEADED PAIRED ARROWS
4552 \& ⮊ ⮈ U+2B8A, U+2B88 RIGHT/LEFTWARDS BLACK CIRCLED WHITE ARROW
4553 \& ⮕ ⬅ U+2B95, U+2B05 RIGHT/LEFTWARDS BLACK ARROW
4554 \& ⮚ ⮘ U+2B9A, U+2B98 THREE\-D TOP\-LIGHTED RIGHT/LEFTWARDS EQUILATERAL
4555 \& ARROWHEAD
4556 \& ⮞ ⮜ U+2B9E, U+2B9C BLACK RIGHT/LEFTWARDS EQUILATERAL ARROWHEAD
4557 \& ⮡ ⮠ U+2BA1, U+2BA0 DOWNWARDS TRIANGLE\-HEADED ARROW WITH LONG TIP
4558 \& RIGHT/LEFTWARDS
4559 \& ⮣ ⮢ U+2BA3, U+2BA2 UPWARDS TRIANGLE\-HEADED ARROW WITH LONG TIP
4560 \& RIGHT/LEFTWARDS
4561 \& ⮩ ⮨ U+2BA9, U+2BA8 BLACK CURVED DOWNWARDS AND RIGHT/LEFTWARDS ARROW
4562 \& ⮫ ⮪ U+2BAB, U+2BAA BLACK CURVED UPWARDS AND RIGHT/LEFTWARDS ARROW
4563 \& ⮱ ⮰ U+2BB1, U+2BB0 RIBBON ARROW DOWN RIGHT/LEFT
4564 \& ⮳ ⮲ U+2BB3, U+2BB2 RIBBON ARROW UP RIGHT/LEFT
4565 \& ⯮ ⯬ U+2BEE, U+2BEC RIGHT/LEFTWARDS TWO\-HEADED ARROW WITH TRIANGLE
4566 \& ARROWHEADS
4567 \& ⸂ ⸃ U+2E02, U+2E03 LEFT/RIGHT SUBSTITUTION BRACKET
4568 \& ⸃ ⸂ U+2E03, U+2E02 RIGHT/LEFT SUBSTITUTION BRACKET
4569 \& ⸄ ⸅ U+2E04, U+2E05 LEFT/RIGHT DOTTED SUBSTITUTION BRACKET
4570 \& ⸅ ⸄ U+2E05, U+2E04 RIGHT/LEFT DOTTED SUBSTITUTION BRACKET
4571 \& ⸉ ⸊ U+2E09, U+2E0A LEFT/RIGHT TRANSPOSITION BRACKET
4572 \& ⸊ ⸉ U+2E0A, U+2E09 RIGHT/LEFT TRANSPOSITION BRACKET
4573 \& ⸌ ⸍ U+2E0C, U+2E0D LEFT/RIGHT RAISED OMISSION BRACKET
4574 \& ⸍ ⸌ U+2E0D, U+2E0C RIGHT/LEFT RAISED OMISSION BRACKET
4575 \& ⸑ ⸐ U+2E11, U+2E10 REVERSED FORKED PARAGRAPHOS, FORKED PARAGRAPHOS
4576 \& ⸜ ⸝ U+2E1C, U+2E1D LEFT/RIGHT LOW PARAPHRASE BRACKET
4577 \& ⸝ ⸜ U+2E1D, U+2E1C RIGHT/LEFT LOW PARAPHRASE BRACKET
4578 \& ⸠ ⸡ U+2E20, U+2E21 LEFT/RIGHT VERTICAL BAR WITH QUILL
4579 \& ⸡ ⸠ U+2E21, U+2E20 RIGHT/LEFT VERTICAL BAR WITH QUILL
4580 \& ⸢ ⸣ U+2E22, U+2E23 TOP LEFT/RIGHT HALF BRACKET
4581 \& ⸤ ⸥ U+2E24, U+2E25 BOTTOM LEFT/RIGHT HALF BRACKET
4582 \& ⸦ ⸧ U+2E26, U+2E27 LEFT/RIGHT SIDEWAYS U BRACKET
4583 \& ⸨ ⸩ U+2E28, U+2E29 LEFT/RIGHT DOUBLE PARENTHESIS
4584 \& ⸶ ⸷ U+2E36, U+2E37 DAGGER WITH LEFT/RIGHT GUARD
4585 \& ⹂ „ U+2E42, U+201E DOUBLE LOW\-REVERSED\-9 QUOTATION MARK, DOUBLE
4586 \& LOW\-9 QUOTATION MARK
4587 \& ⹕ ⹖ U+2E55, U+2E56 LEFT/RIGHT SQUARE BRACKET WITH STROKE
4588 \& ⹗ ⹘ U+2E57, U+2E58 LEFT/RIGHT SQUARE BRACKET WITH DOUBLE STROKE
4589 \& ⹙ ⹚ U+2E59, U+2E5A TOP HALF LEFT/RIGHT PARENTHESIS
4590 \& ⹛ ⹜ U+2E5B, U+2E5C BOTTOM HALF LEFT/RIGHT PARENTHESIS
4591 \& 〈 〉 U+3008, U+3009 LEFT/RIGHT ANGLE BRACKET
4592 \& 《 》 U+300A, U+300B LEFT/RIGHT DOUBLE ANGLE BRACKET
4593 \& 「 」 U+300C, U+300D LEFT/RIGHT CORNER BRACKET
4594 \& 『 』 U+300E, U+300F LEFT/RIGHT WHITE CORNER BRACKET
4595 \& 【 】 U+3010, U+3011 LEFT/RIGHT BLACK LENTICULAR BRACKET
4596 \& 〔 〕 U+3014, U+3015 LEFT/RIGHT TORTOISE SHELL BRACKET
4597 \& 〖 〗 U+3016, U+3017 LEFT/RIGHT WHITE LENTICULAR BRACKET
4598 \& 〘 〙 U+3018, U+3019 LEFT/RIGHT WHITE TORTOISE SHELL BRACKET
4599 \& 〚 〛 U+301A, U+301B LEFT/RIGHT WHITE SQUARE BRACKET
4600 \& 〝 〞 U+301D, U+301E REVERSED DOUBLE PRIME QUOTATION MARK, DOUBLE
4601 \& PRIME QUOTATION MARK
4602 \& ꧁ ꧂ U+A9C1, U+A9C2 JAVANESE LEFT/RIGHT RERENGGAN
4603 \& ﴾ ﴿ U+FD3E, U+FD3F ORNATE LEFT/RIGHT PARENTHESIS
4604 \& ﹙ ﹚ U+FE59, U+FE5A SMALL LEFT/RIGHT PARENTHESIS
4605 \& ﹛ ﹜ U+FE5B, U+FE5C SMALL LEFT/RIGHT CURLY BRACKET
4606 \& ﹝ ﹞ U+FE5D, U+FE5E SMALL LEFT/RIGHT TORTOISE SHELL BRACKET
4607 \& ﹤ ﹥ U+FE64, U+FE65 SMALL LESS\-THAN/GREATER\-THAN SIGN
4608 \& ( ) U+FF08, U+FF09 FULLWIDTH LEFT/RIGHT PARENTHESIS
4609 \& < > U+FF1C, U+FF1E FULLWIDTH LESS\-THAN/GREATER\-THAN SIGN
4610 \& [ ] U+FF3B, U+FF3D FULLWIDTH LEFT/RIGHT SQUARE BRACKET
4611 \& { } U+FF5B, U+FF5D FULLWIDTH LEFT/RIGHT CURLY BRACKET
4612 \& ⦅ ⦆ U+FF5F, U+FF60 FULLWIDTH LEFT/RIGHT WHITE PARENTHESIS
4613 \& 「 」 U+FF62, U+FF63 HALFWIDTH LEFT/RIGHT CORNER BRACKET
4614 \& → ← U+FFEB, U+FFE9 HALFWIDTH RIGHT/LEFTWARDS ARROW
4615 \& 𝄃 𝄂 U+1D103, U+1D102 MUSICAL SYMBOL REVERSE FINAL BARLINE, MUSICAL
4616 \& SYMBOL FINAL BARLINE
4617 \& 𝄆 𝄇 U+1D106, U+1D107 MUSICAL SYMBOL LEFT/RIGHT REPEAT SIGN
4618 \& 👉 👈 U+1F449, U+1F448 WHITE RIGHT/LEFT POINTING BACKHAND INDEX
4619 \& 🔈 🕨 U+1F508, U+1F568 SPEAKER, RIGHT SPEAKER
4620 \& 🔉 🕩 U+1F509, U+1F569 SPEAKER WITH ONE SOUND WAVE, RIGHT SPEAKER WITH
4621 \& ONE SOUND WAVE
4622 \& 🔊 🕪 U+1F50A, U+1F56A SPEAKER WITH THREE SOUND WAVES, RIGHT SPEAKER
4623 \& WITH THREE SOUND WAVES
4624 \& 🕻 🕽 U+1F57B, U+1F57D LEFT/RIGHT HAND TELEPHONE RECEIVER
4625 \& 🖙 🖘 U+1F599, U+1F598 SIDEWAYS WHITE RIGHT/LEFT POINTING INDEX
4626 \& 🖛 🖚 U+1F59B, U+1F59A SIDEWAYS BLACK RIGHT/LEFT POINTING INDEX
4627 \& 🖝 🖜 U+1F59D, U+1F59C BLACK RIGHT/LEFT POINTING BACKHAND INDEX
4628 \& 🗦 🗧 U+1F5E6, U+1F5E7 THREE RAYS LEFT/RIGHT
4629 \& 🠂 🠀 U+1F802, U+1F800 RIGHT/LEFTWARDS ARROW WITH SMALL TRIANGLE
4630 \& ARROWHEAD
4631 \& 🠆 🠄 U+1F806, U+1F804 RIGHT/LEFTWARDS ARROW WITH MEDIUM TRIANGLE
4632 \& ARROWHEAD
4633 \& 🠊 🠈 U+1F80A, U+1F808 RIGHT/LEFTWARDS ARROW WITH LARGE TRIANGLE
4634 \& ARROWHEAD
4635 \& 🠒 🠐 U+1F812, U+1F810 RIGHT/LEFTWARDS ARROW WITH SMALL EQUILATERAL
4636 \& ARROWHEAD
4637 \& 🠖 🠔 U+1F816, U+1F814 RIGHT/LEFTWARDS ARROW WITH EQUILATERAL ARROWHEAD
4638 \& 🠚 🠘 U+1F81A, U+1F818 HEAVY RIGHT/LEFTWARDS ARROW WITH EQUILATERAL
4639 \& ARROWHEAD
4640 \& 🠞 🠜 U+1F81E, U+1F81C HEAVY RIGHT/LEFTWARDS ARROW WITH LARGE
4641 \& EQUILATERAL ARROWHEAD
4642 \& 🠢 🠠 U+1F822, U+1F820 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4643 \& NARROW SHAFT
4644 \& 🠦 🠤 U+1F826, U+1F824 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4645 \& MEDIUM SHAFT
4646 \& 🠪 🠨 U+1F82A, U+1F828 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH BOLD
4647 \& SHAFT
4648 \& 🠮 🠬 U+1F82E, U+1F82C RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH
4649 \& HEAVY SHAFT
4650 \& 🠲 🠰 U+1F832, U+1F830 RIGHT/LEFTWARDS TRIANGLE\-HEADED ARROW WITH VERY
4651 \& HEAVY SHAFT
4652 \& 🠶 🠴 U+1F836, U+1F834 RIGHT/LEFTWARDS FINGER\-POST ARROW
4653 \& 🠺 🠸 U+1F83A, U+1F838 RIGHT/LEFTWARDS SQUARED ARROW
4654 \& 🠾 🠼 U+1F83E, U+1F83C RIGHT/LEFTWARDS COMPRESSED ARROW
4655 \& 🡂 🡀 U+1F842, U+1F840 RIGHT/LEFTWARDS HEAVY COMPRESSED ARROW
4656 \& 🡆 🡄 U+1F846, U+1F844 RIGHT/LEFTWARDS HEAVY ARROW
4657 \& 🡒 🡐 U+1F852, U+1F850 RIGHT/LEFTWARDS SANS\-SERIF ARROW
4658 \& 🡢 🡠 U+1F862, U+1F860 WIDE\-HEADED RIGHT/LEFTWARDS LIGHT BARB ARROW
4659 \& 🡪 🡨 U+1F86A, U+1F868 WIDE\-HEADED RIGHT/LEFTWARDS BARB ARROW
4660 \& 🡲 🡰 U+1F872, U+1F870 WIDE\-HEADED RIGHT/LEFTWARDS MEDIUM BARB ARROW
4661 \& 🡺 🡸 U+1F87A, U+1F878 WIDE\-HEADED RIGHT/LEFTWARDS HEAVY BARB ARROW
4662 \& 🢂 🢀 U+1F882, U+1F880 WIDE\-HEADED RIGHT/LEFTWARDS VERY HEAVY BARB
4663 \& ARROW
4664 \& 🢒 🢐 U+1F892, U+1F890 RIGHT/LEFTWARDS TRIANGLE ARROWHEAD
4665 \& 🢖 🢔 U+1F896, U+1F894 RIGHT/LEFTWARDS WHITE ARROW WITHIN TRIANGLE
4666 \& ARROWHEAD
4667 \& 🢚 🢘 U+1F89A, U+1F898 RIGHT/LEFTWARDS ARROW WITH NOTCHED TAIL
4668 \& 🢡 🢠 U+1F8A1, U+1F8A0 RIGHTWARDS BOTTOM SHADED WHITE ARROW,
4669 \& LEFTWARDS BOTTOM\-SHADED WHITE ARROW
4670 \& 🢣 🢢 U+1F8A3, U+1F8A2 RIGHT/LEFTWARDS TOP SHADED WHITE ARROW
4671 \& 🢥 🢦 U+1F8A5, U+1F8A6 RIGHT/LEFTWARDS RIGHT\-SHADED WHITE ARROW
4672 \& 🢧 🢤 U+1F8A7, U+1F8A4 RIGHT/LEFTWARDS LEFT\-SHADED WHITE ARROW
4673 \& 🢩 🢨 U+1F8A9, U+1F8A8 RIGHT/LEFTWARDS BACK\-TILTED SHADOWED WHITE ARROW
4674 \& 🢫 🢪 U+1F8AB, U+1F8AA RIGHT/LEFTWARDS FRONT\-TILTED SHADOWED WHITE
4675 \& ARROW
4676 \& 🢶 🢴 U+1F8B6, U+1F8B4 NEGATIVE SQUARED RIGHT/LEFTWARDS ARROW
4677 .Ve