📄 generic.htm
字号:
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"><html><head><title>The generic API to SP</title></head><body><h1>The generic API to SP</h1><p>SP provides a generic API in addition to its native API. The genericinterface is much simpler than the native interface. It is generic inthe sense that it could be easily implemented using parsers other thanSP. It provides all ESIS information as well as some otherinformation about the instance that is commonly needed byapplications. However, it doesn't provide access to all informationavailable from SP; in particular, it doesn't provide information aboutthe DTD. It is also slightly less efficient than the nativeinterface.<p>The interface uses two related abstract classes. An<code>SGMLApplication</code> is an object that can handle a number ofdifferent kinds of event which correspond to information in an SGMLdocument. An <code>EventGenerator</code> is an object that cangenerate a sequence of events of the kinds handled by an<code>SGMLApplication</code>. The<code>ParserEventGeneratorKit</code> class makes an<code>EventGenerator</code> that generates events using SP.<h2>Types</h2><p><code>SGMLApplication</code> has a number of local types that are usedin several contexts:<dl><dt><code>Char</code><dd>This typedef is an unsigned integral type that represents a single bitcombination (character). It is <code>unsigned short</code> if<code>SP_MULTI_BYTE</code> is defined and <code>unsigned char</code>otherwise.<dt><code>CharString</code><dd>This struct represents a string of <code>Char</code>.It has the following members:<dl><dt><code>const Char *ptr</code><dd>A pointer to the <code>Char</code>s of the string.<dt><code>size_t len</code><dd>The number of <code>Char</code>s in the string.</dl><dt><code>Location</code><dd>This struct holds information about a location in the entity structureof a document. It is constucted using an <code>OpenEntityPtr</code>and a <code>Position</code>. The <code>CharString</code>s in it willremain valid as long as the <code>OpenEntity</code> that is pointed toby the <code>OpenEntityPtr</code> that was used to construct itremains valid.<p>It has the following members:<dl><dt><code>unsigned long lineNumber</code><dd>The line number.<code>(unsigned long)-1</code> if invalid.<dt><code>unsigned long columnNumber</code><dd>The column number.Note that tabs are not treated specially.<code>(unsigned long)-1</code> if invalid.<dt><code>unsigned long byteOffset</code><dd>The number of bytes in the storage object preceding the location.<code>(unsigned long)-1</code> if invalid.<dt><code>unsigned long entityOffset</code><dd>The number of bit combinations in the entity preceding the location.<code>(unsigned long)-1</code> if invalid.<dt><code>CharString entityName</code><dd>The name of the external entity containing the location.An empty string if invalid.<dt><code>CharString filename</code><dd>The name of the file containing the location.An empty string if invalid.<dt><code>const void *other</code><dd>Other implementation-dependent information about the location. In theSP implementation it will be a pointer to a StorageObjectSpec. 0 ifinvalid.</dl><p>When a location is in an internal entity, the location of the referenceto the entity will be used instead.<dt><code>OpenEntity</code><dd>This class represents a currently open entity. The only use for an<code>OpenEntity</code> is, in conjunction with a<code>Position</code>, to create a <code>Location</code>. An<code>OpenEntity</code> is accessed using an<code>OpenEntityPtr</code>.<dt><code>OpenEntityPtr</code><dd>This class is a reference-counted pointer to an <code>OpenEntity</code>.<dt><code>Position</code><dd>This is an integral type that represents a position in an open entity.The meaning of a <code>Position</code> is completely determined by the<code>OpenEntity</code> object with which it is associated. The onlyuse for an <code>Position</code> is, in conjunction with an<code>OpenEntity</code>, to create a <code>Location</code>.<dt><code>ExternalId</code><dd>This struct represents an external identifier. It has the followingmembers:<dl><dt><code>bool haveSystemId</code><dd>True iff the external identifier included an explicit system identifier.<dt><code>CharString systemId</code><dd>The system identifier included in the external identifier.Valid only if <code>havePublicId</code> is true.<dt><code>bool havePublicId</code><dd>True iff the external identifier included an explicit public identifier.<dt><code>CharString publicId</code><dd>The public identifier included in the external identifier.Valid only if <code>havePublicId</code> is true.<dt><code>bool haveGeneratedSystemId</code><dd>True iff a system identifier was generated for the external identifier.<dt><dt><code>CharString generatedSystemId</code><dd>The system identifier generated for the external identifier.Valid only if <code>haveGeneratedSystemId</code> is true.</dl><dt><code>Notation</code><dd>This struct represents a notation.It has the following members:<dl><dt><code>CharString name</code><dd>The name of the notation.<dt><code>ExternalId externalId</code><dd>The external identifier of the notation.</dl><dt><code>Entity</code><dd>This struct represents an entity.It has the following members.<dl><dt><code>CharString name</code><dd>The name of the entity.<dt><code>Entity::DataType dataType</code><dd>The type of the data of the entity.<p><code>Entity::DataType</code> is a local enum with the following possiblevalues:<dl><dt><code>Entity::sgml</code><dd><dt><code>Entity::cdata</code><dd><dt><code>Entity::sdata</code><dd><dt><code>Entity::ndata</code><dd><dt><code>Entity::subdoc</code><dd><dt><code>Entity::pi</code><dd></dl><dt><code>Entity::DeclType declType</code><dd>The type of the declaration of the entity.<p><code>Entity::DeclType</code> is a local enum with the following possiblevalues:<dl><dt><code>Entity::general</code><dd>The entity is a general entity.<dt><code>Entity::parameter</code><dd>The entity is a parameter entity.<dt><code>Entity::doctype</code><dd>The entity was declared in a doctype declaration.<dt><code>Entity::linktype</code><dd>The entity was declared in a linktype declaration.</dl><dt><code>bool isInternal</code><dd>True iff the entity is internal rather than external.<dt><code>CharString text</code><dd>The replacement text of the entity.Valid only if <code>isInternal</code> is true.<dt><code>ExternalId externalId</code><dd>The external identifier of the entity.Valid only if <code>isInternal</code> is false.<dt><code>const Attribute *attributes</code><dd>Pointer to the data attributes of the entity.Valid only if <code>isInternal</code> is false.<dt><code>size_t nAttributes</code><dd>The number of data attributes of the entity.Valid only if <code>isInternal</code> is false.<dt><code>Notation notation</code><dd>The entity's notation.An empty string if the entity has no notation.Valid only if <code>isInternal</code> is false.</dl><dt><code>Attribute</code><dd>This struct represents an attribute. More precisely it represents theassignment of an attribute value to an attribute name.It has the following members:<dl><dt><code>CharString name</code><dd>The attribute name.<dt><code>Attribute::Type type</code><dd>An enumeration describing the type of the attribute.<p><code>Attribute::Type</code> is a local type with the following possiblevalues:<dl><dt><code>Attribute::invalid</code><dd>The attribute is invalid.<dt><code>Attribute::implied</code><dd>The attribute is an impliable attribute for whichno value was specified.<dt><code>Attribute::cdata</code><dd>The attribute is a CDATA attribute.<dt><code>Attribute::tokenized</code><dd>The attribute is a tokenized attribute.</dl><dt><code>Attribute::Defaulted defaulted</code><dd>An enumeration specifying whether the entity was defaulted, and, ifso, how.This is non-ESIS information.<p><code>Attribute::Defaulted</code> is a local enum with the followingpossible values:<dl><dt><code>Attribute::specified</code><dd>The value was explicitly specified.<dt><code>Attribute::definition</code><dd>The value was defaulted from the attribute definition.<dt><code>Attribute::current</code><dd>The value was defaulted using the CURRENT value of the attribute.</dl><dt><code>size_t nCdataChunks</code><dd>The number of <code>Attribute::CdataChunk</code>s comprising the valueof the attribute. Valid only if <code>type</code> is<code>cdata</code>.<dt><code>const Attribute::CdataChunk *cdataChunks</code><dd>The <code>Attribute::CdataChunk</code>s comprising the value of this attribute.Valid only if <code>type</code> is <code>cdata</code>.<p><code>Attribute::CdataChunk</code> is a local struct with thefollowing members:<dl><dt><code>bool isSdata</code><dd>True iff this chunk is the replacement text of an internal SDATA entity.<dt><code>CharString data</code><dd>The data of this chunk.<dt><code>CharString entityName</code><dd>The name of the internal SDATA entity that this chunk is thereplacement text of. Valid only if <code>isSdata</code> is true.This is non-ESIS information.</dl><dt><code>CharString tokens</code><dd>Valid only if <code>type</code> is <code>Attribute::tokenized</code>.<dt><code>bool isId</code><dd>True iff the declared value is ID.This is non-ESIS information.<dt><code>size_t nEntities</code><dd>The number of entities associated with this attribute.This will be zero unless the declared value is ENTITY or ENTITIES.<dt><code>const Entity *entities</code><dd>The entities associated with this attribute.<dt><code>Notation notation</code><dd>The notation associated with this attribute.If the declared value of the attribute is not NOTATION,then the name member will be an empty string.</dl></dl><h2>Events</h2><p>For each event <code><var>xyz</var>Event</code> handled by<code>SGMLApplication</code>, there is a virtual function of<code>SGMLApplication</code> named <code><var>xyz</var></code> tohandle the event, and a local struct of <code>SGMLApplication</code>named <code><var>Xyz</var>Event</code>.<p>Pointers within an event <code><var>xyz</var>Event</code> are validonly during the call to <code><var>xyz</var></code>. None of thestructs in events have copy constructors or assignment operatorsdefined. It is up to the event handling function to make a copy ofany data that it needs to preserve after the function returns.<p>Except as otherwise stated,the information in events is ESIS information.All position information is non-ESIS information.<p>There are the following types of event:<dl><dt><code>AppinfoEvent</code><dd>Generated for the APPINFO section of the SGML declaration.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of APPINFO parameter of the SGML declaration.<dt><code>bool none</code><dd>True iff APPINFO NONE was specified.<dt><code>CharString string</code><dd>The interpreted value of the minimum literal specifiedin the appinfo parameter of the SGML declaration.Valid only if <code>none</code> is false.</dl><dt><code>PiEvent</code><dd>Generated for a processing instruction.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of the processing instruction.<dt><code>CharString data</code><dd>The system data of the processing instuction.<dt><code>CharString entityName</code><dd>If the processing instruction was the result of thereference to a PI entity, the name of the entity.If not, an empty string.This is non-ESIS information.</dl><dt><code>StartElementEvent</code><dd>Generated for the start of an element.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of the start of the element.<dt><code>CharString gi</code><dd>The generic identifier of the element.<dt><code>Element::ContentType contentType</code><dd>The type of the element's content.This is non-ESIS information.<p><code>Element::ContentType</code> is an enum with the followingpossible values:<dl><dt><code>Element::empty</code><dd>The element has empty content, either because it wasdeclared as EMPTY or because there was a #CONREF attribute.<dt><code>Element::cdata</code><dd>The element has CDATA content.<dt><code>Element::rcdata</code><dd>The element has RCDATA content.<dt><code>Element::mixed</code><dd>The element has mixed content.<dt><code>Element::element</code><dd>The element has element content.</dl><dt><code>bool included</code><dd>True iff the element was an included subelement(rather than a proper subelement).This is non-ESIS information.<dt><code>size_t nAttributes</code><dd>The number of attributes of this element.<dt><code>const Attribute *attributes</code><dd>A pointer to the attributes for this element.</dl><dt><code>EndElementEvent</code><dd>Generated for the end of an elemenet.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of the end of the element.<dt><code>CharString gi</code><dd>The generic identifier of the element.</dl><dt><code>DataEvent</code><dd>Generated for character data.Separate data events may be generated for consecutive data characters.Applications should make no assumptions about how character data is splitinto <code>DataEvent</code>s.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of the first character of the data.<dt><code>CharString data</code><dd>The data.</dl><dt><code>SdataEvent</code><dd>Generated for a reference to an internal sdata entity in content.The event has the following members:<dl><dt><code>Position pos</code><dd>The position of the entity reference.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -