usr/src/cmd/man/src/util/nsgmls.src/doc/generic.htm

   1 <!-- SCCS keyword
   2 #pragma ident   "%Z%%M% %I%     %E% SMI"
   3 -->
   4 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
   5 <html>
   6 <head>
   7 <title>The generic API to SP</title>
   8 </head>
   9 <body>
  10 <h1>The generic API to SP</h1>
  11 <p>
  12 SP provides a generic API in addition to its native API.  The generic
  13 interface is much simpler than the native interface.  It is generic in
  14 the sense that it could be easily implemented using parsers other than
  15 SP.  It provides all ESIS information as well as some other
  16 information about the instance that is commonly needed by
  17 applications.  However, it doesn't provide access to all information
  18 available from SP; in particular, it doesn't provide information about
  19 the DTD.  It is also slightly less efficient than the native
  20 interface.
  21 <p>
  22 The interface uses two related abstract classes.  An
  23 <code>SGMLApplication</code> is an object that can handle a number of
  24 different kinds of event which correspond to information in an SGML
  25 document.  An <code>EventGenerator</code> is an object that can
  26 generate a sequence of events of the kinds handled by an
  27 <code>SGMLApplication</code>.  The
  28 <code>ParserEventGeneratorKit</code> class makes an
  29 <code>EventGenerator</code> that generates events using SP.
  30
  31 <h2>Types</h2>
  32 <p>
  33 <code>SGMLApplication</code> has a number of local types that are used
  34 in several contexts:
  35 <dl>
  36 <dt>
  37 <code>Char</code>
  38 <dd>
  39 This typedef is an unsigned integral type that represents a single bit
  40 combination (character).  It is <code>unsigned short</code> if
  41 <code>SP_MULTI_BYTE</code> is defined and <code>unsigned char</code>
  42 otherwise.
  43 <dt>
  44 <code>CharString</code>
  45 <dd>
  46 This struct represents a string of <code>Char</code>.
  47 It has the following members:
  48 <dl>
  49 <dt>
  50 <code>const Char *ptr</code>
  51 <dd>
  52 A pointer to the <code>Char</code>s of the string.
  53 <dt>
  54 <code>size_t len</code>
  55 <dd>
  56 The number of <code>Char</code>s in the string.
  57 </dl>
  58 <dt>
  59 <code>Location</code>
  60 <dd>
  61 This struct holds information about a location in the entity structure
  62 of a document.  It is constucted using an <code>OpenEntityPtr</code>
  63 and a <code>Position</code>.  The <code>CharString</code>s in it will
  64 remain valid as long as the <code>OpenEntity</code> that is pointed to
  65 by the <code>OpenEntityPtr</code> that was used to construct it
  66 remains valid.
  67 <p>
  68 It has the following members:
  69 <dl>
  70 <dt>
  71 <code>unsigned long lineNumber</code>
  72 <dd>
  73 The line number.
  74 <code>(unsigned long)-1</code> if invalid.
  75 <dt>
  76 <code>unsigned long columnNumber</code>
  77 <dd>
  78 The column number.
  79 Note that tabs are not treated specially.
  80 <code>(unsigned long)-1</code> if invalid.
  81 <dt>
  82 <code>unsigned long byteOffset</code>
  83 <dd>
  84 The number of bytes in the storage object preceding the location.
  85 <code>(unsigned long)-1</code> if invalid.
  86 <dt>
  87 <code>unsigned long entityOffset</code>
  88 <dd>
  89 The number of bit combinations in the entity preceding the location.
  90 <code>(unsigned long)-1</code> if invalid.
  91 <dt>
  92 <code>CharString entityName</code>
  93 <dd>
  94 The name of the external entity containing the location.
  95 An empty string if invalid.
  96 <dt>
  97 <code>CharString filename</code>
  98 <dd>
  99 The name of the file containing the location.
 100 An empty string if invalid.
 101 <dt>
 102 <code>const void *other</code>
 103 <dd>
 104 Other implementation-dependent information about the location.  In the
 105 SP implementation it will be a pointer to a StorageObjectSpec.  0 if
 106 invalid.
 107 </dl>
 108 <p>
 109 When a location is in an internal entity, the location of the reference
 110 to the entity will be used instead.
 111 <dt>
 112 <code>OpenEntity</code>
 113 <dd>
 114 This class represents a currently open entity.  The only use for an
 115 <code>OpenEntity</code> is, in conjunction with a
 116 <code>Position</code>, to create a <code>Location</code>.  An
 117 <code>OpenEntity</code> is accessed using an
 118 <code>OpenEntityPtr</code>.
 119 <dt>
 120 <code>OpenEntityPtr</code>
 121 <dd>
 122 This class is a reference-counted pointer to an <code>OpenEntity</code>.
 123 <dt>
 124 <code>Position</code>
 125 <dd>
 126 This is an integral type that represents a position in an open entity.
 127 The meaning of a <code>Position</code> is completely determined by the
 128 <code>OpenEntity</code> object with which it is associated.  The only
 129 use for an <code>Position</code> is, in conjunction with an
 130 <code>OpenEntity</code>, to create a <code>Location</code>.
 131 <dt>
 132 <code>ExternalId</code>
 133 <dd>
 134 This struct represents an external identifier.  It has the following
 135 members:
 136 <dl>
 137 <dt>
 138 <code>bool haveSystemId</code>
 139 <dd>
 140 True iff the external identifier included an explicit system identifier.
 141 <dt>
 142 <code>CharString systemId</code>
 143 <dd>
 144 The system identifier included in the external identifier.
 145 Valid only if <code>havePublicId</code> is true.
 146 <dt>
 147 <code>bool havePublicId</code>
 148 <dd>
 149 True iff the external identifier included an explicit public identifier.
 150 <dt>
 151 <code>CharString publicId</code>
 152 <dd>
 153 The public identifier included in the external identifier.
 154 Valid only if <code>havePublicId</code> is true.
 155 <dt>
 156 <code>bool haveGeneratedSystemId</code>
 157 <dd>
 158 True iff a system identifier was generated for the external identifier.
 159 <dt>
 160 <dt>
 161 <code>CharString generatedSystemId</code>
 162 <dd>
 163 The system identifier generated for the external identifier.
 164 Valid only if <code>haveGeneratedSystemId</code> is true.
 165 </dl>
 166 <dt>
 167 <code>Notation</code>
 168 <dd>
 169 This struct represents a notation.
 170 It has the following members:
 171 <dl>
 172 <dt>
 173 <code>CharString name</code>
 174 <dd>
 175 The name of the notation.
 176 <dt>
 177 <code>ExternalId externalId</code>
 178 <dd>
 179 The external identifier of the notation.
 180 </dl>
 181 <dt>
 182 <code>Entity</code>
 183 <dd>
 184 This struct represents an entity.
 185 It has the following members.
 186 <dl>
 187 <dt>
 188 <code>CharString name</code>
 189 <dd>
 190 The name of the entity.
 191 <dt>
 192 <code>Entity::DataType dataType</code>
 193 <dd>
 194 The type of the data of the entity.
 195 <p>
 196 <code>Entity::DataType</code> is a local enum with the following possible
 197 values:
 198 <dl>
 199 <dt>
 200 <code>Entity::sgml</code>
 201 <dd>
 202 <dt>
 203 <code>Entity::cdata</code>
 204 <dd>
 205 <dt>
 206 <code>Entity::sdata</code>
 207 <dd>
 208 <dt>
 209 <code>Entity::ndata</code>
 210 <dd>
 211 <dt>
 212 <code>Entity::subdoc</code>
 213 <dd>
 214 <dt>
 215 <code>Entity::pi</code>
 216 <dd>
 217 </dl>
 218 <dt>
 219 <code>Entity::DeclType declType</code>
 220 <dd>
 221 The type of the declaration of the entity.
 222 <p>
 223 <code>Entity::DeclType</code> is a local enum with the following possible
 224 values:
 225 <dl>
 226 <dt>
 227 <code>Entity::general</code>
 228 <dd>
 229 The entity is a general entity.
 230 <dt>
 231 <code>Entity::parameter</code>
 232 <dd>
 233 The entity is a parameter entity.
 234 <dt>
 235 <code>Entity::doctype</code>
 236 <dd>
 237 The entity was declared in a doctype declaration.
 238 <dt>
 239 <code>Entity::linktype</code>
 240 <dd>
 241 The entity was declared in a linktype declaration.
 242 </dl>
 243 <dt>
 244 <code>bool isInternal</code>
 245 <dd>
 246 True iff the entity is internal rather than external.
 247 <dt>
 248 <code>CharString text</code>
 249 <dd>
 250 The replacement text of the entity.
 251 Valid only if <code>isInternal</code> is true.
 252 <dt>
 253 <code>ExternalId externalId</code>
 254 <dd>
 255 The external identifier of the entity.
 256 Valid only if <code>isInternal</code> is false.
 257 <dt>
 258 <code>const Attribute *attributes</code>
 259 <dd>
 260 Pointer to the data attributes of the entity.
 261 Valid only if <code>isInternal</code> is false.
 262 <dt>
 263 <code>size_t nAttributes</code>
 264 <dd>
 265 The number of data attributes of the entity.
 266 Valid only if <code>isInternal</code> is false.
 267 <dt>
 268 <code>Notation notation</code>
 269 <dd>
 270 The entity's notation.
 271 An empty string if the entity has no notation.
 272 Valid only if <code>isInternal</code> is false.
 273 </dl>
 274 <dt>
 275 <code>Attribute</code>
 276 <dd>
 277 This struct represents an attribute.  More precisely it represents the
 278 assignment of an attribute value to an attribute name.
 279 It has the following members:
 280 <dl>
 281 <dt>
 282 <code>CharString name</code>
 283 <dd>
 284 The attribute name.
 285 <dt>
 286 <code>Attribute::Type type</code>
 287 <dd>
 288 An enumeration describing the type of the attribute.
 289 <p>
 290 <code>Attribute::Type</code> is a local type with the following possible
 291 values:
 292 <dl>
 293 <dt><code>Attribute::invalid</code>
 294 <dd>
 295 The attribute is invalid.
 296 <dt><code>Attribute::implied</code>
 297 <dd>
 298 The attribute is an impliable attribute for which
 299 no value was specified.
 300 <dt><code>Attribute::cdata</code>
 301 <dd>
 302 The attribute is a CDATA attribute.
 303 <dt><code>Attribute::tokenized</code>
 304 <dd>
 305 The attribute is a tokenized attribute.
 306 </dl>
 307 <dt>
 308 <code>Attribute::Defaulted defaulted</code>
 309 <dd>
 310 An enumeration specifying whether the entity was defaulted, and, if
 311 so, how.
 312 This is non-ESIS information.
 313 <p>
 314 <code>Attribute::Defaulted</code> is a local enum with the following
 315 possible values:
 316 <dl>
 317 <dt>
 318 <code>Attribute::specified</code>
 319 <dd>
 320 The value was explicitly specified.
 321 <dt>
 322 <code>Attribute::definition</code>
 323 <dd>
 324 The value was defaulted from the attribute definition.
 325 <dt>
 326 <code>Attribute::current</code>
 327 <dd>
 328 The value was defaulted using the CURRENT value of the attribute.
 329 </dl>
 330 <dt>
 331 <code>size_t nCdataChunks</code>
 332 <dd>
 333 The number of <code>Attribute::CdataChunk</code>s comprising the value
 334 of the attribute.  Valid only if <code>type</code> is
 335 <code>cdata</code>.
 336 <dt>
 337 <code>const Attribute::CdataChunk *cdataChunks</code>
 338 <dd>
 339 The <code>Attribute::CdataChunk</code>s comprising the value of this attribute.
 340 Valid only if <code>type</code> is <code>cdata</code>.
 341 <p>
 342 <code>Attribute::CdataChunk</code> is a local struct with the
 343 following members:
 344 <dl>
 345 <dt>
 346 <code>bool isSdata</code>
 347 <dd>
 348 True iff this chunk is the replacement text of an internal SDATA entity.
 349 <dt>
 350 <code>CharString data</code>
 351 <dd>
 352 The data of this chunk.
 353 <dt>
 354 <code>CharString entityName</code>
 355 <dd>
 356 The name of the internal SDATA entity that this chunk is the
 357 replacement text of.  Valid only if <code>isSdata</code> is true.
 358 This is non-ESIS information.
 359 </dl>
 360 <dt>
 361 <code>CharString tokens</code>
 362 <dd>
 363 Valid only if <code>type</code> is <code>Attribute::tokenized</code>.
 364 <dt>
 365 <code>bool isId</code>
 366 <dd>
 367 True iff the declared value is ID.
 368 This is non-ESIS information.
 369 <dt>
 370 <code>size_t nEntities</code>
 371 <dd>
 372 The number of entities associated with this attribute.
 373 This will be zero unless the declared value is ENTITY or ENTITIES.
 374 <dt>
 375 <code>const Entity *entities</code>
 376 <dd>
 377 The entities associated with this attribute.
 378 <dt>
 379 <code>Notation notation</code>
 380 <dd>
 381 The notation associated with this attribute.
 382 If the declared value of the attribute is not NOTATION,
 383 then the name member will be an empty string.
 384 </dl>
 385 </dl>
 386 <h2>Events</h2>
 387 <p>
 388 For each event <code><var>xyz</var>Event</code> handled by
 389 <code>SGMLApplication</code>, there is a virtual function of
 390 <code>SGMLApplication</code> named <code><var>xyz</var></code> to
 391 handle the event, and a local struct of <code>SGMLApplication</code>
 392 named <code><var>Xyz</var>Event</code>.
 393 <p>
 394 Pointers within an event <code><var>xyz</var>Event</code> are valid
 395 only during the call to <code><var>xyz</var></code>.  None of the
 396 structs in events have copy constructors or assignment operators
 397 defined.  It is up to the event handling function to make a copy of
 398 any data that it needs to preserve after the function returns.
 399 <p>
 400 Except as otherwise stated,
 401 the information in events is ESIS information.
 402 All position information is non-ESIS information.
 403 <p>
 404 There are the following types of event:
 405 <dl>
 406 <dt>
 407 <code>AppinfoEvent</code>
 408 <dd>
 409 Generated for the APPINFO section of the SGML declaration.
 410 The event has the following members:
 411 <dl>
 412 <dt><code>Position pos</code>
 413 <dd>
 414 The position of APPINFO parameter of the SGML declaration.
 415 <dt><code>bool none</code>
 416 <dd>
 417 True iff APPINFO NONE was specified.
 418 <dt><code>CharString string</code>
 419 <dd>
 420 The interpreted value of the minimum literal specified
 421 in the appinfo parameter of the SGML declaration.
 422 Valid only if <code>none</code> is false.
 423 </dl>
 424 <dt>
 425 <code>PiEvent</code>
 426 <dd>
 427 Generated for a processing instruction.
 428 The event has the following members:
 429 <dl>
 430 <dt>
 431 <code>Position pos</code>
 432 <dd>
 433 The position of the processing instruction.
 434 <dt>
 435 <code>CharString data</code>
 436 <dd>
 437 The system data of the processing instuction.
 438 <dt>
 439 <code>CharString entityName</code>
 440 <dd>
 441 If the processing instruction was the result of the
 442 reference to a PI entity, the name of the entity.
 443 If not, an empty string.
 444 This is non-ESIS information.
 445 </dl>
 446 <dt>
 447 <code>StartElementEvent</code>
 448 <dd>
 449 Generated for the start of an element.
 450 The event has the following members:
 451 <dl>
 452 <dt>
 453 <code>Position pos</code>
 454 <dd>
 455 The position of the start of the element.
 456 <dt>
 457 <code>CharString gi</code>
 458 <dd>
 459 The generic identifier of the element.
 460 <dt>
 461 <code>Element::ContentType contentType</code>
 462 <dd>
 463 The type of the element's content.
 464 This is non-ESIS information.
 465 <p>
 466 <code>Element::ContentType</code> is an enum with the following
 467 possible values:
 468 <dl>
 469 <dt>
 470 <code>Element::empty</code>
 471 <dd>
 472 The element has empty content, either because it was
 473 declared as EMPTY or because there was a #CONREF attribute.
 474 <dt>
 475 <code>Element::cdata</code>
 476 <dd>
 477 The element has CDATA content.
 478 <dt>
 479 <code>Element::rcdata</code>
 480 <dd>
 481 The element has RCDATA content.
 482 <dt>
 483 <code>Element::mixed</code>
 484 <dd>
 485 The element has mixed content.
 486 <dt>
 487 <code>Element::element</code>
 488 <dd>
 489 The element has element content.
 490 </dl>
 491 <dt>
 492 <code>bool included</code>
 493 <dd>
 494 True iff the element was an included subelement
 495 (rather than a proper subelement).
 496 This is non-ESIS information.
 497 <dt>
 498 <code>size_t nAttributes</code>
 499 <dd>
 500 The number of attributes of this element.
 501 <dt>
 502 <code>const Attribute *attributes</code>
 503 <dd>
 504 A pointer to the attributes for this element.
 505 </dl>
 506 <dt>
 507 <code>EndElementEvent</code>
 508 <dd>
 509 Generated for the end of an elemenet.
 510 The event has the following members:
 511 <dl>
 512 <dt>
 513 <code>Position pos</code>
 514 <dd>
 515 The position of the end of the element.
 516 <dt>
 517 <code>CharString gi</code>
 518 <dd>
 519 The generic identifier of the element.
 520 </dl>
 521 <dt>
 522 <code>DataEvent</code>
 523 <dd>
 524 Generated for character data.
 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 SP.  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 </dl>
 957 <dt>
 958 <code>
 959 void setOption(ParserEventGeneratorKit::OptionWithArg <var>opt</var>, const char *<var>arg</var>)
 960 </code>
 961 <dd>
 962 This can be called any time before <code>makeEventGenerator()</code> is called.
 963 <p>
 964 <code>ParserEventGeneratorKit::OptionWithArg</code> is a local enum with the following possible
 965 values:
 966 <dl>
 967 <dt>
 968 <code>ParserEventGeneratorKit::addCatalog</code>
 969 <dd>
 970 This corresponds to the <code>-m</code> option of nsgmls.
 971 <dt>
 972 <code>ParserEventGeneratorKit::includeParam</code>
 973 <dd>
 974 This corresponds to the <code>-i</code> option of nsgmls.
 975 <dt>
 976 <code>ParserEventGeneratorKit::enableWarning</code>
 977 <dd>
 978 This corresponds to the <code>-w</code> option of nsgmls.
 979 <dt>
 980 <code>ParserEventGeneratorKit::addSearchDir</code>
 981 <dd>
 982 This corresponds to the <code>-D</code> option of nsgmls.
 983 </dl>
 984 </dl>
 985
 986 <h2>Using the interface</h2>
 987 <p>
 988 Creating an application with this interface involves the following steps:
 989 <ul>
 990 <li>
 991 Derive a class from <code>SGMLApplication</code>,
 992 called, say, <code>MyApplication</code>.
 993 <li>
 994 For each kind of event <code><var>Foo</var>Event</code> that the application
 995 needs information from, define a member of <code>MyApplication</code>
 996 <code>void MyApplication::<var>foo</var>(const <var>Foo</var>Event &)</code>.
 997 <li>
 998 Declare an object of type <code>ParserEventGeneratorKit</code>.
 999 <li>
1000 Optionally set options for the <code>ParserEventGeneratorKit</code> using
1001 <code>ParserEventGeneratorKit::setOption</code>.
1002 <li>
1003 Create an <code>EventGenerator</code> using
1004 <code>ParserEventGeneratorKit::makeEventGenerator</code>.
1005 <li>
1006 Create an instance of <code>MyApplication</code>
1007 (usually on the stack).
1008 <li>
1009 Call <code>EventGenerator::run</code> passing it a reference to
1010 the instance of <code>MyApplication</code>.
1011 <li>
1012 Delete the <code>EventGenerator</code>.
1013 </ul>
1014 <p>
1015 The application must include the <code>ParserEventGeneratorKit.h</code>
1016 file (which in turn includes <code>EventGenerator.h</code> and
1017 <code>SGMLApplication.h</code>), which is in the <code>generic</code>
1018 directory.  If your compiler does not support the standard C++
1019 <code>bool</code> type, you must ensure that <code>bool</code> is
1020 defined as a typedef for <code>int</code>, before including this.  One
1021 way to do this is to include <code>config.h</code> and then
1022 <code>Boolean.h</code> from the <code>lib</code> subdirectory of the SP
1023 distribution.
1024 <p>
1025 On Unix, the application must be linked with the
1026 <code>lib/libsp.a</code> library.
1027
1028 <h2>Example</h2>
1029 <p>
1030 Here's a simple example of an application that uses this interface.
1031 The application prints an outline of the element structure of a
1032 document, using indentation to represent nesting.
1033 <pre>
1034 // The next two lines are only to ensure bool gets defined appropriately.
1035 #include "config.h"
1036 #include "Boolean.h"
1037
1038 #include "ParserEventGeneratorKit.h"
1039 #include &lt;iostream.h>
1040
1041 ostream &amp;operator<<<!>(ostream &amp;os, SGMLApplication::CharString s)
1042 {
1043   for (size_t i = 0; i < s.len; i++)
1044     os << char(s.ptr[i]);
1045   return os;
1046 }
1047
1048 class OutlineApplication : public SGMLApplication {
1049 public:
1050   OutlineApplication() : depth_(0) { }
1051   void startElement(const StartElementEvent &amp;event) {
1052     for (unsigned i = 0; i < depth_; i++)
1053       cout << "    ";
1054     cout << event.gi << '\n';
1055     depth_++;
1056   }
1057   void endElement(const EndElementEvent &amp;) { depth_--; }
1058 private:
1059   unsigned depth_;
1060 };
1061
1062 int main(int argc, char **argv)
1063 {
1064   ParserEventGeneratorKit parserKit;
1065   // Use all the arguments after argv[0] as filenames.
1066   EventGenerator *egp = parserKit.makeEventGenerator(argc - 1, argv + 1);
1067   OutlineApplication app;
1068   unsigned nErrors = egp->run(app);
1069   delete egp;
1070   return nErrors > 0;
1071 }
1072 </pre>
1073 <p>
1074 There's a bigger example in the <code>sgmlnorm</code> directory in the SP
1075 distribution.
1076 This uses the <code>SGMLApplication</code> interface, but it doesn't
1077 use the <code>ParserEventGeneratorKit</code> interface.
1078 <p>
1079 <address>
1080 James Clark<BR>
1081 jjc@jclark.com
1082 </address>
1083 </body>
1084 </html>