<HTML>
<HEAD>
<TITLE>What about the handler argument?</TITLE>
</HEAD>
<BODY>
<P><B>Links</B>: <A HREF=generic.html>Next</A> <A HREF=specs.html>Previous</A> <A HREF=sgmlspl.html>Up</A> <A HREF=sgmlspl.html>Top</A></P>
<H1>What about the <IT>handler</IT> argument?</H1>
<P>The second argument to the <TT>sgml</TT> subroutine is
the actual code or data associated with each event. If it is a
string, it will be printed literally using the
<TT>output</TT> subroutine from the <A HREF=output.html><TT>SGMLS::Output</TT></A> library; if
it is a reference to a <A HREF="http://www.metronet.com/0/perlinfo/perl5/manual/perl.html"><TT>perl5</TT></A> subroutine, the subroutine will be
called whenever the event occurs. The following three
<TT>sgml</TT> commands will have identical results:</P>
<P>
<PRE># Example 1
sgml('<DOC>', "\\begin{document}\n");
# Example 2
sgml('<DOC>', sub {
output "\\begin{document}\n";
});
# Example 3
sub do_begin_document { output "\\begin{document}\n"; }
sgml('<DOC>', \&do_begin_document);</PRE>
</P>
<P>For simply printing a string, of course, it does not make sense
to use a subroutine; however, the subroutines can be useful when you
need to check the value of an attribute, perform different actions in
different contexts, or perform other types of relatively more
complicated post-processing.</P>
<P>If your handler is a subroutine, then it will receive two
arguments: the <A HREF="../SGMLSpm/sgmlspm.html"><TT>SGMLS.pm</TT></A> event's data, and the <A HREF="../SGMLSpm/sgmlspm.html"><TT>SGMLS.pm</TT></A> event
itself (see the <A HREF="../SGMLSpm/sgmlspm.html"><TT>SGMLS.pm</TT></A> <A HREF="../SGMLSpm/events.html">documentation</A> for a description
of event and data types). The following example will print
<TT>'\begin{enumerate}'</TT> if the value of the attribute
<TT>TYPE</TT> is <TT>'ORDERED'</TT>, and
<TT>'\begin{itemize}'</TT> if the value of the attribute
<TT>TYPE</TT> is <TT>'UNORDERED'</TT>:</P>
<P>
<PRE>sgml('<LIST>', sub {
my ($element,$event) = @_;
my $type = $element->attribute('TYPE')->value;
if ($type eq 'ORDERED') {
output "\\begin{enumerate}\n";
} elsif ($type eq 'UNORDERED') {
output "\\begin{itemize}\n";
} else {
die "Bad TYPE '$type' for element LIST at line " .
$event->line . " in " . $event->file . "\n";
}
});</PRE>
</P>
<P>You will not always need to use the <IT>event</IT>
argument, but it can be useful if you want to report line numbers or
file names for errors (presuming that you called <TT>sgmls</TT> or <A HREF="http://www.jclark.com/sp.html"><TT>nsgmls</TT></A>
with the <IT>-l</IT> option). If you have a new version
of <A HREF="http://www.jclark.com/sp.html"><TT>nsgmls</TT></A> which accepts the <IT>-h</IT> option, you
can also use the <IT>event</IT> argument to look up
arbitrary entities declared by the program. See the <A HREF="../SGMLSpm/sgmlsevent.html">SGMLS_Event</A> documentation for
more information.</P>
<P><B>Links</B>: <A HREF=generic.html>Next</A> <A HREF=specs.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"><dmeggins@aix1.uottawa.ca></A></ADDRESS>
</BODY>
</HTML>