%META:TOPICINFO{author="NiallMurray" date="1132133598" format="1.0" version="1.3"}%
%META:TOPICPARENT{name="TWikiPlugins"}%
---+ %TOPIC%

This plugin allows you to directly query the GNATS bug report database. Based on the similar BugzillaQueryPlugin.

%TOC%

------

---++ Syntax Rules
There are two syntax variations currently supported:

	* Retrieve the data for a single BR and display using the default FORMAT setting
		* Syntax: ==%<nop>BRQ{"652"}%==
		| *Parameter* | *Description* | *Default* |
		| "123" | A valid GNATS bug report number | |

	* Retrieve the data for one or more BRs matching the query expression
		* Syntax: ==%<nop>BRQ{expr="(Number>'650')" format="'| %s | %s |' Number Synopsis"}%==
		| *Parameter* | *Description* | *Default* |
		| expr | A valid GNATS query expression. See below | |		
		| format | A valid GNATS format. See below | |

---+++ Syntax and variables in 'expr' attribute

Query expressions are used to select specific BRs based on their field contents. The general form is
<verbatim>
  fieldname|'value' operator fieldname|'value' [booleanop ...] 
</verbatim>

| *value* | Is a literal string or regular expression; it must be surrounded by ==single quotes==, otherwise it is interpreted as a *fieldname*. ||
| *fieldname* | Is the name of a field in the BR, e.g. Number, Synopsis, Category, etc. ||
|*operator*| *=* | The value of the left-hand side of the expression must exactly match the regular expression on the right-hand side of the expression. |
|^| *~* | Some portion of the left-hand side of the expression must match the regular expression on the right-hand side. |
|^| *==* | The value of the left-hand side must be equal to the value on the right-hand side of the expression. The equality of two values depends on what type of data is stored in the field(s) being queried. For example, when querying a field containing integer values, literal strings are interpreted as integers. The query expression <b>Number *==* "0123"</b> is identical to <b>Number *==* "123"</b> as the leading zero is ignored. If the values were treated as strings instead of integers, then the two comparisons would return different results. |
|^| *!=* | The not-equal operator. Produces the opposite result of the == operator. |
|^| *<,>* | The left-hand side must have a value less than or greater than the right-hand side. Comparisons are done depending on the type of data being queried; in particular, integer fields and dates use a numeric comparison, and enumerated fields are ordered depending on the numeric equivalent of their enumerated values. |
| *booleanop* | Is either <verbatim>&brvbar; [OR], or &amp; [AND]. </verbatim>||

---++++ Query expression examples 

	* The query expression *Category='baz' | Responsible='blee'* selects all BRs with a =Category= field of =baz= or a =Responsible= field of =blee=. The not operator *!* may be used to negate a test: *! Category='foo'* searches for BRs where the =Category= is *not equal* to the regular expression =foo=.

	* Parenthesis may be used to force a particular interpretation of the expression: *!(Category='foo' & Submitter-Id='blaz')* skips BRs where the =Category= field is equal to =foo= and the =Submitter-Id= field is equal to =blaz=. Parenthesis _may be nested_ to any arbitrary depth.

	* Fieldnames can be specified in several ways. The simplest and most obvious is just a name: *Category='foo'* checks the value of the =Category= field for the value =foo=. A fieldname qualifier may be prepended to the name of the field; a colon is used to separate the qualifier from the name. To refer directly to a builtin field name: *builtin:Number='123'*. In this case, =Number= is interpreted as the builtin name of the field to check. (This is useful if the fields have been renamed).

	* To scan all fields of a particular type, the *fieldtype* qualifier may be used: *fieldtype:Text='bar'* searches all text fields for the regular expression =bar=. Note that it is not necessary that the right-hand side of the expression be a literal string. 

	* To query all BRs where the BR has been modified since it was closed, the expression *Last-Modified != Closed-Date* will work; for each BR, it compares the value of its =Last-Modified= field against its =Closed-Date= field, and returns those PRs where the values differ. However, this query will also return all BRs with empty =Last-Modified= or =Closed-Date= fields. To further narrow the search: *Last-Modified != Closed-Date & Last-Modified != '' & Closed-Date != ''*

	* In general, comparing fields of two different types (an integer field against a date field, for example) will probably not do what you want.

	* Also, a field specifier may be followed by the name of a subfield in braces: *State[type] != 'closed'* or even *builtin:State[type] != 'closed'*

---+++ Syntax and variables in 'format' attribute

Printing formats for PRs are in one of three forms:

| *formatname* | standard | Most fields from the BR are displayed on a number of lines |
|^| full | *All* fields from the BR are displayed on a number of lines|
|^| summary | A subset of fields from the BR are shown on a single line |
| *fieldname* | A single field name may appear here. Only the contents of this field will be displayed. ||
| *'printf string' fieldname fieldname . . .* | This provides a rather flexible mechanism for formatting PR output. (The formatting is identical to that provided by the named formats described by the database configuration.) The printf string can contain the following % sequences: ||
|^| *%[positionalspecifiers]s* | Prints the field as a string. The positional specifiers are similar to those of printf, as +, - and digit qualifiers can be used to force a particular alignment of the field contents. |
|^| *%[positionalspecifiers]S* | Similar to %s, except that the field contents are terminated at the first space character. |
|^| *%[positionalspecifiers]d* | Similar to %s, except that the field contents are written as a numeric value. For integer fields, the value is written as a number. For enumerated fields, the field is converted into a numeric equivalent (i.e. if the field can have two possible values, the result will be either 1 or 2). For date fields, the value is written as seconds since Jan 1, 1970. |
|^| *%F* | The field is written as it would appear within a PR, complete with field header. |
|^| *%D* | For date fields, the date is written in a standard GNATS format. |
|^| *%Q* | For date fields, the date is written in an arbitrary "SQL" format. |

---++ Examples
	* ==%<nop>BRQ{"652"}%==
-------------------------
%BRQ{"652"}%
-------------------------
	* ==%<nop>BRQ{expr="(Number='352')" format="full"}%==
-------------------------
%BRQ{expr="(Number='352')" format="full"}%
-------------------------
	* ==%<nop>BRQ{expr="(Number='352')" format="standard"}%==
-------------------------
%BRQ{expr="(Number='352')" format="standard"}%
-------------------------
	* ==%<nop>BRQ{expr="(Number='350')" format="Description"}%==
-------------------------
%BRQ{expr="(Number='350')" format="Description"}%
-------------------------
	* ==%<nop>BRQ{expr="(Number='555')" format="summary"}%==
-------------------------
%BRQ{expr="(Number='555')" format="summary"}%
-------------------------
	* ==%<nop>BRQ{expr="(Number>'650')" format="'| BR#%s | %s |' Number Synopsis"}%==
-------------------------
| *Number* | *Synopsis* |
%BRQ{expr="(Number>'650')" format="'| BR#%s | %s |' Number Synopsis"}%
-------------------------

---++ <nop>%TOPIC% Settings
<blockquote style="background-color:#f5f5f5">
	* Set URL = https://tangier/twiki/bin/view/GNATSQueryPlugin
	* Set FORMAT = full
	* Set SHORTDESCRIPTION = This plugin is useful to display query results from GNATS.
	* Set GNATS_DB_HOST = printer-24
	* Set GNATS_DB_PORT = 1529
	* Set GNATS_DB_NAME = Development-DB
	* Set DEBUG = 0
</blockquote>

---++ Plugin Installation Instructions
	* Install the GNATS *query-pr* tool on the TWiki server
	* Extract <nop>GNATSQueryPlugin.zip in TWiki root 
	* Edit the GNATSQueryPlugin to your needs changing the path to *query-pr*

---++ Files
	* ==lib/TWiki/Plugins/GNATSQueryPlugin.pm==
	* ==data/TWiki/GNATSQueryPlugin.txt==

---++ Plugin Info
|  Plugin Author: | Main.NiallMurray |
|  Plugin Version: | 1.00 |
|  Change History: | 15 Nov 2005: First version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | GNATS query-pr tool |
|  Perl Version: | 5.0 |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins


-- Main.NiallMurray - 15 Nov 2005

