Learning Perl, 3rd Edition

Chapter 4. Subroutines

System and User Functions

We’ve already seen and used some of the builtin system functions, such as chomp, reverse, print, and so on. But, as other languages do, Perl has the ability to make subroutines, which are user-defined functions.^[1] These let us recycle one chunk of code many times in one program.^[2]

The name of a subroutine is another Perl identifier (letters, digits, and underscores, but can’t start with a digit) with a sometimes-optional ampersand (&) in front. There’s a rule about when you can omit the ampersand and when you cannot; we’ll see that rule by the end of the chapter. For now, we’ll just use it every time that it’s not forbidden, which is always a safe rule. And we’ll tell you every place where it’s forbidden, of course.

That subroutine name comes from a separate namespace, so Perl won’t be confused if you have a subroutine called &fred and a scalar called $fred in the same program—although there’s no reason to do that under normal circumstances.

Defining a Subroutine

To define your own subroutine, use the keyword sub , the name of the subroutine (without the ampersand), then the indented^[3] block of code (in curly braces) which makes up the body of the subroutine, something like this:

sub marine {
  $n += 1;  # Global variable $n
  print "Hello, sailor number $n!\n";
}

Subroutine definitions can be anywhere in your program text, but programmers who come from a background of languages like C or Pascal like to put them at the start of the file. Others may prefer to put them at the end of the file, so that the main part of the program appears at the beginning. It’s up to you. In any case, you don’t normally need any kind of forward declaration.^[4]

Subroutine definitions are global; without some powerful trickiness, there are no private subroutines.^[5] If you have two subroutine definitions with the same name, the later one overwrites the earlier one.^[6] That’s generally considered bad form, or the sign of a confused maintenance programmer.

As you may have noticed in the previous example, you may use any global variables within the subroutine body. In fact, all of the variables we’ve seen so far are globals; that is, they are accessible from every part of your program. This horrifies linguistic purists, but the Perl development team formed an angry mob with torches and ran them out of town years ago. We’ll see how to make private variables in the section “Private Variables in Subroutines” later in this chapter.

Invoking a Subroutine

Invoke a subroutine from within any expression by using the subroutine name (with the ampersand):^[7]

&marine;  # says Hello, sailor number 1!
&marine;  # says Hello, sailor number 2!
&marine;  # says Hello, sailor number 3!
&marine;  # says Hello, sailor number 4!

Sometimes, we refer to the invocation as calling the subroutine.

Return Values

The subroutine is always invoked as part of an expression, even if the result of the expression isn’t being used. When we invoked &marine earlier, we were calculating the value of the expression containing the invocation, but then throwing away the result.

Many times, we’ll call a subroutine and actually do something with the result. This means that we’ll be paying attention to the return value of the subroutine. All Perl subroutines have a return value—there’s no distinction between those that return values and those that don’t. Not all Perl subroutines have a useful return value, however.

Since all Perl subroutines can be called in a way that needs a return value, it’d be a bit wasteful to have to declare special syntax to “return” a particular value for the majority of the cases. So Larry made it simple. Every subroutine is chugging along, calculating values as part of its series of actions. Whatever calculation is last performed in a subroutine is automatically also the return value.

For example, let’s define this subroutine:

sub sum_of_fred_and_barney {
  print "Hey, you called the sum_of_fred_and_barney subroutine!\n";
  $fred + $barney;  # That's the return value
}

The last expression evaluated in the body of this subroutine is the sum of $fred and $barney, so the sum of $fred and $barney will be the return value. Here’s that in action:

$fred = 3;
$barney = 4;
$c = &sum_of_fred_and_barney; # $c gets 7
print "\$c is $c.\n";
$d = 3 * &sum_of_fred_and_barney; # $d gets 21
print "\$d is $d.\n";

That code will produce this output:

Hey, you called the sum_of_fred_and_barney subroutine!
$c is 7.
Hey, you called the sum_of_fred_and_barney subroutine!
$d is 21.

That print statement is just a debugging aid, so that we can see that we called the subroutine. You’d take it out when the program is finished. But suppose you added another line to the end of the code, like this:

sub sum_of_fred_and_barney {
  print "Hey, you called the sum_of_fred_and_barney subroutine!\n";
  $fred + $barney;  # That's not really the return value!
  print "Hey, I'm returning a value now!\n"; # Oops!
}

In this example, the last expression evaluated is not the addition; it’s the print statement. Its return value will normally be 1, meaning “printing was successful,”^[8] but that’s not the return value we actually wanted. So be careful when adding additional code to a subroutine to ensure that the last expression evaluated will be the desired return value.

So, what happened to the sum of $fred and $barney in that subroutine? We didn’t put it anywhere, so Perl discarded it. If you had requested warnings, Perl (noticing that there’s nothing useful about adding two variables and discarding the result) would likely warn you about something like “a useless use of addition in a void context.” The term void context is just a fancy way of saying that the answer isn’t being stored in a variable or used by another function.

“The last expression evaluated” really means the last expression evaluated, rather than the last line of text. For example, this subroutine returns the larger value of $fred or $barney:

sub larger_of_fred_or_barney {
  if ($fred > $barney) {
    $fred;
  } else {
    $barney;
  }
}

The last expression evaluated is the single $fred or $barney, which becomes the return value. We won’t know whether the return value will be $fred or $barney until we see what those variables hold at runtime.

A subroutine can also return a list of values when evaluated in a list context.^[9] Suppose you wanted to get a range of numbers (as from the range operator, ..), except that you want to be able to count down as well as up. The range operator only counts upwards, but that’s easily fixed:

sub list_from_fred_to_barney {
  if ($fred < $barney) {
    # Count upwards from $fred to $barney
    $fred..$barney;
  } else {
    # Count downwards from $fred to $barney
    reverse $barney..$fred;
  }
}
$fred = 11;
$barney = 6;
@c = &list_from_fred_to_barney; # @c gets (11, 10, 9, 8, 7, 6)

In this case, the range operator gives us the list from 6 to 11, then reverse reverses the list, so that it goes from $fred (11) to $barney (6), just as we wanted.

These are all rather trivial examples. It gets better when we can pass values that are different for each invocation into a subroutine instead of relying on global variables. In fact, that’s coming right up.

Arguments

That subroutine called larger_of_fred_or_barney would be much more useful if it didn’t force us to use the global variables $fred and $barney. That’s because, if we wanted to get the larger value from $wilma and $betty, we currently have to copy those into $fred and $barney before we can use larger_of_fred_or_barney. And if we had something useful in those variables, we’d have to first copy those to other variables, say $save_fred and $save_barney. And then, when we’re done with the subroutine, we’d have to copy those back to $fred and $barney again.

Luckily, Perl has subroutine arguments. To pass an argument list to the subroutine, simply place the list expression, in parentheses, after the subroutine invocation, like this:

$n = &max(10, 15);  # This sub call has two parameters

That list is passed to the subroutine; that is, it’s made available for the subroutine to use however it needs to. Of course, this list has to be stored into a variable, so the parameter list (another name for the argument list) is automatically assigned to a special array variable named @_ for the duration of the subroutine. The subroutine can access this variable to determine both the number of arguments and the value of those arguments.

So, that means that the first subroutine parameter is stored in $_[0], the second one is stored in $_[1], and so on. But—and here’s an important note—these variables have nothing whatsoever to do with the $_ variable, any more than $dino[3] (an element of the @dino array) has to do with $dino (a completely distinct scalar variable). It’s just that the parameter list must be stored into some array variable for the subroutine to use it, and Perl uses the array @_ for this purpose.

Now, you could write the subroutine &max to look a little like the subroutine &larger_of_fred_or_barney, but instead of using $fred you could use the first subroutine parameter ($_[0]), and instead of using $barney, you could use the second subroutine parameter ($_[1]). And so you could end up with code something like this:

sub max {
  # Compare this to &larger_of_fred_or_barney
  if ($_[0] > $_[1]) { 
    $_[0];
  } else {
    $_[1];
  }
}

Well, as we said, you could do that. But it’s pretty ugly with all of those subscripts, and hard to read, write, check, and debug, too. We’ll see a better way in a moment.

There’s another problem with this subroutine. The name &max is nice and short, but it doesn’t remind us that this subroutine works properly only if called with exactly two parameters:

$n = &max(10, 15, 27);  # Oops!

Excess parameters are ignored—since the subroutine never looks at $_[2], Perl doesn’t care whether there’s something in there or not. And insufficient parameters are also ignored—you simply get undef if you look beyond the end of the @_ array, as with any other array. We’ll see how to make a better &max, which works with any number of parameters, later in this chapter.

The @_ variable is local to the subroutine;^[10] if there’s a global value in @_, it is saved away before the subroutine is invoked and restored to its previous value upon return from the subroutine.^[11] This also means that a subroutine can pass arguments to another subroutine without fear of losing its own @_ variable—the nested subroutine invocation gets its own @_ in the same way. Even if the subroutine calls itself recursively, each invocation gets a new @_, so @_ is always the parameter list for the current subroutine invocation.

Private Variables in Subroutines

But if Perl can give us a new @_ for every invocation, can’t it give us variables for our own use as well? Of course it can.

By default, all variables in Perl are global variables; that is, they are accessable from every part of the program. But you can create private variables called lexical variables at any time with the my operator:

sub max {
  my($a, $b);       # new, private variables for this block
  ($a, $b) = @_;    # give names to the parameters
  if ($a > $b) { $a } else { $b }
}

These variables are private (or scoped ) to the enclosing block; any other $a or $b is totally unaffected by these two. And that goes the other way, too—no other code can access or modify these private variables, by accident or design.^[12] So, we could drop this subroutine into any Perl program in the world and know that we wouldn’t mess up that program’s $a and $b (if any).^[13]

It’s also worth pointing out that, inside the if’s blocks, there’s no semicolon needed after the return value expression. Although Perl allows for the last semicolon in a block to be omitted, in practice that’s omitted only when the code is so simple that the block is written in a single line, like the previous ones.

The subroutine in the previous example could be made even simpler. Did you notice that the list ($a, $b) was written twice? That my operator can also be applied to a list of variables enclosed in parentheses, so it’s more customary to combine those first two statements in the subroutine:

my($a, $b) = @_;  # Name the subroutine parameters

That one statement creates the private variables and sets their values, so the first parameter now has the easier-to-use name $a and the second has $b. Nearly every subroutine will start with a line much like that one, naming its parameters. When you see that line, you’ll know that the subroutine expects two scalar parameters, which we’ll call $a and $b inside the subroutine.

The local Operator

You might consider this next section a giant footnote, but then we couldn’t have footnotes on footnotes, so we decided to put it up in the main text. Skip over this text on first reading, and pop right on down to Section 4.8. You won’t need any of it to do the exercises or write Perl code for a long time. But someone invariably asks us in class something like “What is that local thing I see in some programs?” so we’re including what we normally say as an aside in class for your enjoyment and edification.

Occasionally, mostly in older code or older Perl books, you’ll see the local operator used instead of my. It often looks much the same as my:

sub max {
  local($a, $b) = @_;  # looks a lot like my
  if ($a > $b) { $a } else { $b }
}

But local is misnamed, or at least misleadingly named. Our friend Chip Salzenberg says that if he ever gets a chance to go back in a time machine to 1986 and give Larry one piece of advice, he’d tell Larry to call local by the name “save” instead.^[14] That’s because local actually will save the given global variable’s value away, so it will later automatically be restored to the global variable. (That’s right: these so-called "local" variables are actually globals!) This save-and-restore mechanism is the same one we’ve already seen twice now, in the control variable of a foreach loop, and in the @_ array of subroutine parameters.

What local actually does, then, is to save away a copy of the variable’s value in a secret place (called the stack). That value can’t be accessed, modified, or deleted^[15] while it is saved. Then local sets the variable to an empty value (undef for scalars, or empty list for arrays), or to whatever value is being assigned. When Perl returns from the subroutine,^[16] the variable is automatically restored to its original value. In effect, the variable was borrowed for a time and given back (hopefully) before anyone noticed that it was borrowed.

The Difference Between local and my

But what if the subroutine called another subroutine, one that did notice that the variable was being borrowed by local? For example:

$office = "global";  # Global $office
&say( );                                # says "global", accessing $office directly

&fred( );                               # says "fred", dynamic scope,
    # because fred's local $office hides the global

&barney( );                             # says "global", lexical scope;
    # barney's $office is visible only in that block

sub say { print "$office\n"; }         # print the currently visible $office
sub fred { local($office) = "fred"; &say( ); }
sub barney { my($office) = "barney"; &say( ); }

First, we call the subroutine &say, which tells us which $office it sees—the global $office. That’s normal.

But then we call Fred’s subroutine. Fred has made his own local $office, so he has actually changed the behavior of the &say subroutine; now it tells us what’s in Fred’s $office. We can’t tell whether that’s what Fred wanted to do or not without understanding the meaning of his code. But it’s a little odd.

Barney, however, is a little smarter, as well as being shorter, so he uses the shorter (and smarter) operator, my. Barney’s variable $office is private, and Barney’s private $office can’t be accessed from outside his subroutine, so the &say subroutine is back to normal; it can see only the global $office. Barney didn’t change the way &say works, which is more like what most programmers would want and expect.

Now, if you’re confused about these two operators at this point, that’s to be expected. But any time that you see local, think “save,” and that may help. In any new code, just use my, since my variables (lexical variables) are faster than globals—remember, so-called local variables are really globals—and they’ll work more like the traditional variables in other modern programming languages. But when you’re maintaining someone else’s old code, you can’t necessarily change every local to my without checking upon whether the programmer was using that save-and-restore functionality.

Variable-length Parameter Lists

In real-world Perl code, subroutines are often given parameter lists of arbitrary length. That’s because of Perl’s “no unnecessary limits” philosophy that we’ve already seen. Of course, this is unlike many traditional programming languages, which require every subroutine to be strictly typed; that is, to permit only a certain, predefined number of parameters of predefined types. It’s nice that Perl is so flexible, but (as we saw with the &max routine earlier) that may cause problems when a subroutine is called with a different number of arguments than the author expected.

Of course, the subroutine can easily check that it has the right number of arguments by examining the @_ array. For example, we could have written &max to check its argument list like this:^[17]

sub max {
  if (@_ != 2) {
    print "WARNING! &max should get exactly two arguments!\n";
  }
  # continue as before...
  .
  .
  .
}

That if-test uses the “name” of the array in a scalar context to find out the number of array elements, as we saw in Chapter 3.

But in real-world Perl programming, this sort of check is hardly ever used; it’s better to make the subroutine adapt to the parameters.

A Better &max Routine

So let’s rewrite &max to allow for any number of arguments:

$maximum = &max(3, 5, 10, 4, 6);

sub max {
  my($max_so_far) = shift @_;  # the first one is the largest yet seen
  foreach (@_) {               # look at the remaining arguments
    if ($_ > $max_so_far) {    # could this one be bigger yet?
      $max_so_far = $_;
    }
  }
  $max_so_far;
}

This code uses what has often been called the “high-water mark” algorithm; after a flood, when the waters have surged and receded for the last time, the high-water mark shows where the highest water was seen. In this routine, $max_so_far keeps track of our high-water mark, the largest number yet seen.

The first line sets $max_so_far to 3 (the first parameter in the example code) by shifting that parameter from the parameter array, @_. So @_ now holds (5, 10, 4, 6), since the 3 has been shifted off. And the largest number yet seen is the only one yet seen: 3, the first parameter.

Now, the foreach loop will step through the remaining values in the parameter list, from @_. The control variable of the loop is, by default, $_. (But, remember, there’s no automatic connection between @_ and $_; it’s just a coincidence that they have such similar names.) The first time through the loop, $_ is 5. The if test sees that it is larger than $max_so_far, so $max_so_far is set to 5—the new high-water mark.

The next time through the loop, $_ is 10. That’s a new record high, so it’s stored in $max_so_far as well.

The next time, $_ is 4. The if test fails, since that’s no larger than $max_so_far, which is 10, so the body of the if is skipped.

The next time, $_ is 6, and the body of the if is skipped again. And that was the last time through the loop, so the loop is done.

Now, $max_so_far becomes the return value. It’s the largest number we’ve seen, and we’ve seen them all, so it must be the largest from the list: 10.

Empty Parameter Lists

That improved &max algorithm works fine now, even if there are more than two parameters. But what happens if there are none?

At first, it may seem too esoteric to worry about. After all, why would someone call &max without giving it any parameters? But maybe someone wrote a line like this one:

$maximum = &max(@numbers);

And the array @numbers might sometimes be an empty list; perhaps it was read in from a file that turned out to be empty, for example. So what does &max do in that case?

The first line of the subroutine sets $max_so_far by using shift on @_, the (now empty) parameter array. That’s harmless; the array is left empty, and shift returns undef to $max_so_far.

Now the foreach loop wants to iterate over @_, but since that’s empty, the loop body is executed zero times.

So in short order, Perl returns the value of $max_so_far—undef—as the return value of the subroutine. In some sense, that’s the right answer, because there is no largest value in an empty list.

Of course, whoever is calling this subroutine should be aware that the return value may be undef—or they could simply ensure that the parameter list is never empty.

Notes on Lexical (my) Variables

Those lexical variables can actually be used in any block, not merely in a subroutine’s block. For example, they can be used in the block of an if, while, or foreach:

foreach (1..10) {
  my($square) = $_ * $_;  # private variable in this loop
  print "$_ squared is $square.\n";
}

The variable $square is private to the enclosing block; in this case, that’s the block of the foreach loop. If there’s no block, the variable is private to the entire source file. For now, your programs aren’t going to use more than one source file, so this isn’t an issue. But the important concept is that the scope of a lexical variable’s name is limited to the smallest enclosing block or file. The only code that can say $square and mean that variable is the code inside that textual scope. This is a big win for maintainability—if the wrong value is found in $square, the culprit will be found within a limited amount of source code. As experienced programmers have learned (often the hard way), limiting the scope of a variable to a page of code, or even to a few lines of code, really speeds along the development and testing cycle.

Note also that the my operator doesn’t change the context of an assignment:

my($num) = @_;  # list context, same as ($num) = @_;
my $num  = @_;  # scalar context, same as $num = @_;

In the first one, $num gets the first parameter, as a list-context assignment; in the second, it gets the number of parameters, in a scalar context. Either line of code could be what the programmer wanted; we can’t tell from that one line alone, and so Perl can’t warn you if you use the wrong one. (Of course, you wouldn’t have both of those lines in the same subroutine, since you can’t have two lexical variables with the same name declared in the same scope; this is just an example.) So, when reading code like this, you can always tell the context of the assignment by seeing what the context would be without the word my.

Of course, you can use my to create new, private arrays as well:^[18]

my @phone_number;

Any new variable will start out empty—undef for scalars, or the empty list for arrays.

The use strict Pragma

Perl tends to be a pretty permissive language. But maybe you want Perl to impose a little discipline; that can be arranged with the use strict pragma.

A pragma is a hint to a compiler, telling it something about the code. In this case, the use strict pragma tells Perl’s internal compiler that it should enforce some good programming rules for the rest of this block or source file.

Why would this be important? Well, imagine that you’re composing your program, and you type a line like this one:

$bamm_bamm = 3;  # Perl creates that variable automatically

Now, you keep typing for a while. After that line has scrolled off the top of the screen, you type this line to increment the variable:

$bammbamm += 1;  # Oops!

Since Perl sees a new variable name (the underscore is significant in a variable name), it creates a new variable and increments that one. If you’re lucky and smart, you’ve turned on warnings, and Perl can tell you that you used one or both of those global variable names only once in your program. But if you’re merely smart, you used each name more than once, and Perl won’t be able to warn you.

To tell Perl that you’re ready to be more restrictive, put the use strict pragma at the top of your program (or in any block or file where you want to enforce these rules):

use strict;  # Enforce some good programming rules

Now, among other restrictions,^[19] Perl will insist that you declare every new variable with my:^[20]

my $bamm_bamm = 3;  # New lexical variable

Now if you try to spell it the other way, Perl can complain that you haven’t declared any variable called $bammbamm, so your mistake is automatically caught at compile time.

$bammbamm += 1;  # No such variable: Compile time error

Of course, this applies only to new variables; Perl’s builtin variables, such as $_ and @_ never need to be declared.^[21]

If you add use strict to an already-written program, you’ll generally get a flood of warning messages, so it’s better to use it from the start, when it’s needed.

Most people recommend that programs that are longer than a screenful of text generally need use strict. And we agree.

From here on, most (but not all) of our examples will be written as if use strict is in effect, even where we don’t show it. That is, we’ll generally declare variables with my where it’s appropriate. But, even though we don’t always do so here, we encourage you to include use strict in your programs as often as possible.

The return Operator

The return operator immediately returns a value from a subroutine:

my @names = qw/ fred barney betty dino wilma pebbles bamm-bamm /;
my $result = &which_element_is("dino", @names);

sub which_element_is {
  my($what, @list) = @_;
  foreach (0..$#list) {  # indices of @list's elements
    if ($what eq $list[$_]) {
      return $_;         # return early once found
    }
  }
  -1;                    # element not found (return is optional here)
}

This subroutine is being used to find the index of "dino" in the array @names. First, the my declaration names the parameters: there’s $what, which is what we’re searching for, and @list, a list of values to search within. That’s a copy of the array @names, in this case. The foreach loop steps through the indices of @list (the first index is 0, and the last one is $#list, as we saw in Chapter 3).

Each time through the foreach loop, we check to see whether the string in $what is equal^[22] to the element from @list at the current index. If it’s equal, we return that index at once. This is the most common use of the keyword return in Perl—to return a value immediately, without executing the rest of the subroutine.

But what if we never found that element? In that case, the author of this subroutine has chosen to return -1 as a “value not found” code. It would be more Perlish, perhaps, to return undef in that case, but this programmer used -1. Saying return -1 on that last line would be correct, but the word return isn’t really needed.

Some programmers like to use return every time there’s a return value, as a means of documenting that it is a return value. For example, you might use return when the return value is not the last line of the subroutine, such as in the subroutine &list_from_fred_to_barney, earlier in this chapter. It’s not really needed, but it doesn’t hurt anything. However, many Perl programmers believe it’s just an extra seven characters of typing. So you’ll need to be able to read code written by both kinds of programmers.

If return is used with no expression, that will return an empty value—undef in a scalar context, or an empty list in a list context. return ( ) does the same, in case you want to be explicit.

Omitting the Ampersand

As promised, now we’ll tell you the rule for when a subroutine call can omit the ampersand. If the compiler sees the subroutine definition before invocation, or if Perl can tell from the syntax that it’s a subroutine call, the subroutine can be called without an ampersand, just like a builtin function. (But there’s a catch hidden in that rule, as we’ll see in a moment.)

This means that if Perl can see that it’s a subroutine call without the ampersand, from the syntax alone, that’s generally fine. That is, if you’ve got the parameter list in parentheses, it’s got to be a function^[23] call:

my @cards = shuffle(@deck_of_cards);  # No & necessary on &shuffle

Or if Perl’s internal compiler has already seen the subroutine definition, that’s generally okay, too; in that case, you can even omit the parentheses around the argument list:

sub division {
  $_[0] / $_[1];                   # Divide first param by second
}

my $quotient = division 355, 113;  # Uses &division

This works because of the rule that parentheses may always be omitted, except when doing so would change the meaning of the code.

But don’t put that subroutine declaration after the invocation, or the compiler won’t know what the attempted invocation of division is all about. The compiler has to see the definition before the invocation in order to use the subroutine call as if it were a builtin.

That’s not the catch, though. The catch is this: if the subroutine has the same name as a Perl builtin, you must use the ampersand to call it. With an ampersand, you’re sure to call the subroutine; without it, you can get the subroutine only if there’s no builtin with the same name:

sub chomp {
  print "Munch, munch!";
}

&chomp;  # That ampersand is not optional!

Without the ampersand, we’d be calling the builtin chomp, even though we’ve defined the subroutine &chomp. So, the real rule to use is this one: until you know the names of all of Perl’s builtin functions, always use the ampersand on function calls. That means that you will use it for your first hundred programs or so. But when you see someone else has omitted the ampersand in their own code, it’s not necessarily a mistake; perhaps they simply know that Perl has no builtin with that name.^[24]

When programmers plan to call their subroutines as if they were calling Perl’s builtins, often when writing modules , they often use prototypes to tell Perl about the parameters to expect. Making modules is an advanced topic, though; when you’re ready for that, see Perl’s documentation (in particular, the perlmod and perlsub documents) for more information about subroutine prototypes and making modules.

Exercises

See Section A.3 for answers to the following exercises:

[12] Write a subroutine, called &total, which returns the total of a list of numbers. Hint: the subroutine should not perform any I/O; it should simply process its parameters and return a value to its caller. Try it out in this sample program, which merely exercises the subroutine to see that it works. The first group of numbers should add up to 25.
```
my @fred = qw{ 1 3 5 7 9 };
my $fred_total = &total(@fred);
print "The total of \@fred is $fred_total.\n";
print "Enter some numbers on separate lines: ";
my $user_total = &total(<STDIN>);
print "The total of those numbers is $user_total.\n";
```
[5] Using the subroutine from the previous problem, make a program to calculate the sum of the numbers from 1 to 1000.

^[1]In Perl, we don’t generally make the distinction that Pascal programmers are used to, between functions, which return a value, and procedures, which don’t. But a subroutine is always user-defined, while a function may or may not be. That is, the word function may be used as a synonym for subroutine, or it may mean one of Perl’s builtin functions. That’s why this chapter is titled Subroutines, because it’s about the ones you can define, not the builtins. Mostly.

^[2]The code examples used in this book are recycled from at least 40% post-consumer programming, and are at least 75% recyclable into your programs when properly decomposed.

^[3]Okay, purists, we admit it: the curly braces are part of the block, properly speaking. And Perl doesn’t require the indentation of the block—but your maintenance programmer will. So please be stylish.

^[4]Unless your subroutine is being particularly tricky and declares a “prototype,” which dictates how a compiler will parse and interpret its invocation arguments. This is rare—see the perlsubmanpage for more information.

^[5]If you wish to be powerfully tricky, read the Perl documentation about coderefs stored in private (lexical) variables.

^[6]A warnable offense, however.

^[7]And frequently a pair of parentheses, even if empty. As written, the subroutine inherits the caller’s @_ value, which we’ll be discussing shortly. So don’t stop reading here, or you’ll be writing code with unintended effects!

^[8]The return value of print is true for a successful operation and false for a failure. We’ll see how to determine the kind of failure later in Chapter 11.

^[9]You can detect whether a subroutine is being evaluated in a scalar or list context using the wantarray function, which lets you easily write subroutines with specific list or scalar context values.

^[10]Unless there’s an ampersand in front of the name for the invocation, and no parentheses (or arguments) afterward, in which case the @_ array is inherited from the caller’s context. That’s generally a bad idea, but is occasionally useful.

^[11]You might recognize that this is the same mechanism as used with the control variable of the foreach loop, as seen in the previous chapter. In either case, the variable’s value is saved and automatically restored by Perl. We’ll see this again with the local operator later in this chapter.

^[12]Advanced programmers will realize that a lexical variable may be accessible by reference from outside its scope, but never by name.

^[13]Of course, if that program already had a subroutine called &max, we’d mess that up.

^[14]We would tell Larry to buy stock in Yahoo!, but Chip is more idealistic than we are.

^[15]Or damaged, defiled, read, checked, touched, seen, changed, or printed, for that matter. There’s no way from within Perl to get at the saved value.

^[16]Or when it finishes execution of the smallest enclosing block or file, to be more precise.

^[17]As soon as you learn about warn (in Chapter 11), you’ll see that you can use it to turn improper usage like this into a proper warning. Or perhaps you’ll decide that this case is severe enough to warrant using die, described in the same chapter.

^[18]Or hashes, which we’ll see in the next chapter.

^[19]To learn about the other restrictions, see the documentation for strict. The documentation for any pragma is filed under that pragma’s name, so the command perldoc strict(or your system’s native documentation method) should find it for you. In brief, the other restrictions require that strings be quoted in most cases, and that references be true (hard) references. Neither of these restrictions should affect beginners in Perl.

^[20]There are some other ways to declare variables, too.

^[21]And, at least in some circumstances, $a and $b won’t need to be declared, because they’re used internally by sort. So if you’re testing this feature, use other variable names than those two. The fact that use strict doesn’t forbid these two is one of the most frequently reported non-bugs in Perl.

^[22]You noticed that we used the string equality test, eq, instead of the numeric equality test, ==, didn’t you?

^[23]In this case, the function is the subroutine &shuffle. But it may be a built-in function, as we’ll see in a moment.

^[24]Then again, maybe it is a mistake; you can search the perlfunc and perlop manpages for that name, though, to see whether it’s the same as a builtin. And Perl will usually be able to warn you about this, when you have warnings turned on.

Get Learning Perl, 3rd Edition now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Learning Perl, 3rd Edition by Tom Phoenix, Randal L. Schwartz