Contents | Parent Topic | Previous Topic | Next Topic
Home | Catalog

# 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.