The Gwyple Format Menu

0. Special notice

This page describes the new format dialog starting from GWYPLE-1.1.0. The documentation for the old mechanism until GWYPLE-1.0.0 is not included in the Gwyple documentation any more. It can still be found in old source distributions (until and including GWYPLE-2.0.0).

1. Intro

The Format menu is brand-new in gwyple and very flexible. It needs some minor Perl knowledge to use, but we think it is sufficiently well documented even for users who don't know Perl

2. Basic Outline

The format roughly consists of three sections:

The name of the environment (here: default)
A perl code section
Three buttons: Apply, Save, Load

3. The Global section of the perl code

# Environment for Gwyple - Global section (must contain valid perl code!)
$filter = '';
$full_filter = '';
$sortorder = '0';
$format_variables = 'title';
$format_design = '@<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<';
$export_file = '';

a) $filter and $full_filter

The filter line can be used to filter out listbox lines that match a specific pattern:

$filter = 'secret';

This will display only listbox lines with the text "secret". Perl Regex syntax applies here.

If the filter text consists of lower case letters only, it will also match if the listbox line contains uppercase letters. The other way around, if the filter cointains uppercase letters, it will only match lines exactly.

$full_filter works similar to $filter, only that it filters based on the full text of available bug reports:

$full_filter = 'ik+entobi';

This will match bug reports which match ikentobi or ikkentobi or ikkkentobi (...) in their fulltext.

b) $sortorder

Here you can define the sort order of the list box:

$sortorder = '3,0';

This is a comma-separated list of field numbers. Field 0 is the name of the MR (column zero of the listbox).

This definition honours a special field number called 't'. Using this field will sort entries according to the "last modification date/time" according to the underlying file object. Newest entries will appear on top of older entries. Use this if you have a high throughput of MRs and you want to have an eye on the newest changes.

All fields can be prepended with a minus (-) sign:

$sortorder = '-3,1,-t';

In this case the sort order is reverse.

c) $format_variables and $format_design

This defines how the listbox looks:

$format_variables = 'severity package title';
$format_design = '@<<<< @<<<<<< @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<';

$format_variables lists bug attributes (a subset of all available attributes for the specific backend) and $format_design defines how much place is available for each field. The number of fields in $format_design has to match the number of fields selected in $format_variables.

The pattern definition will be familiar for perl coders, other users are advised to stick to the examples.

d) The Export destination

$export_file = 'buglist.txt';

This works together with the "export" action in the Move/Delete/Export menu. Above you see the easiest type of usage which writes to the specified file.

It is also possible to write helper applications and use them like this:

$export_file = '|helper.pl';

Note the pipe symbol in the export definition.
More pipes and output redirection are also possible:

$export_file = '| grep secret | helper.pl';

How this works on non-Unix system has not been explored yet.

4. The Backend-specific Perl section

Each loaded backend has its own section of perl code. For the DDTS backend this looks like this:

# Environment for module DDTS
$DDTS::url_fixedpart = "http://some.url.com/ddts_main?bug_id=";
$DDTS::fetch = "lynx -dump -width=132";
# Attributes:
# address area engineer fullstate label mr project severity state submitter swr title tool

This defines in two variables

At which URL to fetch bug reports
What fetch method to use (here it is "lynx -dump")

The last line lists available attributes for the specific backend.
These can be used in the format definition - see section 3c) above.

5. The Environment name and the buttons

Some variables (called the environment) can be stored in a file, for example in "filename.gwy".

With the <save> button you may save such an environment file in the current directory, with the <load> button an environment can be loaded from the corresponding file (and becomes active).

Gwyple tries to load the current environment when performing a directory change. This means if a *.gwy file is present in the target directory that corresponds to the current environment, this will be loaded.

"default" is the name of the default environment.

The <ok> button dismisses the format menu window and re-sorts (and re-filters) the listbox.

Last modified: Thu May 1 10:39:35 MEST 2003