Documentation for ModulesPerl6::Model::Dists

mojo-app/lib/ModulesPerl6/Model/Dists.pm

@@ -82,4 +82,202 @@ sub remove {
     $self;
 }
 
-1;
+1;
+
+__END__
+
+=encoding utf8
+
+=head1 NAME
+
+ModulesPerl6::Model::Dists - model representing Perl 6 distributions
+
+=head1 SYNOPSIS
+
+    my $m = ModulesPerl6::Model::Dists->new( db_file => 'mydb.db' )->deploy;
+    $m->add( $dist );
+    say $_->{url} for $m->find({ name => 'Dist1' })->each;
+    $m->remove({ name => 'Dist1' });
+
+=head1 DESCRIPTION
+
+This module is used to access and manipulate the database of Perl 6
+distributions that is built by the build script.
+
+=head1 METHODS
+
+=head2 C<new>
+
+    my $m = ModulesPerl6::Model::Dists->new;
+
+    my $m = ModulesPerl6::Model::Dists->new( db_file => 'mydb.db' );
+
+Creates and returns a new C<ModulesPerl6::Model::Dists> object. Takes
+these arguments:
+
+=head3 C<db_file>
+
+    my $m = ModulesPerl6::Model::Dists->new( db_file => 'mydb.db' );
+
+B<Optional>. Specifies the filename of the SQLite database with dist info.
+B<Defaults to:> the value of C<MODULESPERL6_DB_FILE> environmental variable,
+if set, or C<modulesperl6.db>.
+
+=head2 C<add>
+
+    $m->add({
+        name         => 'Dist1',
+        url          => 'https://github.com/perl6/modules.perl6.org/',
+        description  => 'Test Dist1',
+        author_id    => 'Dynacoder',
+        logo         => 'dist1',
+        has_readme   => 1,
+        panda        => 2,
+        has_tests    => 1,
+        travis_status=> 'passing',
+        stars        => 42,
+        issues       => 12,
+        date_updated => 1446999664,
+        date_added   => 1446694664,
+    });
+
+    $m->add( $dist1, $dist2 );
+
+Add new dist to the database. Takes a list of hashrefs, where each hashref
+represents a dist. The keys of the hashref are as follows:
+
+=head3 C<name>
+
+Name of the dist.
+
+=head3 C<url>
+
+URL of the dist's GitHub repo.
+
+=head3 C<description>
+
+Short descripton of the dist.
+
+=head3 C<author_id>
+
+Dists's "authority".
+
+=head3 C<logo>
+
+The name of dist's logo within the sprite generated by the build script
+(this likely will be the name of the dist with C<\W+> changed to underscores).
+
+=head3 C<has_readme>
+
+Boolean: does the dist have README file?
+
+=head3 C<panda>
+
+Takes values C<0> (dist not conformant to latest specs),
+C<1> (dist conforms to specs, except for S11), or C<2> (dist fully conforms
+to current spec).
+
+=head3 C<has_tests>
+
+Boolean: does the dist have tests?
+
+=head3 C<travis_status>
+
+Takes a valid string of L<Travis-CI.org|https://travis-ci.org/> build status
+(e.g. C<passing>, C<failing>, C<unknown>, etc). Will accept any value.
+If not specified, will be set to C<not set up>.
+
+=head3 C<stars>
+
+Number of dists's "Stargazers" (people who starred the repo on GitHub).
+
+=head3 C<issues>
+
+Number of open Issues the dist has on GitHub
+
+=head3 C<date_updated>
+
+Unix epoch of when the dist was last updated (usually, date of last
+commit on GitHUb)
+
+=head3 C<date_added>
+
+Unix epoch of when the dist was added to the Perl 6 Ecosystem (this is NOT
+the same as when the repo was first created on GitHub).
+
+=head2 C<deploy>
+
+    $m->deploy
+
+B<Takes> no arguments. B<Returns> its invocant. Deploys (creates) the SQL
+tables needed for this module to operate. B<Will die> if they already exists.
+
+=head2 C<find>
+
+    my $dists = $m->find; # return all dists in the db
+    my $dists = $m->find({ name => 'Dist1'  });  # exact match
+    my $dists = $m->find({ name => \'Dist1' }); # SQL "like" match
+    my $dist  = $m->find({
+        name        => \'Dist',
+        description => \'Test Dist1',
+    })->first;
+
+Searches the database for dists that match given criteria. B<Returns>
+a, possibly empty, L<Mojo::Collection> object containing found dists
+as hashrefs. Each hashref will contain the same keys and type of values
+as were given to L</add> method, B<except> the L</has_readme>, L</has_tests>,
+and L</panda> metrics are combined into a Kwalitee metric ranging from
+C<0> to C<100>.
+
+B<Without arguments>, returns all dists in the database.
+B<Takes> a hashref specifying search criteria. If the search criteria a
+string, it will be matched exactly. If it's a scalar reference, its value
+will be matched partially and case-insensitively (i.e. something like
+C<m/.*foo.*/i>). More than one criteria can be specified. Valid criteria are:
+
+=head3 C<name>
+
+Search by the name of the distribution
+
+=head3 C<description>
+
+Search by the description of the dist
+
+=head3 C<author_id>
+
+Search by the authority of the dist
+
+=head3 C<travis_status>
+
+Search by the Travis CI status
+
+=head2 C<remove>
+
+    $m->remove({ name => 'Dist1' });
+
+B<Takes> the same argument as L</find> and any matching dists will be deleted
+from the database. B<Returns> its invocant.
+
+=head1 PRIVATE METHODS
+
+B<These methods are documented for developers working on this module.
+Do NOT use these methods outside of this package.>
+
+=head2 C<_find>
+
+    $self->_find(1, { name => 'Dist1'});
+
+Used by L</find> and L</remove> methods. Second argument is the search
+criteria hashref (if not specified, empty one will be used). The first argument
+is a boolean that specifies whether the database search result objects should
+be converted into hashrefs using L<DBIx::Class::ResultClass::HashRefInflator>
+result class.
+
+=head1 CONTACT INFORMATION
+
+Original version of this module was written by Zoffix Znet
+(L<https://github.com/zoffixznet/>, C<Zoffix> on irc.freenode.net).
+
+=head1 LICENSE
+
+You can use and distribute this module under the same terms as Perl itself.