doc/examples.xml

   1 <page title="Closure HTML Examples">
   2   <p>
   3     Simple examples using Closure HTML.
   4   </p>
   5
   6   <toc/>
   7
   8   <div style="width: 60%">
   9     <b>Note on non-Unicode Lisps:</b> The examples on this page were
  10     written for Lisps with Unicode support.  When using Closure HTML on
  11     Lisps without Unicode characters, some changes need to be made.  For
  12     example, <tt>make-string-sink</tt> is not available without Unicode
  13     support, but <tt>make-string-sink/utf8</tt> can be substituted in
  14     some of the examples.
  15   </div>
  16
  17   <div style="float: left">
  18   <section>Parsing a string</section>
  19   <example-box>
  20     <fun>parse</fun>
  21     <fun>make-lhtml-builder</fun>
  22     <fun>serialize-lhtml</fun>
  23     <fun>make-string-sink</fun>
  24   </example-box>
  25
  26   <p>Parse into LHTML:</p>
  27   <example>(chtml:parse "&lt;p>nada&lt;/p>" (chtml:make-lhtml-builder))</example>
  28   <result>(:HTML NIL (:HEAD NIL) (:BODY NIL (:P NIL "nada")))</result>
  29
  30   <p>Serialize LHTML back into a string:</p>
  31   <example>(chtml:serialize-lhtml * (chtml:make-string-sink))</example>
  32   <result>"&lt;HTML>&lt;HEAD>&lt;/HEAD>&lt;BODY>&lt;P>nada&lt;/P>&lt;/BODY>&lt;/HTML>"</result>
  33
  34   <section>Parsing a file</section>
  35
  36   <example-box>
  37     <fun>parse</fun>
  38     <fun>make-lhtml-builder</fun>
  39   </example-box>
  40
  41   <p>
  42     Note that the filename must be passed as a pathname (written
  43     using <tt>#p</tt>), not just a
  44     string, because a string would be interpreted as a literal HTML
  45     document as in the first example above.
  46   </p>
  47   <example>(chtml:parse #p"example.html" (chtml:make-lhtml-builder))</example>
  48   <result>(:HTML NIL (:HEAD NIL) (:BODY NIL (:P NIL "nada")))</result>
  49
  50   <section>Cleaning up broken HTML</section>
  51   <example-box>
  52     <fun>parse</fun>
  53     <fun>make-string-sink</fun>
  54   </example-box>
  55
  56   <p>
  57     Many HTML syntax errors are corrected by Closure HTML
  58     automatically.  In this example, we parse from a string and
  59     serialize it back immediately.
  60   </p>
  61   <example>(defun clean-html (string)
  62     (chtml:parse string (chtml:make-string-sink)))</example>
  63   <result>CLEAN-HTML</result>
  64   <p>
  65     Note the differences between input and output in the following document:
  66   </p>
  67   <ul>
  68     <li>&lt;title> is moved into &lt;head>.</li>
  69     <li>The <tt>bogus</tt> attribute is removed.</li>
  70     <li>&lt;br is corrected to &lt;br> and &lt;/oops> to &lt;/p>.</li>
  71   </ul>
  72   <example>(clean-html "&lt;title>cleanup example&lt;/title>
  73 &lt;p bogus>
  74 &lt;br
  75 &lt;/oops>")</example>
  76   <result>"&lt;HTML>&lt;HEAD>&lt;TITLE>cleanup example&lt;/TITLE>&lt;/HEAD>&lt;BODY>&lt;P>
  77 &lt;BR>&lt;/P>&lt;/BODY>&lt;/HTML>"</result>
  78
  79   <section>Translating an HTML file to XHTML</section>
  80   <example-box>
  81     <fun>parse</fun>
  82     <a href="http://common-lisp.net/project/cxml/sax.html#serialization">
  83       cxml:make-octet-stream-sink
  84     </a>
  85   </example-box>
  86
  87   <p>
  88     In this example, we parse an HTML file and serialize it into XHTML.
  89   </p>
  90   <p>
  91     This example
  92     uses <a href="http://common-lisp.net/project/cxml">Closure XML</a>.
  93   </p>
  94   <example>(defun html2xhtml (file &amp;key (if-exists :error))
  95     (with-open-file (out (make-pathname :type "xml" :defaults file)
  96                          :element-type '(unsigned-byte 8)
  97                          :if-exists if-exists
  98                          :direction :output)
  99       (chtml:parse (pathname file)
 100                    (cxml:make-octet-stream-sink out))))</example>
 101   <result>HTML2XHTML</result>
 102   Use like this:
 103   <example>(html2xhtml "/home/david/test.html" :if-exists :supersede)</example>
 104   <p>
 105     The following input file and its XHTML version illustrate some of
 106     the differences between the two syntaxes.
 107   </p>
 108   <p>
 109     <b>test.html</b>:
 110     <pre style="border: solid 1px #9c0000;
 111                 padding: 1em;
 112                 width: 60%;">&lt;p>foo&lt;/p>
 113 &lt;br>
 114 &lt;br>
 115 &lt;br>
 116 &lt;select>
 117 &lt;option selected>123
 118 &lt;option>456
 119 &lt;/select></pre>
 120   </p>
 121   <p>
 122     <b>test.xml</b>:
 123     <pre style="border: solid 1px #9c0000;
 124                 padding: 1em;
 125                 width: 60%;">&lt;?xml version="1.0" encoding="UTF-8"?>
 126 &lt;html xmlns="http://www.w3.org/1999/xhtml">&lt;head/>&lt;body>&lt;p>foo&lt;/p>
 127 &lt;br/>
 128 &lt;br/>
 129 &lt;br/>
 130 &lt;select>&lt;option selected="selected">123
 131 &lt;/option>&lt;option>456
 132 &lt;/option>&lt;/select>
 133 &lt;/body>&lt;/html></pre>
 134   </p>
 135
 136   <section>Translating an XHTML file to HTML</section>
 137   <example-box>
 138     <a href="http://common-lisp.net/project/cxml/sax.html">
 139       cxml:parse
 140     </a>
 141     <fun>make-octet-stream-sink</fun>
 142   </example-box>
 143
 144   <p>
 145     This is a continuation of the opposite example above.  In that
 146     example, we converted an HTML file to HTML.   Going back to HTML is
 147     just as easy:
 148   </p>
 149   <example>(defun xhtml2html (file &amp;key (if-exists :error))
 150     (with-open-file (out (make-pathname :type "html" :defaults file)
 151                          :element-type '(unsigned-byte 8)
 152                          :if-exists if-exists
 153                          :direction :output)
 154       (cxml:parse (pathname file)
 155                   (chtml:make-octet-stream-sink out))))</example>
 156   <result>XHTML2HTML</result>
 157   Running this function on the example above results in a clean-up
 158   version of the original document:
 159   <p>
 160     <b>test.html</b>:
 161     <pre style="border: solid 1px #9c0000;
 162                 padding: 1em;
 163                 width: 60%;">&lt;html>&lt;head>&lt;/head>&lt;body>&lt;p>foo&lt;/p>
 164 &lt;br>
 165 &lt;br>
 166 &lt;br>
 167 &lt;select>&lt;option selected>123
 168 &lt;/option>&lt;option>456
 169 &lt;/option>&lt;/select>
 170 &lt;/body>&lt;/html></pre>
 171   </p>
 172
 173   <section>Fetching and parsing Google search results</section>
 174   <example-box>
 175     <fun>parse</fun>
 176     <a href="http://weitz.de/drakma/#http-request">
 177       drakma:http-request
 178     </a>
 179     <a href="http://www.lichteblau.com/cxml-stp/doc/pages/cxml-stp__fun__make-builder.html">
 180       cxml-stp:make-builder
 181     </a>
 182     <a href="http://www.lichteblau.com/cxml-stp/doc/pages/cxml-stp__macro__do-recursively.html">
 183       cxml-stp:do-recursively
 184     </a>
 185     <a href="http://www.lichteblau.com/cxml-stp/doc/pages/cxml-stp__class__element.html">
 186       cxml-stp:element
 187     </a>
 188     <a href="http://www.lichteblau.com/cxml-stp/doc/pages/cxml-stp__fun__local-name.html">
 189       cxml-stp:local-name
 190     </a>
 191     <a href="http://www.lichteblau.com/cxml-stp/doc/pages/cxml-stp__fun__attribute-value.html">
 192       cxml-stp:attribute-value
 193     </a>
 194   </example-box>
 195
 196   <p>
 197     In this example, we perform a google search and print the first ten
 198     results by looking for all links of the form &lt;a class="l">.
 199   </p>
 200   <p>
 201     This example
 202     uses <a href="http://weitz.de/drakma">Drakma</a> to perform the HTTP
 203     request, and the DOM
 204     alternative <a href="http://www.lichteblau.com/cxml-stp/">cxml-stp</a>.
 205   </p>
 206   <example>(defun show-google-hits (term)
 207     (let* ((query (list (cons "q" term)))
 208            (str (drakma:http-request "http://www.google.com/search"
 209                                      :parameters query))
 210            (document (chtml:parse str (cxml-stp:make-builder))))
 211       (stp:do-recursively (a document)
 212         (when (and (typep a 'stp:element)
 213                    (equal (stp:local-name a) "a")
 214                    (equal (stp:attribute-value a "class") "l"))
 215           (format t "~A:~%  ~A~%~%"
 216                   (stp:string-value a)
 217                   (stp:attribute-value a "href"))))))</example>
 218   <result>SHOW-GOOGLE-HITS</result>
 219   Searching for "lisp" we get these results:
 220   <example>(show-google-hits "lisp")</example>
 221   <result>Lisp (programming language) - Wikipedia, the free encyclopedia:
 222   http://en.wikipedia.org/wiki/Lisp_programming_language
 223
 224 Lisp - Wikipedia, the free encyclopedia:
 225   http://en.wikipedia.org/wiki/Lisp
 226
 227 Association of Lisp Users:
 228   http://www.lisp.org/
 229
 230 An Introduction and Tutorial for Common Lisp:
 231   http://www.apl.jhu.edu/~hall/lisp.html
 232
 233 Lisp:
 234   http://www.paulgraham.com/lisp.html
 235
 236 The Roots of Lisp:
 237   http://www.paulgraham.com/rootsoflisp.html
 238
 239 Planet Lisp:
 240   http://planet.lisp.org/
 241
 242 Practical Common Lisp:
 243   http://www.gigamonkeys.com/book/
 244
 245 CLISP - an ANSI Common Lisp Implementation:
 246   http://clisp.cons.org/
 247
 248 Lisp FAQ:
 249   http://www.cs.cmu.edu/Groups/AI/html/faqs/lang/lisp/top.html</result>
 250
 251 <!--
 252   <section>Serializing using WITH-HTML-OUTPUT</section>
 253   <example-box>
 254     <macro>with-html-output</macro>
 255     <macro>with-element</macro>
 256     <fun>attribute</fun>
 257     <fun>text</fun>
 258   </example-box>
 259 -->
 260
 261   </div>
 262 </page>