1. Types and operations

NOTE: Names of element types, attributes and entities should be treated as far as possible as a real type. In versions prior to 1.0 names are represented by lisp symbols but in 1.0 they are strings.

Perhaps I should make a `psgml-api.el' that defines some functions to deal with names. Then it would be possible to write code that works in both 0.4 and 1.0.

1.1 The element structure

Data type: element

The basic data type representing the element structure is the Element (this happens to be a node in the parse tree).

1.1.1 Mapping buffer positions to elements

Function: sgml-find-context-of pos

Return the element current at buffer position pos. If pos is in markup, sgml-markup-type will be a symbol identifying the markup type. It will be nil if pos is outside markup.

Function: sgml-find-element-of pos

Return the element containing the character at buffer position pos.

1.1.2 Functions operating on elements

Function: sgml-element-name element

Returns the name of the element. (obsolete)

Function: sgml-element-gi element

Return the general identifier (string) of element.

Function: sgml-element-level element

Returns the level of element in the element structure. The document element is level 1.

1.1.2.1 Structure

Function: sgml-top-element

Return the document element.

Function: sgml-off-top-p element

True if element is the pseudo element above the document element.

These functions return other related elements, or possibly nil.

Function: sgml-element-content element

First element in content of element, or nil.

Function: sgml-element-next element

Next sibling of element. To loop thru all sub elements of an element, el, You could do like this:

(let ((c (sgml-element-content el))) (while c <<Do something with c>> (setq c (sgml-element-next c))))

Function: sgml-element-parent element

Parent of element.

1.1.2.2 Tags

Function: sgml-element-stag-optional element

Return true if the start-tag of element is omissible.

Function: sgml-element-etag-optional element

Return true if the end-tag of element is omissible.

Function: sgml-element-stag-len element

Return the length of the start-tag of element. If the start-tag has been omitted the length is 0.

Function: sgml-element-etag-len element

Return the length of the end-tag of element. If the end-tag has been omitted the length is 0.

Function: sgml-element-net-enabled element

Return true, if element or some parent of the element has null end tag (NET) enabled. Return t, if it is element that has NET enabled.

1.1.2.3 Positions

These functions relates an element to positions in the buffer.

Function: sgml-element-start element

Position of start of element.

Function: sgml-element-end element

Position after element.

Function: sgml-element-stag-end element

Position after start-tag of element.

Function: sgml-element-etag-start element

Position before end-tag of element.

1.1.2.4 Attributes

Function: sgml-element-attlist element

Return the attribute declaration list for element.

Function: sgml-element-attribute-specification-list element

Return the attribute specification list for element.

Function: sgml-element-attval element attribute

Return the value of the attribute in element, string or nil.

1.1.2.5 Misc technical

Function: sgml-element-data-p element

True if element can contain data characters.

Function: sgml-element-mixed element

True if element has mixed content.

Function: sgml-element-eltype element

Function: sgml-element-empty element

True if element is empty.

Function: sgml-element-excludes element

Function: sgml-element-includes element

Function: sgml-element-model element

Declared content or content model of element.

Function: sgml-element-context-string element

Return string describing context of element.

1.2 Attribute Types

Basic types for attributes are names and values. (See note about names in 1. Types and operations.) And attribute values (attval) by lisp strings.

1.2.1 Attribute Declaration List Type

Data type: attlist attdecl*

This is the result of the ATTLIST declarations in the DTD. All attribute declarations for an element is the elements attlist.

Function: sgml-lookup-attdecl name attlist

Return attribute declaration (attdecl) for attribute name in attribute declaration list attlist.

Function: sgml-attribute-with-declared-value attlist declared-value

Find the first attribute in attlist that has declared-value.

1.2.2 Attribute Declaration Type

Data type: attdecl name declared-value default-value

This is the representation of an individual attribute declaration contained in an ATTLIST declaration.

Function: sgml-make-attdecl name declared-value default-value

Produces an attdecl.

Function: sgml-attdecl-name attdecl

Returns the name of an attribute declaration.

Function: sgml-attdecl-declared-value attdecl

Returns the declared-value of attribute declaration attdecl.

Function: sgml-attdecl-default-value: attdecl

Returns the default-value of attribute declaration attdecl.

1.2.3 Declared Value Type

Data type: declared-value (token-group | notation | simple)

A declared value of an SGML attribute can be of different kinds. If the declared value is a token group there is an associated list of name tokens. For notation there is also a list of associated names, the allowed notation names. The other declared values are represented by the type name as a lisp symbol.

Function: sgml-declared-value-token-group declared-value

Return the name token group for the declared-value. This applies to name token groups. For other declared values nil is returned.

Function: sgml-declared-value-notation declared-value

Return the list of notation names for the declared-value. This applies to notation declared value. For other declared values nil is returned.

1.2.4 Default Value Type

Data type: default-value (required | implied | conref | specified )

There are several kinds of default values. The required, implied, and conref has no associated information. The specified have an associated attribute value and can be either fixed or normal.

Function: sgml-make-default-value type &optional attval

Function: sgml-default-value-attval default-value

Return the actual default value of the declared default-value. The actual value is a string. Return nil if no actual value.

Function: sgml-default-value-type-p type default-value

Return true if default-value is of type. Where type is a symbol, one of required, implied, conref, or fixed.

1.2.5 Attribute Specification Type

Data type: attspec name attval

This is the result of parsing an attribute specification.

Function: sgml-make-attspec name attval

Create an attspec from name and attval. Special case, if attval is nil this is an implied attribute.

Function: sgml-attspec-name attspec

Return the name of the attribute specified by attspec.

Function: sgml-attspec-attval attspec

Return the value (attval) of attribute specification attspec. If attspec is nil, nil is returned.

1.2.6 Attribute Specification List Type

Data type: asl attspec*

This is the result of parsing an attribute specification list.

Function: sgml-lookup-attspec name asl

Return the attribute specification for attribute with name in the attribute specification list asl. If the attribute is unspecified nil is returned.

1.3 Parser state

The state of the parser that needs to be kept between commands are stored in a buffer local variable. Some global variables are initialised from this variable when parsing starts.

Variable: sgml-buffer-parse-state

The state of the parser that is kept between commands. The value of this variable is of type pstate.

Data type: pstate

The parser state.

Function: sgml-pstate-dtd pstate

The document type information (dtd) for the parser.

1.4 DTD

Data type: dtd

Represents what PSGML knows about the DTD.

Function: sgml-dtd-doctype dtd

The document type name.

Function: sgml-dtd-eltypes dtd

The table of element types.

Function: sgml-dtd-entities dtd

The table of declared general entities (entity-table).

Function: sgml-dtd-parameters dtd

The table of declared parameter entities (entity-table).

Function: sgml-dtd-shortmaps dtd

The list of short reference maps.

Function: sgml-dtd-notations dtd

Not yet implemented.

1.5 Entities

Data type: entity

An entity has the following properties:

name

The name of the entity (a string). This is either the name of a declared entity (general or parameter) or the doctype name if it is the implicit entity referred to by the doctype declaration.

type

This is a symbol. It is text if it is a text entity, other values are cdata, ndata, sdata, sgml or dtd.

text

This is the text of the entity, either a string or an external identifier.

Operations on entities

Function: sgml-make-entity name type text

Create an entity.

Function: sgml-entity-name entity

The name of the entity.

Function: sgml-entity-type entity

The type of the entity.

Function: sgml-entity-text entity

The text of the entity.

Function: sgml-entity-insert-text entity

Insert the text of the entity into the current buffer at point.

Function: sgml-entity-data-p entity

True if entity is a data entity, that is not of type text.

Data type: entity-table

A table of entities that can be referenced by entity name.

Function: sgml-lookup-entity name entity-table

The entity with named name in the table entity-table. If no such entity exists, nil is returned.

Function: sgml-entity-declare name entity-table type text

Create an entity from name, type and text; and enter the entity into the table entity-table.

Function: sgml-entity-completion-table entity-table

Make a completion table from the entity-table.

Function: sgml-map-entities fn entity-table &optional collect

Apply the function fn to all entities in entity-table. If collect is t, the results of the applications are collected in a list and returned.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.