Recipe 10.11. Prototyping Functions (Perl Cookbook)

10.11. Prototyping Functions

Problem

You want to use function prototypes so the compiler can check your argument types.

Perl has something of a prototype facility, but it isn't what you're thinking. Perl's function prototypes are more like a context coercion used to write functions that behave like some of Perl's built-ins, such as push and pop.

Discussion

Manually checking the validity of a function's arguments can't happen until run-time. If you make sure the function is declared before it is used, you can tickle the compiler into using a very limited form of prototype checking to help you here. Don't confuse Perl's function prototypes with those found in any other language. Perl prototypes serve only to emulate the behavior of built-in functions.

A Perl function prototype is zero or more spaces, backslashes, or type characters enclosed in parentheses after the subroutine definition or name. A backslashed type symbol means that the argument is passed by reference, and the argument in that position must start with that type character.

A prototype forces context on the arguments to the prototyped function call. This is done when Perl compiles your program, and in most cases this does not necessarily mean that Perl checks the number or type of the arguments to your function. If Perl sees func(3, 5) for a function prototyped as sub func ($), it will stop with a compile-time error. But if it sees func(@array) with the same prototype, it will merely put @array into scalar context instead of saying "you can't pass an array - I'm expecting a scalar."

This is so important that it bears repeating: don't use Perl prototypes expecting the compiler to check type and number of arguments for you.

So what use are they? They have two main uses, although as you experiment with them you may find others. The first use is to tell Perl how many arguments your subroutine has, so you can leave off parentheses when you call the function. The second is to create a subroutine that has the same calling syntax as a built-in.

Omitting parentheses

Ordinarily your subroutines take a list of arguments, and you can omit parentheses on the function call if you like:

@results = myfunc 3, 5;

Without prototypes, this is the same as:

@results = myfunc(3, 5);

In the absence of parentheses, Perl will put the right hand side of the subroutine call into list context. You can use prototypes to change this behavior:

sub myfunc($);
@results = myfunc 3, 5;

Now this is the same as:

@results = ( myfunc(3), 5 );

You can also provide an empty prototype to indicate the function takes no arguments, like the built-in function time. This is how Fcntl provides the LOCK_SH, LOCK_EX, and LOCK_UN constants. They are exported functions defined to have an empty prototype:

sub LOCK_SH () { 1 }
sub LOCK_EX () { 2 }
sub LOCK_UN () { 4 }

Mimicking built-ins

The other common use of prototypes is to give the convenient pass-without-flattening behavior of built-in functions like push and shift. When you call push as push(@array, 1, 2, 3) the function gets a reference to @array instead of the actual array. This is accomplished by backslashing the @ character in the prototype:

sub mypush (\@@) {
  my $array_ref = shift;
  my @remainder = @_;

  # ...
}

The \@ in the prototype says "require the first argument to begin with an @ character, and pass it by reference." The second @ says "the rest of the arguments are a (possibly empty) list." A backslash in a prototype requires that the argument actually begin with the literal type character, which can sometimes be annoying. You can't even use the conditional ?: construct to pick which array to pass:

 mypush( $x > 10 ? @a : @b , 3, 5 );          # WRONG

Instead, you must play games with references:

 mypush( @{ $x > 10 ? \@a : \@b }, 3, 5 );    # RIGHT

Here's an hpush function that works like push, but on hashes. It appends a list of key/value pairs to an existing hash, overwriting previous contents for those keys.

sub hpush(\%@) {
    my $href = shift;
    while ( my ($k, $v) = splice(@_, 0, 2) ) {
        $href->{$k} = $v;
    } 
} 
hpush(%pieces, "queen" => 9, "rook" => 5);

10.11. Prototyping Functions

Problem

Solution

Discussion

Omitting parentheses

Mimicking built-ins

See Also


10.10. Returning Failure		10.12. Handling Exceptions