NAME

WWW::GoKGS - KGS Go Server (http://www.gokgs.com/) Scraper

SYNOPSIS

  use WWW::GoKGS;

  my $gokgs = WWW::GoKGS->new;

  # Game archives
  my $game_archives_1 = $gokgs->scrape( '/gameArchives.jsp?user=foo' );
  my $game_archives_2 = $gokgs->game_archives->query( user => 'foo' );

  # Top 100 players
  my $top_100_1 = $gokgs->scrape( '/top100.jsp' );
  my $top_100_2 = $gokgs->top_100->query;

  # List of tournaments 
  my $tourn_list_1 = $gokgs->scrape( '/tournList.jsp?year=2014' );
  my $tourn_list_2 = $gokgs->tourn_list->query( year => 2014 );

  # Information for the tournament
  my $tourn_info_1 = $gokgs->scrape( '/tournInfo.jsp?id=123' );
  my $tourn_info_2 = $gokgs->tourn_info->query( id => 123 );

  # The tournament entrants
  my $tourn_entrants_1 = $gokgs->scrape( '/tournEntrans.jsp?id=123&sort=n' );
  my $tourn_entrants_2 = $gokgs->tourn_entrants->query( id => 123, sort => 'n' );

  # The tournament games
  my $tourn_games_1 = $gokgs->scrape( '/tournGames.jsp?id=123&round=1' );
  my $tourn_games_2 = $gokgs->tourn_games->query( id => 123, round => 1 );

DESCRIPTION

This module is a KGS Go Server (http://www.gokgs.com/) scraper. KGS allows the users to play a board game called go a.k.a. baduk (Korean) or weiqi (Chinese). Although the web server provides resources generated dynamically, such as Game Archives, they are formatted as HTML, the only format. This module provides yet another representation of those resources, Perl data structure.

This class maps a URI preceded by http://www.gokgs.com/ to a proper scraper. The supported resources on KGS are as follows:

KGS Game Archives (http://www.gokgs.com/archives.jsp)

Handled by WWW::GoKGS::Scraper::GameArchives.

Top 100 KGS Players (http://www.gokgs.com/top100.jsp)

Handled by WWW::GoKGS::Scraper::Top100.

KGS Tournaments (http://www.gokgs.com/tournList.jsp)

Handled by WWW::GoKGS::Scraper::TournList, WWW::GoKGS::Scraper::TournInfo, WWW::GoKGS::Scraper::TournEntrants and WWW::GoKGS::Scraper::TournGames.

ATTRIBUTES

$UserAgent = $gokgs->user_agent

Returns an LWP::UserAgent object which is used to GET the requested resource. This attribute is read-only.

  use LWP::UserAgent;

  my $gokgs = WWW::GoKGS->new(
      user_agent => LWP::UserAgent->new(
          agent => 'MyAgent/1.00'
      )
  );

$CodeRef = $gokgs->html_filter

Returns an HTML filter. Defaults to an anonymous subref which just returns the given argument (sub { $_[0] }). The callback is called with an HTML string. The return value is used as the filtered value. This attribute is read-only.

  my $gokgs = WWW::GoKGS->new(
      html_filter => sub {
          my $html = shift;
          $html =~ s/<.*?>//g; # strip HTML tags
          $html;
      }
  );

$CodeRef = $gokgs->date_filter

Returns a date filter. Defaults to an anonymous subref which just returns the given argument (sub { $_[0] }). The callback is called with a date string such as 2014-05-17T19:05Z. The return value is used as the filtered value. This attribute is read-only.

  use Time::Piece qw/gmtime/;

  my $gokgs = WWW::GoKGS->new(
      date_filter => sub {
          my $date = shift; # => "2014-05-17T19:05Z"
          gmtime->strptime( $date, '%Y-%m-%dT%H:%MZ' );
      }
  );

$GameArchive = $gokgs->game_archives

Returns a WWW::GoKGS::Scraper::GameArchives object. This attribute is read-only.

$Top100 = $gokgs->top_100

Returns a WWW::GoKGS::Scraper::Top100 object. This attribute is read-only.

$TournList = $gokgs->tourn_list

Returns a WWW::GoKGS::Scraper::TournList object. This attribute is read-only.

$TournInfo = $gokgs->tourn_info

Returns a WWW::GoKGS::Scraper::TournInfo object. This attribute is read-only.

$TournEntrants = $gokgs->tourn_entrants

Returns a WWW::GoKGS::Scraper::TournEntrants object. This attribute is read-only.

$TournGames = $gokgs->tourn_games

Returns a WWW::GoKGS::Scraper::TournGames object. This attribute is read-only.

METHODS

$HashRef = $gokgs->scrape( '/gameArchives.jsp?user=foo' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/gameArchives.jsp?user=foo' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/gameArchives.jsp?user=foo' );
  my $game_archives = $gokgs->game_archives->scrape( $uri );

See WWW::GoKGS::Scraper::GameArchives for details.

$HashRef = $gokgs->scrape( '/top100.jsp' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/top100.jsp' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/top100.jsp' );
  my $top_100 = $gokgs->top_100->scrape( $uri );

See WWW::GoKGS::Scraper::Top100 for details.

$HashRef = $gokgs->scrape( '/tournList.jsp?year=2014' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/tournList.jsp?year=2014' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/tournList.jsp?year=2014' );
  my $tourn_list = $gokgs->tourn_list->scrape( $uri );

See WWW::GoKGS::Scraper::TournList for details.

$HashRef = $gokgs->scrape( '/tournInfo.jsp?id=123' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/tournInfo.jsp?id=123' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/tournInfo.jsp?id=123' );
  my $tourn_info = $gokgs->tourn_info->scrape( $uri );

See WWW::GoKGS::Scraper::TournInfo for details.

$HashRef = $gokgs->scrape( '/tournEntrants.jsp?id=123&s=n' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/tournEntrants.jsp?id=123&s=n' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/tournEntrants.jsp?id=123&s=n' );
  my $tourn_entrants = $gokgs->tourn_entrants->scrape( $uri );

See WWW::GoKGS::Scraper::TournEntrants for details.

$HashRef = $gokgs->scrape( '/tournGames.jsp?id=123&round=1' )

$HashRef = $gokgs->scrape( 'http://www.gokgs.com/tournGames.jsp?id=123&round=1' )

A shortcut for:

  my $uri = URI->new( 'http://www.gokgs.com/tournGames.jsp?id=123&round=1' );
  my $tourn_games = $gokgs->tourn_games->scrape( $uri );

See WWW::GoKGS::Scraper::TournGames for details.

ACKNOWLEDGEMENT

Thanks to wms, the author of KGS Go Server, we can enjoy playing go online for free.

SEE ALSO

KGS Go Server, Web::Scraper

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.