Net::Gnats - Perl interface to GNU Gnats daemon
0.22
Net::Gnats provides a perl interface to the gnatsd command set. Although most of the gnatsd command are present and can be explicitly called through Net::Gnats, common gnats tasks can be accompished through some methods which simplify the process (especially querying the database, editing bugs, etc).
use Net::Gnats; # Instantiates object with Gnats hostname 'localhost' and port '1529'. my $g = Net::Gnats->new; # Creates the session between Net::Gnats and the gnatsd process. say 'Connected.' if $g->gnatsd_connect; # Retrieves the list of databases hosted by the server. Typically, # it's the only command that can be performed without logging in. my $db_names = $g->get_dbnames; $g->login("default","somedeveloper","password"); # Change field values in Gnats immediately by using the replaceField # method. my $pr = $g->get_pr_by_number(2); $pr->replaceField('Synopsis', 'The New Synopsis String'); $pr->replaceField('Responsible', 'joe', q|Because It's Joe's|); # Change field values and submit the PR for update. This is the # preferred method if many fields require updating. my $pr = $g->get_pr_by_number(3); $pr->setField('Synopsis', 'The New Synopsis String'); $pr->setField('Responsible', 'joe', q|Because It's Joe's|); $g->update_pr($pr); my $new_pr = $g->new_pr(); $new_pr->setField("Submitter-Id","developer"); $g->submitPR($new_pr); # Close the session. The session will close abruptly if the program # simply exits. $g->disconnect;
Fetching database names is the only action that can be done on a Gnats object before logging in via the login() method.
my $g = Net::Gnats->new; $g->gnatsd_connect; my @dbNames = $g->getDBNames;
Note that getDBNames() is different than listDatabases(), which requires logging in first and gets a little more info than just names.
The Gnats object has to be logged into a database to perform almost all actions.
my $g = Net::Gnats->new; $g->gnatsd_connect; $g->login("default","myusername","mypassword");
The Net::Gnats::PR object acts as a container object to store information about a PR (new or otherwise). A new PR is submitted to gnatsperl by constructing a PR object.
my $pr = $g->new_pr; $pr->setField("Submitter-Id","developer"); $pr->setField("Originator","Doctor Wifflechumps"); $pr->setField("Organization","GNU"); $pr->setField("Synopsis","Some bug from perlgnats"); $pr->setField("Confidential","no"); $pr->setField("Severity","serious"); $pr->setField("Priority","low"); $pr->setField("Category","gnatsperl"); $pr->setField("Class","sw-bug"); $pr->setField("Description","Something terrible happened"); $pr->setField("How-To-Repeat","Like this. Like this."); $pr->setField("Fix","Who knows"); $g->submit_pr($pr);
Obviously, fields are dependent on a specific gnats installation, since Gnats administrators can rename fields and add constraints. There are some methods in Net::Gnats to discover field names and constraints, all described below.
Instead of setting each field of the PR individually, the setFromString() method is available. The string that is passed to it must be formatted in the way Gnats handles the PRs. This is useful when handling a Gnats email submission ($pr->setFromString($email)) or when reading a PR file directly from the database. See Net::Gnats::PR for more details.
my $prNums = $g->query('Number>"12"', "Category=\"$thisCat\""); print "Found " . join(":", @$prNums ) . " matching PRs \n";
Pass a list of query expressions to query(). A list of PR numbers of matching PRs is returned. You can then pull out each PR as described next.
my $prnum = 23; my $PR = $g->get_pr_by_number($prnum); print $PR->getField('synopsis'); print $PR->asString();
The method get_pr_by_number() will return a Net::Gnats::PR object corresponding to the PR num that was passed to it. The getField() and asString() methods are documented in Net::Gnats::PR, but I will note here that asString() returns a string in the proper Gnats format, and can therefore be submitted directly to Gnats via email or saved to the db directory for instance. Also:
$pr->setFromString($oldPR->asString() ); works fine and will result in a duplicate of the original PR object.
There are 2 methods of modifying fields in a Net::Gnats::PR object.
The first is to use the replaceField() or appendField() methods which uses the gnatsd REPL and APPN commands. This means that the changes to the database happen immediatly.
my $prnum = 23; my $PR = $g->get_pr_by_number($prnum); if (! $PR->replaceField('Synopsis','New Synopsis')) { warn "Error replacing field (" . $g->get_error_message . ")\n"; }
If the field requires a change reason, it must be supplied as the 3rd argument.
$PR->replaceField('Responsible','joe',"It's joe's problem");
The second is to use the setField() and updatePR() methods which uses the gnatsd EDIT command. This should be used when multiple fields of the same PR are being changed, since the datbase changes occur at the same time.
my $prnum = 23; my $PR = $g->get_pr_by_number($prnum); $PR->setField('Synopsis','New Synopsis'); $PR->setField('Responsible','joe',"It's joe's problem"); if (! $g->updatePR($PR) ) { warn "Error updating $prNum: " . $g->get_error_message . "\n"; }
Constructor, optionally taking one or two arguments of hostname and port of the target gnats server. If not supplied, the hostname defaults to localhost and the port to 1529.
Exported function.
Retrieves the currently used session (last initialized).
If you are using a custom gnats daemon, your version number might "not be supported". If you are sure you know what you are doing and am willing to take the consequences:
my $g = Net::Gnats->new(); $g->skip_version_check(1);
Retrieve the session currently in effect. Used for Net::Gnats instantiated objects only.
my $session = $g->session;
Sets verbose on. By default, verbose is off. The default setting is optimized for headless execution.
To turn verbose on, change to 1.
Sets the verbose level. The levels are:
0: No level (based on verbose being on) 1: Brief error, displays Gnats error codes. 2: Detailed error, displays Gnats error codes and any messages. 3: Trace, full code path walking.
Connects to the gnats server. No arguments. Returns true if successfully connected, false otherwise.
Issues the QUIT command to the Gnats server, thereby closing the connection.
Although the Gnats documentation says there is not a failure case for this command, it responds true/false accordingly.
$g->disconnect;
Issues the DBLS command, and returns a list of database names in the gnats server. Unlike listDatabases, one does not need to use the logn method before using this method.
my $list = $g->get_dbnames;
Issues the LIST DATABASES command, and returns a list of hashrefs with keys 'name', 'desc', and 'path'.
Issues the LIST CATEGORIES command, and returns a list of hashrefs with keys 'name', 'desc', 'contact', and '?'.
Issues the LIST SUBMITTERS command, and returns a list of hashrefs with keys 'name', 'desc', 'contract', '?', and 'responsible'.
my $s = $gnats->list_submitters;
Issues the LIST RESPONSIBLE command, and returns a list of hashrefs with keys 'name', 'realname', and 'email'.
Issues the LIST STATES command, and returns a list of hashrefs with keys 'name', 'type', and 'desc'.
Issues the LIST FIELDNAMES command, and returns a list of hashrefs with key 'name'.
Protocol: returns an anonymous array of field names.
Issues the LIST INITIALINPUTFIELDS command, and returns a list of hashrefs with key 'name'.
Expects a single fieldname or an anonymous array of field types.
Returns 0 if the type information could not be retrieved.
Returns a list of types based on the number of fields passed.
Expects a fieldname and property as arguments, and issues the FTYPINFO command. Returns text response or undef if error.
Expects a fieldname as sole argument, and issues the FDSC command. Returns text response or undef if error.
Expects a fieldname as sole argument, and issues the FIELDFLAGS command. Returns text response or undef if error.
Expects a fieldname as sole argument, and issues the FVLD command. Returns text response or undef if error.
Expects a Net::Gnats::FieldInstance object, and issues the VFLD command. Returns true if propose value is acceptable, false otherwise.
$g->validate_field(Net::Gnats::FieldInstance->new(name => 'Originator', value => 'rich'));
Expects a fieldname as sole argument, and issues the INPUTDEFAULT command. Returns text response or undef if error.
Issues the RSET command, returns true if successful, false otherwise.
Issues the LKDB command, returns true if successful, false otherwise.
Issues the UNDB command, returns true if successful, false otherwise.
Expects a PR number and user name as arguments, and issues the LOCK command. Returns true if PR is successfully locked, false otherwise.
NEW: Note that the response content has the PR. If you would like the PR from this response:
my $s = $gnats->session; $s->issue(Net::Gnats::Command->lock_pr( ... ))->response->as_list;
Expects a PR number a sole argument, and issues the UNLK command. Returns true if PR is successfully unlocked, false otherwise.
Expects a PR number a sole argument, and issues the DELETE command. Returns true if PR is successfully deleted, false otherwise.
Expects the text representation of a PR (see COMMON TASKS above) as input and issues the CHEK initial command. Returns true if the given PR is a valid entry, false otherwise.
Expects an email address as sole argument, and issues the EDITADDR command. Returns true if email successfully set, false otherwise.
Expects a PR number, a fieldname, a replacement value, and optionally a changeReason value as arguments, and issues the REPL command. Returns true if field successfully replaced, false otherwise.
If the field has requireChangeReason attribute, then the changeReason must be passed in, otherwise the routine will return false.
replaceField changes happen immediatly in the database. To change multiple fields in the same PR it is more efficiant to use updatePR.
Expects a PR number, a fieldname, and a append value as arguments, and issues the APPN command. Returns true if field successfully appended to, false otherwise.
Expect a Gnats::PR object as sole argument, and issues the SUMB command. Returns true if PR successfully submitted, false otherwise.
DEPRECATION NOTICE: This method will be deprecated soon. Please be aware that you can submit a PR from a PR object.
$pr = $pr->submit;
And $pr will contain the new PR number. See PR.pm for details.
Expect a Gnats::PR object as sole argument, and issues the EDIT command. Returns true if PR successfully submitted, false otherwise.
Use this instead of replace_field if more than one field has changed.
returns undef if the session is not initialized.
Expects a number as sole argument. Returns a Gnats::PR object.
Expects one or more query expressions as argument(s). Returns an anonymous array of PR numbers.
If there is an error, then it will return an empty set.
Expects a database name, user name, and password as arguments and issues the CHDB command. Returns true if successfully logged in, false otherwise.
my $g = Net::Gnats->new; $g->login('mydb', 'joe', 'joepass');
Returns the current access mode of the gnats database. Either "edit", "view", or undef;
Most methods will return undef if a major error is encountered.
The most recent error codes and messages which Net::Gnats encounters while communcating with gnatsd are stored, and can be accessed with the get_error_code() and get_error_message() methods.
This library is not compatible with the Gnats protocol prior to GNATS 4.
Bug reports are very welcome. Please submit to the project page (noted below).
No externalized configuration or environment at this time.
No runtime dependencies other than the Perl core at this time.
Current Maintainer: Richard Elberger riche@cpan.org
Original Author: Mike Hoolehan, <lt>mike@sycamore.us<gt>
Contributions By: Jim Searle, <lt>jims2@cox.net<gt> Project hosted at sourceforge, at http://gnatsperl.sourceforge.net
Copyright (c) 2014, Richard Elberger. All Rights Reserved.
Copyright (c) 1997-2003, Mike Hoolehan. All Rights Reserved.
This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself.
To install Net::Gnats, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Gnats
CPAN shell
perl -MCPAN -e shell install Net::Gnats
For more information on module installation, please visit the detailed CPAN module installation guide.