File Coverage

blib/lib/JSAN/Index.pm

Criterion	Covered	Total	%
statement	55	71	77.4
branch	3	10	30.0
condition	1	2	50.0
subroutine	22	31	70.9
pod	14	18	77.7
total	95	132	71.9

package JSAN::Index;

=pod

=head1 NAME

JSAN::Index - JavaScript Archive Network (JSAN) SQLite/ORLite Index

=head1 DESCRIPTION

JSAN is the JavaScript Archive Network, a port of CPAN to JavaScript.

You can find the JSAN at L.

As well as a flat text file index like CPAN, the JSAN index is also
distributed as a L database.

C is a L wrapper built around the JSAN
SQLite index.

It allow you to easily do all sorts of nifty things with the index in a
simple and straight forward way.

=head2 Using The JSAN Index / Terminology

Once loaded, most of the functionality of the index is accessed through
the classes that implement the various objects in the index.

These are:

=over 4

=item L

An author is a single human (or under certain very special circumstances
a company or mailing list) that creates distributions and uploads them
to the JSAN.

=item L

A distribution is a single software component that may go through a number
of releases

=item L

A release is a compressed archive file containing a single version of a
paricular distribution.

=item L

A library is a single class, or rather a "pseudo-namespace", that
defines an interface to provide some functionality. Distributions often
contain a number of libraries, making up a complete "API".

=back

=head1 METHODS

There are only a very limited number of utility methods available
directly from the C class itself.

=cut

use 5.008005;
use strict;
use warnings;
use Params::Util   1.00 ();
use Carp                ();
use DBI                 ();


use JSAN::Transport;
use JSAN::Index::Author                 ();
use JSAN::Index::Library                ();
use JSAN::Index::Release                ();
use JSAN::Index::Release::Dependency    ();
use JSAN::Index::Release::Source        ();
use JSAN::Index::Distribution           ();

our $VERSION = '0.29';

my $SINGLETON = undef;

#####################################################################
# Constructor

=pod

=head2 init param => $value, ...

The C method initializes the JSAN index adapter. It takes a set of
parameters and initializes the C class. JSAN::Index is a
singleton, so only it can initialized only once. Any further attempts
to do so will result in an exception being thrown.

=cut


sub init {
    Carp::croak("JSAN::Index already initialized") if $SINGLETON;

    my $class  = shift;
    my $params = Params::Util::_HASH(shift) || {};

    my $transport = JSAN::Transport->new(
        mirror_remote => delete $params->{mirror_remote},
        mirror_local  => delete $params->{mirror_local},
        verbose       => $params->{verbose},
    );

    $SINGLETON = bless {
        transport   => $transport,
        file        => $transport->index_file,
        verbose     => delete $params->{verbose}
    }, $class;
}




#####################################################################
# Top-level Methods

=pod

=head2 dependency param => $value

The C method creates and returns an dependency resolution
object that is used by L to schedule which releases to
install.

If the optional parameter 'build' is true, creates a build-time
dependency resolve, which will additionally install releases only needed
for testing.

Returns an L object.

=cut

sub dependency {
    my $class  = shift;
    JSAN::Index::Release::Dependency->new( @_ );
}


=pod

=head2 transport

This accessor return an instance of JSAN::Transport, which can be used
for managing files of current mirror.

=cut

sub transport {
    Carp::croak("JSAN::Index is not initialized") unless $SINGLETON;
    $SINGLETON->{transport}
}


=pod

=head2 self

This accessor return a singleton instance of JSAN::Index, or undef is its
not initialized yet.

=cut

sub self {
    $SINGLETON
}

#####################################################################
# Database connectivity


sub sqlite {
    $SINGLETON || Carp::croak('JSAN::Index is not initialized yet');

    $SINGLETON->{file}
}

sub dsn {
    "dbi:SQLite:" . shift->sqlite
}


sub dbh {
    $_[0]->connect;
}

sub connect {
    DBI->connect( $_[0]->dsn, undef, undef, {
        PrintError => 0,
        RaiseError => 1,
    } );
}

sub prepare {
    shift->dbh->prepare(@_);
}

sub do {
    shift->dbh->do(@_);
}

sub selectall_arrayref {
    shift->dbh->selectall_arrayref(@_);
}

sub selectall_hashref {
    shift->dbh->selectall_hashref(@_);
}

sub selectcol_arrayref {
    shift->dbh->selectcol_arrayref(@_);
}

sub selectrow_array {
    shift->dbh->selectrow_array(@_);
}

sub selectrow_arrayref {
    shift->dbh->selectrow_arrayref(@_);
}

sub selectrow_hashref {
    shift->dbh->selectrow_hashref(@_);
}

sub pragma {
    $_[0]->do("pragma $_[1] = $_[2]") if @_ > 2;
    $_[0]->selectrow_arrayref("pragma $_[1]")->[0];
}

sub iterate {
    my $class = shift;
    my $call  = pop;
    my $sth   = $class->prepare( shift );
    $sth->execute( @_ );
    while ( $_ = $sth->fetchrow_arrayref ) {
        $call->() or last;
    }
    $sth->finish;
}


1;

__END__