NAME

WWW::GoKGS::Scraper::GameArchives - KGS Game Archives

SYNOPSIS

use WWW::GoKGS::Scraper::GameArchives;
my $game_archives = WWW::GoKGS::Scraper::GameArchives->new;
my $result = $game_archives->query( user => 'YourAccount' );

DESCRIPTION

KGS Game Archives preserves Go games played by the users. You can search games by filling in the HTML forms. The search result is provided as an HTML document naturally.

This module provides yet another interface to send a query to the archives, and also parses the result into a neatly arranged Perl data structure.

This class inherits from WWW::GoKGS::Scraper.

DISCLAIMER

According to KGS's robots.txt, bots are not allowed to crawl the Game Archives:

User-agent: *
Disallow: /gameArchives.jsp

Although this module can be used to implement crawlers, the author doesn't intend to violate their policy. Use at your own risk.

CLASS METHODS

$uri = $class->base_uri

# => "http://www.gokgs.com/gameArchives.jsp"

$URI = $class->build_uri( $k1 => $v1, $k2 => $v2, ... )

$URI = $class->build_uri({ $k1 => $v1, $k2 => $v2, ... })

$URI = $class->build_uri([ $k1 => $v1, $k2 => $v2, ... ])

Given key-value pairs of query parameters, constructs a URI object which consists of base_uri and the parameters.

INSTANCE METHODS

$UserAgent = $game_archives->user_agent

$game_archives->user_agent( LWP::UserAgent->new(...) )

Can be used to get or set an LWP::UserAgent object which is used to GET the requested resource. Defaults to the LWP::UserAgent object shared by Web::Scraper users ($Web::Scraper::UserAgent).

$HashRef = $game_archives->query( user => 'YourAccount', ... )

Given key-value pairs of query parameters, returns a hash reference which represnets the result. The hashref is formatted as follows:

{
    games => [
        {
            sgf_uri => 'http://files.gokgs.com/.../foo-bar.sgf',
            white => [
                {
                    name => 'foo',
                    rank => '4k',
                    uri  => 'http://...&user=foo...'
                }
            ],
            black => [
                {
                    name => 'bar',
                    rank => '6k',
                    uri  => 'http://...&user=bar...'
                }
            ],
            board_size => '19',
            handicap => '2',
            start_time => '2013-07-04T05:32Z',
            type => 'Ranked',
            result => 'W+Resign'
        },
        ...
    ],
    zip_uri => 'http://.../foo-2013-7.zip',    # contains SGF files
    tgz_uri => 'http://.../foo-2013-7.tar.gz', # created in July 2013
    calendar => [
        ...
        {
            year  => 2011,
            month => 7,
            uri   => '/gameArchives.jsp?user=foo&year=2011&month=7'
        },
        ...
    ]
}

The possible parameters are as follows:

user (required)

Represents a KGS username.

my $result = $game_archives->query( user => 'foo' );

year, month

Can be used to search games played in the specified month.

my $result = $game_archives->query(
    user  => 'foo',
    year  => 2013
    month => 7
);

oldAccounts

Can be used to search games played by expired and guest accounts.

my $result = $game_archives->query(
    user        => 'foo',
    oldAccounts => 'y'
);

tags

Can be used to search games tagged by the specified user.

my $result = $game_archives->query(
    user => 'foo',
    tags => 't'
);

$HashRef = $game_archives->scrape( $stuff )

The given arguments are passed to Web::Scraper's scrape method. query method is just a wrapper of this method. For example, you can pass URIs included by the return value of query method.

EXAMPLES

use JSON::Path qw/jpath_map/; 
use Time::Piece qw/gmtime/;

# convert start times for games into Time::Piece objects
jpath_map { gmtime->strftime('%Y-%m-%dT%H:%MZ', $_) }
    $result, '$.games[*].start_time';

HISTORY

WWW::KGS::GameArchives was renamed to WWW::GoKGS::Scraper::GameArchives (this module). The return value of the scrape method ($result) was modified as follows:

- Remove $result->{summary}
- Rename $game->{kifu_uri} to $game->{sgf_uri}
- Rename $game->{editor} to $game->{owner}
- Remove $game->{setup}
- Add $game->{board_size}
- Add $game->{handicap}
- $user->{name} does not end with a rank string such as "[2k]"
- Add $user->{rank}
- Rename $user->{link} to $user->{uri}

where $game denotes an element of $result->{games} and $user denotes $game->{owner}, an element of $game->{white} or an element of $game->{black} respectively.

SEE ALSO

WWW::GoKGS

AUTHOR

Ryo Anazawa (anazawa@cpan.org)

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.