One aspect worth considering is how the coder would work around lack of the convenience function, and how irritated she is likely to be about needing to. If, for example, you have a file_parse but not a filehandle_parse, that's likely to be very irritating when you have a filehandle but don't know the filename; when it's the other way round it isn't too bad, since you can just open the file to get the filehandle.

Similarly, if you have a string rather than a filehandle it may not be too difficult to work around (open(my $fh, "<", \$string) is newly available in 5.8.0), but if the code is only going to do:

  sub filehandle_parse {
    my $fh = shift;
    my $string = do { local $/; <$fh> };
    ... work on $string
  }
[download]

It can also be worth putting in some placeholders for future optimisation: if string_parse is your primary entry point, but you anticipate that some users of the module may need to parse large files, putting in a

  sub filehandle_parse {
    my $fh = shift;
    string_parse(do { local $/; <$fh> });
  }
[download]

No hard and fast rules, though; the main danger is that the "surface" of your module may become too complex. I'm a great believer in polymorphic methods to reduce that complexity ("EXPR may be a filehandle or a string"), but that approach isn't for everyone.

I find convenience methods necessary - I don't want to slurp a file into a scalar, I want to pass a filename (or a file glob or an URI, or a callback, if applicable) to the function. This boils down to either massive dwimmery within the core function or some (several) wrapper functions, for example for the parse_file/parse_uri part versus the parse_scalar part.

If you fear that those helper functions bloat your original module, create a *::Simple or *::Common module, which encapsulates the more common cases (for example, HTML::LinkExtor, HTTP::Request::Common or Regex::Common are such modules). A *::Simple module would cut down on the options and supply sensible defaults.

perl -MHTTP::Daemon -MHTTP::Response -MLWP::Simple -e ' ;    # The  
$d = new HTTP::Daemon and fork and getprint $d->url and exit;#spider
($c = $d->accept())->get_request(); $c->send_response( new   #in the
HTTP::Response(200,$_,$_,qq(Just another Perl hacker\n))); ' #  web
[download]

(my $style_guide_preferred = "brian d. foy") =~ tr/.//d;
[download]

-- Randal L. Schwartz, Perl hacker
Be sure to read my standard disclaimer if this is a reply.

Totally off-topic, but I'm curious - what's with the style of "brian d foy?" I found this style guide which creates a lot more questions than answers (such as WHY?). He also has press mentions all of which is giving me a really surreal haven't slept in 72 hours type feeling. Anyone know why he insists on that notation of his name?

From what I remember (I think it was in a TPJ issue) - perl is case sensitive and so is brian.

-derby

I can still name variables with mixed case in Perl though.

He's the artist formerly known as Brian D. Foy.

And that, as far as I can tell, is the jist of the whole thing.

Matt

Maybe he is an ee cummings fan :)

--
Life is a tale told by an idiot -- full of sound and fury, signifying nothing. William Shakespeare, Macbeth

Bloat is subjective: If there's a lot of stuff in an API that I don't have any use for, it's bloat. The stuff I use isn't bloat.

The problem comes when an API (or a program) starts serving diverse communities, with non- (or barely-) overlapping needs and desires. Each might have a valid reason for a set of convenience methods, but, taken as a whole, everyone cries bloat. Microsoft Word is a good example of how this happens. The Word Product Managers will tell you that for every feature, there was someone who asked for it.

The only no-brainer bloat is stuff that nobody uses.

To my mind, a feature becomes bloat when I can achieve the feature in my own code, using less code than it adds to the module.

Perl itself doesn't have a log₁₀ function, as this can easily be simulated by the programmer using the provided log₂ function.

Personally, there are quite a few CPAN modules that have features I would use, if I didn't have to take all the 'value-add' functionality as well. I think that providing generic functionality in many modules detracts from them rather than adding to them.

Example. There appear to be at least 3 different modules that will perform url-encoding and decoding.

Wouldn't it make more sense to have a single, lightweight module to do this and have the other 3 modules require it?

Where a module provides a collection of features that are unlikely to all be used in every program that uses the module, the POSIX' modules way of only loading those subs that are asked for is much prefereable to the method used in some others where the code is loaded regardless, but only those subs asked for are exposed. This seems to be the worst of all worlds as it means that I am loading code that there is simply no way for my program to use anyway, which seems more than a little pointless.

Not, mind, that I'm being cynical or grumpy at the moment.

oakbox