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 <http://www.gokgs.com>, 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.

