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

# 6.5. Event Processing

## 6.5.1. The on Macro

The on macro allows you to execute an arbitrary piece of Perl code during document conversion. The syntax of the on macro is:

     !on type pattern; [id]; action

where:

- type specifies the event type
- pattern is a Perl regular expression string, anchored at both ends, which specifies which styles (or names) the action is to be executed for
- id is optionally used to name an event for later disabling via the off macro
- action is the block of Perl code to execute.

For example, the following statement makes every heading a hypertext target named itself:

      !on paragraph 'H\d';; $attr{'id'} = $text

## 6.5.2. Event Types

The types supported and the symbols available in the respective actions include:

Type | Symbols
paragraph | $style, $text, %attr
phrase | $style, $text, %attr
macro | $name, $args
filter | $name, $params
table | $style, %param

## 6.5.3. Event Patterns

Some example event patterns are given below.

Pattern | Comments
'XYZ' | matches a thing called XYZ
'AB|CD|E' | matches things named AB, CD or E
'H1' | for paragraphs, matches a level 1 normal heading
'H[1-4]' | for paragraphs, matches normal headings at levels 1 to 4
'[HAP]\d' | for paragraphs, matches all headings

If the pattern is an empty string, the action is executed for all entities of that type.

If multiple actions are registered for a given type, actions are executed in "last in, first out" order.

## 6.5.4. The off Macro

The off macro is used to cancel an event. The syntax is:

     !off type id

For example:

      !on paragraph 'H\d'; XYZ; $attr{'id'} = $text
      # lots of SDF
      !off paragraph XYZ

If two events are given the same name, the most-recently-named event will be cancelled. i.e. nested event cancelling works as expected.

## 6.5.5. Examples

### 6.5.5.1. Generating Hypertext Targets

To make all level 1 and 2 headings hypertext targets:

      !on paragraph '[HAP][12]';; $attr{"id"} = $text

### 6.5.5.2. Generating Index Entries

To make index entries for all commands (CMD character tags):

      !on phrase 'CMD';; $attr{"index"} = $text

### 6.5.5.3. Adjusting Heading Levels

To move normal headings down one level:

      !on paragraph 'H\d';; $style =~ tr/1234/2345/

### 6.5.5.4. Changing Spelling

To convert selected words to North American spelling:

      !on paragraph '';; $text =~ s/colour/color/ig; \
                         $text =~ s/ise\b/ize/g

This approach uses Perl's substitute operator on the text in each paragraph:

- the 'i' switch means case insensitive
- the 'g' switch means global. i.e. all occurances in each paragraph
- the '\b' symbol matches a word boundary.