generic.htm

SP是一个基于GNU C++编译器

<dt>
<code>CharString text</code>
<dd>
The replacement text of the entity.
<dt>
<code>CharString entityName</code>
<dd>
The entity name.
This is non-ESIS information.
</dl>
<dt>
<code>ExternalDataEntityRefEvent</code>
<dd>
Generated for a reference to an external data entity.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the entity reference.
<dt>
<code>Entity entity</code>
<dd>
The referenced entity.
</dl>
<dt>
<code>SubdocEntityRefEvent</code>
<dd>
Generated for a reference to a subdoc entity.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the entity reference.
<dt>
<code>Entity entity</code>
<dd>
The referenced entity.
</dl>
<dt>
<code>StartDtdEvent</code>
<dd>
Generated at the start of a document type declaration.
This is non-ESIS information.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the start of the document type declaration.
<dt>
<code>CharString name</code>
<dd>
The document type name.
<dt>
<code>bool haveExternalId</code>
<dd>
The external identifier for the entity declared in the document type
declaration.
<dt>
<code>ExternalId externalId</code>
<dd>
Valid iff haveExternalId is true.
</dl>
<dt>
<code>EndDtdEvent</code>
<dd>
Generated at the end of a document type declaration.
This is non-ESIS information.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the end of the DTD.
<dt>
<code>CharString name</code>
<dd>
</dl>
<dt>
<code>EndPrologEvent</code>
<dd>
Generated at the end of the prolog.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the start of the instance.
</dl>
<dt>
<code>GeneralEntityEvent</code>
<dd>
Generated for each general entity in the name space of the governing
doctype, but only if the
<code>ParserEventGeneratorKit::outputGeneralEntities</code> option is
enabled.  This is non-ESIS information.  The event has the following
members:
<dl>
<dt>
<code>Entity entity</code>
<dd>
The entity.
</dl>
<p>
No event will be generated for the declaration of the
<code>#default</code> entity; instead an event will be generated when
an entity reference uses the <code>#default</code> entity if that is
the first time on which an entity with that name is used.  This means
that <code>GeneralEntityEvent</code> can occur after the end of the
prolog.
<dt>
<code>CommentDeclEvent</code>
<dd>
Generated for each comment declaration in the instance, but only if
<code>ParserEventGeneratorKit::outputCommentDecls</code> option is
enabled.  This is non-ESIS information.  The event has the following
members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the start of the comment declaration.
<dt>
<code>size_t nComments</code>
<dd>
The number of comments in the comment declaration.
<dt>
<code>const CharString *comments</code>
<dd>
The content of each comment in the declaration.
This excludes the com delimiters.
<dt>
<code>const CharString *seps</code>
<dd>
The separator following each comment in the declaration.
</dl>
<dt>
<code>MarkedSectionStartEvent</code>
<dd>
Generated for the start of a marked section in the instance,
but only if the <code>ParserEventGeneratorKit::outputMarkedSections</code>
option is enabled.
This is non-ESIS information.
The event has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the start of the marked section declaration.
<dt>
<code>MarkedSectionStartEvent::Status status</code>
<dd>
The effective status of the marked section.
<p>
<code>MarkedSectionStartEvent::Status</code> is a local enum with the
following possible values:
<ul>
<li><code>MarkedSectionStartEvent::include</code>
<li><code>MarkedSectionStartEvent::rcdata</code>
<li><code>MarkedSectionStartEvent::cdata</code>
<li><code>MarkedSectionStartEvent::ignore</code>
</ul>
<dt>
<code>size_t nParams</code>
<dd>
The number of top-level parameters in the status keyword specification.
<dt>
<code>const MarkedSectionStartEvent::Param *params</code>
<dd>
The top-level parameters in the status keyword specification.
<p>
<code>Param</code> is a local struct with the following members:
<dl>
<dt>
<code>MarkedSectionStartEvent::Param::Type type</code>
<dd>
The type of top-level parameter:
<p>
<code>MarkedSectionStartEvent::Param::Type</code> is a local enum with the
following possible values:
<dl>
<dt>
<code>MarkedSectionStartEvent::Param::temp</code>
<dt>
<code>MarkedSectionStartEvent::Param::include</code>
<dt>
<code>MarkedSectionStartEvent::Param::rcdata</code>
<dt>
<code>MarkedSectionStartEvent::Param::cdata</code>
<dt>
<code>MarkedSectionStartEvent::Param::ignore</code>
<dd>
The parameter is the corresponding keyword.
<dt>
<code>MarkedSectionStartEvent::Param::entityRef</code>
<dd>
The parameter is an entity reference.
</dl>
<dt>
<code>CharString entityName</code>
<dd>
Valid when <code>type</code> is
<code>MarkedSectionStartEvent::Param::entityRef</code>.
</dl>
</dl>
<dt>
<code>MarkedSectionEndEvent</code>
<dd>
Generated for the end of a marked section in the instance, but only if
the <code>ParserEventGeneratorKit::outputMarkedSections</code> option is
enabled.  This is non-ESIS information.  The event has the following
members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the end of the marked section declaration.
<dt>
<code>MarkedSectionEndEvent::Status status</code>
<dd>
The effective status of the marked section.
<p>
<code>MarkedSectionEndEvent::Status</code> is a local enum with the
following possible values:
<ul>
<li><code>MarkedSectionEndEvent::include</code>
<li><code>MarkedSectionEndEvent::rcdata</code>
<li><code>MarkedSectionEndEvent::cdata</code>
<li><code>MarkedSectionEndEvent::ignore</code>
</ul>
</dl>
<dt>
<code>IgnoredCharsEvent</code>
<dd>
Generated for a sequence of characters in an ignored marked section in
the instance, but only if the
<code>ParserEventGeneratorKit::outputMarkedSections</code> option is
enabled.  This is non-ESIS information.  The event has the following
members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position of the first of the ignored characters.
<dt>
<code>CharString data</code>
<dd>
The ignored characters.
</dl>
<dt>
<code>ErrorEvent</code>
<dd>
Generated for each error detected by the parser,
and also for any other cases where the parser produces a message.
This is non-ESIS information.
It has the following members:
<dl>
<dt>
<code>Position pos</code>
<dd>
The position at which the error was detected.
<dt>
<code>ErrorEvent::Type type</code>
<dd>
The type of error.
<p>
<code>ErrorEvent::Type</code> is a local enum with the following possible
values:
<dl>
<dt>
<code>ErrorEvent::quantity</code>
<dd>
Exceeding a quantity limit.
<dt>
<code>ErrorEvent::idref</code>
<dd>
An IDREF to a non-existent ID.
<dt>
<code>ErrorEvent::capacity</code>
<dd>
Exceeding a capacity limit.
<dt>
<code>ErrorEvent::otherError</code>
<dd>
Any other kind of error.
<dt>
<code>ErrorEvent::warning</code>
<dd>
A warning.  Not actually an error.
<dt>
<code>ErrorEvent::info</code>
<dd>
An informational message.  Not actually an error.
</dl>
<dt>
<code>CharString message</code>
<dd>
The message produced by the parser.
If messages are not disabled, this will be the same as the message
printed to standard error.
</dl>
</dl>
<p>
<code>SGMLApplication</code> also has a virtual function
<pre>
void openEntityChange(const OpenEntityPtr &);
</pre>
<p>
which is similar to an event.  An application that wishes to makes use
of position information must maintain a variable of type
<code>OpenEntityPtr</code> representing the current open entity, and
must provide an implementation of the <code>openEntityChange</code>
function that updates this variable.  It can then use the value of
this variable in conjunction with a <code>Position</code> to obtain a
<code>Location</code>; this can be relatively slow.  Unlike events, an
<code>OpenEntityPtr</code> has copy constructors and assignment
operators defined.

<h2>EventGenerator</h2>
<p>
The <code>EventGenerator</code> interface provides the following
functions:
<dl>
<dt>
<code>unsigned run(SGMLApplication &<var>app</var>)</code>
<dd>
Generate the sequence of events, calling the corresponding member of
<code><var>app</var></code> for each event.  Returns the number of
errors.  This must not be called more than once for any
<code>EventGenerator</code>object.
<dt>
<code>
EventGenerator *makeSubdocEventGenerator(const SGMLApplication::Char *<var>s</var>, size_t <var>n</var>)
</code>
<dd>
Makes a new <code>EventGenerator</code> for a subdocument of the
current document.  <var>s</var> and <var>n</var> together specify the
system identifier of the subdocument entity.  These should usually be
obtained from the <code>generatedSystemId</code> member of the
<code>externalId</code> member of the <code>Entity</code> object for
the subdocument entity.  This function can only be called after
<code>run</code> has been called; the call to <code>run</code> need
not have returned, but the <code>SGMLApplication
</code>
must have been passed events from the prolog or instance (ie the SGML
declaration must have been parsed).
<dt>
<code>void inhibitMessages(bool <var>b</var>)</code>
<dd>
If <var>b</var> is true, disables error and warning messages,
otherwise enables them.  Initially errors and warnings are enabled.
This function may be called at any time, including while
<code>run()</code> is executing.
<dt>
<code>void halt()</code>
<dd>
Halt the generation of events by <code>run()</code>.
This can be at any point during the execution of <code>run()</code>.
It is safe to call this function from a different thread from that which
called <code>run()</code>.
</dl>
<h2>ParserEventGeneratorKit</h2>
<p>
The <code>ParserEventGeneratorKit</code> class is used to create an
<code>EventGenerator</code> that  generate events using SP.  It
provides the following members:
<dl>
<dt>
<code>EventGenerator *makeEventGenerator(int <var>nFiles</var>, char *const *<var>files</var>)</code>
<dd>
This returns a new <code>EventGenerator</code> that will generate events
for the SGML document whose document entity is contained in the
<code><var>files</var></code>.
The returned <code>EventGenerator</code> should be deleted when it
is no longer needed.
<code>makeEventGenerator</code> may be called more than once.
<dt>
<code>void setOption(ParserEventGeneratorKit::Option <var>opt</var>)</code>
<dd>
This can be called any time before <code>makeEventGenerator()</code> is called.
<p>
<code>ParserEventGeneratorKit::Option</code> is a local enum with the following possible
values:
<dl>
<dt>
<code>ParserEventGeneratorKit::showOpenEntities</code>
<dd>
This corresponds to the <code>-e</code> option of nsgmls.
<dt>
<code>ParserEventGeneratorKit::showOpenElements</code>
<dd>
This corresponds to the <code>-g</code> option of nsgmls.
<dt>
<code>ParserEventGeneratorKit::outputCommentDecls</code>
<dd>
This will cause <code>CommentDeclEvent</code>s to be generated.
<dt>
<code>ParserEventGeneratorKit::outputMarkedSections</code>
<dd>
This will cause
<code>MarkedSectionStartEvent</code>s,
<code>MarkedSectionStartEvent</code>s
and <code>IgnoredCharsEvent</code>s
to be generated.
<dt>
<code>ParserEventGeneratorKit::outputGeneralEntities</code>
<dd>
This will cause <code>GeneralEntityEvent</code>s to be generated.
</dl>
<dt>
<code>
void setOption(ParserEventGeneratorKit::OptionWithArg <var>opt</var>, const char *<var>arg</var>)
</code>
<dd>
This can be called any time before <code>makeEventGenerator()</code> is called.
<p>
<code>ParserEventGeneratorKit::OptionWithArg</code> is a local enum with the following possible
values:
<dl>
<dt>
<code>ParserEventGeneratorKit::addCatalog</code>
<dd>
This corresponds to the <code>-m</code> option of nsgmls.
<dt>
<code>ParserEventGeneratorKit::includeParam</code>
<dd>
This corresponds to the <code>-i</code> option of nsgmls.
<dt>
<code>ParserEventGeneratorKit::enableWarning</code>
<dd>
This corresponds to the <code>-w</code> option of nsgmls.
<dt>
<code>ParserEventGeneratorKit::addSearchDir</code>
<dd>
This corresponds to the <code>-D</code> option of nsgmls.
</dl>
</dl>

<h2>Using the interface</h2>
<p>
Creating an application with this interface involves the following steps:
<ul>
<li>
Derive a class from <code>SGMLApplication</code>,
called, say, <code>MyApplication</code>.
<li>
For each kind of event <code><var>Foo</var>Event</code> that the application
needs information from, define a member of <code>MyApplication</code>
<code>void MyApplication::<var>foo</var>(const <var>Foo</var>Event &)</code>.
<li>
Declare an object of type <code>ParserEventGeneratorKit</code>.
<li>
Optionally set options for the <code>ParserEventGeneratorKit</code> using
<code>ParserEventGeneratorKit::setOption</code>.
<li>
Create an <code>EventGenerator</code> using
<code>ParserEventGeneratorKit::makeEventGenerator</code>.
<li>
Create an instance of <code>MyApplication</code>
(usually on the stack).
<li>
Call <code>EventGenerator::run</code> passing it a reference to
the instance of <code>MyApplication</code>.
<li>
Delete the <code>EventGenerator</code>.
</ul>
<p>
The application must include the <code>ParserEventGeneratorKit.h</code>
file (which in turn includes <code>EventGenerator.h</code> and
<code>SGMLApplication.h</code>), which is in the <code>generic</code>
directory.  If your compiler does not support the standard C++
<code>bool</code> type, you must ensure that <code>bool</code> is
defined as a typedef for <code>int</code>, before including this.  One
way to do this is to include <code>config.h</code> and then
<code>Boolean.h</code> from the <code>lib</code> subdirectory of the SP
distribution.
<p>
On Unix, the application must be linked with the
<code>lib/libsp.a</code> library.

<h2>Example</h2>
<p>
Here's a simple example of an application that uses this interface.
The application prints an outline of the element structure of a
document, using indentation to represent nesting.
<pre>
// The next two lines are only to ensure bool gets defined appropriately.
#include "config.h"
#include "Boolean.h"

#include "ParserEventGeneratorKit.h"
#include &lt;iostream.h>

ostream &amp;operator<<<!>(ostream &amp;os, SGMLApplication::CharString s)
{
  for (size_t i = 0; i < s.len; i++)
    os << char(s.ptr[i]);
  return os;
}

class OutlineApplication : public SGMLApplication {
public:
  OutlineApplication() : depth_(0) { }
  void startElement(const StartElementEvent &amp;event) {
    for (unsigned i = 0; i < depth_; i++)
      cout << "    ";
    cout << event.gi << '\n';
    depth_++;
  }
  void endElement(const EndElementEvent &amp;) { depth_--; }
private:
  unsigned depth_;
};

int main(int argc, char **argv)
{
  ParserEventGeneratorKit parserKit;
  // Use all the arguments after argv[0] as filenames.
  EventGenerator *egp = parserKit.makeEventGenerator(argc - 1, argv + 1);
  OutlineApplication app;
  unsigned nErrors = egp->run(app);
  delete egp;
  return nErrors > 0;
}
</pre>
<p>
This example will only work for the non-multibyte version of SP;
for the multibyte version you will need to use the standard C++ library's
facilities for wide character output, or roll your own equivalents
(like the OutputCharStream used by SP applications).
<p>
There's a bigger example in the <code>sgmlnorm</code> directory in the SP
distribution.
This uses the <code>SGMLApplication</code> interface, but it doesn't
use the <code>ParserEventGeneratorKit</code> interface.
<p>
<address>
James Clark<BR>
[e-mail]
</address>
</body>
</html>