Recipe 10.11. Prototyping Functions
Author: Tom Christiansen & Nathan Torkington
Date: 1999-07-02T01:39:58Z

#

| Chapter 10 Subroutines |

## 10.11. Prototyping Functions

### Problem

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

### Solution

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);

### See Also

The `prototype` function in perlfunc (1); the section on "Prototypes" in Chapter 2 of Programming Perl and in perlsub (1); Recipe 10.5

10.10. Returning Failure |  | 10.12. Handling Exceptions