From 23183b1989f7a63b9033810433ad8ec97c3f7ab9 Mon Sep 17 00:00:00 2001 From: Marius Gavrilescu Date: Thu, 18 Jun 2015 21:15:45 +0300 Subject: [PATCH] Write documentation for Gruntmaster::Data functions --- lib/Gruntmaster/Data.pm | 168 ++++++++++++++++++---------------------- 1 file changed, 76 insertions(+), 92 deletions(-) diff --git a/lib/Gruntmaster/Data.pm b/lib/Gruntmaster/Data.pm index 8c2fb17..3b634ca 100644 --- a/lib/Gruntmaster/Data.pm +++ b/lib/Gruntmaster/Data.pm @@ -289,167 +289,151 @@ Gruntmaster::Data - Gruntmaster 6000 Online Judge -- database interface and tool =head1 SYNOPSIS - my $db = Gruntmaster::Data->connect('dbi:Pg:'); - - my $problem = $db->problem('my_problem'); - $problem->update({timeout => 2.5}); # Set time limit to 2.5 seconds - $problem->rerun; # And rerun all jobs for this problem - - # ... - - my $contest = $db->contests->create({ # Create a new contest - id => 'my_contest', - name => 'My Awesome Contest', - start => time + 100, - end => time + 1900, - }); - $db->contest_problems->create({ # Add a problem to the contest - contest => 'my_contest', - problem => 'my_problem', - }); - - say 'The contest has not started yet' if $contest->is_pending; - - # ... - - my @jobs = $db->jobs->search({contest => 'my_contest', owner => 'MGV'})->all; - $_->rerun for @jobs; # Rerun all jobs sent by MGV in my_contest =head1 DESCRIPTION -Gruntmaster::Data is the interface to the Gruntmaster 6000 database. Read the L documentation for usage information. +Gruntmaster::Data is the interface to the Gruntmaster 6000 database. -In addition to the typical DBIx::Class::Schema methods, this module contains several convenience methods: +All functions are exported by default. =over -=item contests +=item B(I<@args>) -Equivalent to C<< $schema->resultset('Contest') >> +This function connects to the database. I<@args> are the arguments +passed to the L constructor. -=item contest_problems +=item B(I<$url_path>) -Equivalent to C<< $schema->resultset('ContestProblem') >> +Purges a relative URL from the Varnish Cache by sending PURGE +$url_path requests to all hosts in the PURGE_HOSTS environment +variable. -=item jobs +=item B -Equivalent to C<< $schema->resultset('Job') >> +Returns a L object for interacting with the database +directly. Use this when no other function in this module is suitable. -=item problems +=item B -Equivalent to C<< $schema->resultset('Problem') >> +Returns an arrayref of the top 200 users. -=item users +=item B(I<$id>) -Equivalent to C<< $schema->resultset('User') >> +Returns a hashref describing the user I<$id>. -=item contest($id) +=item B([I<%args>]) -Equivalent to C<< $schema->resultset('Contest')->find($id) >> +Returns an arrayref of problems. -=item job($id) +Takes the following named arguments: -Equivalent to C<< $schema->resultset('Job')->find($id) >> - -=item problem($id) +=over -Equivalent to C<< $schema->resultset('Problem')->find($id) >> +=item owner -=item user($id) +Only show problems owned by this user -Equivalent to C<< $schema->resultset('User')->find($id) >> +=item contest -=item user_list +Only show problems in this contest -Returns a list of users as an arrayref containing hashrefs. +=item private -=item user_entry($id) +If true, include private problems. Always true if contest is present. -Returns a hashref with information about the user $id. +=item solution -=item problem_list([%args]) +If true, include problem solutions -Returns a list of problems grouped by level. A hashref with levels as keys. +=back -Takes the following arguments: +=item B(i<$id>, [I<$contest>]) -=over +Returns a hashref describing the problem I<$id>. If $contest is +present, contest start and stop times are included, and the solution +is deleted. -=item owner +=item B -Only show problems owned by this user +Returns an arrayref of contests. -=item contest +=item B(I<$id>) -Only show problems in this contest +Returns a hashref describing the contest I<$id>. -=back +=item B(I<$contest>, I<$problem>) -=item problem_entry($id, [$contest, $user]) +Returns true if the contest I<$contest> includes the problem +I<$problem>, false otherwise. -Returns a hashref with information about the problem $id. If $contest and $user are present, problem open data is updated. +=item B([I<%args>]) -=item contest_list([%args]) +In scalar context, returns an arrayref of jobs. In list context, +returns an arrayref of jobs and a hashref of information about pages. -Returns a list of contests grouped by state. A hashref with the following keys: +Takes the following named arguments: =over -=item pending - -An arrayref of hashrefs representing pending contests +=item page -=item running +Show this page of the job log. Defaults to 1. -An arrayref of hashrefs representing running contests +=item owner -=item finished +Only show jobs submitted by this user. -An arrayref of hashrefs representing finished contests +=item contest -=back +Only show jobs submitted in this contest. -Takes the following arguments: +=item problem -=over +Only show jobs submitted for this problem. -=item owner +=item result -Only show contests owned by this user. +Only show jobs with this result (see the constants in +L). -=back +=item private -=item contest_entry($id) +If true, include private jobs. Defaults to false. -Returns a hashref with information about the contest $id. +=back -=item job_list([%args]) +=item B(I<$id>) -Returns a list of jobs as an arrayref containing hashrefs. Takes the following arguments: +Returns a hashref describing the job I<$id>. -=over +=item B(I<%args>) -=item owner +Insert a new job into the database. This function also updates the +lastjob field for the job's owner. -Only show jobs submitted by this user. +=item B(I<$ct>) -=item contest +Returns an arrayref of the standings of contest I<$ct>. -Only show jobs submitted in this contest. +=item B -=item problem +Rebuilds the problem_status and contest_status tables. -Only show jobs submitted for this problem. +=item B(I<$id>) -=item page +Marks the job $id as pending and clears its results, so that it will +be run again by the daemon. -Show this page of results. Defaults to 1. Pages have 10 entries, and the first page has the most recent jobs. +=item B(I<$daemon>) -=back +Marks a random job as being run by I<$daemon>. Returns a hashref +describing the job, or undef if no job was available. -=item job_entry($id) +=item B(I<$job>, I<$private>, I<%results>) -Returns a hashref with information about the job $id. +Updates the job $job with the results in %results. If $private is +false, also updates the problem_status table. =back -- 2.30.2