This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Accidental interpolation of $@ in Pod::Html [PATCH]
[perl5.git] / pod / perldata.pod
CommitLineData
a0d0e21e
LW
1=head1 NAME
2
cb1a09d0 3perldata - Perl data types
a0d0e21e
LW
4
5=head1 DESCRIPTION
6
7=head2 Variable names
8
d55a8828 9Perl has three built-in data types: scalars, arrays of scalars, and
692ef166
SF
10associative arrays of scalars, known as "hashes". A scalar is a
11single string (of any size, limited only by the available memory),
12number, or a reference to something (which will be discussed
13in L<perlref>). Normal arrays are ordered lists of scalars indexed
14by number, starting with 0. Hashes are unordered collections of scalar
15values indexed by their associated string key.
a0d0e21e 16
d55a8828 17Values are usually referred to by name, or through a named reference.
b88cefa9
PP
18The first character of the name tells you to what sort of data
19structure it refers. The rest of the name tells you the particular
d55a8828
TC
20value to which it refers. Usually this name is a single I<identifier>,
21that is, a string beginning with a letter or underscore, and
22containing letters, underscores, and digits. In some cases, it may
23be a chain of identifiers, separated by C<::> (or by the slightly
24archaic C<'>); all but the last are interpreted as names of packages,
25to locate the namespace in which to look up the final identifier
26(see L<perlmod/Packages> for details). It's possible to substitute
27for a simple identifier, an expression that produces a reference
28to the value at runtime. This is described in more detail below
29and in L<perlref>.
30
31Perl also has its own built-in variables whose names don't follow
32these rules. They have strange names so they don't accidentally
33collide with one of your normal variables. Strings that match
34parenthesized parts of a regular expression are saved under names
35containing only digits after the C<$> (see L<perlop> and L<perlre>).
36In addition, several special variables that provide windows into
37the inner working of Perl have names containing punctuation characters
38and control characters. These are documented in L<perlvar>.
39
40Scalar values are always named with '$', even when referring to a
41scalar that is part of an array or a hash. The '$' symbol works
42semantically like the English word "the" in that it indicates a
43single value is expected.
a0d0e21e
LW
44
45 $days # the simple scalar value "days"
46 $days[28] # the 29th element of array @days
47 $days{'Feb'} # the 'Feb' value from hash %days
48 $#days # the last index of array @days
49
d55a8828
TC
50Entire arrays (and slices of arrays and hashes) are denoted by '@',
51which works much like the word "these" or "those" does in English,
52in that it indicates multiple values are expected.
a0d0e21e
LW
53
54 @days # ($days[0], $days[1],... $days[n])
d55a8828 55 @days[3,4,5] # same as ($days[3],$days[4],$days[5])
a0d0e21e
LW
56 @days{'a','c'} # same as ($days{'a'},$days{'c'})
57
d55a8828 58Entire hashes are denoted by '%':
a0d0e21e
LW
59
60 %days # (key1, val1, key2, val2 ...)
61
d55a8828
TC
62In addition, subroutines are named with an initial '&', though this
63is optional when unambiguous, just as the word "do" is often redundant
64in English. Symbol table entries can be named with an initial '*',
65but you don't really care about that yet (if ever :-).
66
67Every variable type has its own namespace, as do several
68non-variable identifiers. This means that you can, without fear
69of conflict, use the same name for a scalar variable, an array, or
70a hash--or, for that matter, for a filehandle, a directory handle, a
71subroutine name, a format name, or a label. This means that $foo
72and @foo are two different variables. It also means that C<$foo[1]>
73is a part of @foo, not a part of $foo. This may seem a bit weird,
74but that's okay, because it is weird.
75
76Because variable references always start with '$', '@', or '%', the
77"reserved" words aren't in fact reserved with respect to variable
78names. They I<are> reserved with respect to labels and filehandles,
79however, which don't have an initial special character. You can't
80have a filehandle named "log", for instance. Hint: you could say
81C<open(LOG,'logfile')> rather than C<open(log,'logfile')>. Using
82uppercase filehandles also improves readability and protects you
83from conflict with future reserved words. Case I<is> significant--"FOO",
84"Foo", and "foo" are all different names. Names that start with a
85letter or underscore may also contain digits and underscores.
a0d0e21e
LW
86
87It is possible to replace such an alphanumeric name with an expression
d55a8828 88that returns a reference to the appropriate type. For a description
a0d0e21e
LW
89of this, see L<perlref>.
90
5f05dabc 91Names that start with a digit may contain only more digits. Names
9539f610
RGS
92that do not start with a letter, underscore, digit or a caret (i.e.
93a control character) are limited to one character, e.g., C<$%> or
94C<$$>. (Most of these one character names have a predefined
95significance to Perl. For instance, C<$$> is the current process
96id.)
a0d0e21e
LW
97
98=head2 Context
99
100The interpretation of operations and values in Perl sometimes depends
101on the requirements of the context around the operation or value.
d55a8828 102There are two major contexts: list and scalar. Certain operations
a0d0e21e 103return list values in contexts wanting a list, and scalar values
d55a8828
TC
104otherwise. If this is true of an operation it will be mentioned in
105the documentation for that operation. In other words, Perl overloads
a0d0e21e 106certain operations based on whether the expected return value is
d55a8828
TC
107singular or plural. Some words in English work this way, like "fish"
108and "sheep".
a0d0e21e
LW
109
110In a reciprocal fashion, an operation provides either a scalar or a
111list context to each of its arguments. For example, if you say
112
113 int( <STDIN> )
114
c47ff5f1 115the integer operation provides scalar context for the <>
a0d0e21e
LW
116operator, which responds by reading one line from STDIN and passing it
117back to the integer operation, which will then find the integer value
118of that line and return that. If, on the other hand, you say
119
120 sort( <STDIN> )
121
c47ff5f1 122then the sort operation provides list context for <>, which
a0d0e21e
LW
123will proceed to read every line available up to the end of file, and
124pass that list of lines back to the sort routine, which will then
125sort those lines and return them as a list to whatever the context
126of the sort was.
127
d55a8828
TC
128Assignment is a little bit special in that it uses its left argument
129to determine the context for the right argument. Assignment to a
130scalar evaluates the right-hand side in scalar context, while
131assignment to an array or hash evaluates the righthand side in list
132context. Assignment to a list (or slice, which is just a list
133anyway) also evaluates the righthand side in list context.
134
9f1b1f2d
GS
135When you use the C<use warnings> pragma or Perl's B<-w> command-line
136option, you may see warnings
d55a8828
TC
137about useless uses of constants or functions in "void context".
138Void context just means the value has been discarded, such as a
139statement containing only C<"fred";> or C<getpwuid(0);>. It still
140counts as scalar context for functions that care whether or not
141they're being called in list context.
142
143User-defined subroutines may choose to care whether they are being
144called in a void, scalar, or list context. Most subroutines do not
145need to bother, though. That's because both scalars and lists are
146automatically interpolated into lists. See L<perlfunc/wantarray>
147for how you would dynamically discern your function's calling
148context.
a0d0e21e
LW
149
150=head2 Scalar values
151
d55a8828
TC
152All data in Perl is a scalar, an array of scalars, or a hash of
153scalars. A scalar may contain one single value in any of three
154different flavors: a number, a string, or a reference. In general,
155conversion from one form to another is transparent. Although a
156scalar may not directly hold multiple values, it may contain a
157reference to an array or hash which in turn contains multiple values.
158
159Scalars aren't necessarily one thing or another. There's no place
160to declare a scalar variable to be of type "string", type "number",
161type "reference", or anything else. Because of the automatic
162conversion of scalars, operations that return scalars don't need
163to care (and in fact, cannot care) whether their caller is looking
164for a string, a number, or a reference. Perl is a contextually
165polymorphic language whose scalars can be strings, numbers, or
166references (which includes objects). Although strings and numbers
167are considered pretty much the same thing for nearly all purposes,
168references are strongly-typed, uncastable pointers with builtin
169reference-counting and destructor invocation.
a0d0e21e
LW
170
171A scalar value is interpreted as TRUE in the Boolean sense if it is not
19799a22 172the null string or the number 0 (or its string equivalent, "0"). The
d55a8828
TC
173Boolean context is just a special kind of scalar context where no
174conversion to a string or a number is ever performed.
175
176There are actually two varieties of null strings (sometimes referred
177to as "empty" strings), a defined one and an undefined one. The
178defined version is just a string of length zero, such as C<"">.
179The undefined version is the value that indicates that there is
180no real value for something, such as when there was an error, or
181at end of file, or when you refer to an uninitialized variable or
182element of an array or hash. Although in early versions of Perl,
183an undefined scalar could become defined when first used in a
184place expecting a defined value, this no longer happens except for
185rare cases of autovivification as explained in L<perlref>. You can
186use the defined() operator to determine whether a scalar value is
187defined (this has no meaning on arrays or hashes), and the undef()
188operator to produce an undefined value.
189
190To find out whether a given string is a valid non-zero number, it's
191sometimes enough to test it against both numeric 0 and also lexical
692ef166
SF
192"0" (although this will cause noises if warnings are on). That's
193because strings that aren't numbers count as 0, just as they do in B<awk>:
4633a7c4
LW
194
195 if ($str == 0 && $str ne "0") {
196 warn "That doesn't look like a number";
54310121 197 }
4633a7c4 198
d55a8828
TC
199That method may be best because otherwise you won't treat IEEE
200notations like C<NaN> or C<Infinity> properly. At other times, you
201might prefer to determine whether string data can be used numerically
202by calling the POSIX::strtod() function or by inspecting your string
203with a regular expression (as documented in L<perlre>).
cb1a09d0
AD
204
205 warn "has nondigits" if /\D/;
5a964f20
TC
206 warn "not a natural number" unless /^\d+$/; # rejects -3
207 warn "not an integer" unless /^-?\d+$/; # rejects +3
208 warn "not an integer" unless /^[+-]?\d+$/;
209 warn "not a decimal number" unless /^-?\d+\.?\d*$/; # rejects .2
210 warn "not a decimal number" unless /^-?(?:\d+(?:\.\d*)?|\.\d+)$/;
54310121 211 warn "not a C float"
cb1a09d0
AD
212 unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
213
d55a8828 214The length of an array is a scalar value. You may find the length
fc518ee5 215of array @days by evaluating C<$#days>, as in B<csh>. However, this
216isn't the length of the array; it's the subscript of the last element,
217which is a different value since there is ordinarily a 0th element.
d55a8828
TC
218Assigning to C<$#days> actually changes the length of the array.
219Shortening an array this way destroys intervening values. Lengthening
220an array that was previously shortened does not recover values
221that were in those elements. (It used to do so in Perl 4, but we
222had to break this to make sure destructors were called when expected.)
223
210b36aa 224You can also gain some minuscule measure of efficiency by pre-extending
d55a8828
TC
225an array that is going to get big. You can also extend an array
226by assigning to an element that is off the end of the array. You
19799a22 227can truncate an array down to nothing by assigning the null list
d55a8828 228() to it. The following are equivalent:
a0d0e21e 229
84f709e7 230 @whatever = ();
3e3baf6d 231 $#whatever = -1;
a0d0e21e 232
d55a8828
TC
233If you evaluate an array in scalar context, it returns the length
234of the array. (Note that this is not true of lists, which return
235the last value, like the C comma operator, nor of built-in functions,
236which return whatever they feel like returning.) The following is
237always true:
a0d0e21e 238
84f709e7
JH
239 scalar(@whatever) == $#whatever - $[ + 1;
240
241Version 5 of Perl changed the semantics of C<$[>: files that don't set
242the value of C<$[> no longer need to worry about whether another
243file changed its value. (In other words, use of C<$[> is deprecated.)
244So in general you can assume that
245
a0d0e21e
LW
246 scalar(@whatever) == $#whatever + 1;
247
d55a8828
TC
248Some programmers choose to use an explicit conversion so as to
249leave nothing to doubt:
4633a7c4
LW
250
251 $element_count = scalar(@whatever);
252
d55a8828
TC
253If you evaluate a hash in scalar context, it returns false if the
254hash is empty. If there are any key/value pairs, it returns true;
255more precisely, the value returned is a string consisting of the
256number of used buckets and the number of allocated buckets, separated
257by a slash. This is pretty much useful only to find out whether
258Perl's internal hashing algorithm is performing poorly on your data
259set. For example, you stick 10,000 things in a hash, but evaluating
260%HASH in scalar context reveals C<"1/16">, which means only one out
261of sixteen buckets has been touched, and presumably contains all
126c71c8
YST
26210,000 of your items. This isn't supposed to happen. If a tied hash
263is evaluated in scalar context, a fatal error will result, since this
264bucket usage information is currently not available for tied hashes.
a0d0e21e 265
5a964f20 266You can preallocate space for a hash by assigning to the keys() function.
65841adf 267This rounds up the allocated buckets to the next power of two:
5a964f20
TC
268
269 keys(%users) = 1000; # allocate 1024 buckets
270
a0d0e21e
LW
271=head2 Scalar value constructors
272
d55a8828 273Numeric literals are specified in any of the following floating point or
a0d0e21e
LW
274integer formats:
275
a0d0e21e
LW
276 12345
277 12345.67
d55a8828 278 .23E-10 # a very small number
928753ea 279 3.14_15_92 # a very important number
1d277562 280 4_294_967_296 # underscore for legibility
d55a8828 281 0xff # hex
928753ea 282 0xdead_beef # more hex
802a55ac 283 0377 # octal (only numbers, begins with 0)
d55a8828 284 0b011011 # binary
a0d0e21e 285
d4ced10d
JH
286You are allowed to use underscores (underbars) in numeric literals
287between digits for legibility. You could, for example, group binary
288digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
289or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
1d277562 290
55497cff 291String literals are usually delimited by either single or double
d55a8828
TC
292quotes. They work much like quotes in the standard Unix shells:
293double-quoted string literals are subject to backslash and variable
19799a22
GS
294substitution; single-quoted strings are not (except for C<\'> and
295C<\\>). The usual C-style backslash rules apply for making
d55a8828 296characters such as newline, tab, etc., as well as some more exotic
4a4eefd0 297forms. See L<perlop/"Quote and Quote-like Operators"> for a list.
d55a8828
TC
298
299Hexadecimal, octal, or binary, representations in string literals
300(e.g. '0xff') are not automatically converted to their integer
301representation. The hex() and oct() functions make these conversions
302for you. See L<perlfunc/hex> and L<perlfunc/oct> for more details.
68dc0745 303
5f05dabc 304You can also embed newlines directly in your strings, i.e., they can end
a0d0e21e
LW
305on a different line than they begin. This is nice, but if you forget
306your trailing quote, the error will not be reported until Perl finds
307another line containing the quote character, which may be much further
308on in the script. Variable substitution inside strings is limited to
d55a8828 309scalar variables, arrays, and array or hash slices. (In other words,
b88cefa9 310names beginning with $ or @, followed by an optional bracketed
a0d0e21e 311expression as a subscript.) The following code segment prints out "The
184e9718 312price is $Z<>100."
a0d0e21e 313
692ef166
SF
314 $Price = '$100'; # not interpolated
315 print "The price is $Price.\n"; # interpolated
316
317There is no double interpolation in Perl, so the C<$100> is left as is.
a0d0e21e 318
d55a8828 319As in some shells, you can enclose the variable name in braces to
f1cbbd6e
GS
320disambiguate it from following alphanumerics (and underscores).
321You must also do
d55a8828
TC
322this when interpolating a variable into a string to separate the
323variable name from a following double-colon or an apostrophe, since
324these would be otherwise treated as a package separator:
325
84f709e7 326 $who = "Larry";
d55a8828
TC
327 print PASSWD "${who}::0:0:Superuser:/:/bin/perl\n";
328 print "We use ${who}speak when ${who}'s here.\n";
329
330Without the braces, Perl would have looked for a $whospeak, a
331C<$who::0>, and a C<$who's> variable. The last two would be the
332$0 and the $s variables in the (presumably) non-existent package
333C<who>.
334
335In fact, an identifier within such curlies is forced to be a string,
336as is any simple identifier within a hash subscript. Neither need
337quoting. Our earlier example, C<$days{'Feb'}> can be written as
338C<$days{Feb}> and the quotes will be assumed automatically. But
719b43e8
RGS
339anything more complicated in the subscript will be interpreted as an
340expression. This means for example that C<$version{2.0}++> is
341equivalent to C<$version{2}++>, not to C<$version{'2.0'}++>.
d55a8828 342
692ef166
SF
343=head3 Version Strings
344
4aad3274 345B<Note:> Version Strings (v-strings) have been deprecated. They will
f61b605b
JH
346be removed in some future release after Perl 5.8.1. The marginal
347benefits of v-strings were greatly outweighed by the potential for
348Surprise and Confusion.
4aad3274 349
191d61a7 350A literal of the form C<v1.20.300.4000> is parsed as a string composed
6b2463a0
JH
351of characters with the specified ordinals. This form, known as
352v-strings, provides an alternative, more readable way to construct
353strings, rather than use the somewhat less readable interpolation form
354C<"\x{1}\x{14}\x{12c}\x{fa0}">. This is useful for representing
355Unicode strings, and for comparing version "numbers" using the string
356comparison operators, C<cmp>, C<gt>, C<lt> etc. If there are two or
357more dots in the literal, the leading C<v> may be omitted.
b9c62f5b
GS
358
359 print v9786; # prints UTF-8 encoded SMILEY, "\x{263a}"
360 print v102.111.111; # prints "foo"
361 print 102.111.111; # same
362
363Such literals are accepted by both C<require> and C<use> for
191d61a7
GS
364doing a version check. The C<$^V> special variable also contains the
365running Perl interpreter's version in this form. See L<perlvar/$^V>.
6b2463a0
JH
366Note that using the v-strings for IPv4 addresses is not portable unless
367you also use the inet_aton()/inet_ntoa() routines of the Socket package.
191d61a7 368
d32a65d2 369Note that since Perl 5.8.1 the single-number v-strings (like C<v65>)
8fa72689
JH
370are not v-strings before the C<< => >> operator (which is usually used
371to separate a hash key from a hash value), instead they are interpreted
15ecd4ae
JH
372as literal strings ('v65'). They were v-strings from Perl 5.6.0 to
373Perl 5.8.0, but that caused more confusion and breakage than good.
374Multi-number v-strings like C<v65.66> and C<65.66.67> continue to
375be v-strings always.
d32a65d2 376
692ef166
SF
377=head3 Special Literals
378
d55a8828 379The special literals __FILE__, __LINE__, and __PACKAGE__
68dc0745
PP
380represent the current filename, line number, and package name at that
381point in your program. They may be used only as separate tokens; they
382will not be interpolated into strings. If there is no current package
3e92a254
GS
383(due to an empty C<package;> directive), __PACKAGE__ is the undefined
384value.
385
386The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
387may be used to indicate the logical end of the script before the actual
388end of file. Any following text is ignored.
389
390Text after __DATA__ but may be read via the filehandle C<PACKNAME::DATA>,
391where C<PACKNAME> is the package that was current when the __DATA__
392token was encountered. The filehandle is left open pointing to the
393contents after __DATA__. It is the program's responsibility to
394C<close DATA> when it is done reading from it. For compatibility with
395older scripts written before __DATA__ was introduced, __END__ behaves
396like __DATA__ in the toplevel script (but not in files loaded with
397C<require> or C<do>) and leaves the remaining contents of the
398file accessible via C<main::DATA>.
399
400See L<SelfLoader> for more description of __DATA__, and
d55a8828
TC
401an example of its use. Note that you cannot read from the DATA
402filehandle in a BEGIN block: the BEGIN block is executed as soon
403as it is seen (during compilation), at which point the corresponding
a00c1fe5 404__DATA__ (or __END__) token has not yet been seen.
a0d0e21e 405
692ef166
SF
406=head3 Barewords
407
748a9306 408A word that has no other interpretation in the grammar will
a0d0e21e
LW
409be treated as if it were a quoted string. These are known as
410"barewords". As with filehandles and labels, a bareword that consists
411entirely of lowercase letters risks conflict with future reserved
9f1b1f2d
GS
412words, and if you use the C<use warnings> pragma or the B<-w> switch,
413Perl will warn you about any
a0d0e21e
LW
414such words. Some people may wish to outlaw barewords entirely. If you
415say
416
417 use strict 'subs';
418
419then any bareword that would NOT be interpreted as a subroutine call
420produces a compile-time error instead. The restriction lasts to the
54310121 421end of the enclosing block. An inner block may countermand this
a0d0e21e
LW
422by saying C<no strict 'subs'>.
423
692ef166
SF
424=head3 Array Joining Delimiter
425
d55a8828
TC
426Arrays and slices are interpolated into double-quoted strings
427by joining the elements with the delimiter specified in the C<$">
692ef166
SF
428variable (C<$LIST_SEPARATOR> if "use English;" is specified),
429space by default. The following are equivalent:
a0d0e21e 430
84f709e7 431 $temp = join($", @ARGV);
a0d0e21e
LW
432 system "echo $temp";
433
434 system "echo @ARGV";
435
436Within search patterns (which also undergo double-quotish substitution)
d55a8828 437there is an unfortunate ambiguity: Is C</$foo[bar]/> to be interpreted as
a0d0e21e
LW
438C</${foo}[bar]/> (where C<[bar]> is a character class for the regular
439expression) or as C</${foo[bar]}/> (where C<[bar]> is the subscript to array
440@foo)? If @foo doesn't otherwise exist, then it's obviously a
441character class. If @foo exists, Perl takes a good guess about C<[bar]>,
442and is almost always right. If it does guess wrong, or if you're just
443plain paranoid, you can force the correct interpretation with curly
d55a8828 444braces as above.
a0d0e21e 445
7e3b091d 446If you're looking for the information on how to use here-documents,
210b36aa
AMS
447which used to be here, that's been moved to
448L<perlop/Quote and Quote-like Operators>.
be16fac9 449
a0d0e21e
LW
450=head2 List value constructors
451
452List values are denoted by separating individual values by commas
453(and enclosing the list in parentheses where precedence requires it):
454
455 (LIST)
456
d55a8828
TC
457In a context not requiring a list value, the value of what appears
458to be a list literal is simply the value of the final element, as
459with the C comma operator. For example,
a0d0e21e 460
84f709e7 461 @foo = ('cc', '-E', $bar);
a0d0e21e 462
d55a8828 463assigns the entire list value to array @foo, but
a0d0e21e 464
84f709e7 465 $foo = ('cc', '-E', $bar);
a0d0e21e 466
d55a8828
TC
467assigns the value of variable $bar to the scalar variable $foo.
468Note that the value of an actual array in scalar context is the
469length of the array; the following assigns the value 3 to $foo:
a0d0e21e 470
84f709e7 471 @foo = ('cc', '-E', $bar);
7e3b091d 472 $foo = @foo; # $foo gets 3
a0d0e21e 473
54310121 474You may have an optional comma before the closing parenthesis of a
a0d0e21e
LW
475list literal, so that you can say:
476
84f709e7 477 @foo = (
7e3b091d
DA
478 1,
479 2,
480 3,
a0d0e21e
LW
481 );
482
d55a8828
TC
483To use a here-document to assign an array, one line per element,
484you might use an approach like this:
485
84f709e7 486 @sauces = <<End_Lines =~ m/(\S.*\S)/g;
7e3b091d
DA
487 normal tomato
488 spicy tomato
489 green chile
490 pesto
491 white wine
d55a8828
TC
492 End_Lines
493
a0d0e21e 494LISTs do automatic interpolation of sublists. That is, when a LIST is
d55a8828 495evaluated, each element of the list is evaluated in list context, and
a0d0e21e 496the resulting list value is interpolated into LIST just as if each
5a964f20 497individual element were a member of LIST. Thus arrays and hashes lose their
a0d0e21e
LW
498identity in a LIST--the list
499
5a964f20 500 (@foo,@bar,&SomeSub,%glarch)
a0d0e21e
LW
501
502contains all the elements of @foo followed by all the elements of @bar,
5a964f20 503followed by all the elements returned by the subroutine named SomeSub
d55a8828 504called in list context, followed by the key/value pairs of %glarch.
a0d0e21e
LW
505To make a list reference that does I<NOT> interpolate, see L<perlref>.
506
19799a22 507The null list is represented by (). Interpolating it in a list
a0d0e21e
LW
508has no effect. Thus ((),(),()) is equivalent to (). Similarly,
509interpolating an array with no elements is the same as if no
510array had been interpolated at that point.
511
c2689353 512This interpolation combines with the facts that the opening
ab1f959b 513and closing parentheses are optional (except when necessary for
c2689353
NC
514precedence) and lists may end with an optional comma to mean that
515multiple commas within lists are legal syntax. The list C<1,,3> is a
516concatenation of two lists, C<1,> and C<3>, the first of which ends
517with that optional comma. C<1,,3> is C<(1,),(3)> is C<1,3> (And
518similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.) Not that
519we'd advise you to use this obfuscation.
520
a0d0e21e 521A list value may also be subscripted like a normal array. You must
54310121 522put the list in parentheses to avoid ambiguity. For example:
a0d0e21e
LW
523
524 # Stat returns list value.
84f709e7 525 $time = (stat($file))[8];
a0d0e21e 526
4633a7c4 527 # SYNTAX ERROR HERE.
84f709e7 528 $time = stat($file)[8]; # OOPS, FORGOT PARENTHESES
4633a7c4 529
a0d0e21e 530 # Find a hex digit.
84f709e7 531 $hexdigit = ('a','b','c','d','e','f')[$digit-10];
a0d0e21e
LW
532
533 # A "reverse comma operator".
534 return (pop(@foo),pop(@foo))[0];
535
d55a8828
TC
536Lists may be assigned to only when each element of the list
537is itself legal to assign to:
a0d0e21e 538
84f709e7 539 ($a, $b, $c) = (1, 2, 3);
a0d0e21e 540
84f709e7 541 ($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);
a0d0e21e 542
d55a8828
TC
543An exception to this is that you may assign to C<undef> in a list.
544This is useful for throwing away some of the return values of a
545function:
546
84f709e7 547 ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
d55a8828
TC
548
549List assignment in scalar context returns the number of elements
4633a7c4
LW
550produced by the expression on the right side of the assignment:
551
7e3b091d
DA
552 $x = (($foo,$bar) = (3,2,1)); # set $x to 3, not 2
553 $x = (($foo,$bar) = f()); # set $x to f()'s return count
4633a7c4 554
d55a8828 555This is handy when you want to do a list assignment in a Boolean
19799a22 556context, because most list functions return a null list when finished,
4633a7c4
LW
557which when assigned produces a 0, which is interpreted as FALSE.
558
ab1f959b
PN
559It's also the source of a useful idiom for executing a function or
560performing an operation in list context and then counting the number of
561return values, by assigning to an empty list and then using that
562assignment in scalar context. For example, this code:
563
84f709e7 564 $count = () = $string =~ /\d+/g;
ab1f959b
PN
565
566will place into $count the number of digit groups found in $string.
567This happens because the pattern match is in list context (since it
568is being assigned to the empty list), and will therefore return a list
569of all matching parts of the string. The list assignment in scalar
570context will translate that into the number of elements (here, the
571number of times the pattern matched) and assign that to $count. Note
572that simply using
573
84f709e7 574 $count = $string =~ /\d+/g;
ab1f959b
PN
575
576would not have worked, since a pattern match in scalar context will
577only return true or false, rather than a count of matches.
578
579The final element of a list assignment may be an array or a hash:
a0d0e21e 580
84f709e7 581 ($a, $b, @rest) = split;
5a964f20 582 my($a, $b, %rest) = @_;
a0d0e21e 583
4633a7c4 584You can actually put an array or hash anywhere in the list, but the first one
d55a8828
TC
585in the list will soak up all the values, and anything after it will become
586undefined. This may be useful in a my() or local().
a0d0e21e 587
d55a8828
TC
588A hash can be initialized using a literal list holding pairs of
589items to be interpreted as a key and a value:
a0d0e21e
LW
590
591 # same as map assignment above
84f709e7 592 %map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
a0d0e21e 593
d55a8828 594While literal lists and named arrays are often interchangeable, that's
4633a7c4
LW
595not the case for hashes. Just because you can subscript a list value like
596a normal array does not mean that you can subscript a list value as a
597hash. Likewise, hashes included as parts of other lists (including
598parameters lists and return lists from functions) always flatten out into
599key/value pairs. That's why it's good to use references sometimes.
a0d0e21e 600
c47ff5f1
GS
601It is often more readable to use the C<< => >> operator between key/value
602pairs. The C<< => >> operator is mostly just a more visually distinctive
b88cefa9 603synonym for a comma, but it also arranges for its left-hand operand to be
695ff5bd
RGS
604interpreted as a string -- if it's a bareword that would be a legal simple
605identifier (C<< => >> doesn't quote compound identifiers, that contain
606double colons). This makes it nice for initializing hashes:
a0d0e21e 607
84f709e7 608 %map = (
7e3b091d
DA
609 red => 0x00f,
610 blue => 0x0f0,
611 green => 0xf00,
4633a7c4
LW
612 );
613
614or for initializing hash references to be used as records:
615
84f709e7 616 $rec = {
7e3b091d
DA
617 witch => 'Mable the Merciless',
618 cat => 'Fluffy the Ferocious',
619 date => '10/31/1776',
4633a7c4
LW
620 };
621
622or for using call-by-named-parameter to complicated functions:
623
84f709e7 624 $field = $query->radio_group(
7e3b091d 625 name => 'group_name',
4633a7c4
LW
626 values => ['eenie','meenie','minie'],
627 default => 'meenie',
628 linebreak => 'true',
84f709e7 629 labels => \%labels
4633a7c4 630 );
cb1a09d0
AD
631
632Note that just because a hash is initialized in that order doesn't
633mean that it comes out in that order. See L<perlfunc/sort> for examples
634of how to arrange for an output ordering.
635
692ef166
SF
636=head2 Subscripts
637
fa11829f 638An array is subscripted by specifying a dollar sign (C<$>), then the
692ef166
SF
639name of the array (without the leading C<@>), then the subscript inside
640square brackets. For example:
641
642 @myarray = (5, 50, 500, 5000);
643 print "Element Number 2 is", $myarray[2], "\n";
644
645The array indices start with 0. A negative subscript retrieves its
646value from the end. In our example, C<$myarray[-1]> would have been
6475000, and C<$myarray[-2]> would have been 500.
648
649Hash subscripts are similar, only instead of square brackets curly brackets
650are used. For example:
651
652 %scientists =
653 (
654 "Newton" => "Isaac",
655 "Einstein" => "Albert",
656 "Darwin" => "Charles",
657 "Feynman" => "Richard",
658 );
659
660 print "Darwin's First Name is ", $scientists{"Darwin"}, "\n";
661
d55a8828
TC
662=head2 Slices
663
56d7751a
GS
664A common way to access an array or a hash is one scalar element at a
665time. You can also subscript a list to get a single element from it.
d55a8828 666
7e3b091d
DA
667 $whoami = $ENV{"USER"}; # one element from the hash
668 $parent = $ISA[0]; # one element from the array
669 $dir = (getpwnam("daemon"))[7]; # likewise, but with list
d55a8828
TC
670
671A slice accesses several elements of a list, an array, or a hash
56d7751a
GS
672simultaneously using a list of subscripts. It's more convenient
673than writing out the individual elements as a list of separate
d55a8828
TC
674scalar values.
675
7e3b091d
DA
676 ($him, $her) = @folks[0,-1]; # array slice
677 @them = @folks[0 .. 3]; # array slice
678 ($who, $home) = @ENV{"USER", "HOME"}; # hash slice
679 ($uid, $dir) = (getpwnam("daemon"))[2,7]; # list slice
d55a8828
TC
680
681Since you can assign to a list of variables, you can also assign to
682an array or hash slice.
683
84f709e7 684 @days[3..5] = qw/Wed Thu Fri/;
d55a8828 685 @colors{'red','blue','green'}
7e3b091d 686 = (0xff0000, 0x0000ff, 0x00ff00);
d55a8828
TC
687 @folks[0, -1] = @folks[-1, 0];
688
689The previous assignments are exactly equivalent to
690
84f709e7
JH
691 ($days[3], $days[4], $days[5]) = qw/Wed Thu Fri/;
692 ($colors{'red'}, $colors{'blue'}, $colors{'green'})
7e3b091d 693 = (0xff0000, 0x0000ff, 0x00ff00);
88fd19e3 694 ($folks[0], $folks[-1]) = ($folks[-1], $folks[0]);
d55a8828
TC
695
696Since changing a slice changes the original array or hash that it's
56d7751a
GS
697slicing, a C<foreach> construct will alter some--or even all--of the
698values of the array or hash.
d55a8828
TC
699
700 foreach (@array[ 4 .. 10 ]) { s/peter/paul/ }
701
00cb5da1 702 foreach (@hash{qw[key1 key2]}) {
7e3b091d
DA
703 s/^\s+//; # trim leading whitespace
704 s/\s+$//; # trim trailing whitespace
705 s/(\w+)/\u\L$1/g; # "titlecase" words
d55a8828
TC
706 }
707
08cd8952
GS
708A slice of an empty list is still an empty list. Thus:
709
84f709e7
JH
710 @a = ()[1,0]; # @a has no elements
711 @b = (@a)[0,1]; # @b has no elements
712 @c = (0,1)[2,3]; # @c has no elements
56d7751a
GS
713
714But:
715
84f709e7
JH
716 @a = (1)[1,0]; # @a has two elements
717 @b = (1,undef)[1,0,2]; # @b has three elements
08cd8952 718
19799a22
GS
719This makes it easy to write loops that terminate when a null list
720is returned:
d55a8828 721
84f709e7 722 while ( ($home, $user) = (getpwent)[7,0]) {
7e3b091d 723 printf "%-8s %s\n", $user, $home;
d55a8828
TC
724 }
725
726As noted earlier in this document, the scalar sense of list assignment
727is the number of elements on the right-hand side of the assignment.
19799a22 728The null list contains no elements, so when the password file is
d55a8828
TC
729exhausted, the result is 0, not 2.
730
731If you're confused about why you use an '@' there on a hash slice
732instead of a '%', think of it like this. The type of bracket (square
733or curly) governs whether it's an array or a hash being looked at.
734On the other hand, the leading symbol ('$' or '@') on the array or
735hash indicates whether you are getting back a singular value (a
736scalar) or a plural one (a list).
737
5f05dabc 738=head2 Typeglobs and Filehandles
cb1a09d0
AD
739
740Perl uses an internal type called a I<typeglob> to hold an entire
741symbol table entry. The type prefix of a typeglob is a C<*>, because
54310121 742it represents all types. This used to be the preferred way to
cb1a09d0 743pass arrays and hashes by reference into a function, but now that
5a964f20
TC
744we have real references, this is seldom needed.
745
746The main use of typeglobs in modern Perl is create symbol table aliases.
747This assignment:
748
749 *this = *that;
750
751makes $this an alias for $that, @this an alias for @that, %this an alias
752for %that, &this an alias for &that, etc. Much safer is to use a reference.
753This:
5f05dabc 754
5a964f20
TC
755 local *Here::blue = \$There::green;
756
757temporarily makes $Here::blue an alias for $There::green, but doesn't
758make @Here::blue an alias for @There::green, or %Here::blue an alias for
759%There::green, etc. See L<perlmod/"Symbol Tables"> for more examples
760of this. Strange though this may seem, this is the basis for the whole
84f709e7 761module import/export system.
5a964f20 762
d55a8828 763Another use for typeglobs is to pass filehandles into a function or
5a964f20
TC
764to create new filehandles. If you need to use a typeglob to save away
765a filehandle, do it this way:
5f05dabc 766
84f709e7 767 $fh = *STDOUT;
5f05dabc
PP
768
769or perhaps as a real reference, like this:
770
84f709e7 771 $fh = \*STDOUT;
5f05dabc 772
5a964f20
TC
773See L<perlsub> for examples of using these as indirect filehandles
774in functions.
775
776Typeglobs are also a way to create a local filehandle using the local()
777operator. These last until their block is exited, but may be passed back.
778For example:
5f05dabc
PP
779
780 sub newopen {
7e3b091d
DA
781 my $path = shift;
782 local *FH; # not my!
783 open (FH, $path) or return undef;
784 return *FH;
5f05dabc 785 }
84f709e7 786 $fh = newopen('/etc/passwd');
5f05dabc 787
d55a8828 788Now that we have the C<*foo{THING}> notation, typeglobs aren't used as much
5a964f20
TC
789for filehandle manipulations, although they're still needed to pass brand
790new file and directory handles into or out of functions. That's because
d55a8828
TC
791C<*HANDLE{IO}> only works if HANDLE has already been used as a handle.
792In other words, C<*FH> must be used to create new symbol table entries;
793C<*foo{THING}> cannot. When in doubt, use C<*FH>.
794
36392fcf
GS
795All functions that are capable of creating filehandles (open(),
796opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
797automatically create an anonymous filehandle if the handle passed to
798them is an uninitialized scalar variable. This allows the constructs
799such as C<open(my $fh, ...)> and C<open(local $fh,...)> to be used to
800create filehandles that will conveniently be closed automatically when
801the scope ends, provided there are no other references to them. This
802largely eliminates the need for typeglobs when opening filehandles
803that must be passed around, as in the following example:
804
805 sub myopen {
84f709e7 806 open my $fh, "@_"
7e3b091d
DA
807 or die "Can't open '@_': $!";
808 return $fh;
36392fcf
GS
809 }
810
811 {
812 my $f = myopen("</etc/motd");
7e3b091d
DA
813 print <$f>;
814 # $f implicitly closed here
36392fcf
GS
815 }
816
b92795fe
AMS
817Note that if an initialized scalar variable is used instead the
818result is different: C<my $fh='zzz'; open($fh, ...)> is equivalent
819to C<open( *{'zzz'}, ...)>.
d83fe814
AT
820C<use strict 'refs'> forbids such practice.
821
d55a8828
TC
822Another way to create anonymous filehandles is with the Symbol
823module or with the IO::Handle module and its ilk. These modules
824have the advantage of not hiding different types of the same name
825during the local(). See the bottom of L<perlfunc/open()> for an
826example.
827
828=head1 SEE ALSO
829
830See L<perlvar> for a description of Perl's built-in variables and
831a discussion of legal variable names. See L<perlref>, L<perlsub>,
832and L<perlmod/"Symbol Tables"> for more discussion on typeglobs and
833the C<*foo{THING}> syntax.