Links: Next Previous Up Top

# What are the generic events?

`sgmlspl` recognises the twelve generic events listed in table 1. You may provide any one of these as the first argument to `sgml` to declare a handler (string or subroutine) for that event.

### Table 1: `sgmlspl` generic events

Event
  `'start'`
Description
  Execute <IT>handler</IT> (with no arguments) at the beginning of the parse.

Event
  `'end'`
Description
  Execute <IT>handler</IT> (with no arguments) at the end of the parse.

Event
  `'start_element'`
Description
  Execute <IT>handler</IT> at the beginning of every element without a specific start handler.

Event
  `'end_element'`
Description
  Execute <IT>handler</IT> at the end of every element without a specific end handler.

Event
  `'cdata'`
Description
  Execute <IT>handler</IT> for every character-data string.

Event
  `'sdata'`
Description
  Execute <IT>handler</IT> for every special-data string without a specific handler.

Event
  `'re'`
Description
  Execute <IT>handler</IT> for every record end.

Event
  `'pi'`
Description
  Execute <IT>handler</IT> for every processing instruction.

Event
  `'entity'`
Description
  Execute <IT>handler</IT> for every external data entity without a specific handler.

Event
  `'start_subdoc'`
Description
  Execute <IT>handler</IT> at the beginning of every subdocument entity without a specific handler.

Event
  `'end_subdoc'`
Description
  Execute <IT>handler</IT> at the end of every subdocument entity without a specific handler.

Event
  `'conforming'`
Description
  Execute <IT>handler</IT> once, at the end of the document parse, if and only if the document was conforming.

The handlers for all of these except the document events `'start'` and `'end'` will receive two arguments whenever they are called: the first will be the data associated with the event (if any), and the second will be the `SGMLS_Event` object itself (see the document for `SGMLS.pm`). Note the following example, which allows processing instructions for including the date or the hostname in the document at parse time:

    sgml('pi', sub {
        my ($instruction) = @_;
        if ($instruction eq 'date') {
          output `date`;
        } elsif ($instruction eq 'hostname') {
          output `hostname`;
        } else {
          print STDERR "Warning: unknown processing instruction: $instruction\n";
        }
    });

With this handler, any occurance of `<?date>` in the original SGML document would be replaced by the current date and time, and any occurance of `<?hostname>` would be replaced by the name of the host.

Links: Next Previous Up Top