1 Introduction
2 SHTML and SXML
shtml-comment-symbol
shtml-decl-symbol
shtml-empty-symbol
shtml-end-symbol
shtml-entity-symbol
shtml-pi-symbol
shtml-start-symbol
shtml-text-symbol
shtml-top-symbol
shtml-named-char-id
shtml-numeric-char-id
make-shtml-entity
shtml-entity-value
3 Tokenizing
make-html-tokenizer
tokenize-html
shtml-token-kind
4 Parsing
parse-html/ tokenizer
html->sxml-0nf
html->sxml-1nf
html->sxml-2nf
html->sxml
html->shtml
5 Emitting HTML
write-shtml-as-html
shtml->html
6 History
7 Legal
Version: 0.20

HtmlPrag: Pragmatic Parsing and Emitting of HTML using SXML and SHTML

Neil Van Dyke

License: LGPL 3   Web: http://www.neilvandyke.org/htmlprag/

 (require (planet neil/htmlprag:1:=7))

1 Introduction

Note: This package has been obsoleted by newer SXML/xexp tools of the author.

HtmlPrag provides permissive HTML parsing and emitting capability to Scheme programs. The parser is useful for software agent extraction of information from Web pages, for programmatically transforming HTML files, and for implementing interactive Web browsers. HtmlPrag emits “SHTML,” which is an encoding of HTML in SXML, so that conventional HTML may be processed with XML tools such as SXPath. Like Oleg Kiselyov’s SSAX-based HTML parser, HtmlPrag provides a permissive tokenizer, but also attempts to recover structure. HtmlPrag also includes procedures for encoding SHTML in HTML syntax.

The HtmlPrag parsing behavior is permissive in that it accepts erroneous HTML, handling several classes of HTML syntax errors gracefully, without yielding a parse error. This is crucial for parsing arbitrary real-world Web pages, since many pages actually contain syntax errors that would defeat a strict or validating parser. HtmlPrag’s handling of errors is intended to generally emulate popular Web browsers’ interpretation of the structure of erroneous HTML. We euphemistically term this kind of parse “pragmatic.”

HtmlPrag also has some support for XHTML, although XML namespace qualifiers are currently accepted but stripped from the resulting SHTML. Note that valid XHTML input is of course better handled by a strict XML parser.

HtmlPrag requires R5RS, SRFI-6, and SRFI-23. This version of HtmlPrag is specific to PLT Scheme, due to a transition period in how portability is handled, but the exceedingly portable version 0.16 is available at: http://www.neilvandyke.org/htmlprag/htmlprag-0-16.scm

2 SHTML and SXML

SHTML is a variant of SXML, with two minor but useful extensions:

shtml-comment-symbol : any/c

shtml-decl-symbol : any/c

shtml-empty-symbol : any/c

shtml-end-symbol : any/c

shtml-entity-symbol : any/c

shtml-pi-symbol : any/c

shtml-start-symbol : any/c

shtml-text-symbol : any/c

shtml-top-symbol : any/c

These variables are bound to the following case-sensitive symbols used in SHTML, respectively: *COMMENT*, *DECL*, *EMPTY*, *END*, *ENTITY*, *PI*, *START*, *TEXT*, and *TOP*. These can be used in lieu of the literal symbols in programs read by a case-insensitive Scheme reader.

shtml-named-char-id : any/c

shtml-numeric-char-id : any/c

These variables are bound to the SHTML entity public identifier strings used in SHTML *ENTITY* named and numeric character entity references.

(make-shtml-entity val)  any/c
  val : any/c

Yields an SHTML character entity reference for val. For example:

(make-shtml-entity "rArr")                  ==> (& rArr)
(make-shtml-entity (string->symbol "rArr")) ==> (& rArr)
(make-shtml-entity 151)                     ==> (& 151)

(shtml-entity-value obj)  any/c
  obj : any/c

Yields the value for the SHTML entity obj, or #f if obj is not a recognized entity. Values of named entities are symbols, and values of numeric entities are numbers. An error may raised if obj is an entity with system ID inconsistent with its public ID. For example:

(define (f s) (shtml-entity-value (cadr (html->shtml s))))
(f " ")  ==> nbsp
(f "ߐ") ==> 2000

3 Tokenizing

The tokenizer is used by the higher-level structural parser, but can also be called directly for debugging purposes or unusual applications. Some of the list structure of tokens, such as for start tag tokens, is mutated and incorporated into the SHTML list structure emitted by the parser.

(make-html-tokenizer in normalized?)  any/c
  in : any/c
  normalized? : any/c

Constructs an HTML tokenizer procedure on input port in. If boolean normalized? is true, then tokens will be in a format conducive to use with a parser emitting normalized SXML. Each call to the resulting procedure yields a successive token from the input. When the tokens have been exhausted, the procedure returns the null list. For example:

(define input (open-input-string "<a href=\"foo\">bar</a>"))
(define next  (make-html-tokenizer input #f))
(next) ==> (a (@ (href "foo")))
(next) ==> "bar"
(next) ==> (*END* a)
(next) ==> ()
(next) ==> ()

(tokenize-html in normalized?)  any/c
  in : any/c
  normalized? : any/c

Returns a list of tokens from input port in, normalizing according to boolean normalized?. This is probably most useful as a debugging convenience. For example:

(tokenize-html (open-input-string "<a href=\"foo\">bar</a>") #f)
==> ((a (@ (href "foo"))) "bar" (*END* a))

(shtml-token-kind token)  any/c
  token : any/c

Returns a symbol indicating the kind of tokenizer token: *COMMENT*, *DECL*, *EMPTY*, *END*, *ENTITY*, *PI*, *START*, *TEXT*. This is used by higher-level parsing code. For example:

(map shtml-token-kind
     (tokenize-html (open-input-string "<a<b>><c</</c") #f))
==> (*START* *START* *TEXT* *START* *END* *END*)

4 Parsing

Most applications will call a parser procedure such as html->shtml rather than calling the tokenizer directly.

(parse-html/tokenizer tokenizer    
  normalized?)  any/c
  tokenizer : any/c
  normalized? : any/c

Emits a parse tree like html->shtml and related procedures, except using tokenizer as a source of tokens, rather than tokenizing from an input port. This procedure is used internally, and generally should not be called directly.

(html->sxml-0nf input)  any/c
  input : any/c

(html->sxml-1nf input)  any/c
  input : any/c

(html->sxml-2nf input)  any/c
  input : any/c

(html->sxml input)  any/c
  input : any/c

(html->shtml input)  any/c
  input : any/c

Permissively parse HTML from input, which is either an input port or a string, and emit an SHTML equivalent or approximation. To borrow and slightly modify an example from Kiselyov’s discussion of his HTML parser:

(html->shtml
 "<html><head><title></title><title>whatever</title></head><body>\n<a href=\"url\">link</a><p align=center><ul compact style=\"aa\">\n<p>BLah<!-- comment <comment> --> <i> italic <b> bold <tt> ened</i>\nstill &lt; bold </b></body><P> But not done yet...")
 
 
 
==>
(*TOP* (html (head (title) (title "whatever"))
             (body "\n"
                   (a (@ (href "url")) "link")
                   (p (@ (align "center"))
                      (ul (@ (compact) (style "aa")) "\n"))
                   (p "BLah"
                      (*COMMENT* " comment <comment> ")
                      " "
                      (i " italic " (b " bold " (tt " ened")))
                      "\n"
                      "still < bold "))
             (p " But not done yet...")))

Note that in the emitted SHTML the text token "still < bold" is not inside the b element, which represents an unfortunate failure to emulate all the quirks-handling behavior of some popular Web browsers.

The procedures html->sxml-nnf for n 0 through 2 correspond to 0th through 2nd normal forms of SXML as specified in SXML, and indicate the minimal requirements of the emitted SXML.

html->sxml and html->shtml are currently aliases for html->sxml-0nf, and can be used in scripts and interactively, when terseness is important and any normal form of SXML would suffice.

5 Emitting HTML

Two procedures encoding the SHTML representation as conventional HTML, write-shtml-as-html and shtml->html. These are perhaps most useful for emitting the result of parsed and transformed input HTML. They can also be used for emitting HTML from generated or handwritten SHTML.

(write-shtml-as-html shtml    
  out    
  foreign-filter)  any/c
  shtml : any/c
  out : any/c
  foreign-filter : any/c

Writes a conventional HTML transliteration of the SHTML shtml to output port out. If out is not specified, the default is the current output port. HTML elements of types that are always empty are written using HTML4-compatible XHTML tag syntax.

If foreign-filter is specified, it is a procedure of two argument that is applied to any non-SHTML (“foreign”) object encountered in shtml, and should yield SHTML. The first argument is the object, and the second argument is a boolean for whether or not the object is part of an attribute value.

No inter-tag whitespace or line breaks not explicit in shtml is emitted. The shtml should normally include a newline at the end of the document. For example:

(write-shtml-as-html
 '((html (head (title "My Title"))
         (body (@ (bgcolor "white"))
               (h1 "My Heading")
               (p "This is a paragraph.")
               (p "This is another paragraph.")))))

outputs:

<html><head><title>My Title</title></head><body bgcolor="whi

te"><h1>My Heading</h1><p>This is a paragraph.</p><p>This is

 another paragraph.</p></body></html>

(shtml->html shtml)  any/c
  shtml : any/c

Yields an HTML encoding of SHTML shtml as a string. For example:

(shtml->html
 (html->shtml
  "<P>This is<br<b<I>bold </foo>italic</ b > text.</p>"))
==> "<p>This is<br /><b><i>bold italic</i></b> text.</p>"

Note that, since this procedure constructs a string, it should normally only be used when the HTML is relatively small. When encoding HTML documents of conventional size and larger, write-shtml-as-html is much more efficient.

6 History

7 Legal

Copyright (c) 2003 – 2011 Neil Van Dyke. This program is Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See http://www.gnu.org/licenses/ for details. For other licenses and consulting, please contact the author.

Standard Documentation Format Note: The API signatures in this documentation are likely incorrect in some regards, such as indicating type any/c for things that are not, and not indicating when arguments are optional. This is due to a transitioning from the Texinfo documentation format to Scribble, which the author intends to finish someday.