WWW::Ohloh::API::Projects - a set of Ohloh projects

    use WWW::Ohloh::API;

    my $ohloh = WWW::Ohloh::API->new( api_key => $my_api_key );
    my $projects = $ohloh->get_projects( query => 'Ohloh', max => 100 );

    while ( my $p = $projects->next ) {
        print $p->name;
    }

    # typical iterator
    while( my $project = $projects->next ) {
        print $project->name;
    }

    # read projects 10 at a time
    while( my @p = $project->next( 10 ) ) {
        # do something with them...
    }

    my $projects = $ohloh->get_projects( sort => 'stack_count', max => 100 );
    # get the first project special
    $top = $projects->next;
    # get the rest
    @most_stacked = $projects->all;

    while( my $p = <$projects> ) { 
        ### do stuff with $p
    }

package WWW::Ohloh::API::Projects;

use strict;
use warnings;

use Carp;
use Object::InsideOut;
use XML::LibXML;
use Readonly;
use List::MoreUtils qw/ none any /;

use overload '<>' => \&next;

our $VERSION = '0.3.1';

my @all_read : Field : Default(0);
my @cache_of : Field;
my @total_entries_of : Field : Default(-1);
my @ohloh_of : Field : Arg(ohloh);
my @page_of : Field : Default(0);
my @query_of : Field : Arg(query);
my @sort_order_of : Field : Arg(sort) :
  Type(\&WWW::Ohloh::API::Projects::is_allowed_sort);
my @max_entries_of : Field : Arg(max) : Get(max);

Readonly our @ALLOWED_SORTING => map { $_, $_ . '_reverse' }
  qw/ created_at description id name stack_count updated_at /;

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub is_allowed_sort {
    my $s = shift;
    return any { $s eq $_ } @ALLOWED_SORTING;
}

sub _init : Init {
    my $self = shift;

    $cache_of[$$self] = [];    # initialize to empty array

    if ( my $s = $sort_order_of[$$self] ) {
        if ( none { $s eq $_ } @ALLOWED_SORTING ) {
            croak "sorting order given: $s, must be one of the following: "
              . join ', ' => @ALLOWED_SORTING;
        }
    }
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub next {
    my $self = shift;
    my $nbr_requested = shift || 1;

    while ( @{ $cache_of[$$self] } < $nbr_requested
        and not $all_read[$$self] ) {
        $self->_gather_more;
    }

    my @bunch = splice @{ $cache_of[$$self] }, 0, $nbr_requested;

    if (@bunch) {
        return wantarray ? @bunch : $bunch[0];
    }

    # we've nothing else to return

    $page_of[$$self]  = 0;
    $all_read[$$self] = 0;

    return;
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub _gather_more {
    my $self = shift;

    my ( $url, $xml ) = $ohloh_of[$$self]->_query_server(
        'projects.xml',
        {   ( query => $query_of[$$self] ) x !!$query_of[$$self],
            ( sort => $sort_order_of[$$self] ) x !!$sort_order_of[$$self],
            page => ++$page_of[$$self] } );

    my @new_batch =
      map {
        WWW::Ohloh::API::Project->new(
            ohloh => $ohloh_of[$$self],
            xml   => $_,
          )
      } $xml->findnodes('project');

    # get total projects + where we are

    $total_entries_of[$$self] =
      $xml->findvalue('/response/items_available/text()');

    my $first_item = $xml->findvalue('/response/first_item_position/text()');

    $all_read[$$self] = 1 unless $total_entries_of[$$self];

    if ( $first_item + @new_batch - 1 >= $total_entries_of[$$self] ) {
        $all_read[$$self] = 1;
    }

    if ( my $max = $self->max ) {
        if ( $first_item + @new_batch - 1 >= $max ) {
            @new_batch = splice @new_batch, 0, $max - $first_item;
            $all_read[$$self] = 1;
        }
    }

    push @{ $cache_of[$$self] }, @new_batch;

    return;
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub all {
    my $self = shift;

    unless ( $self->max ) {
        croak "call to all only permitted if 'max' set in get_projects()";
    }

    $self->_gather_more until ( $all_read[$$self] );

    my @bunch = @{ $cache_of[$$self] };
    $cache_of[$$self] = [];

    $page_of[$$self]  = 0;
    $all_read[$$self] = 0;

    return @bunch;
}

'end of WWW::Ohloh::API::Projects';
__END__