[Home] [ToC] [Up] [Prev] [Next]
iHTML defines a type and set of functions for accessing a browser's internal parse tree representation. This allows language modules to not only dynamically construct HTML documents, but to also examine and modify existing documents.
A browser must implement these functions. At the very
least, they are used by the iHTML Library component to parse
<OBJECT> markup: the browser hands the
library the node for each of these tags that it encounters, and the
library then uses the browser's parse tree services to examine that
data and determine how to handle it.
void* (This is an opaque
type that is defined by the browser's internal
implementation.)
The HTMLNode is the
object through which other components in the iHTML system
interact with a browser's internal HTML parse tree. It
represents a single node in that tree. E.g., a tag, block of
text, comment, etc. All interaction with the parse tree is
done by calling functions with the opaque pointers to these
nodes.
HTMLNode BR_AllocMarkup(IHLanguage*
lang, IHMarkup owner, const void* type, const char*
attrs)
(IHLanguage*)
lang
(IHMarkup)
owner
(const void*)
type
(const char*)
attrs
(HTMLNode) A newly created
browser-side markup node.
Allocates a new node with the given type and
attributes. If the type is "<text" or
"<comment", the attrs argument is
interpreted as the new node's text.
HTMLNode BR_ChildMarkup(HTMLNode
current)
(HTMLNode)
current
(HTMLNode) The node that is
the first child to current in its
tree.
Returns the node that is the child to the given node in the tree, or NULL if current is a leaf in the tree. This essentially traverses deeper into the parse tree.
HTMLNode BR_CutMarkup(HTMLNode
pos, HTMLNode end)
(HTMLNode)
pos
(HTMLNode)
end
(HTMLNode) The node that
has replaced the first cut node.
Deletes markup nodes from pos to end, and all of their child nodes. If end is NULL, deletes all nodes from pos to the last node in this branch. Returns the markup node that has replaced these in the tree, i.e. the one that is the next after pos.
HTMLNode
BR_FirstMarkup(HTMLNode current)
(HTMLNode)
current
(HTMLNode) The very top/first
node in current's tree.
Returns the absolute first
HTMLNode in the
given tree, i.e. the root of the tree, which should always be
<HTML>
void BR_FreeMarkup(HTMLNode root)
(HTMLNode)
root
Deallocates a tree of HTMLNode objects, being sure to remove all references within it and generally keep everything synchronized with any language-side objects associated with the nodes. The only nodes actually deallocated are the ones owned by the same IHMarkup object as the given root node. However, all references to other owners from these are also removed, so they may be deallocated as a side-effect.
void BR_FreeMarkupAttr(char*
value)
(char*)
value
Deallocates the memory associated with an attribute value previously returned by BR_MarkupAttr(). Any value returned by that function can be used here, including NULL.
void* BR_GetTagID(const char* tag)
(const char*)
tag
(void*) An abstract browser ID
for this tag type.
Returns the ID number the browser uses for
this particular tag. The exact ID code returned is
browser-dependent; it may be an enumeration,
the address of a string, etc. In addition to the normal tag
names, such as "HEAD", "EM",
"TABLE", etc., the following names are
defined:
>text"
>comment"
>text"
>unknown"
If the browser does not recognize the give tag type, it always
returns the ID for the ">unknown" type.
The value returned is almost completely opaque -- the only thing a program can do with a tag ID is to compare it for equality to another tag ID.
HTMLNode BR_InitMarkup(HTMLNode root,
IHLanguage* lang, IHMarkup owner)
(HTMLNode)
root
(IHLanguage*)
lang
(IHMarkup)
owner
(HTMLNode) The last node in
the resulting tree.
Initializes a raw HTMLNode tree returned by the browser's parser. E.g., the NCSA Mosaic implementation fills in each node's "prev" and "parent" parent pointers, and sets the owner of all the nodes to owner and lang. This function must be called on any raw HTMLNode tree which the scripting routines get from the browser. It returns the last node in the resulting tree.
HTMLNode BR_InsertMarkup(HTMLNode pos,
HTMLNode last, HTMLNode markup)
(HTMLNode) pos
(HTMLNode) last
(HTMLNode) markup
<B>.
(HTMLNode) The node that has
replaced the first cut node.
Inserts the given markup node into the tree, making its children the range from pos to the node before next. If pos is the same as next (or the node content type is EMPTY, or it is a text node), the node will have no children. If next is NULL, all of the nodes from pos to the end of this branch will be set as the new node's children.
HTMLNode BR_InsHeadMarkup(HTMLNode
parent, HTMLNode tree)
(HTMLNode)
parent
(HTMLNode)
tree
(HTMLNode) The newly placed
node, identical to tree
Places the given markup node (or a complete HTML tree) as the first child of the given parent node. If it already has a child node, it is inserted before them.
HTMLNode BR_InsTailMarkup(HTMLNode
parent, HTMLNode tree)
(HTMLNode)
parent
(HTMLNode)
tree
(HTMLNode) The newly placed
node, identical to tree
Appends the given markup node (or a complete HTML tree) as the last child of the given parent node.
HTMLNode
BR_LastMarkup(HTMLNode current)
(HTMLNode)
current
(HTMLNode) The very
bottom/last
node in current's tree.
Returns the absolute last
HTMLNode in the
given tree, i.e. the very last leaf node of the tree.
char* BR_MarkupAttr(HTMLNode
node, const char* attr)
(HTMLNode)
node
(const char*)
attr
(char*) A C string
representing the desired
attribute's value.
Returns a pointer to a standard C string that is the value (if any) that the requested attribute has for this node. A NULL indicates this attribute was not supplied, the string "\0" is returned for attributes supplied with no value, and any other string is the attribute's value.
Note that the value returned by this functions must be deallocated when you are done with it by calling BR_FreeMarkupAttr().
IHLanguage* BR_MarkupLanguage(HTMLNode
node)
(HTMLNode)
node
(IHLanguage*) The language of
this node's owner.
Returns a handle on the interface to the
language that owns this node. Since the IHMarkup
is an opaque type, the system can not use it to determine which
language module it exists in. Thus every node must be able to
store that language, so that it's language-side owner can be
manipulated along with it.
IHMarkup BR_MarkupOwner(HTMLNode
node)
(HTMLNode)
node
(IHMarkup) The language-side
object that owns this node.
Every browser node can have a language-side object associated with it, that "owns" that node in the tree. These objects must work together, to keep each other in sync, so they call into each other's components as operations on the tree are performed. This function returns the object that owns this node.
char* BR_MarkupText(HTMLNode
node)
(HTMLNode)
node
(char*) The raw ASCII text
associated with this node.
Returns a pointer to a standard C string, that is the ASCII text associated with it. This function is valid only for nodes of type ">text" and ">comment". Nodes that are actually tags do not have any text associated with them, and return NULL. This text is a part of the node object -- it is valid as long as the node itself exists.
void* BR_MarkupType(HTMLNode
node)
(HTMLNode)
node
(void*) What type of node this
is.
Returns an opaque value that indicates the type of node this is. The only thing that can be done with this to value is to compare it with other type values that have been returned by the browser -- if they are the same, they are the same types.
HTMLNode
BR_NextMarkup(HTMLNode current)
(HTMLNode)
current
(HTMLNode) The node logically
after current in the tree.
Returns a pointer to the markup node that
occurs logically after the given node in its parse tree.
If the given node contains any other nodes
(i.e., it is a <B> with text
inside),
the returned node is the one after its
associated closing tag.
If this is the last node in the branch, a NULL
is returned.
Essentially, this function moves forward through the children of their parent node.
HTMLNode BR_NextMarkupDepth(HTMLNode
current)
(HTMLNode)
current
(HTMLNode) The node that
occurs after current in its parse
tree, in depth-first order.
Returns the node that would occur next in the tree, if a depth-first traversal were being performed. This is essentially the order that the nodes occurred in the original HTML document.
HTMLNode BR_NextMarkupType(HTMLNode
current, const void* type)
(HTMLNode)
current
(const void*)
type
<A>, a text node, etc.
(HTMLNode) The node that
occurs after current in its parse
tree, in depth-first order, and is of the given type.
Performs a depth-first search starting at the given place in the HTML tree, looking for the next node with the given type. Returns NULL if there are none.
HTMLNode BR_ParentMarkup(HTMLNode
current)
(HTMLNode)
current
(HTMLNode) The node that is
the parent to current in its tree.
Returns the node that is the parent to the given node in the tree, or NULL if current is the root of the tree. This essentially traverses up out of the parse tree.
HTMLNode BR_ParseHTML(const char* text,
IHLanguage* lang, IHMarkup owner)
(const char*)
text
(IHLanguage*)
lang
(IHMarkup)
owner
(HTMLNode) The first node in
the newly created HTML parse tree.
Allocates a complete HTML sub-tree based on
the given fragment of ASCII HTML markup. The text is parsed
identically to text in an HTML body or header, except that HTML
fragments are allowed (e.g., a string that begins with
<TABLE>), so that sub-trees can be
created that are later inserted into a complete HTML parse
tree.
HTMLNode BR_PasteMarkup(HTMLNode pos,
HTMLNode tree, int after)
(HTMLNode)
pos
(HTMLNode)
tree
(int)
after
(HTMLNode) The node that is
now at the
same position as pos. This is pos if
after is FALSE, otherwise it is tree
Places the given markup node (or a complete HTML tree) into the tree given by pos. Normally place the new markup into the position pos is at, but if after is TRUE, it will be placed immediately after.
HTMLNode
BR_PrevMarkup(HTMLNode current)
(HTMLNode)
current
(HTMLNode) The node logically
before current in the tree.
Returns a pointer to the markup node that
occurs logically before the given node in its parse tree.
If the given node contains any other nodes
(i.e., it is a <B> with text
inside),
the returned node is the one before its
associated closing tag.
If this is the last node in the branch, a NULL
is returned.
Essentially, this function moves backwards through the children of their parent node.
HTMLNode BR_PrevMarkupDepth(HTMLNode
current)
(HTMLNode)
current
(HTMLNode) The node that
occurs before current in its parse
tree, in depth-first order.
Returns the node that would occur previously in the tree, if a reverse depth-first traversal were being performed. This is essentially the reverse order that the nodes occurred in the original HTML document.
HTMLNode BR_RemoveMarkup(HTMLNode
node)
(HTMLNode)
node
(HTMLNode) The node that
replaced the given node.
Deletes the given markup node, but not any of the nodes that it contains. It returns the markup node that it has been replaced with, which is its first child node.
[Home] [ToC] [Up] [Prev] [Next]
| Dianne Kyra Hackborn <hackbod@angryredplanet.com> | Last modified: Sat Oct 26 20:04:58 PDT 1996 |