it's easier to provide an OO interface instead of something that looks like a filehandle but really isn't

As I understand, tied filehandles really are filehandles, so that issue is avoided. The main motivation for using tied values in this API is to reuse Perl APIs instead of inventing new ones.

This led to the tied aggregate interfaces in WARC::Fields when I realized that I could either reinvent array and hash access with OO methods, or just tie the real thing and "fill out" the ready-made interface form from perltie. That class has very few instance methods as a result, with only one for data access: ->field, which takes a field name (and possibly a new value for that field). Yet complex operations are possible: adding a concurrent record is push @{$record->fields->{WARC_Concurrent_To}}, $other_record->field('WARC-Record-ID'); regardless of how many WARC-Concurrent-To values $record currently has. I am considering adding convenience accessors to WARC::Record for some fields, like ->id for WARC-Record-ID and ->date for WARC-Date (as a WARC::Date object instead of the string that ->field would return).

Is your code already online somewhere (GitHub?), for context?

The code that needs tied handles has not been written yet, but I have been making development preview releases on CPAN and collecting smoketest reports. (Amusingly, I have had more failures with the bundled POD test than with the code so far.) Look for JCB/WARC/WARC-v0.0.0_2.tar.gz for the version that prompted this question. It has the WARC::Fields module implemented and some POD describing the planned API so far. I posted a very early draft of that planned API on PerlMonks as Planning a new CPAN module for WARC support (DSLIP: IdpOp).

Back then, the parse WARC::Fields method was two different methods that have since been merged into a single parse WARC::Fields method. I do not have a problem with distinguishing IO handles and strings because I decided to require slightly different calls: parse WARC::Fields $text vs. parse WARC::Fields from => $filehandle — "from" is not a valid "application/warc-fields" document, so there is no ambiguity. The library itself will always use the from => $filehandle form since it is reading from a WARC volume. The other form internally opens a filehandle on the passed string and reads from that instead of duplicating the entire parser.

On a side note, do you know of any community Git hosting sites suitable for Perl libraries that do not rely on JavaScript to function and preferably run on Free software? Those are my chief objections to using GitHub for a new project. I have occasionally made pull requests there to contribute to other projects, but I would not want to actually host a project there. Or is this last paragraph itself a good question for the SoPW section here?