new release
[cxml-rng.git] / index.xml
blobf0f2194467918434d4d14bf766aac0ea0f2223ae
1 <page>
2   <p>
3     An implementation
4     of <a href="http://relaxng.org/spec-20011203.html">Relax
5       NG</a> schema validation
6     written in Common
7     Lisp, including support for compact syntax, DTD Compatibility, and
8     the XSD type library.
9   </p>
10   <p>
11     cxml-rng was written
12     by <a href="mailto:david@lichteblau.com">David
13       Lichteblau</a> and is designed as an add-on library for
14     <a href="http://common-lisp.net/project/cxml">Closure XML</a>.
15     It is available under an X11-style license.
16   </p>
17   <p>
18     Please send bug reports
19     to <a href="mailto:cxml-devel@common-lisp.net">
20       cxml-devel@common-lisp.net</a>
21     (<a href="http://common-lisp.net/cgi-bin/mailman/listinfo/cxml-devel">list information</a>).
22   </p>
24   <h3>Download and Installation</h3>
26 <!--
27   <p>
28     Download cxml-rng
29     <a href="http://www.lichteblau.com/cxml-rng/download/">tarballs</a>
30     or get it from git: <tt>http://www.lichteblau.com/git/cxml-rng.git</tt>
31   </p>
32 -->
33   <p>
34     Download a cxml-rng
35     <a href="http://www.lichteblau.com/cxml-rng/download/">tarball</a>.
36   </p>
37   <p>
38     cxml-rng needs
39     <a href="http://common-lisp.net/project/cxml">Closure XML</a>, 
40     <a href="http://weitz.de/cl-ppcre/">CL-PPCE</a>,
41     <a href="http://www.pps.jussieu.fr/~jch/software/cl-yacc/">CL-Yacc</a>,
42     <a href="http://www.cliki.net/PARSE-NUMBER">parse-number</a>,
43     and <a href="http://www.cliki.net/cl-base64">cl-base64</a>.
44     <a href="http://www.cliki.net/asdf">ASDF</a> is used for
45     compilation.  Register the .asd file, e.g. by symlinking it,
46     then compile cxml-rng using <tt>asdf:operate</tt>.
47   </p>
48   <pre>$ ln -sf `pwd`/cxml-rng.asd /path/to/your/registry/
49 * (asdf:operate 'asdf:load-op :cxml-rng)</pre>
51   <h3>Implementation-specific notes</h3>
52   <p>
53     At this point, cxml-rng is written to work with Lisp strings
54     (as opposed to runes and rods), and is meant to be used on
55     Lisp implementations with Unicode support.
56   </p>
58   <h3>Documentation</h3>
59   <p>
60     <a href="doc/index.html">API documentation</a> is available.
61   </p>
63   <h3>Example</h3>
64   <p>
65     Use <a href="doc/pages/cxml-rng__parse-schema.html">cxml-rng:parse-schema</a>
66     to parse a Relax NG schema file.  The
67     resulting <a
68                  href="doc/pages/cxml-rng__schema.html">schema</a>
69     object is a representation of a simplified schema using Lisp
70     objects, which has gone through simplification as
71     described the Relax NG
72     specification.  <a href="doc/pages/cxml-rng__serialize-schema.html">cxml-rng:serialize-schema</a>
73     can be used to write a Relax NG file in XML syntax for this
74     grammar.
75   </p>
76   <p>
77     In order to validate XML against a schema, create a
78     validation handler for the grammar
79     using <a href="doc/pages/cxml-rng__make-validator.html">cxml-rng:make-validator</a>.
80     The validation
81     handler processes SAX events and can be used with any
82     function generating such events, in particular
83     with <a
84             href="http://common-lisp.net/project/cxml/sax.html#parser">cxml:parse-file</a>.
85   </p>
86   <pre class="code">(cxml:parse-file "example.xml"
87                  <blau>(cxml-rng:make-validator
88                   (cxml-rng:parse-schema #p"example.rng"))</blau>)</pre>
89   <p>
90     The validator accepts another SAX handler as an optional
91     second argument.  For example, to parse XML into DOM while also
92     validating it, use the validator like this:
93   </p>
94   <pre class="code" style="color: #777777">(cxml:parse-file "example.xml"
95                  <blau>(cxml-rng:make-validator</blau>
96                   (cxml-rng:parse-schema #p"example.rng")
97                   <blau>(cxml-dom:make-dom-builder))</blau>)</pre>
98   <p>
99     When using the klacks parser, create a validating source.
100   </p>
101   <pre class="code" style="color: #777777">(klacks:with-open-source
102     (s <blau>(cxml-rng:make-validating-source
103         #p"example.xml"
104         (cxml-rng:parse-schema #p"example.rng"))</blau>)
105   (loop for key = (klacks:peek-next s) while key do (print key)))</pre>
106   <p>
107     DTD Compatibility processing (basically, checking of IDs and
108     addition of default values) is done using a
109     <a href="doc/pages/cxml-rng__make-dtd-compatibility-handler.html">DTD Compatibility handler</a>.
110     You can use this handler together with a validator or by its own.
111   </p>
112   <pre class="code" style="color: #777777">(cxml:parse-file "example.xml"
113                  <blau>(cxml-rng:make-dtd-compatibility-handler</blau>
114                   (cxml-rng:parse-schema #p"example.rng")
115                   <blau>(cxml-dom:make-dom-builder))</blau>)</pre>
117   <h3>Recent changes</h3>
118   <p><b>2008-11-30</b></p>
119   <ul>
120     <li>
121       Build fix: Upgraded to current cl-ppcre.
122     </li>
123     <li>
124       Use 21 bit characters on Lisps offering them.
125       (Also fixes OpenMCL issues.)
126     </li>
127   </ul>
128   <p><b>2007-10-21</b></p>
129   <ul>
130     <li>
131       Slightly better error messages around attribute issues.
132     </li>
133     <li>
134       Update to current CXML.
135     </li>
136   </ul>
137   <p><b>2007-07-01</b></p>
138   <ul>
139     <li>
140       Allows comments in grammar contents.
141     </li>
142   </ul>
143   <p><b>2007-05-26</b></p>
144   <ul>
145     <li>
146       Initial public release. 
147     </li>
148   </ul>
149 </page>