doc/generic.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
   2 <html>
   3 <head>
   4 <title>The generic API to OpenSP</title>
   5 </head>
   6 <body>
   7 <h1>The generic API to OpenSP</h1>
   8 <p>
   9 OpenSP provides a generic API in addition to its native API.  The generic
  10 interface is much simpler than the native interface.  It is generic in
  11 the sense that it could be easily implemented using parsers other than
  12 OpenSP.  It provides all ESIS information as well as some other
  13 information about the instance that is commonly needed by
  14 applications.  However, it doesn't provide access to all information
  15 available from OpenSP; in particular, it doesn't provide information about
  16 the DTD.  It is also slightly less efficient than the native
  17 interface.
  18 <p>
  19 The interface uses two related abstract classes.  An
  20 <code>SGMLApplication</code> is an object that can handle a number of
  21 different kinds of event which correspond to information in an SGML
  22 document.  An <code>EventGenerator</code> is an object that can
  23 generate a sequence of events of the kinds handled by an
  24 <code>SGMLApplication</code>.  The
  25 <code>ParserEventGeneratorKit</code> class makes an
  26 <code>EventGenerator</code> that generates events using OpenSP.
  27
  28 <h2>Types</h2>
  29 <p>
  30 <code>SGMLApplication</code> has a number of local types that are used
  31 in several contexts:
  32 <dl>
  33 <dt>
  34 <code>Char</code>
  35 <dd>
  36 This typedef is an unsigned integral type that represents a single bit
  37 combination (character).  It is <code>unsigned short</code> if
  38 <code>SP_MULTI_BYTE</code> is defined and <code>unsigned char</code>
  39 otherwise.
  40 <dt>
  41 <code>CharString</code>
  42 <dd>
  43 This struct represents a string of <code>Char</code>.
  44 It has the following members:
  45 <dl>
  46 <dt>
  47 <code>const Char *ptr</code>
  48 <dd>
  49 A pointer to the <code>Char</code>s of the string.
  50 <dt>
  51 <code>size_t len</code>
  52 <dd>
  53 The number of <code>Char</code>s in the string.
  54 </dl>
  55 <dt>
  56 <code>Location</code>
  57 <dd>
  58 This struct holds information about a location in the entity structure
  59 of a document.  It is constucted using an <code>OpenEntityPtr</code>
  60 and a <code>Position</code>.  The <code>CharString</code>s in it will
  61 remain valid as long as the <code>OpenEntity</code> that is pointed to
  62 by the <code>OpenEntityPtr</code> that was used to construct it
  63 remains valid.
  64 <p>
  65 It has the following members:
  66 <dl>
  67 <dt>
  68 <code>unsigned long lineNumber</code>
  69 <dd>
  70 The line number.
  71 <code>(unsigned long)-1</code> if invalid.
  72 <dt>
  73 <code>unsigned long columnNumber</code>
  74 <dd>
  75 The column number.
  76 Note that tabs are not treated specially.
  77 <code>(unsigned long)-1</code> if invalid.
  78 <dt>
  79 <code>unsigned long byteOffset</code>
  80 <dd>
  81 The number of bytes in the storage object preceding the location.
  82 <code>(unsigned long)-1</code> if invalid.
  83 <dt>
  84 <code>unsigned long entityOffset</code>
  85 <dd>
  86 The number of bit combinations in the entity preceding the location.
  87 <code>(unsigned long)-1</code> if invalid.
  88 <dt>
  89 <code>CharString entityName</code>
  90 <dd>
  91 The name of the external entity containing the location.
  92 An empty string if invalid.
  93 <dt>
  94 <code>CharString filename</code>
  95 <dd>
  96 The name of the file containing the location.
  97 An empty string if invalid.
  98 <dt>
  99 <code>const void *other</code>
 100 <dd>
 101 Other implementation-dependent information about the location.  In the
 102 OpenSP implementation it will be a pointer to a StorageObjectSpec.  0 if
 103 invalid.
 104 </dl>
 105 <p>
 106 When a location is in an internal entity, the location of the reference
 107 to the entity will be used instead.
 108 <dt>
 109 <code>OpenEntity</code>
 110 <dd>
 111 This class represents a currently open entity.  The only use for an
 112 <code>OpenEntity</code> is, in conjunction with a
 113 <code>Position</code>, to create a <code>Location</code>.  An
 114 <code>OpenEntity</code> is accessed using an
 115 <code>OpenEntityPtr</code>.
 116 <dt>
 117 <code>OpenEntityPtr</code>
 118 <dd>
 119 This class is a reference-counted pointer to an <code>OpenEntity</code>.
 120 <dt>
 121 <code>Position</code>
 122 <dd>
 123 This is an integral type that represents a position in an open entity.
 124 The meaning of a <code>Position</code> is completely determined by the
 125 <code>OpenEntity</code> object with which it is associated.  The only
 126 use for an <code>Position</code> is, in conjunction with an
 127 <code>OpenEntity</code>, to create a <code>Location</code>.
 128 <dt>
 129 <code>ExternalId</code>
 130 <dd>
 131 This struct represents an external identifier.  It has the following
 132 members:
 133 <dl>
 134 <dt>
 135 <code>bool haveSystemId</code>
 136 <dd>
 137 True iff the external identifier included an explicit system identifier.
 138 <dt>
 139 <code>CharString systemId</code>
 140 <dd>
 141 The system identifier included in the external identifier.
 142 Valid only if <code>havePublicId</code> is true.
 143 <dt>
 144 <code>bool havePublicId</code>
 145 <dd>
 146 True iff the external identifier included an explicit public identifier.
 147 <dt>
 148 <code>CharString publicId</code>
 149 <dd>
 150 The public identifier included in the external identifier.
 151 Valid only if <code>havePublicId</code> is true.
 152 <dt>
 153 <code>bool haveGeneratedSystemId</code>
 154 <dd>
 155 True iff a system identifier was generated for the external identifier.
 156 <dt>
 157 <dt>
 158 <code>CharString generatedSystemId</code>
 159 <dd>
 160 The system identifier generated for the external identifier.
 161 Valid only if <code>haveGeneratedSystemId</code> is true.
 162 </dl>
 163 <dt>
 164 <code>Notation</code>
 165 <dd>
 166 This struct represents a notation.
 167 It has the following members:
 168 <dl>
 169 <dt>
 170 <code>CharString name</code>
 171 <dd>
 172 The name of the notation.
 173 <dt>
 174 <code>ExternalId externalId</code>
 175 <dd>
 176 The external identifier of the notation.
 177 </dl>
 178 <dt>
 179 <code>Entity</code>
 180 <dd>
 181 This struct represents an entity.
 182 It has the following members.
 183 <dl>
 184 <dt>
 185 <code>CharString name</code>
 186 <dd>
 187 The name of the entity.
 188 <dt>
 189 <code>Entity::DataType dataType</code>
 190 <dd>
 191 The type of the data of the entity.
 192 <p>
 193 <code>Entity::DataType</code> is a local enum with the following possible
 194 values:
 195 <dl>
 196 <dt>
 197 <code>Entity::sgml</code>
 198 <dd>
 199 <dt>
 200 <code>Entity::cdata</code>
 201 <dd>
 202 <dt>
 203 <code>Entity::sdata</code>
 204 <dd>
 205 <dt>
 206 <code>Entity::ndata</code>
 207 <dd>
 208 <dt>
 209 <code>Entity::subdoc</code>
 210 <dd>
 211 <dt>
 212 <code>Entity::pi</code>
 213 <dd>
 214 </dl>
 215 <dt>
 216 <code>Entity::DeclType declType</code>
 217 <dd>
 218 The type of the declaration of the entity.
 219 <p>
 220 <code>Entity::DeclType</code> is a local enum with the following possible
 221 values:
 222 <dl>
 223 <dt>
 224 <code>Entity::general</code>
 225 <dd>
 226 The entity is a general entity.
 227 <dt>
 228 <code>Entity::parameter</code>
 229 <dd>
 230 The entity is a parameter entity.
 231 <dt>
 232 <code>Entity::doctype</code>
 233 <dd>
 234 The entity was declared in a doctype declaration.
 235 <dt>
 236 <code>Entity::linktype</code>
 237 <dd>
 238 The entity was declared in a linktype declaration.
 239 </dl>
 240 <dt>
 241 <code>bool isInternal</code>
 242 <dd>
 243 True iff the entity is internal rather than external.
 244 <dt>
 245 <code>CharString text</code>
 246 <dd>
 247 The replacement text of the entity.
 248 Valid only if <code>isInternal</code> is true.
 249 <dt>
 250 <code>ExternalId externalId</code>
 251 <dd>
 252 The external identifier of the entity.
 253 Valid only if <code>isInternal</code> is false.
 254 <dt>
 255 <code>const Attribute *attributes</code>
 256 <dd>
 257 Pointer to the data attributes of the entity.
 258 Valid only if <code>isInternal</code> is false.
 259 <dt>
 260 <code>size_t nAttributes</code>
 261 <dd>
 262 The number of data attributes of the entity.
 263 Valid only if <code>isInternal</code> is false.
 264 <dt>
 265 <code>Notation notation</code>
 266 <dd>
 267 The entity's notation.
 268 An empty string if the entity has no notation.
 269 Valid only if <code>isInternal</code> is false.
 270 </dl>
 271 <dt>
 272 <code>Attribute</code>
 273 <dd>
 274 This struct represents an attribute.  More precisely it represents the
 275 assignment of an attribute value to an attribute name.
 276 It has the following members:
 277 <dl>
 278 <dt>
 279 <code>CharString name</code>
 280 <dd>
 281 The attribute name.
 282 <dt>
 283 <code>Attribute::Type type</code>
 284 <dd>
 285 An enumeration describing the type of the attribute.
 286 <p>
 287 <code>Attribute::Type</code> is a local type with the following possible
 288 values:
 289 <dl>
 290 <dt><code>Attribute::invalid</code>
 291 <dd>
 292 The attribute is invalid.
 293 <dt><code>Attribute::implied</code>
 294 <dd>
 295 The attribute is an impliable attribute for which
 296 no value was specified.
 297 <dt><code>Attribute::cdata</code>
 298 <dd>
 299 The attribute is a CDATA attribute.
 300 <dt><code>Attribute::tokenized</code>
 301 <dd>
 302 The attribute is a tokenized attribute.
 303 </dl>
 304 <dt>
 305 <code>Attribute::Defaulted defaulted</code>
 306 <dd>
 307 An enumeration specifying whether the entity was defaulted, and, if
 308 so, how.
 309 This is non-ESIS information.
 310 <p>
 311 <code>Attribute::Defaulted</code> is a local enum with the following
 312 possible values:
 313 <dl>
 314 <dt>
 315 <code>Attribute::specified</code>
 316 <dd>
 317 The value was explicitly specified.
 318 <dt>
 319 <code>Attribute::definition</code>
 320 <dd>
 321 The value was defaulted from the attribute definition.
 322 <dt>
 323 <code>Attribute::current</code>
 324 <dd>
 325 The value was defaulted using the CURRENT value of the attribute.
 326 </dl>
 327 <dt>
 328 <code>size_t nCdataChunks</code>
 329 <dd>
 330 The number of <code>Attribute::CdataChunk</code>s comprising the value
 331 of the attribute.  Valid only if <code>type</code> is
 332 <code>cdata</code>.
 333 <dt>
 334 <code>const Attribute::CdataChunk *cdataChunks</code>
 335 <dd>
 336 The <code>Attribute::CdataChunk</code>s comprising the value of this attribute.
 337 Valid only if <code>type</code> is <code>cdata</code>.
 338 <p>
 339 <code>Attribute::CdataChunk</code> is a local struct with the
 340 following members:
 341 <dl>
 342 <dt>
 343 <code>bool isSdata</code>
 344 <dd>
 345 True iff this chunk is the replacement text of an internal SDATA entity.
 346 <dt>
 347 <code>CharString data</code>
 348 <dd>
 349 The data of this chunk.
 350 <dt>
 351 <code>CharString entityName</code>
 352 <dd>
 353 The name of the internal SDATA entity that this chunk is the
 354 replacement text of.  Valid only if <code>isSdata</code> is true.
 355 This is non-ESIS information.
 356 </dl>
 357 <dt>
 358 <code>CharString tokens</code>
 359 <dd>
 360 Valid only if <code>type</code> is <code>Attribute::tokenized</code>.
 361 <dt>
 362 <code>bool isId</code>
 363 <dd>
 364 True iff the declared value is ID.
 365 This is non-ESIS information.
 366 <dt>
 367 <code>size_t nEntities</code>
 368 <dd>
 369 The number of entities associated with this attribute.
 370 This will be zero unless the declared value is ENTITY or ENTITIES.
 371 <dt>
 372 <code>const Entity *entities</code>
 373 <dd>
 374 The entities associated with this attribute.
 375 <dt>
 376 <code>Notation notation</code>
 377 <dd>
 378 The notation associated with this attribute.
 379 If the declared value of the attribute is not NOTATION,
 380 then the name member will be an empty string.
 381 </dl>
 382 </dl>
 383 <h2>Events</h2>
 384 <p>
 385 For each event <code><var>xyz</var>Event</code> handled by
 386 <code>SGMLApplication</code>, there is a virtual function of
 387 <code>SGMLApplication</code> named <code><var>xyz</var></code> to
 388 handle the event, and a local struct of <code>SGMLApplication</code>
 389 named <code><var>Xyz</var>Event</code>.
 390 <p>
 391 Pointers within an event <code><var>xyz</var>Event</code> are valid
 392 only during the call to <code><var>xyz</var></code>.  None of the
 393 structs in events have copy constructors or assignment operators
 394 defined.  It is up to the event handling function to make a copy of
 395 any data that it needs to preserve after the function returns.
 396 <p>
 397 Except as otherwise stated,
 398 the information in events is ESIS information.
 399 All position information is non-ESIS information.
 400 <p>
 401 There are the following types of event:
 402 <dl>
 403 <dt>
 404 <code>AppinfoEvent</code>
 405 <dd>
 406 Generated for the APPINFO section of the SGML declaration.
 407 The event has the following members:
 408 <dl>
 409 <dt><code>Position pos</code>
 410 <dd>
 411 The position of APPINFO parameter of the SGML declaration.
 412 <dt><code>bool none</code>
 413 <dd>
 414 True iff APPINFO NONE was specified.
 415 <dt><code>CharString string</code>
 416 <dd>
 417 The interpreted value of the minimum literal specified
 418 in the appinfo parameter of the SGML declaration.
 419 Valid only if <code>none</code> is false.
 420 </dl>
 421 <dt>
 422 <code>PiEvent</code>
 423 <dd>
 424 Generated for a processing instruction.
 425 The event has the following members:
 426 <dl>
 427 <dt>
 428 <code>Position pos</code>
 429 <dd>
 430 The position of the processing instruction.
 431 <dt>
 432 <code>CharString data</code>
 433 <dd>
 434 The system data of the processing instuction.
 435 <dt>
 436 <code>CharString entityName</code>
 437 <dd>
 438 If the processing instruction was the result of the
 439 reference to a PI entity, the name of the entity.
 440 If not, an empty string.
 441 This is non-ESIS information.
 442 </dl>
 443 <dt>
 444 <code>StartElementEvent</code>
 445 <dd>
 446 Generated for the start of an element.
 447 The event has the following members:
 448 <dl>
 449 <dt>
 450 <code>Position pos</code>
 451 <dd>
 452 The position of the start of the element.
 453 <dt>
 454 <code>CharString gi</code>
 455 <dd>
 456 The generic identifier of the element.
 457 <dt>
 458 <code>Element::ContentType contentType</code>
 459 <dd>
 460 The type of the element's content.
 461 This is non-ESIS information.
 462 <p>
 463 <code>Element::ContentType</code> is an enum with the following
 464 possible values:
 465 <dl>
 466 <dt>
 467 <code>Element::empty</code>
 468 <dd>
 469 The element has empty content, either because it was
 470 declared as EMPTY or because there was a #CONREF attribute.
 471 <dt>
 472 <code>Element::cdata</code>
 473 <dd>
 474 The element has CDATA content.
 475 <dt>
 476 <code>Element::rcdata</code>
 477 <dd>
 478 The element has RCDATA content.
 479 <dt>
 480 <code>Element::mixed</code>
 481 <dd>
 482 The element has mixed content.
 483 <dt>
 484 <code>Element::element</code>
 485 <dd>
 486 The element has element content.
 487 </dl>
 488 <dt>
 489 <code>bool included</code>
 490 <dd>
 491 True iff the element was an included subelement
 492 (rather than a proper subelement).
 493 This is non-ESIS information.
 494 <dt>
 495 <code>size_t nAttributes</code>
 496 <dd>
 497 The number of attributes of this element.
 498 <dt>
 499 <code>const Attribute *attributes</code>
 500 <dd>
 501 A pointer to the attributes for this element.
 502 </dl>
 503 <dt>
 504 <code>EndElementEvent</code>
 505 <dd>
 506 Generated for the end of an elemenet.
 507 The event has the following members:
 508 <dl>
 509 <dt>
 510 <code>Position pos</code>
 511 <dd>
 512 The position of the end of the element.
 513 <dt>
 514 <code>CharString gi</code>
 515 <dd>
 516 The generic identifier of the element.
 517 </dl>
 518 <dt>
 519 <code>DataEvent</code>
 520 <dd>
 521 Generated for character data.
 522 Separate data events may be generated for consecutive data characters.
 523 Applications should make no assumptions about how character data is split
 524 into <code>DataEvent</code>s.
 525 The event has the following members:
 526 <dl>
 527 <dt>
 528 <code>Position pos</code>
 529 <dd>
 530 The position of the first character of the data.
 531 <dt>
 532 <code>CharString data</code>
 533 <dd>
 534 The data.
 535 </dl>
 536 <dt>
 537 <code>SdataEvent</code>
 538 <dd>
 539 Generated for a reference to an internal sdata entity in content.
 540 The event has the following members:
 541 <dl>
 542 <dt>
 543 <code>Position pos</code>
 544 <dd>
 545 The position of the entity reference.
 546 <dt>
 547 <code>CharString text</code>
 548 <dd>
 549 The replacement text of the entity.
 550 <dt>
 551 <code>CharString entityName</code>
 552 <dd>
 553 The entity name.
 554 This is non-ESIS information.
 555 </dl>
 556 <dt>
 557 <code>ExternalDataEntityRefEvent</code>
 558 <dd>
 559 Generated for a reference to an external data entity.
 560 The event has the following members:
 561 <dl>
 562 <dt>
 563 <code>Position pos</code>
 564 <dd>
 565 The position of the entity reference.
 566 <dt>
 567 <code>Entity entity</code>
 568 <dd>
 569 The referenced entity.
 570 </dl>
 571 <dt>
 572 <code>SubdocEntityRefEvent</code>
 573 <dd>
 574 Generated for a reference to a subdoc entity.
 575 The event has the following members:
 576 <dl>
 577 <dt>
 578 <code>Position pos</code>
 579 <dd>
 580 The position of the entity reference.
 581 <dt>
 582 <code>Entity entity</code>
 583 <dd>
 584 The referenced entity.
 585 </dl>
 586 <dt>
 587 <code>StartDtdEvent</code>
 588 <dd>
 589 Generated at the start of a document type declaration.
 590 This is non-ESIS information.
 591 The event has the following members:
 592 <dl>
 593 <dt>
 594 <code>Position pos</code>
 595 <dd>
 596 The position of the start of the document type declaration.
 597 <dt>
 598 <code>CharString name</code>
 599 <dd>
 600 The document type name.
 601 <dt>
 602 <code>bool haveExternalId</code>
 603 <dd>
 604 The external identifier for the entity declared in the document type
 605 declaration.
 606 <dt>
 607 <code>ExternalId externalId</code>
 608 <dd>
 609 Valid iff haveExternalId is true.
 610 </dl>
 611 <dt>
 612 <code>EndDtdEvent</code>
 613 <dd>
 614 Generated at the end of a document type declaration.
 615 This is non-ESIS information.
 616 The event has the following members:
 617 <dl>
 618 <dt>
 619 <code>Position pos</code>
 620 <dd>
 621 The position of the end of the DTD.
 622 <dt>
 623 <code>CharString name</code>
 624 <dd>
 625 </dl>
 626 <dt>
 627 <code>EndPrologEvent</code>
 628 <dd>
 629 Generated at the end of the prolog.
 630 The event has the following members:
 631 <dl>
 632 <dt>
 633 <code>Position pos</code>
 634 <dd>
 635 The position of the start of the instance.
 636 </dl>
 637 <dt>
 638 <code>GeneralEntityEvent</code>
 639 <dd>
 640 Generated for each general entity in the name space of the governing
 641 doctype, but only if the
 642 <code>ParserEventGeneratorKit::outputGeneralEntities</code> option is
 643 enabled.  This is non-ESIS information.  The event has the following
 644 members:
 645 <dl>
 646 <dt>
 647 <code>Entity entity</code>
 648 <dd>
 649 The entity.
 650 </dl>
 651 <p>
 652 No event will be generated for the declaration of the
 653 <code>#default</code> entity; instead an event will be generated when
 654 an entity reference uses the <code>#default</code> entity if that is
 655 the first time on which an entity with that name is used.  This means
 656 that <code>GeneralEntityEvent</code> can occur after the end of the
 657 prolog.
 658 <dt>
 659 <code>CommentDeclEvent</code>
 660 <dd>
 661 Generated for each comment declaration in the instance, but only if
 662 <code>ParserEventGeneratorKit::outputCommentDecls</code> option is
 663 enabled.  This is non-ESIS information.  The event has the following
 664 members:
 665 <dl>
 666 <dt>
 667 <code>Position pos</code>
 668 <dd>
 669 The position of the start of the comment declaration.
 670 <dt>
 671 <code>size_t nComments</code>
 672 <dd>
 673 The number of comments in the comment declaration.
 674 <dt>
 675 <code>const CharString *comments</code>
 676 <dd>
 677 The content of each comment in the declaration.
 678 This excludes the com delimiters.
 679 <dt>
 680 <code>const CharString *seps</code>
 681 <dd>
 682 The separator following each comment in the declaration.
 683 </dl>
 684 <dt>
 685 <code>MarkedSectionStartEvent</code>
 686 <dd>
 687 Generated for the start of a marked section in the instance,
 688 but only if the <code>ParserEventGeneratorKit::outputMarkedSections</code>
 689 option is enabled.
 690 This is non-ESIS information.
 691 The event has the following members:
 692 <dl>
 693 <dt>
 694 <code>Position pos</code>
 695 <dd>
 696 The position of the start of the marked section declaration.
 697 <dt>
 698 <code>MarkedSectionStartEvent::Status status</code>
 699 <dd>
 700 The effective status of the marked section.
 701 <p>
 702 <code>MarkedSectionStartEvent::Status</code> is a local enum with the
 703 following possible values:
 704 <ul>
 705 <li><code>MarkedSectionStartEvent::include</code>
 706 <li><code>MarkedSectionStartEvent::rcdata</code>
 707 <li><code>MarkedSectionStartEvent::cdata</code>
 708 <li><code>MarkedSectionStartEvent::ignore</code>
 709 </ul>
 710 <dt>
 711 <code>size_t nParams</code>
 712 <dd>
 713 The number of top-level parameters in the status keyword specification.
 714 <dt>
 715 <code>const MarkedSectionStartEvent::Param *params</code>
 716 <dd>
 717 The top-level parameters in the status keyword specification.
 718 <p>
 719 <code>Param</code> is a local struct with the following members:
 720 <dl>
 721 <dt>
 722 <code>MarkedSectionStartEvent::Param::Type type</code>
 723 <dd>
 724 The type of top-level parameter:
 725 <p>
 726 <code>MarkedSectionStartEvent::Param::Type</code> is a local enum with the
 727 following possible values:
 728 <dl>
 729 <dt>
 730 <code>MarkedSectionStartEvent::Param::temp</code>
 731 <dt>
 732 <code>MarkedSectionStartEvent::Param::include</code>
 733 <dt>
 734 <code>MarkedSectionStartEvent::Param::rcdata</code>
 735 <dt>
 736 <code>MarkedSectionStartEvent::Param::cdata</code>
 737 <dt>
 738 <code>MarkedSectionStartEvent::Param::ignore</code>
 739 <dd>
 740 The parameter is the corresponding keyword.
 741 <dt>
 742 <code>MarkedSectionStartEvent::Param::entityRef</code>
 743 <dd>
 744 The parameter is an entity reference.
 745 </dl>
 746 <dt>
 747 <code>CharString entityName</code>
 748 <dd>
 749 Valid when <code>type</code> is
 750 <code>MarkedSectionStartEvent::Param::entityRef</code>.
 751 </dl>
 752 </dl>
 753 <dt>
 754 <code>MarkedSectionEndEvent</code>
 755 <dd>
 756 Generated for the end of a marked section in the instance, but only if
 757 the <code>ParserEventGeneratorKit::outputMarkedSections</code> option is
 758 enabled.  This is non-ESIS information.  The event has the following
 759 members:
 760 <dl>
 761 <dt>
 762 <code>Position pos</code>
 763 <dd>
 764 The position of the end of the marked section declaration.
 765 <dt>
 766 <code>MarkedSectionEndEvent::Status status</code>
 767 <dd>
 768 The effective status of the marked section.
 769 <p>
 770 <code>MarkedSectionEndEvent::Status</code> is a local enum with the
 771 following possible values:
 772 <ul>
 773 <li><code>MarkedSectionEndEvent::include</code>
 774 <li><code>MarkedSectionEndEvent::rcdata</code>
 775 <li><code>MarkedSectionEndEvent::cdata</code>
 776 <li><code>MarkedSectionEndEvent::ignore</code>
 777 </ul>
 778 </dl>
 779 <dt>
 780 <code>IgnoredCharsEvent</code>
 781 <dd>
 782 Generated for a sequence of characters in an ignored marked section in
 783 the instance, but only if the
 784 <code>ParserEventGeneratorKit::outputMarkedSections</code> option is
 785 enabled.  This is non-ESIS information.  The event has the following
 786 members:
 787 <dl>
 788 <dt>
 789 <code>Position pos</code>
 790 <dd>
 791 The position of the first of the ignored characters.
 792 <dt>
 793 <code>CharString data</code>
 794 <dd>
 795 The ignored characters.
 796 </dl>
 797 <dt>
 798 <code>ErrorEvent</code>
 799 <dd>
 800 Generated for each error detected by the parser,
 801 and also for any other cases where the parser produces a message.
 802 This is non-ESIS information.
 803 It has the following members:
 804 <dl>
 805 <dt>
 806 <code>Position pos</code>
 807 <dd>
 808 The position at which the error was detected.
 809 <dt>
 810 <code>ErrorEvent::Type type</code>
 811 <dd>
 812 The type of error.
 813 <p>
 814 <code>ErrorEvent::Type</code> is a local enum with the following possible
 815 values:
 816 <dl>
 817 <dt>
 818 <code>ErrorEvent::quantity</code>
 819 <dd>
 820 Exceeding a quantity limit.
 821 <dt>
 822 <code>ErrorEvent::idref</code>
 823 <dd>
 824 An IDREF to a non-existent ID.
 825 <dt>
 826 <code>ErrorEvent::capacity</code>
 827 <dd>
 828 Exceeding a capacity limit.
 829 <dt>
 830 <code>ErrorEvent::otherError</code>
 831 <dd>
 832 Any other kind of error.
 833 <dt>
 834 <code>ErrorEvent::warning</code>
 835 <dd>
 836 A warning.  Not actually an error.
 837 <dt>
 838 <code>ErrorEvent::info</code>
 839 <dd>
 840 An informational message.  Not actually an error.
 841 </dl>
 842 <dt>
 843 <code>CharString message</code>
 844 <dd>
 845 The message produced by the parser.
 846 If messages are not disabled, this will be the same as the message
 847 printed to standard error.
 848 </dl>
 849 </dl>
 850 <p>
 851 <code>SGMLApplication</code> also has a virtual function
 852 <pre>
 853 void openEntityChange(const OpenEntityPtr &);
 854 </pre>
 855 <p>
 856 which is similar to an event.  An application that wishes to makes use
 857 of position information must maintain a variable of type
 858 <code>OpenEntityPtr</code> representing the current open entity, and
 859 must provide an implementation of the <code>openEntityChange</code>
 860 function that updates this variable.  It can then use the value of
 861 this variable in conjunction with a <code>Position</code> to obtain a
 862 <code>Location</code>; this can be relatively slow.  Unlike events, an
 863 <code>OpenEntityPtr</code> has copy constructors and assignment
 864 operators defined.
 865
 866 <h2>EventGenerator</h2>
 867 <p>
 868 The <code>EventGenerator</code> interface provides the following
 869 functions:
 870 <dl>
 871 <dt>
 872 <code>unsigned run(SGMLApplication &<var>app</var>)</code>
 873 <dd>
 874 Generate the sequence of events, calling the corresponding member of
 875 <code><var>app</var></code> for each event.  Returns the number of
 876 errors.  This must not be called more than once for any
 877 <code>EventGenerator</code>object.
 878 <dt>
 879 <code>
 880 EventGenerator *makeSubdocEventGenerator(const SGMLApplication::Char *<var>s</var>, size_t <var>n</var>)
 881 </code>
 882 <dd>
 883 Makes a new <code>EventGenerator</code> for a subdocument of the
 884 current document.  <var>s</var> and <var>n</var> together specify the
 885 system identifier of the subdocument entity.  These should usually be
 886 obtained from the <code>generatedSystemId</code> member of the
 887 <code>externalId</code> member of the <code>Entity</code> object for
 888 the subdocument entity.  This function can only be called after
 889 <code>run</code> has been called; the call to <code>run</code> need
 890 not have returned, but the <code>SGMLApplication
 891 </code>
 892 must have been passed events from the prolog or instance (ie the SGML
 893 declaration must have been parsed).
 894 <dt>
 895 <code>void inhibitMessages(bool <var>b</var>)</code>
 896 <dd>
 897 If <var>b</var> is true, disables error and warning messages,
 898 otherwise enables them.  Initially errors and warnings are enabled.
 899 This function may be called at any time, including while
 900 <code>run()</code> is executing.
 901 <dt>
 902 <code>void halt()</code>
 903 <dd>
 904 Halt the generation of events by <code>run()</code>.
 905 This can be at any point during the execution of <code>run()</code>.
 906 It is safe to call this function from a different thread from that which
 907 called <code>run()</code>.
 908 </dl>
 909 <h2>ParserEventGeneratorKit</h2>
 910 <p>
 911 The <code>ParserEventGeneratorKit</code> class is used to create an
 912 <code>EventGenerator</code> that  generate events using OpenSP.  It
 913 provides the following members:
 914 <dl>
 915 <dt>
 916 <code>EventGenerator *makeEventGenerator(int <var>nFiles</var>, char *const *<var>files</var>)</code>
 917 <dd>
 918 This returns a new <code>EventGenerator</code> that will generate events
 919 for the SGML document whose document entity is contained in the
 920 <code><var>files</var></code>.
 921 The returned <code>EventGenerator</code> should be deleted when it
 922 is no longer needed.
 923 <code>makeEventGenerator</code> may be called more than once.
 924 <dt>
 925 <code>void setOption(ParserEventGeneratorKit::Option <var>opt</var>)</code>
 926 <dd>
 927 This can be called any time before <code>makeEventGenerator()</code> is called.
 928 <p>
 929 <code>ParserEventGeneratorKit::Option</code> is a local enum with the following possible
 930 values:
 931 <dl>
 932 <dt>
 933 <code>ParserEventGeneratorKit::showOpenEntities</code>
 934 <dd>
 935 This corresponds to the <code>-e</code> option of nsgmls.
 936 <dt>
 937 <code>ParserEventGeneratorKit::showOpenElements</code>
 938 <dd>
 939 This corresponds to the <code>-g</code> option of nsgmls.
 940 <dt>
 941 <code>ParserEventGeneratorKit::outputCommentDecls</code>
 942 <dd>
 943 This will cause <code>CommentDeclEvent</code>s to be generated.
 944 <dt>
 945 <code>ParserEventGeneratorKit::outputMarkedSections</code>
 946 <dd>
 947 This will cause
 948 <code>MarkedSectionStartEvent</code>s,
 949 <code>MarkedSectionStartEvent</code>s
 950 and <code>IgnoredCharsEvent</code>s
 951 to be generated.
 952 <dt>
 953 <code>ParserEventGeneratorKit::outputGeneralEntities</code>
 954 <dd>
 955 This will cause <code>GeneralEntityEvent</code>s to be generated.
 956 <dt>
 957 <code>ParserEventGeneratorKit::showErrorNumbers</code>
 958 <dd>
 959 This corresponds to the <code>-n</code> option of nsgmls.
 960 </dl>
 961 <dt>
 962 <code>
 963 void setOption(ParserEventGeneratorKit::OptionWithArg <var>opt</var>, const char *<var>arg</var>)
 964 </code>
 965 <dd>
 966 This can be called any time before <code>makeEventGenerator()</code> is called.
 967 <p>
 968 <code>ParserEventGeneratorKit::OptionWithArg</code> is a local enum with the following possible
 969 values:
 970 <dl>
 971 <dt>
 972 <code>ParserEventGeneratorKit::addCatalog</code>
 973 <dd>
 974 This corresponds to the <code>-m</code> option of nsgmls.
 975 <dt>
 976 <code>ParserEventGeneratorKit::includeParam</code>
 977 <dd>
 978 This corresponds to the <code>-i</code> option of nsgmls.
 979 <dt>
 980 <code>ParserEventGeneratorKit::enableWarning</code>
 981 <dd>
 982 This corresponds to the <code>-w</code> option of nsgmls.
 983 <dt>
 984 <code>ParserEventGeneratorKit::addSearchDir</code>
 985 <dd>
 986 This corresponds to the <code>-D</code> option of nsgmls.
 987 </dl>
 988 </dl>
 989
 990 <h2>Using the interface</h2>
 991 <p>
 992 Creating an application with this interface involves the following steps:
 993 <ul>
 994 <li>
 995 Derive a class from <code>SGMLApplication</code>,
 996 called, say, <code>MyApplication</code>.
 997 <li>
 998 For each kind of event <code><var>Foo</var>Event</code> that the application
 999 needs information from, define a member of <code>MyApplication</code>
1000 <code>void MyApplication::<var>foo</var>(const <var>Foo</var>Event &)</code>.
1001 <li>
1002 Declare an object of type <code>ParserEventGeneratorKit</code>.
1003 <li>
1004 Optionally set options for the <code>ParserEventGeneratorKit</code> using
1005 <code>ParserEventGeneratorKit::setOption</code>.
1006 <li>
1007 Create an <code>EventGenerator</code> using
1008 <code>ParserEventGeneratorKit::makeEventGenerator</code>.
1009 <li>
1010 Create an instance of <code>MyApplication</code>
1011 (usually on the stack).
1012 <li>
1013 Call <code>EventGenerator::run</code> passing it a reference to
1014 the instance of <code>MyApplication</code>.
1015 <li>
1016 Delete the <code>EventGenerator</code>.
1017 </ul>
1018 <p>
1019 The application must include the <code>ParserEventGeneratorKit.h</code>
1020 file (which in turn includes <code>EventGenerator.h</code> and
1021 <code>SGMLApplication.h</code>), which is in the <code>generic</code>
1022 directory.  If your compiler does not support the standard C++
1023 <code>bool</code> type, you must ensure that <code>bool</code> is
1024 defined as a typedef for <code>int</code>, before including this.  One
1025 way to do this is to include <code>config.h</code> and then
1026 <code>Boolean.h</code> from the <code>lib</code> subdirectory of the OpenSP
1027 distribution.
1028 <p>
1029 On Unix, the application must be linked with the
1030 <code>lib/libsp.a</code> library.
1031
1032 <h2>Example</h2>
1033 <p>
1034 Here's a simple example of an application that uses this interface.
1035 The application prints an outline of the element structure of a
1036 document, using indentation to represent nesting.
1037 <pre>
1038 // The next two lines are only to ensure bool gets defined appropriately.
1039 #include "config.h"
1040 #include "Boolean.h"
1041
1042 #include "ParserEventGeneratorKit.h"
1043 #include &lt;iostream.h>
1044
1045 ostream &amp;operator<<<!>(ostream &amp;os, SGMLApplication::CharString s)
1046 {
1047   for (size_t i = 0; i < s.len; i++)
1048     os << char(s.ptr[i]);
1049   return os;
1050 }
1051
1052 class OutlineApplication : public SGMLApplication {
1053 public:
1054   OutlineApplication() : depth_(0) { }
1055   void startElement(const StartElementEvent &amp;event) {
1056     for (unsigned i = 0; i < depth_; i++)
1057       cout << "    ";
1058     cout << event.gi << '\n';
1059     depth_++;
1060   }
1061   void endElement(const EndElementEvent &amp;) { depth_--; }
1062 private:
1063   unsigned depth_;
1064 };
1065
1066 int main(int argc, char **argv)
1067 {
1068   ParserEventGeneratorKit parserKit;
1069   // Use all the arguments after argv[0] as filenames.
1070   EventGenerator *egp = parserKit.makeEventGenerator(argc - 1, argv + 1);
1071   OutlineApplication app;
1072   unsigned nErrors = egp->run(app);
1073   delete egp;
1074   return nErrors > 0;
1075 }
1076 </pre>
1077 <p>
1078 This example will only work for the non-multibyte version of OpenSP;
1079 for the multibyte version you will need to use the standard C++ library's
1080 facilities for wide character output, or roll your own equivalents
1081 (like the OutputCharStream used by OpenSP applications).
1082 <p>
1083 There's a bigger example in the <code>osgmlnorm</code> directory in the OpenSP
1084 distribution.
1085 This uses the <code>SGMLApplication</code> interface, but it doesn't
1086 use the <code>ParserEventGeneratorKit</code> interface.
1087 </body>
1088 </html>