NAME

WebService::Vichan - API client for 4chan and vichan-based imageboards

SYNOPSIS

  use WebService::Vichan qw/:all/;
  my $chan = WebService::Vichan->new(API_4CHAN);

  my @boards = $chan->boards;
  say 'Boards on 4chan: ', join ', ', map { $_->board } @boards;

  my @all_pages_of_wsg = $chan->threads('wsg');
  my @wsg = @{$all_pages_of_wsg[0]->threads};
  say 'IDs of threads on the first page of /wsg/: ', join ', ', map { $_->no } @wsg;

  my @all_threads_of_g = $chan->threads_flat('g');
  my @posts_in_23rd_thread = $chan->thread('g', $all_threads_of_g[22]);
  printf "There are %d posts in the 23rd thread of /g/\n", scalar @posts_in_23rd_thread;
  my $the_post = $posts_in_23rd_thread[1];
  say 'HTML of the 2nd post in the 23rd thread of /g/: ', $the_post->com;

DESCRIPTION

This is an api client for 4chan.org and imageboards that use vichan (such as 8ch.net). It offers the following methods:

Note: functions that ordinarily return lists will return arrayrefs if called in scalar context.

WebService::Vichan->new($url)

Creates a new WebService::Vichan object with the given base URL.

Two constants are exported on request by this module: API_4CHAN and API_8CHAN, which represent the base URLs for 4chan.org and 8ch.net.

$chan->boards

Returns a list of available boards. These are blessed imageboard-dependent hashrefs which should at least have the methods board (returning the board code as a string) and title.

$chan->threads($board)

Takes a board object (or a board code as a string) and returns a list of pages of thread OPs. Each page is a blessed hashref with methods page (the index of the page) and threads (an arrayref of thread OPs on that page). Each thread OP is a blessed hashref which has at least the methods no (the thread number) and last_modified.

$chan->threads_flat($board)

Same as threads but page information is dropped. Returns a list of thread OPs as described above.

$chan->catalog($board)

Same as threads, but much more information is returned about each thread OP.

$chan->catalog_flat($board)

Same as threads_flat, but much more information is returned about each thread OP.

$chan->thread($board, $threadno, [$is_4chan])

Takes a board object (or a board code as a string), a thread OP object (or a thread number) and an optional boolean indicating whether to use 4chan logic for the request (by default 4chan logic is used if the URL contains 4cdn.org).

Returns a post object (blessed hashref) with methods as described in the API documentation (see links in the SEE ALSO section).

To comply with API usage rules every request is cached for 10 seconds, and requests are rate-limited to one per second. If a method is called less than 1 second after a request has happened, it will sleep before issuing a second request to ensure the rate limitation is followed.

SEE ALSO

https://github.com/4chan/4chan-API, https://github.com/vichan-devel/vichan-API/

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2017 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.3 or, at your option, any later version of Perl 5 you may have available.