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:


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:

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:

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:

Within a view, the parameters supported are:


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.