A. Understanding Class Interfaces

A.1. Overview

General Syntax

The general syntax for declaring and/or formatting a table of objects in the class is shown first. By convention, the filter is shown using the block and endblock macros, although filters can also be used with other macros, including include and execute.

Object Attributes

The attributes supported for each class are listed in a table with the following columns:

Field - the field name
Category - key, mandatory or optional
Rule - the pattern, if any, used to validate the value.

A.2. Parameters

Overview

All class filters support the set of parameters listed below.

Name	Type	Description
data	boolean	define objects but do not display them
cited	boolean	number these objects as the cited ones (for [1] style references)
root	string	string to prepend to Jump attribute, if any
columns	string	comma-separated list of attributes to display in table
style	string	table style to use (the default is plain)
compact	boolean	display in a compact table, (make cellpadding and cellspacing both equal to zero)
wide	boolean	use sidehead when formatting on paper
headings	boolean	display the column headings
where	string	filter the rows using the nominated expression
sort	string	comma-separated list of columns to sort by
colaligns	string	a comma-separated list of horizontal alignments values (Left, Center, Right) for columns; alternatively, a single word containing the letters L, C and R can be used for the value
colvaligns	string	a comma-separated list of vertical alignments values (Top, Middle, Bottom, Baseline) for columns; alternatively, a single word containing the letters T, M, B and L can be used for the value
select	string	a comma-separated list of columns to display
delete	string	a comma-separated list of columns to delete
wrap	integer	number of logical rows to place on a physical row

A.3. Building the Columns

Using the columns Parameter

The columns parameter is a comma-separated list of:

   [tag":"]attribute["&"view]

where:

tag is a phrase style (or expression format)
attribute is the name of an attribute of the class
view is a view to apply to the object when looking up or calculating that attribute (see Object Views below).

To remember the syntax for applying an object view, think of C's bit-masking operator, &.

Examples are given below:

Column	Description
Code	output the Code attribute
2:Code	output the Code using the 2 (emphasised) phrase style
BUG:Code	output the Code using the BUG phrase style
CONCISE:Date	output the Date attribute using the CONCISE format

Calculated Attributes

Some class filters support calculated attributes, so the total set of attributes you can place in the columns parameter can be quite large. For example, for references, an unknown attribute which is sequence of uppercase letters is assumed to be a file extension and the generated attribute is an icon providing a jump to that file, if any. For example, if a reference has a Jump attribute of xyz.html, then the PDF attribute is an image (pdf.gif) which provides a jump to xyz.pdf.

Object Views

On some occasions, it can be very useful if the value placed in a column is a variation of an attribute, rather than the attribute itself. For example, the references class supports an attribute called PS which is an image (postscript.gif) with a jump to xyz.ps (assuming the Jump attribute is xyz.html). But what if the PostScript file is in a different place to the HTML file? In this case, you need to use an object view.

For example, the SDF Document Catalog provides access to SDF's documents in several formats:

PDF and PostScript, stored on SDF's web site
HTML, stored locally.

This catalog was created by using the following columns parameter:

  columns='PDF&website,PS&website,DOC:Document,Date,Pages'

where website is a file containing the following:

  prefix_Jump=http://www.mincom.com/mtr/sdf/

The name of a view is either a file or a directory:

If the name of a view is a file, then the view is loaded from that file. The format is a same as a set of name-value pairs in an INI file.
If the name of a view is a directory, then a view with prefix_Jump=name/ is returned.

Within a view, the parameters supported are:

prefix_xxx - prefix for attribute xxx
suffix_xxx - suffix for attribute xxx.

Note: If it proves helpful, I'm happy to expand this list to include other types of parameters like default_xxx and value_xxx, say.

A.4. Filtering and Sorting

Filter Expressions

The where attribute takes an expression which is evaluated for each record. Special symbols available are:

Symbol	Meaning
$_	the current record
$o{"xyz"}	the value of column xyz
$var{"abc"}	the value of variable abc

For example:

 !define MODULE_CODE "XYZ"
 ...
 !include "../document.reg"; references; compact; \
   where='$o{"Reference"} =~ /$var{"MODULE_CODE"}/'; \
   columns="PS,REF:Reference,DOC:Document,CONCISE:Date"

Sorting

sort takes a comma-separated list of column names to sort on. If no columns are specified, the data is sorted using all columns in the order in which they appear. All sorting is done alphabetically - numeric sorting is not supported.

Using the delete Parameter

The delete parameter is particularly useful if you want to sort or filter a table (using the sort and where parameters, respectively) using columns which you don't want in the output. For example:

  # Load the bug tracking module
  !use "bugtrack"

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !include 'bugs.reg'; bugs; headings; \
           columns='Code,BUGTITLE:Title,Status,Priority'; \
           where='$o{"Status"} eq "Open"'; \
           sort='Priority'; \
           delete='Status'

Note: The order of the parameters to a class filter are not important, although the order above best reflects the processing.

In the case above, the columns parameter builds a data table which is then filtered and sorted. Note that the Status and Priority attributes are required in the columns as those attributes are required to do the filtering and sorting. However, as the heading tell the user that this is the table of open defects, we don't need/want the Status attribute in the output, so we delete it.

Filtering Using the catalog Macro

Another way of building the table above is to use the catalog macro like this:

  # Load the bug tracking module
  !use "bugtrack"

  # Load the bug data
  !include 'bugs.reg'; bugs; data

  # Display the open bugs, sorted by priority
  H1: Open Defects
  !catalog bugs 'Status:Open'; headings; \
           columns='Code,BUGTITLE:Title,Priority'; \
           sort='Priority'

In this case, the filtering is done before the data reaches the class filter, so things are easier once the data has been loaded.