#!/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();
}

##</code><code>##

$ ./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...

##</code><code>##

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

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