2.4.2 Formatting query-pr output

Printing formats for PRs are in one of three forms:

formatname

This is a named format which is described by the database (specifically, these formats are described in the dbconfig file associated with the database). The default configuration contains five such formats: standard, full, summary, sql, and sql2.

The first three are the ones most commonly used when performing queries. standard is the format used by default if no other format is specified.

Use of the latter two are discouraged; they are merely kept for historical purposes. Other named formats may have been added by the database administrator.

fieldname

A single field name may appear here. Only the contents of this field will be displayed.

'"printf string" fieldname fieldname ...'

This provides a very flexible mechanism for formatting PR output. (The formatting is identical to that provided by the named formats described by the database configuration, See Named query definitions. 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.

An example formatted query looks as follows (note that the whole format specification should be quoted):

     query-pr --format '"%s, %s" Synopsis State'