Preferred technique for named subroutine parameters?

Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

I'm writing a module that, from the constructor, will accept essentially named parameters, and I'm wondering which of the two common ways of doing so is preferred.

Should I accept a single argument of a hashref:

# new MyModule({arg1 => 'val1', arg2 => 'val2'})
sub new {
    my $class = shift;
    croak('oh crap!') if ref($_[0]) != 'HASH'
    my %args = %{$_[0]};
}
[download]

Or should I cast all arguments into a hash:

# new MyModule(arg1 => 'val1', arg2 => 'val2')
sub new {
    my $class = shift;
    croak('oh crap!') if @_ % 2;
    my %args = @_;
}
[download]

I've seen both techniques used in many places, but which one is generally preferred and/or considered better API design?

Comment on Preferred technique for named subroutine parameters? Select or Download Code

Replies are listed 'Best First'.
Re: Preferred technique for named subroutine parameters? (PBP) by toolic (Bishop) on May 22, 2009 at 21:06 UTC
For the record, the Perl Best Practices book (chapter 9, section titled "Named Arguments") recommends passing a hashref. The reason cited is the same as that given by AnomalousMonk in Re: Preferred technique for named subroutine parameters?. In fact, that sub-thread would make a great appendix to the PBP section!	[reply]
Re^2: Preferred technique for named subroutine parameters? (PBP) by shmem (Chancellor) on May 23, 2009 at 10:16 UTC
That is another point where I strongly disagree with 'Perl Best Practices'. Passing a hash reference as an argument to a sub is just that -: it is passing one argument to a subroutine which expects one argument - a hash reference, and not a list of parameters (named or not). In my book of 'Personal Best Practices' curlies are for hash references or for code blocks. Constructing and destroying a hash to pass named params is just silly. See also my answer to AnomalousMonk.	[reply]
Re^2: Preferred technique for named subroutine parameters? (PBP) by AnomalousMonk (Archbishop) on May 22, 2009 at 21:45 UTC
Actually, I was pretty sure I had read it somewhere, I was just too lazy to look it up; but I knew it worked!	[reply]
Re: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 20:03 UTC
I, too, dislike having bunches of curly brackets cluttering up my code. However, the `func({ key1 => 'value1', key2 => 'etc', });` invocation style for named arguments has a benefit I consider very valuable: if an invocation is malformed, a warning is issued at the point of invocation. In the alternate, arguably cleaner, invocation style that does not use an anonymous hash, the warning is issued at a point within the called function, so the question immediately becomes "Where was this function invoked, so I can go there and fix the improperly specified arguments". `use warnings; use strict; func_1({ one => 'uno', two => 'dos', three => }); # <-- line 38 func_2(one => 'uno', two => 'dos', three => ); sub func_1 { my %args = %{ $_[0] }; print "func_1: one translates to $args{one} \n"; } sub func_2 { my %args = @_; # <-- line 48 print "func_2: one translates to $args{one} \n"; }` [download] Output: `>perl 765727_1.pl Odd number of elements in anonymous hash at 765727_1.pl line 38. func_1: one translates to uno Odd number of elements in hash assignment at 765727_1.pl line 48. func_2: one translates to uno` [download]	[reply] [d/l] [select]
Re^2: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 20:28 UTC
That's because you are doing it wrong. Carp is your friend: `use warnings; use strict; use Carp; func(one => 'uno', two => 'dos', three => ); sub func { croak "wrong number of arguments for func(); has to be even" if sc +alar(@_) % 2; my %args = @_; print "func: one translates to $args{one} \n"; }` [download] prints `wrong number of arguments for func(); has to be even at a.pl line 8 main::func('one', 'uno', 'two', 'dos', 'three') called at a.pl lin +e 5` [download]	[reply] [d/l] [select]
Re^3: Preferred technique for named subroutine parameters? by tilly (Archbishop) on May 22, 2009 at 20:51 UTC
I happen to like Carp so much that I rewrote it to make it better, but try as it might it cannot always properly assign blame. In this case it reaches all of the way up the call stack, gives up, and gives a complete stack backtrace. If your code appeared in a module, you'd have blamed the user with a very confusing message. By contrast the anonymous hash always blames the exact right line of code. While I have preferred the flat list approach, I'm going to have to rethink that preference based on this point.	[reply]
Re^4: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 21:00 UTC
Re^5: Preferred technique for named subroutine parameters? by tilly (Archbishop) on May 22, 2009 at 21:05 UTC
Some notes below your chosen depth have not been shown here
Re^5: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 21:23 UTC
Re^3: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 20:43 UTC
But then you have to test, `croak` and `carp` all over the place. This mitigates against 'clean' code (for some definition of 'clean'). With the anonymous hash approach, don't you get pertinent warnings 'for free'?	[reply] [d/l] [select]
Re^4: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 20:47 UTC
Re^5: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 22:16 UTC
Re^2: Preferred technique for named subroutine parameters? by shmem (Chancellor) on May 23, 2009 at 10:08 UTC
Valid point, but Carp::cluck tells you of the invocation point, also. If you would want that globally, you could `$SIG{__WARN__} = \&Carp::cluck` and comment that out in the final version. Too expensive for me if there's no other reason to pass named parameters as an anonymous hash: `use Benchmark qw(cmpthese); sub f{} cmpthese ( -1 => { list => sub { f( foo => 1) }, ref => sub { f({foo => 1})}, } ); __END__ Rate ref list ref 232162/s -- -88% list 1989486/s 757% --` [download] Contructing and destructing a full blown hash only to pass named parameters is just a waste. Breaking named parameters into several lines aligning the fat commata vertically helps. I did commit the gaffe of passing an odd number of arguments as named subroutine parameters maybe twice in all my time as a perl programmer, but more often I've been bitten by missing the curlies for apis which required a hash ref for named parameters.	[reply] [d/l] [select]
Re^3: Preferred technique for named subroutine parameters? by wfsp (Abbot) on May 23, 2009 at 10:58 UTC
My benchmark foo is very poor but does this show that if you do something with the arguments the "waste" is not as dramatic as your figures show? `#!/usr/bin/perl use strict; use warnings; use Benchmark qw(cmpthese); sub f{ my %hash = @_; my $value = $hash{foo}; } sub g{ my $hash_ref = shift; my $value = $hash_ref->{foo} } cmpthese ( -1 => { list => sub { f( foo => 1) }, ref => sub { g({foo => 1})}, } ); __END__ Rate ref list ref 693652/s -- -25% list 919951/s 33% --` [download]	[reply] [d/l]
Re^4: Preferred technique for named subroutine parameters? by shmem (Chancellor) on May 23, 2009 at 11:30 UTC
Re^2: Preferred technique for named subroutine parameters? by LanX (Saint) on May 23, 2009 at 15:13 UTC
> a warning is issued at the point of invocation. well the argument in PPP is much stronger, the warning is issued at compile-time !!! The point of invocation can still be found out in run-time, e.g. with carp like already discused! But a run-time-error can happen years after you wrote and sold the code ... Cheers Rolf	[reply]
Re^3: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 23, 2009 at 22:12 UTC
... the argument in PPP is much stronger, the warning is issued at compile-time !!! My PBP (1st English ed., printed July 2005, which seems from the O'Reilly website info to be the latest English edition and printing) does say (pg. 183, 2nd para.) "... will be reported (usually at compile time) in the caller's context ...", but I don't see how this is so. (I have also checked the on-line errata list and there is no correction of this statement.) Certainly the malformed function call `func_1({ one => 'uno', two => 'dos', three => });` from my example code in Re: Preferred technique for named subroutine parameters? does compile and only warns at run time. Can you give an example of a compile time error associated with this invocation format, or any explanation or example of what Conway was referring to? But a run-time-error can happen years after you wrote and sold the code ... True, but if it does happen years after I wrote and sold the code, cashed the check, spent the money and moved to another state ... Update: "edition" -> "edition and printing" in para. 1.	[reply] [d/l]
Re^4: Preferred technique for named subroutine parameters? by LanX (Saint) on May 24, 2009 at 12:22 UTC
Re: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 19:12 UTC
This seems to be a hot topic today! Both methods are widely used, so you are on your own�� sometimes one way makes more sense than the other; some people have preferences. I like flat lists�� less parentheses, and you can use non-string keys if you need to (or: someone who extends your module can add non-string stuff without breaking all pre-existing code). Or you could support both.	[reply]
Re^2: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 20:34 UTC
... you can use non-string keys if you need to (or: someone who extends your module can add non-string stuff without breaking all pre-existing code). I don't understand this point. Isn't it always possible to use 'non-string' (actually non-bareword) keys as long as they are appropriately disambiguated? Anyone who is aware of the calling convention of your module (as they surely must be to extend the module or to use it in the first place) can easily avoid this pitfall. The classic example: You have a constant `KONSTANT` (defined with the `use constant ...` pragma) that you want to use as a key. Then just disambiguate `KONSTANT` as the function call it really is: `func({ KONSTANT() => 'foo' });` Leaving aside a multitude of ambiguities arising from confusion about the precedence of the `,` (comma) and `=>` operators versus other operators, it's hard to imagine another realistic example in which this problem would arise.	[reply] [d/l] [select]
Re^3: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 20:43 UTC
Try using a reference as a hash key (or check out the relevant question in perlfaq4).	[reply]
Re^4: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 22, 2009 at 21:06 UTC
Re^5: Preferred technique for named subroutine parameters? by akho (Hermit) on May 22, 2009 at 21:09 UTC
Some notes below your chosen depth have not been shown here
Re^5: Preferred technique for named subroutine parameters? by LanX (Saint) on May 22, 2009 at 22:06 UTC
Some notes below your chosen depth have not been shown here
Re: Preferred technique for named subroutine parameters? by perrin (Chancellor) on May 22, 2009 at 19:20 UTC
The latter is more common and I prefer it in my code. That's my vote.	[reply]
Re: Preferred technique for named subroutine parameters? by Arunbear (Prior) on May 23, 2009 at 22:30 UTC
I like the hash method combined with Params::Validate which nicely does what it says on the can and is great value for money. Give it a try ! `use Params::Validate qw/:all/; # MyModule->new(foo => 'val1', bar => 'val2') sub new { my $class = shift; my %args = validate(@_, { foo => 1, bar => 0 }); # foo required; b +ar optional ... }` [download]	[reply] [d/l]
Re^2: Preferred technique for named subroutine parameters? by shmem (Chancellor) on May 23, 2009 at 22:40 UTC
I like the hash method Plain list not hashref, I would say by your example ;-)	[reply]
Re: Preferred technique for named subroutine parameters? by AnomalousMonk (Archbishop) on May 24, 2009 at 02:35 UTC
BTW, `croak('oh crap!') if ref($_[0]) != 'HASH'` [download] should be `croak('oh crap!') if ref($_[0]) ne 'HASH';` [download] in the example code of the OP.	[reply] [d/l] [select]
Re^2: Preferred technique for named subroutine parameters? by salazar (Scribe) on May 24, 2009 at 08:20 UTC
Sooomebody isn't using strict and warnings... :P.	[reply]
Re: Preferred technique for named subroutine parameters? by spacebat (Beadle) on May 26, 2009 at 22:36 UTC
While I lean towards the flat list, I dislike more having to remember which convention is required in a particular piece of code. So I tend to support both forms: `sub new { my $class = shift; my $args = (ref $_[0] eq 'HASH') ? shift : { @_ }; # ... }` [download] update: possibly bad example - that's how I retrofit some of the legacy code at work. New code would inherit new() from Moose or Mouse :)	[reply] [d/l]

Back to Seekers of Perl Wisdom