/usr/share/doc/sgmls-doc/sgmlspl/handlers.html

<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('&lt;DOC&gt;', "\\begin{document}\n");

# Example 2
sgml('&lt;DOC&gt;', sub {
  output "\\begin{document}\n";
});

# Example 3
sub do_begin_document { output "\\begin{document}\n"; }
sgml('&lt;DOC&gt;', \&amp;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('&lt;LIST&gt;', 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">&lt;dmeggins@aix1.uottawa.ca&gt;</A></ADDRESS>
</BODY>
</HTML>
sgmls-doc 1.03ii-32 / usr / share / doc / sgmls-doc / sgmlspl / handlers.html
