****************************************************************************** README - PXP, the XML parser for O'Caml ****************************************************************************** ============================================================================== Abstract ============================================================================== PXP is a validating parser for XML-1.0 which has been written entirely in Objective Caml. PXP is the new name of the parser formerly known as "Markup". PXP means "Polymorphic XML parser" and emphasizes its most useful property: that the API is polymorphic and can be configured such that different objects are used to store different types of elements. ============================================================================== Download ============================================================================== You can download PXP as gzip'ed tarball [1]. The parser needs the Netstring [2] package (0.9.3). Note that PXP requires O'Caml 3.00. ============================================================================== User's Manual ============================================================================== The manual is included in the distribution both as Postscript document and bunch of HTML files. An online version can be found here [3]. ============================================================================== Author, Credits, Copying ============================================================================== PXP has been written by Gerd Stolpmann [4]; it contains contributions by Claudio Sacerdoti Coen. You may copy it as you like, you may use it even for commercial purposes as long as the license conditions are respected, see the file LICENSE coming with the distribution. It allows almost everything. Thanks also to Alain Frisch and Haruo Hosoya for discussions and bug reports. ============================================================================== Description ============================================================================== PXP is a validating XML parser for O'Caml [5]. It strictly complies to the XML-1.0 [6] standard. The parser is simple to call, usually only one statement (function call) is sufficient to parse an XML document and to represent it as object tree. Once the document is parsed, it can be accessed using a class interface. The interface allows arbitrary access including transformations. One of the features of the document representation is its polymorphic nature; it is simple to add custom methods to the document classes. Furthermore, the parser can be configured such that different XML elements are represented by objects created from different classes. This is a very powerful feature, because it simplifies the structure of programs processing XML documents. Note that the class interface does not comply to the DOM standard. It was not a development goal to realize a standard API (industrial developers can this much better than I); however, the API is powerful enough to be considered as equivalent with DOM. More important, the interface is compatible with the XML information model required by many XML-related standards. ------------------------------------------------------------------------------ Detailed feature list ------------------------------------------------------------------------------ - The XML instance is validated against the DTD; any violation of a validation constraint leads to the rejection of the instance. The validator has been carefully implemented, and conforms strictly to the standard. If needed, it is also possible to run the parser in a well-formedness mode. - If possible, the validator applies a deterministic finite automaton to validate the content models. This ensures that validation can always be performed in linear time. However, in the case that the content models are not deterministic, the parser uses a backtracking algorithm which can be much slower. - It is also possible to reject non-deterministic content models. - In particular, the validator also checks the complicated rules whether parentheses are properly nested with respect to entities, and whether the standalone declaration is satisfied. On demand, it is checked whether the IDREF attributes only refer to existing nodes. - Entity references are automatically resolved while the XML text is being scanned. It is not possible to recognize in the object tree where a referenced entity begins or ends; the object tree only represents the logical structure. - External entities are loaded using a configurable resolver infrastructure. It is possible to connect the parser with an arbitrary XML source. - The parser can read XML text encoded in a variety of character sets. Independent of this, it is possible to choose the encoding of the internal representation of the tree nodes; the parser automatically converts the input text to this encoding. Currently, the parser supports UTF-8 and ISO-8859-1 as internal encodings. - The interface of the parser has been designed such that it is best integrated into the language O'Caml. The first goal was simplicity of usage which is achieved by many convenience methods and functions, and by allowing the user to select which parts of the XML text are actually represented in the tree. For example, it is possible to store processing instructions as tree nodes, but the parser can also be configured such that these instructions are put into hashtables. The information model is compatible with the requirements of XML-related standards such as XPath. - In particular, the node tree can optionally contain or leave out processing instructions and comments. It is also possible to generate a "super root" object which is the parent of the root element. The attributes of elements are normally not stored as nodes, but it is possible to get them wrapped into nodes. - There is also an interface for DTDs; you can parse and access sequences of declarations. The declarations are fully represented as recursive O'Caml values. ------------------------------------------------------------------------------ Code examples ------------------------------------------------------------------------------ This distribution contains several examples: - validate: simply parses a document and prints all error messages - readme: Defines a DTD for simple "README"-like documents, and offers conversion to HTML and text files [7]. - xmlforms: This is already a sophisticated application that uses XML as style sheet language and data storage format. It shows how a Tk user interface can be configured by an XML style, and how data records can be stored using XML. ------------------------------------------------------------------------------ Restrictions and missing features ------------------------------------------------------------------------------ The following restrictions apply that are not violations of the standard: - The attributes "xml:space", and "xml:lang" are not supported specially. (The application can do this.) - The built-in support for SYSTEM and PUBLIC identifiers is limited to local file access. There is no support for catalogs. The parser offers a hook to add missing features. - It is currently not possible to check for interoperatibility with SGML. The following features are also missing: - There is no special support for namespaces. (Perhaps in the next release?) - There is no support for XPATH or XSLT. However, I hope that these features will be implemented soon, either by myself or by contributors (who are invited to do so). ------------------------------------------------------------------------------ Recent Changes ------------------------------------------------------------------------------ - Changed in 1.0: Support for document order. - Changed in 0.99.8: Several fixes of bugs reported by Haruo Hosoya and Alain Frisch. The class type "node" has been extended: you can go directly to the next and previous nodes in the list; you can refer to nodes by position. There are now some iterators for nodes: find, find_all, find_element, find_all_elements, map_tree, iter_tree. Experimental support for viewing attributes as nodes; I hope that helps Alain writing his XPath evaluator. The user's manual has been revised and is almost up to date. - Changed in 0.99.7: There are now additional node types T_super_root, T_pinstr and T_comment, and the parser is able to create the corresponding nodes. The functions for character set conversion have been moved to the Netstring package; they are not specific for XML. - Changed in 0.99.6: Implemented a check on deterministic content models. Added an alternate validator basing on a DFA. - This means that now all mandatory features for an XML-1.0 parser are implemented! The parser is now substantially complete. - Changed in 0.99.5: The handling of ID and IDREF attributes has changed. The index of nodes containing an ID attribute is now separated from the document. Optionally the parser now checks whether the IDREF attributes refer to existing elements. The element nodes can optionally store the location in the source XML code. The method 'write' writes the XML tree in every supported encoding. (Successor of 'write_compact_as_latin1'.) Several smaller changes and fixes. - Changed in 0.99.4: The module Pxp_reader has been modernized. The resolver classes are simpler to use. There is now support for URLs. The interface of Pxp_yacc has been improved: The type 'source' is now simpler. The type 'domspec' has gone; the new 'spec' is opaque and performs better. There are some new parsing modes. Many smaller changes. - Changed in 0.99.3: The markup_* modules have been renamed to pxp_*. There is a new compatibility API that tries to be compatible with markup-0.2.10. The type "encoding" is now a polymorphic variant. - Changed in 0.99.2: Added checks for the constraints about the standalone declaration. Added regression tests about attribute normalization, attribute checks, standalone checks. Fixed some minor errors of the attribute normalization function. The bytecode/native archives are now separated in a general part, in a ISO-8859-1-relevant part, and a UTF-8-relevant part. The parser can again be compiled with ocamlopt. - Changed in 0.99.1: In general, this release is an early pre-release of the next stable version 1.00. I do not recommend to use it for serious work; it is still very experimental! The core of the parser has been rewritten using a self-written parser generator. The lexer has been restructured, and can now handle UTF-8 encoded files. Numerous other changes. -------------------------- [1] see http://www.ocaml-programming.de/packages/pxp-1.0.tar.gz [2] see http://www.ocaml-programming.de/packages/documentation/netstring [3] see http://www.ocaml-programming.de/packages/documentation/pxp/manual [4] see mailto:gerd@gerd-stolpmann.de [5] see http://caml.inria.fr/ [6] see http://www.w3.org/TR/1998/REC-xml-19980210.html [7] This particular document is an example of this DTD!