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