bugs1Add my vote for this tag database1Add my vote for this tag create new tag
, view all tags

GNATS Query Plugin

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

Syntax Rules

There are two syntax variations currently supported:

  • Retrieve the data for a single BR and display using the default FORMAT setting

  • Retrieve the data for one or more BRs matching the query expression
    • Syntax: %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

  fieldname|'value' operator fieldname|'value' [booleanop ...] 

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 Number == "0123" is identical to Number == "123" 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
&brvbar; [OR], or &amp; [AND]. 

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 BRs 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 BRs 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 BR 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 BR, 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.


  • %BRQ{"652"}%

  • %BRQ{expr="(Number='352')" format="full"}%

%BRQ{expr="(Number='352')" format="full"}%
  • %BRQ{expr="(Number='352')" format="standard"}%

%BRQ{expr="(Number='352')" format="standard"}%
  • %BRQ{expr="(Number='350')" format="Description"}%

%BRQ{expr="(Number='350')" format="Description"}%
  • %BRQ{expr="(Number='555')" format="summary"}%

%BRQ{expr="(Number='555')" format="summary"}%
  • %BRQ{expr="(Number>'650')" format="'| BR#%s | %s |' Number Synopsis"}%

Number Synopsis
%BRQ{expr="(Number>'650')" format="'| BR#%s | %s |' Number Synopsis"}%

Plugin Settings

  • Set URL = http://twiki.org/cgi-bin/view/GNATSQueryPlugin
  • Set FORMAT = full
  • Set SHORTDESCRIPTION = Display query results from the GNATS bug report database
  • Set GNATS_DB_HOST = gnats
  • Set GNATS_DB_PORT = 1529
  • Set GNATS_DB_NAME = bugs
  • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
  • Install the GNATS query-pr tool on the TWiki server
  • Download the ZIP file from the Plugin web (see below)
  • Unzip GNATSQueryPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/GNATSQueryPlugin.txt Plugin topic
    data/TWiki/GNATSQueryPlugin.txt,v Plugin topic repository
    lib/TWiki/Plugins/GNATSQueryPlugin.pm Plugin Perl module
  • Edit the GNATSQueryPlugin to your needs changing the path to query-pr


The plugin assumes that it is querying GNATS on a remote host, and calls query-pr with the -H and --port options to specify host and port to which to connect. This doesn't work if the GNATS database is local, and gnatsd is not running,

I (RobertInder) got around this by editing GNATSQueryPlugin.pm and replacing line 296...

  $result = `$queryBin -H $dbHost --port $dbPort --database $dbName --expr \'$expr\' --format \'$format\' 2>&1`;
...with the following:
  if ($dbHost eq 'localhost') {
     $result = `$queryBin --database $dbName --expr \'$expr\' --format \'$format\' 2>&1`;
  } else {
     $result = `$queryBin -H $dbHost --port $dbPort --database $dbName --expr \'$expr\' --format \'$format\' 2>&1`;
  return $result;

then setting GNATS_DB_HOST to "localhost".

Plugin Info

Plugin Author: TWiki:Main.NiallMurray
Plugin Version: 16 Nov 2005 (V1.000)
Change History:  
16 Nov 2005: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.1
CPAN Dependencies: none
Other Dependencies: GNATS query-pr tool
Perl Version: 5.005
License: GPL (GNU General Public License)
Benchmarks: GoodStyle 99%, FormattedSearch 99%, GNATSQueryPlugin 83%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/GNATSQueryPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/GNATSQueryPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/GNATSQueryPluginAppraisal

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main.NiallMurray - 16 Nov 2005

Topic attachments
I Attachment History Action Size Date Who Comment
Compressed Zip archivezip GNATSQueryPlugin.zip r1 manage 6.3 K 2005-11-16 - 11:20 NiallMurray  
Edit | Attach | Watch | Print version | History: r6 < r5 < r4 < r3 < r2 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r6 - 2006-01-17 - RobertInder
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.