What I have so far:

My current idea (a.k.a. "first draft") for the API is demonstrated by the following simple usage example, which would be a script for finding TV series by name:

#!/usr/bin/perl
use warnings;
use strict;
use My::Hypothetical::Web::Query::Module qw(register_query);


# Defining the query:

register_query 'tvdb_series_search' => {
    url   => 'http://thetvdb.com/api/GetSeries.php?seriesname=%s',
    cache => 'tvdb_search_%s.xml',
    items => '/Data/Series',  # this is an XPath expression!
    class => 'Series',
    parse => { 'name' => './SeriesName',
               'year' => ['./FirstAired', qr/^(\d{0,4})/],
               'desc' => './Overview' },
};


# Defining the type for the query's result items:

package Series {
    use Moo;
    has name => (is => 'ro');
    has year => (is => 'ro');
    has desc => (is => 'ro');
    
    sub summary {
        my $self = shift;
        return sprintf "%s [%s]\n  %s\n", $self->name, $self->year,
                   substr($self->desc, 0, 64).'...';
    }
}


# Executing the query and iterating over its result list:

my $it = tvdb_series_search( $ARGV[0] );

while (my $series = $it->()) {
    print $series->summary();
}
[download]

Sample output:

$ ./findseries.pl cards
House of Cards [1990]
  The PM made a deadly mistake when he passed over Francis Urquhar...
House of Cards (US) [2013]
  House of Cards is an American political drama series developed a...
[download]

I.e. a query is defined using a hash, some of whose values (like the URL) are sprintf patterns that will get filled by the parameter(s) passed to the query each time it is executed. Each of the parsing rules (items and the child values of parse) can be given as an XPath expression or a regex, or as an array of multiple XPath expressions and regexes where each one narrows down the result of the preceding one.

The register_query function takes this hash, and constructs a query subroutine from it which it dynamically injects into the program's symbol table, so that executing the query is as simple as calling that function with the desired parameters.

The result items are optionally returned as objects of the type specified by the class option, which admittedly is overkill in a simple example like the above, but will be useful in more complex use-cases.

Some additional planned options for register_query, that are not demonstrated above:

    args  => sub { ... },  # transform query parameters before they
                           # are passed to sprintf

    pre   => &IO::Uncompress::Unzip::unzip,  # preprocess download
                                             # before parsing
[download]

Questions:

• Does what I'm trying to do seem sensible, or am I completely off track?
  
  
• Any comments (or suggestions for improvement) regarding the proposed API?
  
  
• Is dynamically adding functions to the global symbol table considered an acceptable practice these days? Will it cause problems? And which would be the preferable way to implement it:
  1. by generating code for a function that is perfectly tailored to the query at hand, and then eval'ing it?
  2. by instantiating a closure that closes over the hash (and will re-parses it each time the query is executed), and using typeglob magic to give that closure a global name?
  
  
• Would it be too crazy to push the "result items as objects" idea further, and let register_query automatically generate a class for them based on the keys of the parse option, and take an optional role option for specifying a Moo::Role that will be applied to that class (if that is even possible to do at runtime)?