Question

I have to pass two references as arguments to a subroutine (buildRanges) as hash key-value pairs as show below

Example:

@array = (“0A0”, “005”, “001”, “004”, “0BC”, “004”, “002”, “001”);
@ranges = ();
$numRanges = buildRanges(VALUES => \@array, REF_RANGES=>\@ranges);

My question is
1. is the syntax for the sub-routine call above is correct?
2. what are VALUES and REF_RANGES?

franckly speaking, i couldnt understand the sub-routine call, but i have been told to use that call only.

Thanks.

KK

Answer 1

Explanations

Yes. This syntax is correct and idiomatic for Perl. Let’s dissect all parts of your function call — most likely you already know parts of the explanation.

Preparation: your input data

@array = (“0A0”, “005”, “001”, “004”, “0BC”, “004”, “002”, “001”);
@ranges = ();
# \@array and \@ranges are now normal scalar references.

I hope you understand the concept of references to arrays. If not, read perlreftut or perllol. Actually, this doesn’t affect the calling syntax that you are asking about. By the way, you might also have written:

$array_ref=[“0A0”, “005”, “001”, “004”, “0BC”, “004”, “002”, “001”];
$range_ref=[];

$numRanges = buildRanges(VALUES => $array_ref, REF_RANGES=> $range_ref);

The function call

In Perl, the arrow operator => is working just like a normal comma (with a small side-effect that we discuss in a moment). The following calls are absolutely identical:

$numRanges = buildRanges(VALUES => $array_ref, REF_RANGES => $range_ref);
$numRanges = buildRanges("VALUES", $array_ref, "REF_RANGES", $range_ref);

So, you are simply calling the function buildRanges with four arguments: two constant strings and two array references. You noticed that the word VALUES was changed to a constant string “VALUE”; the same applied to the word REF_RANGES. This is the special rule: before an arrow => and inside curly brackets {}, plain identifiers are silently converted to strings. We see this again below. But other expressions like $a => $b stay as they are, no silent conversions to strings happen here.

You may be asking why does Perl do this? This is syntactic sugar: The => operator does nothing that you couldn’t do easily without it. But for experienced perl programmers the format KEY => $value looks clearer than “KEY”, $value.

The function definition

The definition of the function buildRanges may look like this (and we use this in our explanation):

sub buidRanges { my(%info)=@_; 
  my $values    = $info{VALUES};
  my $ref_ranges= $info{REF_RANGES};
  my $special_feature = $info{SPECIAL_FEATURE}; # explained below
  if($special_feature) { ... return special_result; }
  ... process $values and $ref_ranges ... return $numRanges.
}

With your input data, each of the following four lines have the same effect:

my(%info)=@_;                                          # the actual code
my(%info)=(VALUES => \@array, REF_RANGES=> \@ranges ); # what this does

my %info; $info{"VALUES"}=\@array; $info{"REF_RANGES"}=\@ranges; 
my %info; $info{ VALUES }=\@array; $info{ REF_RANGES }=\@ranges; 

Basically, the input data is converted into a hash that allows access to each argument. The constant strings in the function call become hash keys.

Pick one line that you understand and compare it to the other lines: They do the same thing. Look at perldsc for more explanations.

Note that @_ is the array of input arguments, in our case

@_ = ( VALUES => \@array, REF_RANGES=> \@ranges); 
@_ = ("VALUES",  \@array,"REF_RANGES", \@ranges);  # without syntactic sugar

You may have noticed that $info{VALUES} is equivalent to $info{“VALUES”} — again, this is syntactic sugar, as explained above.

Further down in our hypothetical implementation, we pull the input data out of the hash:

 my $values     = $info{VALUES};       # i.e:  my $value      = \@array;
 my $ref_ranges = $info{REF_RANGES};   # i.e:  my $ref_renges = \@ranges;

Now, our function implementation can work with the input data.

Why do we do this not simpler? — Named arguments

So far, we could have achieved a similar effect much simpler:

$numRanges = buildRanges($array_ref, $range_ref);  # simpler function call

sub buidRanges { my($values, $ref_ranges)=@_; 
  ... process $values and $ref_ranges ... return $numRanges.
}

This is most likely the programming style that you already understand well.

So: Why make it some Perl programmers more complicated (and also much slower)?
The answer is: It’s more flexible, and somewhat more self-documenting.

To make the point more clear, I added a SPECIAL_FEATURE to our function definition. Now, the function can also be called like this:

$numRanges = buildRanges(VALUES => \@array, SPECIAL_FEATURE=> "infinite ranges");

The implemented function can tell that the SPECIAL_FEATURE is requested and that the REF_RANGES are not provided.

In some high-level functions, you have quite a number of extra features that are sometimes (but not always) useful, so it makes a lot of sense to let the caller decide which features to use and which not. Here, the named arguments come in handy.

Of course, I can’t tell you what special features are recognized by your
buildRanges function — you need to look at its implementation or ask the person that told you to use it. It’s also possible that, as a general convention, all high-level functions in some project use this calling style, even though some of them don’t provide much special features.