The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
<HTML>
<HEAD>
<TITLE>How should I handle forward references?</TITLE>
</HEAD>
<BODY>

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

<H1>How should I handle forward references?</H1>

<P>Because <A HREF=sgmlspl.html><TT>sgmlspl</TT></A> processes the document as a linear data
stream, from beginning to end, it is easy to refer
<EM>back</EM> to information, but relatively difficult to
refer <EM>forward</EM>, since you do not know what will be
coming later in the parse.  Here are a few suggestions.</P>

<P>First, you could use <A HREF=pushoutput.html><TT>push_output</TT></A> and
<A HREF=popoutput.html><TT>pop_output</TT></A> to
save up output in a large string.  When you have found the information
which you need, you can make any necessary modifications to the string
and print it then. This will work for relatively small chunks of a
document, but you would not want to try it for anything larger.</P>

<P>Next, you could use the <A HREF="../SGMLSpm/extend.html"><TT>ext</TT></A> method to
add extra pointers, and build a parse tree of the whole document
before processing any of it.  This method will work well for small
documents, but large documents will place some serious stress on your
system's memory and/or swapping.</P>

<P>A more sophisticated solution, however, involves the
<TT>Refs.pm</TT> module, included in this
distribution.  In your <A HREF=sgmlspl.html><TT>sgmlspl</TT></A> script, include the line</P>

<P>
<PRE>use SGMLS::Refs.pm;</PRE>
</P>
<P>to activate the library.  The library will create a database
file to keep track of references between passes, and to tell you if
any references have changed.  For example, you might want to try
something like this:</P>

<P>
<PRE>sgml('start', sub {
  my $Refs = new SGMLS::Refs('references.refs');
});
sgml('end', sub {
  $Refs->warn;
  destroy $Refs;
});</PRE>
</P>
<P>This code will create an object, $Refs, linked to a file of
references called <TT>references.refs</TT>.  The
<TT>SGMLS::Refs</TT> class understands the methods
listed in table 4</P>


<H3>Table 4: The SGMLS::Refs class</H3>

<HR>
<DL>
<DT><B>Method</B></DT>
<DD><TT>new</TT>(<IT>filename</IT>,[<IT>logfile_handle</IT>])</DD>
<DT><B>Return Type</B></DT>
<DD><TT>SGMLS::Refs</TT></DD>
<DT><B>Description</B></DT>
<DD>Create a new <TT>SGMLS::Refs</TT> object.
Arguments are the name of the hashfile and (optionally) a writable
filehandle for logging changes.</DD>

</DL>
<HR>


<DL>
<DT><B>Method</B></DT>
<DD><TT>get</TT>(<IT>key</IT>)</DD>
<DT><B>Return Type</B></DT>
<DD>string</DD>
<DT><B>Description</B></DT>
<DD>Look up a reference key in the hash file and return its value.</DD>

</DL>
<HR>


<DL>
<DT><B>Method</B></DT>
<DD><TT>put</TT>(<IT>key</IT>,<IT>value</IT>)</DD>
<DT><B>Return Type</B></DT>
<DD>[none]</DD>
<DT><B>Description</B></DT>
<DD>Set a new value for the key in the hashfile.</DD>

</DL>
<HR>


<DL>
<DT><B>Method</B></DT>
<DD><TT>count</TT></DD>
<DT><B>Return Type</B></DT>
<DD>number</DD>
<DT><B>Description</B></DT>
<DD>Return the number of references whose values have changed (thus
far).</DD>

</DL>
<HR>


<DL>
<DT><B>Method</B></DT>
<DD><TT>warn</TT></DD>
<DT><B>Return Type</B></DT>
<DD>1 or 0</DD>
<DT><B>Description</B></DT>
<DD>Print a warning mentioning the number of references which have
changed, and return 1 if a warning was printed.</DD>

</DL>
<HR>



<P><B>Links</B>: <A HREF=bugs.html>Next</A> <A HREF=skel.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>