DMEGG / SGMLSpm-1.03 / DOC / HTML / sgmlspl / generic.html 
<HTML>
<HEAD>
<TITLE>What are the generic events?</TITLE>
</HEAD>
<BODY>

<P><B>Links</B>: <A HREF=specific.html>Next</A> <A HREF=handlers.html>Previous</A> <A HREF=sgmlspl.html>Up</A> <A HREF=sgmlspl.html>Top</A></P>

<H1>What are the generic events?</H1>

<P><A HREF=sgmlspl.html><TT>sgmlspl</TT></A> recognises the twelve generic events listed in table
1.  You may provide any one of these
as the first argument to <TT>sgml</TT> to declare a handler
(string or subroutine) for that event.</P>


<H3>Table 1: <A HREF=sgmlspl.html><TT>sgmlspl</TT></A> generic events</H3>

<HR>
<DL>
<DT><B>Event</B></DT>
<DD><TT>'start'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> (with no arguments) at
the beginning of the parse.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'end'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> (with no arguments) at
the end of the parse.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'start_element'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> at the beginning of every
element without a specific start handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'end_element'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> at the end of every
element without a specific end handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'cdata'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> for every character-data
string.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'sdata'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> for every special-data
string without a specific handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'re'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> for every
record end.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'pi'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> for every processing
instruction.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'entity'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> for every external data
entity without a specific handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'start_subdoc'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> at the beginning of every
subdocument entity without a specific handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'end_subdoc'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> at the end of every
subdocument entity without a specific handler.</DD>

</DL>
<HR>


<DL>
<DT><B>Event</B></DT>
<DD><TT>'conforming'</TT></DD>
<DT><B>Description</B></DT>
<DD>Execute <IT>handler</IT> once, at the end of the
document parse, if and only if the document was conforming.</DD>

</DL>
<HR>


<P>The handlers for all of these except the document events
<TT>'start'</TT> and <TT>'end'</TT> 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
<TT>SGMLS_Event</TT> object itself (see the document for
<A HREF="../SGMLSpm/sgmlspm.html"><TT>SGMLS.pm</TT></A>).  Note the following example, which allows processing
instructions for including the date or the hostname in the document at
parse time:</P>

<P>
<PRE>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";
    }
});</PRE>
</P>
<P>With this <A HREF=handlers.html>handler</A>, any occurance
of <TT>&lt;?date&gt;</TT> in the original <A HREF="http://www.sil.org/sgml/sgml.html"><B>SGML</B></A> document
would be replaced by the current date and time, and any occurance of
<TT>&lt;?hostname&gt;</TT> would be replaced by the name of
the host.</P>


<P><B>Links</B>: <A HREF=specific.html>Next</A> <A HREF=handlers.html>Previous</A> <A HREF=sgmlspl.html>Up</A> <A HREF=sgmlspl.html>Top</A></P>


<ADDRESS>David Megginson <A HREF="mailto:dmeggins@aix1.uottawa.ca">&lt;dmeggins@aix1.uottawa.ca&gt;</A></ADDRESS>
</BODY>
</HTML>