NAME

Net::Gnats::Command - Command factory and base class.

VERSION

0.18

DESCRIPTION

Encapsulates all Gnats Daemon commands and their command processing codes.

This module implements the factory pattern for retrieving specific commands.

CONSTRUCTOR

new

Instantiates a new Net::Gnats::Command object.

 $c = Net::Gnats::Command->new;

This class is not instantiated directly; it is a superclass for all Gnats command objects.

ACCESSORS

field

Sets and retrieves a Net::Gnats::FieldInstance to the command.

field_change_reason

Sets and retrieves a Net::Gnats::FieldInstance for Change Reasons to the command.

This may be removed in the future given a FieldInstance now manages its own Change Reason.

pr

For commands that must send a serialized PR, or serialized field, after issuing a command.

error_codes

Retrieves the valid error codes for the command. Not used yet.

 my $codes = $c->error_codes;

success_codes

Retrieves the valid success codes for the command. Not used yet.

 my $codes = $c->success_codes;

response

Manages the response outcome from the server encapsulated in a Net::Gnats::Response object.

When the command has not been issued yet, the value will be undef.

 $response = $c->response;
 $code = $c->response->code;

requests_multi

A flag for knowing if multiple responses are expected. Normally used and managed internally. May become a private method later.

METHODS

as_string

Returns the currently configured command as a string.

from

This method is used for commands where 1..n fields can be defined for a given command, and the issuer needs to match up field names to values.

 $c = Net::Gnats::Command->fdsc( [ 'FieldA', 'FieldB' ];
 Net::Gnats->current_session->issue( $c );
 $value = $c->from( 'FieldA' ) unless not $c->is_ok;

EXPORTED METHODS

The following exported methods are helpers for executing all Gnats protocol commands.

admv

 my $c = Net::Gnats::Command->admv;

appn

Manages the command for appending field content to an existing PR field. The field key is a Net::Gnats::FieldInstance object.

 $c = Net::Gnats::Command->appn( pr_number => 5, field => $field );

See Net::Gnats::Command::APPN for details.

chdb

Manages the command for changing databases within the same Net::Gnats::Session instance.

 $c = Net::Gnats::Command->chdb( database => 'external' );

See Net::Gnats::Command::CHDB for details.

chek

Manages the command for checking the validity of a PR before sending.

 # New problem reports:
 $c = Net::Gnats::Command->chek( type => 'initial', pr => $pr );

 # Existing problem reports:
 $c = Net::Gnats::Command->chek( pr => $pr );

See Net::Gnats::Command::CHEK for details.

dbls

Manages the command to list server databases. This command is the only command that typically does not require credentials.

 $c = Net::Gnats::Command->dbls;

See Net::Gnats::Command::DBLS for details.

dbdesc

Manages the command for returning the description of the databases existing on the server.

 $c = Net::Gnats::Command->dbdesc;

See Net::Gnats::Command::DBDESC for details.

delete_pr

Manages the command for deleting a PR from the database. Only those with 'admin' credentials can successfully issue this command.

 $c = Net::Gnats::Command->delete_pr( pr => $pr );

See Net::Gnats::Command::DELETE for details.

edit

Manages the command for submitting an update to an existing PR to the database.

 $c = Net::Gnats::Command->edit( pr => $pr );

See Net::Gnats::Command::EDIT for details.

editaddr

Manages the command for setting the active email address for the session. This is most relevant when submitting or editing PRs.

 $address = 'joe@somewhere.com';
 $c = Net::Gnats::Command->editaddr( address => $address );

See Net::Gnats::Command::EDITADDR for details.

expr

Manages the command for setting the query expression for a PR. Query expressions AND together.

This method may change in the future.

 $c = Net::Gnats::Command->expr( expressions => ['foo="bar"', 'bar="baz"'] );

See Net::Gnats::Command::EXPR for details.

fdsc

Manages the command for retrieving the description for one or more fields.

 $c = Net::Gnats::Command->fdsc( fields => 'MyField' );
 $c = Net::Gnats::Command->fdsc( fields => [ 'Field1', 'Field2' ] );

See Net::Gnats::Command::FDSC for details.

fieldflags

Manages the command for retrieving field flags for one or more fields.

 $c = Net::Gnats::Command->fieldflags( fields => 'MyField' );
 $c = Net::Gnats::Command->fieldflags( fields => [ 'Field1', 'Field2' ] );

See Net::Gnats::Command::FIELDFLAGS for details.

ftyp

Manages the command for retrieving the data type for one or more fields.

 $c = Net::Gnats::Command->ftyp( fields => 'MyField' );
 $c = Net::Gnats::Command->ftyp( fields => [ 'Field1', 'Field2' ] );

See Net::Gnats::Command::FTYP for details.

ftypinfo

Manages the command for retrieving the type information for a field. Relevant to MultiEnum fields only.

 $c = Net::Gnats::Command->ftypinfo( field => 'MyField' );
 $c = Net::Gnats::Command->ftypinfo( field => 'MyField',
                                     property => 'separators );

See Net::Gnats::Command::FTYPINFO for details.

fvld

Manages the command for retrieving the set field validators defined in the Gnats schema.

 $c = Net::Gnats::Command->fvld( field => 'MyField' );

See Net::Gnats::Command::FVLD for details.

inputdefault

Manages the command for retrieving field default values.

 $c = Net::Gnats::Command->inputdefault( fields => 'MyField' );
 $c = Net::Gnats::Command->inputdefault( fields => [ 'Field1', 'Field2' ] );

See Net::Gnats::Command::INPUTDEFAULT for details.

list

Manages the command for different lists that can be retrieved from Gnats.

 $c = Net::Gnats::Command->list( subcommand => 'Categories' );
 $c = Net::Gnats::Command->list( subcommand => 'Submitters' );
 $c = Net::Gnats::Command->list( subcommand => 'Responsible' );
 $c = Net::Gnats::Command->list( subcommand => 'States' );
 $c = Net::Gnats::Command->list( subcommand => 'FieldNames' );
 $c = Net::Gnats::Command->list( subcommand => 'InitialInputFields' );
 $c = Net::Gnats::Command->list( subcommand => 'InitialRequiredFields' );
 $c = Net::Gnats::Command->list( subcommand => 'Databases' );

See Net::Gnats::Command::LIST for details.

lkdb

Manages the command for locking the gnats main database.

 $c = Net::Gnats::Command->lkdb;

See Net::Gnats::Command::LKDB for details.

lock_pr

Manages the command for locking a specific PR. Usually this occurs prior to updating a PR through the edit command.

 $c = Net::Gnats::Command->lock_pr( pr => $pr, user => $user );
 $c = Net::Gnats::Command->lock_pr( pr => $pr, user => $user, pid => $pid );

See Net::Gnats::Command::LOCK for details.

qfmt

Manages the command for setting the PR output format. Net::Gnats parses 'full' format only. If you choose another format, you can retrieve the response via $c->response->as_string.

 $c = Net::Gnats::Command->qfmt( format => 'full' );

See Net::Gnats::Command::QFMT for details.

quer

Manages the command for querying Gnats. It assumes the expressions have already been set. If specific numbers are set, the command will query only those PR numbers.

 $c = Net::Gnats::Command->quer;
 $c = Net::Gnats::Command->quer( pr_numbers => ['10'] );
 $c = Net::Gnats::Command->quer( pr_numbers => ['10', '12'] );

See Net::Gnats::Command::QUER for details.

quit

Manages the command for disconnecting the current Gnats session.

 $c = Net::Gnats::Command->quit;

See Net::Gnats::Command::QUIT for details.

repl

Manages the command for replacing field contents.

 $c = Net::Gnats::Command->appn( pr_number => 5, field => $field );

See Net::Gnats::Command::REPL for details.

rset

Manages the command for resetting the index and any query expressions on the server.

 $c = Net::Gnats::Command->rset;

See Net::Gnats::Command::RSET for details.

subm

Manages the command for submitting a new PR to Gnats. If the named PR already has a 'Number', a new PR with the same field contents will be created.

 $c = Net::Gnats::Command->subm( pr => $pr );

See Net::Gnats::Command::SUBM for details.

undb

Manages the command for unlocking the Gnats main database.

 $c = Net::Gnats::Command->undb;

See Net::Gnats::Command::UNDB for details.

unlk

Manages the command for unlocking a specific PR.

 $c = Net::Gnats::Command->unlk( pr_number => $pr->get_field('Number')->value );

See Net::Gnats::Command::UNLK for details.

user

Manages the command for setting the security context for the session.

 $c = Net::Gnats::Command->user( username => $username, password => $password );

See Net::Gnats::Command::USER for details.

vfld

Manages the command for validating a specific field. The field is a Net::Gnats::FieldInstance object.

 $c = Net::Gnats::Command->vfld( field => $field );
 $c = Net::Gnats::Command->vfld( field => $pr->get_field('Synopsis');

See Net::Gnats::Command::VFLD for details.