perltutorial kyle <blockquote>"You will be miserable until you learn the difference between scalar and list context"</blockquote> — Programming Perl 3rd ed, page 69 An introduction to context Context is everywhere in Perl. Every operand is evaluated in some context. Every operator imposes a context to its operands. Every expression is constrained by the context in which it is evaluated. The two main contexts are scalar context and list context. Another is void. An operator that works on scalars imposes a scalar context. You can tell which kind of context an operator has by checking the standard Perl documentation. Every operator that creates a list context for its operands has "LIST" in its syntactic description. Context matters because operands in Perl can behave differently according to context. This is sort of like overloading. A function (or other expression) can provide different results depending on the context it's in. <readmore> Context in action For these examples, I'll use [doc://localtime] since it's a common function which evaluates differently according to context. In a list context, it returns a series of numeric values that describe the current time. In a scalar context, it returns a human readable string to describe the current time. <c> # Example 1. # @now will be (40, 51, 20, 9, 0, 109, 5, 8, 0) @now = localtime(); # Example 2. # $now will be "Fri Jan 9 20:51:40 2009" $now = localtime(); </c> In example 1, we assign [doc://localtime] to an array, which imposes a list context. The array takes in all the values returned by <c>localtime</c>. In example 2, [doc://localtime] is assigned to a scalar, which imposes a scalar context. In that context, <c>localtime</c> returns the string, "Fri Jan 9 20:51:40 2009". You can try this yourself on the command line. If you're on a Windows box, you can run the code in Example 1 like this: <c> perl -e "@now = localtime(); for $now(@now) {print $now;}" 432351301092120 perl -e "$now = localtime(); print $now;" Tue Jan 13 05:26:30 2009 </c> If you're on a Unix-like operating system (like Linux or newer Macs), replace the double quotes above with single quotes. Now, back to context. <c> # Example 3. # $sec will be 40, $min will be 51, $hr will be 20 ($sec,$min,$hr) = localtime(); </c> In example 3, [doc://localtime] is assigned to a list expression which has three scalar variables in it (wrapped in parentheses). Because of the list expression, <c>localtime()</c> is in list context. The three variables get the first three values from the list that <c>localtime()</c> returns, and its other return values are discarded. Note that this assignment is also to a list expression: <c> my ($x) = localtime(); # Example 4 </c> To write it without the list context, drop the parentheses. <c> my $x = localtime(); # Example 5 </c> Other common occurrences of context When creating a hash, the elements are in list context. This probably doesn't do what's intended: <c> # BAD! [Example 6] my %h = ( now => localtime() ); </c> Instead, [doc://localtime] needs [doc://scalar] to force it to be a single value associated with the key. There's more about <c>scalar</c> later in this tutorial. <c> # GOOD [Example 7] my %h = ( now => scalar localtime() ); </c> If you want to have the list returned from [doc://localtime] in an array in the hash, an anonymous array reference is the best way to do that. <c> # GOOD [Example 8] my %h = ( now => [ localtime() ] ); </c> If you're not familiar with references, see [doc://perlreftut], [doc://perlref], and [id://69927]. The arguments to a call to a user-defined sub are in list context also. <c> # Example 9 sub print_time { my $now = shift @_; print "The time is now $now\n"; } # prints "The time is now 40" print_time( localtime() ); # prints "The time is now Tue Jan 13 05:26:30 2009" print_time( scalar localtime() ); </c> There is a way for a user-defined function to have its arguments in a scalar context, but that's seldom used, often discouraged, and outside the scope of this tutorial. Most of the time, subs' arguments are in list context. Perl's built-ins don't follow this rule at all. Example 10 does not do what's intended. <c> # Example 10 my @loc = ($offset, $length); my $part = substr( $string, @loc ); </c> Perl's [doc://substr] takes only scalar arguments. Putting some of those arguments into an array this way won't work. (The above is equivalent to "<c>substr( $string, 2 )</c>" because <c>@loc</c> is in scalar context.) Context propagates into sub calls When control reaches a [doc://return], the operand to the right of that return finds itself in the context that the sub was in when it was called. That means that in the following code, [doc://localtime] is in the list context from [doc://print]. <c> print clock(); # Example 11 sub clock { return localtime(); } </c> A sub's calling context might come from some operator high up in the call stack. Forcing scalar context If you want to force a scalar context on an operand, use [doc://scalar]. For example: <c> print scalar localtime(); # Example 12 </c> When you [doc://print], its operands are in list context. It accepts a list of values to be printed. If you just "<c>print localtime()</c>", it will print something like "40512090109580" (the list of values all stuck together), but "<c>scalar localtime()</c>" looks like "Fri Jan 9 20:51:40 2009". Forcing list context To force a list context where there wouldn't be one otherwise, assign to an empty list. <c> my $match_count = ()= /x/g; # Example 13 </c> The "<c>/x/g</c>" in scalar context would match only once, but with the list context, it finds every match. The value of "<c>()=</c>" in scalar context is the number of items in the list. Void context Void context is a special case of scalar context. It's the context of something that doesn't have an operator working on it. The value of a thing in void context is discarded, not used for anything. For example, the body of a <c>while</c> loop is in void context. <c> # Example 14 while (<>) { ponder( $_ ); # void context } </c> The only way void context is like scalar context is that it's not list context. The only way void context is not like scalar context is that some things in void context can generate [doc://warnings] that they wouldn't generate in a scalar context. Determining context with wantarray A sub can determine what context it was called in by using [doc://wantarray]. If the sub is in list context, <c>wantarray</c> will return a true value. In scalar context, it returns a false value that's [doc://defined]. In void context, it will return [doc://undef]. <c> # Example 15 sub print_context { if ( wantarray() ) { print "list\n"; } elsif ( defined wantarray() ) { print "scalar\n"; } else { print "void\n"; } } print_context(); ()= print_context(); scalar print_context(); __END__ void list scalar </c> More flavors of scalars The Camel book subdivides scalar context into numeric, string, and don't care context, but it's more useful to think of these as casts. Scalar assignment is a "don't care" because numbers and strings are treated the same—passed through to the scalar variable to have and to hold just as they are. Another "don't care" cast is boolean because strings and numbers aren't converted when being interpreted as true or false. To learn more about how values are treated in boolean context, see [id://495975] In numeric and string contexts, a variable might undergo a transformation from one to the other in order to facilitate the workings of the operator. In example 16, a string is cast to a number to accommodate the numeric operation of the postfix "<c>--</c>" operator. <c> # Example 16 my $beer_inventory = '99 bottles'; print "how much beer? $beer_inventory\n"; $beer_inventory--; # take one down... print "how much beer? $beer_inventory\n"; __END__ how much beer? 99 bottles how much beer? 98 </c> To force an expression to a string, use "<c>''.</c>" (that is, append to an empty string). To interpret an expression as a number, use "<c>0+</c>" (that is, add zero). It's better to use "<c>0+</c>" than some other identity function (such as "<c>1*</c>") because that's what [doc://overload] uses to designate the numeric cast. To force a boolean interpretation, use "<c>!!</c>" (that is, boolean negation twice). <c> # Example 17 my $s = "12 monkeys"; my $n = 31337; my $stringified = ''. $n; # "31337" my $numified = 0+ $s; # 12 my $boolean = !! $n; # 1 </c> Every cast is possible. Strings can be cast to numbers or booleans. Numbers can be cast to strings or booleans. Booleans can be cast to numbers or strings. Context clash A single value (such as a scalar) in a list context becomes a list with one item. <c> # Example 18 my $scaley = 'snake'; my @listy = $scaley; # does the same thing: #my @listy = ('snake'); </c> That's simple enough. What about the other way around? In scalar context, a list of expressions separated by commas evaluates to the whatever the last item evaluates to in scalar context. A slice of an array or hash in scalar context will similarly evaluate to the last element in the slice (for more on slices, see [doc://perldata#Slices]). <c> # Example 19 my @t = ( 'one', 'two' ); my $x = ( 'one', 'two' ); # 'two' my $y = @t[0,1]; # 'two' my $z = ( 'larry', 'moe', @t[0,1] ); # 'two' my $r = ( 'larry', 'moe', @t ); # 2 my $f = ( 'old', 'man', localtime() ); # "Fri Jan 9 20:51:40 2009" </c> Other things ordinarily used in list context have their own special scalar context behaviors. One particularly useful one is demonstrated by the <c>$r</c> value in example 19. An array in scalar context evaluates to the number of items in the array. For a list of others, see [id://347416]. Interpolative context This isn't a full fledged context like scalar and list context, but it helps to know in which places variables are expanded (interpolated) into their values. For a full list of these, see [doc://perlop#Quote-and-Quote-like-Operators|Quote and Quote-like Operators]. For a brief example, see below. <c> # Example 20 my $friend = 'Perl'; my $literal = '$friend'; # literally, '$friend' my $expanded = "$friend"; # literally, 'Perl' </c> To reiterate, this isn't a context the way "scalar context" is a context, and it isn't what we normally mean when we say simply "context." Still, it may help to think of it as a context when one is considering interpolation. For the full scoop including many other places this is relevant, see the full documentation ([doc://perlop#Quote-and-Quote-like-Operators|Quote and Quote-like Operators]). More context If the deep dark magic of [doc://wantarray] leaves you wanting for more, look into [mod://Want] and [mod://Contextual::Return], which are advertised to detect contexts I have not mentioned here. Also, look at [doc://overload] for creating an object which can interpret itself differently in numeric and string contexts. Another good source of information about context is [http://perl.plover.com/context.html|What is Scalar Context?] by [Dominus]. Thanks to [belg4mit], [tye], [theorbtwo], [Arunbear], [bart], [zentara], [ikegami], [Limbic~Region], [Narveson], [jdporter], [moritz], [Porculus], [ww], [gwadej], [oshalla], and [gwadej] for commenting on an earlier draft! </readmore>