Perl Subroutine Prototyping -- The correct way to do it

Question

I have a subroutine called debug I use in my code. It basically allows me to see what's going on, etc.

sub debug {
    my $message      = shift;
    my $messageLevel = shift;

    our $debugLevel;
    $messageLevel = 1 if not defined $messageLevel;
    return if $messageLevel > $debugLevel;
    my $printMessage = "    " x $messageLevel . "DEBUG: $message\n";
    print STDERR $printMessage;
    return $printMessage;
}

I want to prototype this, so I can do things like this:

debug "Here I am! And the value of foo is $foo";

or

debug "I am in subroutine foo", 3;

At the same time, I like putting subroutine definitions at the bottom of my program, so you don't have to wade 1/2 way through the code to find the meat of the program.

I'd like to do this:

sub debug($;$);  #Prototype debug subroutine

/Here goes the main program code/

sub debug {      #The entire subroutine goes here
   /Here goes the debug subroutine code/
}

However, I get a warning when I do this:

Prototype mismatch: sub main::debug ($;$) vs none at foo.pl line 249.

So, I'm stuck putting the prototype definition in both places. What is the correct way to do something like this?

---

RESPONSE

Stop! Module time. – Chris Lutz

A module? You mean create a separate file? That adds a bit of complication without solving the issue I'm trying to solve: Removing the need for parentheses around this particular subroutine.

our $debugLevel; should not be in the sub body anyway, but I agree with Chris on this. – Sinan Ünür 3 hours ago

The our $debugLevel does not have to be there in this case, but if I defined a class and I want to use this subroutine in my class for debugging, I need it. I can put it in my class as ::debug

Surprisingly, Far more than everything you ever wanted to know about prototypes in Perl doesn't address this, but I believe you cannot avoid writing the prototype in both places.

I was hoping for an easy way to avoid it. There is a way as Eric Strom showed. Unfortunately, it's longer than my debug routine.

I used to use prototypes, but I've developed the habit of not writing separate declarations for subroutines and using parentheses on all calls: debug("I am in subroutine foo", 3);. It's been suggested that prototypes really aren't a good idea. TMTOWTDI – Keith Thompson 3 hours

Except I'll tend to do:

debug (qq(The value of Foo is "$foo"), 3);

which can be less clear when reading, and can be a pain to type. Whenever you double up parenthese, you're asking for trouble. The last thing I want to do is debug my debug statements.

Why do you want prototypes? See this question How to pass optional parameters to a Perl function – TLP

Yes, there are lots of problems with prototyping. The main problem is that it simply doesn't do what people think it should do: Declare the variable types for the parameters you're passing to your function.

This is not the reason I'm using prototyping here.

I rarely use prototypes. In fact, this is probably the only case in all of my code where I do.

Answer 1

If I am understanding correctly, you want to prototype and predeclare so that you can use the function (prototyped and braceless) within the same file. This is what the subs pragma is for.

For example, this code works correctly:

#!/usr/bin/env perl

use strict;
use warnings;

use subs qw/mysay/;

mysay "Yo";
mysay "Yo", "Joel";

sub mysay ($;$) {
  my $message = shift;
  my $speaker = shift;
  if (defined $speaker) {
    $message = "$speaker says: " . $message;
  }
  print $message, "\n";
}

Answer 2

You have to declare the same prototype when you define your subroutine:

sub debug($;$); # prototype/declare

... meat of the program ...

sub debug($;$) {
    ...
}

Answer 3

The prototype is attached to the coderef and not the name, so when you replace the coderef with the new declaration, you are clearing the prototype. You can avoid having to cross-reference and match prototypes with a helper function:

sub debug ($;$);

debug 'foo';

use Scalar::Util 'set_prototype';
sub install {
    my ($name, $code) = @_;
    my $glob = do {no strict 'refs'; \*$name};
    set_prototype \&$code, prototype \&$glob;
    *$glob = $code;
}

BEGIN {
    install debug => sub {
        print "body of debug: @_\n";
    };
}

install is just a wrapper around Scalar::Util's set_prototype function, which allows you to change the prototype of a coderef after it is created.

Prototypes can be very useful, but when using the scalar prototype, always ask yourself if that is really what you intended. Because the ($;$) prototype tells perl "debug is a function that can take one or two arguments, each with scalar context imposed on the call site".

The bit about context is where people usually get tripped up, because then if you try to do this:

my @array = qw(one two);

debug @array;

Then @array gets seen in scalar context, and becomes 2. So the call becomes debug 2; rather than debug 'one', 'two'; as you might have expected.