[Note for Netscape, MSIE, Mosaic and most other browsers: get a browser that supports HTML shorttags. This document is littered with these elements, which are an official part of the HTML standard and have been since HTML 1.0. The HTML Widget Set described on these pages does know about them...]

XmHTMLParser provides an Object capable of parsing HTML 3.2 text. It offers both HTML 3.2 verification and repair of non-conforming HTML documents as well as incremental document parsing. XmHTMLParser objects can be used for creating a fully interactive HTML 3.2 parser application thru XmHTMLParser's callback resources.

## Class Information

Include File: | <Xm/Parser.h>
Class Name: | XmHTMLParser
Class Hierarchy: | Object->XmHTMLParser
Class Pointer: | xmHTMLParserObjectClass
Functions/Macros: | XmCreateHTMLParser, XmHTMLParser... routines, XmIsHTMLParser.

## New Resources

XmHTMLParser defines the following resources.

<b/Name/ | <b/Type/ | <b/Default/ | <b/Access/
XmNmimeType | String | text/html | CSG
XmNparserIsProgressive | Boolean | False | CSG
XmNretainSource | Boolean | False | CSG
XmNstrictHTMLChecking | Boolean | False | CSG
XmNuserData | Pointer | NULL | CSG

XmNmimeType
  This resource informs how XmHTMLParser should parse text. XmHTMLParser knows how to handle the following mime types: text/html, text/plain and every image mime type specification that starts with /image/.

XmNparserIsProgressive
  Setting this resource to <b/True/ will cause XmHTMLParser to enter progressive mode.

XmNretainSource
  When set to <b/True/, XmHTMLParser will keep the source text it has parsed until new text should be parsed. The default behaviour is to discard the source text once it has been parsed.

XmNstrictHTMLChecking
  This resource enables <b/strict/ checking of HTML files according to the <b/HTML 3.2/ standard. Beware that <i/many/ (if not all) HTML files are in violation of this standard (this document is) and that the result might be not exactly what is intended.

XmNuserData
  A pointer to data that the application can attach to the Object. This resource is unused internally.

## Callback Resources

XmHTMLParser defines the following callback resources:

<b/Callback/ | <b/Reason Constant/ | <b/Callback Structure/
XmNdocumentCallback | XmCR_HTML_DOCUMENT | XmHTMLDocumentCallbackStruct
XmNmodifyVerifyCallback | XmCR_HTML_MODIFYING_TEXT_VALUE | XmHTMLVerifyCallbackStruct
XmNparserCallback | XmCR_HTML_PARSER | XmXmHTMLParserCallbackStruct

All callback resources also reference XmAnyCallbackStruct.

XmNdocumentCallback is activated when XmHTMLParser has finished parsing a document and before XmHTMLParserSetString or XmHTMLParserUpdateSource returns.

XmNmodifyVerifyCallback is activated when XmHTMLParser is about to insert or remove text in or from the current source text.

XmNparserCallback is activated when XmHTMLParser encounters a HTML element that is in error. XmHTMLParser detects unknown, unbalanced, badly placed as well as unterminated HTML elements and HTML 3.2 violations.

### XmHTMLDocumentCallbackStruct

The XmNdocumentCallback callback resource references the following structure:

    typedef struct
    {
    	int		reason;		/* the reason the callback was called */
    	XEvent		*event;		/* always NULL */
    	Boolean		html32;		/* True when document was HTML 3.2 conforming */
    	Boolean		verified;	/* True when document has been verified */
    	Boolean		balanced;	/* True when parser tree is balanced */
    	Boolean		terminated;	/* True if parser is terminated prematurely */
    	int		pass_level;	/* current parser level count. */
    	Boolean		redo;		/* See below */
    }XmHTMLDocumentCallbackStruct;

The <i/reason/ field is always XmCR_HTML_DOCUMENT.

The <i/event/ field is always NULL.

The <i/html32/ field is set to <b/True/ when the loaded document was found to be HTML 3.2 conformant. XmHTML performs checks on both the occurance and contents of all HTML 3.2 elements.

The <i/verified/ field is set to <b/True/ when XmHTML has successfully verified the HTML semantics of the loaded document.

The <i/balanced/ field is set to <b/True/ when the parser has generated a balanced tree. A balanced tree is one in which each terminated HTML element has its opening and closing members at the same level in the tree.

The <i/terminated/ field will be set to True when the parser finished parsing the current document before it actually ended. This can only happen when the parser encounters an internal error. The <i/pass_level/ field contains the number of passes performed so far by the parser. This number starts at 1.

Setting the <i/redo/ field to <b/True/ will instruct the parser to make another pass on the current document. It is only effective when the parser failed to generate a balanced tree. Since using an unbalanced tree can lead to weird markup, XmHTML will set this field to <b/True/ by default.

When no XmNdocumentCallback callback resource is installed, XmHTML will make at most two passes on the current document. See the Parser Description document for more information.

### XmHTMLVerifyCallbackStruct

The XmNmodifyVerifyCallback callback resource references the following structure:

    typedef struct{
    	int 		reason;		/* the reason the callback was called */
    	XEvent		*event;		/* always NULL */
    	Boolean		doit;		/* unused */
    	int		action;		/* type of modification */
    	int		line_no;	/* current line number in input text */
    	int		start_pos;	/* start of text to change */
    	int		end_pos;	/* end of text to change */
    	XmHTMLTextBlock	text;		/* describes text to remove or insert */
    }XmHTMLVerifyCallbackStruct, *XmHTMLVerifyPtr;

The <i/reason/ field is always XmCR_HTML_MODIFYING_TEXT_VALUE.

The <i/event/ field is always NULL.

The <i/action/ field contains the type of action XmHTMLParser is about to make to the current source text. When this field contains the value <b/HTML_REMOVE/, XmHTMLParser is removing text, and when it is <b/HTML_INSERT/, XmHTMLParser is inserting text.

<i/start_pos/ specifies the location at which to start modifying text while <i/end_pos/ specifies the location at which to stop modifying text. <i/end_pos/ is the same as <i/start_pos/ when <i/action/ is <b/HTML_INSERT/. Both positions are always absolute to the first character of the current source text (defined as 0) and take the number of characters inserted or removed so far into account.

The <i/line_no/ field contains the line number in the <i/unmodified/ source text where the action takes place.

The <i/text/ field points to the structure below, which specifies the text that is about to be inserted or removed.

    typedef struct{
    	String		ptr;		/* pointer to text to remove/insert */
    	int		len;		/* length of this text */
    }XmHTMLTextBlockRec, *XmHTMLTextBlock;

The <i/doit/ field is currently unused and is reserved for future use.

### XmHTMLParserCallbackStruct

The XmNparserCallback resource references the following structure:

    typedef struct{
    	int		reason;		/* the reason the callback was called */
    	XEvent		*event;		/* always NULL */
    	int		errno;		/* total error count uptil now */
    	int		line_no;	/* current line number in input text */
    	int		start_pos;	/* start of text in error */
    	int		end_pos;	/* end of text in error */
    	parserError	error;		/* type of error */
    	unsigned char	action;		/* suggested correction action */
    	XmHTMLTextBlock	repair;		/* proposed element to insert */
    	XmHTMLTextBlock	current;	/* current element */
    	XmHTMLTextBlock	offender;	/* offending element */
    }XmHTMLParserCallbackStruct, *XmHTMLParserPtr;

The <i/reason/ field is always XmCR_HTML_PARSER

The <i/event/ field is always NULL.

The <i/errno/ field contains the total number of errors encountered so far.

The <i/line_no/ field contains the line number in the <i/unmodified/ source text where the error was found.

<i/start_pos/ specifies the location at which the offending element starts while <i/end_pos/ specifies the location at which the offending element ends. Both positions are always absolute to the first character of the current source text (defined as 0) and take the number of characters inserted or removed so far into account.

<i/current/ describes the element prior to inserting the offending element, <i/offender/ describes the element that is in error, and <i/repair/ describes the element that can possibly repair this error. Except when <i/error/ is HTML_TERMINATE or HTML_NOTIFY, <i/offender/ will always contain a valid value.

The <i/error/ field indicates the type of error encountered by XmHTMLParser. The table below lists all possible values for this field, a description of what this error represents, the default action XmHTMLParser undertakes when this error is encountered and whether the <i/current/ and <i/repair/ fields are valid.

<b/error/ | <b/Description/ | <b/Default Action/ | current/repair
HTML_BAD | An element is completely out of order and the internal autocorrection routines cannot find a proper place for this element. | HTML_REMOVE | Yes/No
HTML_CLOSE_BLOCK | A closing block level element is encountered while it was never opened. | HTML_REMOVE | No/Yes
HTML_INTERNAL | An internal error was encountered. | HTML_TERMINATE | No/No
HTML_NOTIFY | Notification of insertion of an optional opening/closing element. | HTML_INSERT | No/Yes
HTML_OPEN_BLOCK | A new block-level element is encountered while a previous block element is still open. | HTML_INSERT | Yes/Yes
HTML_OPEN_ELEMENT | an unbalanced terminator is encountered. | HTML_SWITCH | Yes/Yes
HTML_VIOLATION | a HTML 3.2 violation was encountered. | HTML_INSERT, HTML_KEEP or HTML_REMOVE | Yes/Dynamic
HTML_UNKNOWN_ELEMENT | an unknown element was encountered. | HTML_REMOVE | No/No

The HTML_VIOLATION error is a special case. When XmHTMLParser can find a suitable element that will cause the offending element to be no longer in violation of the HTML 3.2 standard, it will propose to insert this new element. When it can't find one, the default action depends on the value of the XmNstrictHTMLChecking resource. When this resource is set to <b/True/, the default action will be to remove the offending element and to keep it otherwise.

<i/action/ suggests the appropriate action to undertake in response to a given error. Setting this action field to a different value than the suggested one will cause the parser to change its behavior. Shown below are all possible values for the <i/action/ field, their meaning and for which error this action is a valid response. When action is set to <i/HTML_TERMINATE/ the parsing process will be terminated immediatly.

<b/Action/ | <b/Meaning/ | <b/Allowed For/
HTML_ALIAS | Replace <i/offender/ with <i/repair/ | HTML_UNKNOWN_ELEMENT
HTML_IGNORE | Ignore this error, proceed as if nothing happened | HTML_BAD, HTML_INTERNAL
HTML_INSERT | Insert <i/repair/ | HTML_CLOSE_BLOCK, HTML_NOTIFY, HTML_OPEN_BLOCK, HTML_VIOLATION
HTML_KEEP | Keep <i/offender/ | HTML_CLOSE_BLOCK, HTML_OPEN_BLOCK, HTML_VIOLATION
HTML_REMOVE | Remove <i/offender/ | all <b/except/ HTML_NOTIFY and HTML_INTERNAL
HTML_SWITCH | Switch <i/offender/ and <i/repair/ | HTML_OPEN_ELEMENT
HTML_TERMINATE | Terminate parser | All errors

## Inherited Resources

XmHTMLParser inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them.

<b/Resource/ | <b/Inherited From/
XmNdestroyCallback | Object

## Translations

XmHTMLParser does not define any translations.

## Action Routines

XmHTMLParser does not define any actions.

©Copyright 1996-1997 by Ripley Software Development
Last update: September 19, 1997 by Koen