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]

then it may seem like an unreasonable inefficiency, particularly since the string_parse functionality could be exposed directly (as below) for almost no extra cost.

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]

leaves room to implement that in a more memory-gentle manner in the future, without your users needing to change their code. Of course the functionality itself determines how likely that is ever to be useful.

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.

Hugo