HaXml

Note! The new stable version (1.20 onwards) significantly changes the API of some modules over the previous stable version (1.13). (If you have already been using the development versions (1.14-1.19.x), then you are probably OK.)

Notes for migrating code from the old 2006 stable (1.13) version of HaXml to the 2009 stable (1.20) version.

HaXml is a collection of many utilities for parsing, filtering, transforming, and generating XML documents using Haskell. In summary, its facilities include:

• a parser for XML,
• a separate error-correcting parser for HTML,
• a SAX-like stream parser for XML events,
• an XML validator,
• pretty-printers for XML and HTML,
• combinator libraries for querying/transforming/generating XML,
• a stand-alone XPath-like query tool,
• a translator from DTD types to Haskell datatypes, with associated parsers and pretty-printers,
• a translator from Schema definitions to Haskell datatypes, with associated parsers and pretty-printers.

For high-level processing of XML documents, the following components are provided:

• Combinators is a combinator library for generic XML document processing, including transformation, editing, and generation.
• XmlContent is a replacement class for Haskell's Show/Read classes: it allows you to read and write ordinary Haskell data as XML documents (and vice versa). The DrIFT tool (available from http://repetae.net/~john/computer/haskell/DrIFT/) can automatically derive this class for you.
• DtdToHaskell is a tool for translating any valid XML DTD into equivalent Haskell types, together with XmlContent instances.
• XsdToHaskell is a tool for translating any valid XML Schema definition into equivalent Haskell types, together with SchemaType instances.
• Finally, Xtract is a grep-like tool for XML documents, loosely based on the XPath and XQL query languages. It can be used either from the command-line, or within your own code as part of the library.

Detailed documentation of the HaXml APIs is generated automatically by Haddock directly from the source code.

An introduction to HaXml for people who know more about XML than about Haskell can be found at IBM DeveloperWorks. Please note that the DeveloperWorks article was based on an older version of HaXml. If you try to use the examples given there, you will need a couple of minor but important edits, given as a diff patch here.

A paper describing and comparing the generic Combinators with the typed representation (DtdToHaskell/XmlContent) is available here: (12 pages of double-column A4)

• icfp99.dvi (LaTeX dvi format)
• icfp99.ps.gz (PostScript format - gzipped)
• icfp99.html (HTML format)

Some additional info about using the various facilities is here:

• Combinators (HTML format)
• XmlContent class (HTML format)
• DtdToHaskell tool (HTML format)
• XsdToHaskell tool (HTML format)
• Xtract tool (HTML format)

Known problems:

• To use -package HaXml interactively with GHCi, you need at least ghci-5.02.3.
• The function toDTD generates Parameter Entity Declarations in the internal subset of the DTD, which don't conform to the strict well-formedness conditions of XML. We think the constraint in question is spurious, and any reasonable XML tool ought to deal adequately with full PEs. Nevertheless, many standard XML processors reject these auto-generated DTDs. The solution is easy - just write the DTD into a separate file!
• DtdToHaskell generates the Haskell String type for DTD attributes that are of Tokenized or Notation Types in XML. This may not be entirely accurate.

Latest version:
HaXml-1.25.4, release date 2017.06.19
From Hackage
By HTTP: .tar.gz.

Ongoing development: The development version of HaXml is also available through
darcs get http://code.haskell.org/HaXml

To install HaXml, you must have a Haskell compiler: ghc-6.2 or later, and/or nhc98-1.16/hmake-3.06 or later, and/or Hugs98 (Sept 2003) or later. You must also first download and install the polyparse package as a pre-requisite.

Then, for more recent compilers, use the standard Cabal method of installation:

    cabal update
    cabal install HaXml-1.25.4

    runhaskell Setup.hs configure [--prefix=...] [--buildwith=...]
    runhaskell Setup.hs build
    runhaskell Setup.hs install

    ./configure [--prefix=...] [--buildwith=...]
    make
    make install

To build/install on a Windows system without the Cygwin shell and utilities, you can avoid the configure/make steps by simply using the minimal Build.bat script. Edit it first for the location of your compiler etc.

Version 1.25.4 fixes the generation of the HaXml version string on Windows.
Version 1.25.3 fixes the cabal file to reduce build time.
Version 1.25.2 works around another Haddock parsing bug.
Version 1.25.1 works around a ghc bug that prevents Haddock from documenting some modules.
Version 1.25 improves the XsdToHaskell compiler some more.

Version 1.24.1 changes the cpp for transmitting version numbers into src.
Version 1.24 bumps the dependency on polyparse to 1.9 or later, and adds some better handling of incorrectly unescaped ampersand characters.

Version 1.23.3 fixes another haddock documentation bug.
Version 1.23.2 fixes a haddock documentation bug.
Version 1.23.1 fixes a packaging bug Version 1.23 improves the XSD to Haskell translation, focussed mainly on FpML as the driving application.

Version 1.22.3 fixes another haddock documentation bug.
Version 1.22.2 fixes a haddock documentation bug.
Version 1.22.1 fixes a packaging bug.
Version 1.22 is compatible with ghc-7 and improves the new XsdToHaskell tool.

Version 1.21 adds better support for XML namespaces, and introduces the new XsdToHaskell tool.

Version 1.20.2 adds --version and --help arguments to all executables.
Version 1.20.1 fixes a small bug in DtdToHaskell.
Version 1.20 is the new stable version.

Version 1.19.7 requires package polyparse-1.2 (previous versions require polyparse-1.1).
Version 1.19.6 has some bugfixes to XmlContent, to ensure that types created via DtdToHaskell get converted back to XML correctly.
Version 1.19.5 has some bugfixes to DtdToHaskell, to cope with especially large datatypes.
Version 1.19.4 has some minor bugfixes to increase compatibility with the ByteString package.
Version 1.19.2 updates the Cabal file to enable HaXml to build with both ghc-6.6.x and ghc-6.8.x.
Version 1.19.1 fixes a build error in 1.19.
Version 1.19 improved the lazy XML parsing, and fixed some space leaks in the XtractLazy tool.

Version 1.18 pulled out the parser combinator libraries as a separate package (called polyparse), which must now be downloaded and installed before installing HaXml.

Version 1.17 essentially just fixes compatibility with ghc-6.6. However, it also include a lazier pretty-printer to use in conjunction with the lazy parser, to save running out of memory on large datasets.

Version 1.16 adds laziness to the parser combinator libraries, such that they can start to return partial results before a whole entity has been parsed. Partial is also used in the sense that the returned value can contain bottom - an error which gets thrown as an exception when you try to explore the inner regions of the value. In terms of XML, it means you get an element back as soon as its start-tag has been consumed, but if there are parse errors later on, BOOM. However, if there are no errors, it does mean that your processing will be (a) faster and (b) less memory hungry. Another cool thing is that, even in the presence of errors, you still might get enough output to satisfy your processing task before the error is noticed.

Use Text.XML.HaXml.ParseLazy and Text.XML.HaXml.Html.ParseLazy to try it out. There are also lazy versions of the supplied demo programs: CanonicaliseLazy and XtractLazy.

Version 1.15 is essentially 1.14 with some bugfixes, and some new functionality, especially in the parser combinator libraries. DrIFT now supports deriving the XmlContent class, and DtdToHaskell now also derives the XmlContent class, in addition to determining a collection of Haskell datatypes equivalent to a given DTD.

Error messages from parsing are much improved in 1.15 - they should locate any error far more specifically and accurately. Let me know about examples which do not report correctly.

Prior to 1.14, there were two separate classes, Xml2Haskell and Haskell2Xml. They are now combined into the single class XmlContent. Make sure you get a recent version of DrIFT if you want to derive this class from Haskell datatypes - the included version of DtdToHaskell has not yet been updated for deriving the class the other way, from an XML DTD.

Version 1.14 also contains a new SAX-like stream parser.

A while back, Graham Klyne extended the 1.12 version of HaXml significantly, in particular to ensure that the parser passes a large XML acceptance test suite, and to deal more correctly with Unicode, namespaces, and parameter entity expansion. His modifications will eventually be merged back in to the main CVS tree, but in the meantime, you can get his version here: http://www.ninebynine.org/Software/HaskellUtils/

The previous stable version (1.13) had the following features and fixes:

• Bugfixes to the document validator: no more infinite loops.
• Bugfixes to lexing mixed text and references between quote chars.
• Updated to work with ghc-6.4's new package mechanism.

We are interested in hearing your feedback on these XML facilities - suggestions for improvements, comments, criticisms, bug reports. Please mail

• Malcolm.Wallace@me.com (implementation & design)
• Colin.Runciman@cs.york.ac.uk (design)

Development of these XML libraries was originally funded by Canon Research Europe Ltd, in 1998-1999. Subsequent maintenance and development has been indirectly supported by the EPSRC, the University of York, QinetiQ, BAE Systems, and Standard Chartered Bank.

Licence: The library is Free and Open Source Software, i.e., the bits we wrote are copyright to us, but freely licensed for your use, modification, and re-distribution, provided you don't restrict anyone else's use of it. The HaXml library is distributed under the GNU Lesser General Public Licence (LGPL) - see file LICENCE-LGPL for more details. We allow one special exception to the LGPL - see COPYRIGHT. The HaXml tools are distributed under the GNU General Public Licence (GPL) - see LICENCE-GPL. (If you don't like any of these licensing conditions, please contact us to discuss your requirements.)

• Some recent (2010) papers by Masato Takeichi show how HaXml can be bi-directionalized, and how a bi-directionalized HaXml can be used for web-page maintenance. http://www.ipl.t.u-tokyo.ac.jp/~takeichi/pages/_68.html http://www.ipl.t.u-tokyo.ac.jp/~takeichi/pages/_69.html
• Joe English wrote a more space-efficient parser for XML in Haskell, called hxml. What is more, it can be used as a simple drop-in replacement for the HaXml parser! Available here. This predates the introduction of lazy parsing in HaXml, which is another way of improving the space efficiency.
• Uwe Schmidt designed another Haskell XML Toolbox based on the ideas of HaXml and hxml. It is well-maintained, and uses arrow-based combinators rather than filters as in HaXml.
• To use HaXml and HXT together, Henning Thielemann has put together WraXML, a wrapper using an alternative tree data structure, together with conversions to/from HaXml and HXT.
• Some comparisons between functional language approaches to processing XML can be found in Bijan Parsia's article on xml.com
• Christian Lindig has written an XML parser in O'Caml: here.
• Andreas Neumann of the University of Trier has written a validating XML parser in Standard ML: here.
• Erik Meijer and Mark Shields have a design for a functional programming language that treats XML documents as basic data types: XMLambda.
• Benjamin Pierce and Haruo Hosoya have a different but similar design in XDuce, which is also implemented.
• Taking XDuce's approach further, is the very cool CDuce by Véronique Benzaken, Guiseppe Castagna, and Alain Frisch. The CDuce language does fully statically-typed transformation of XML documents, thus guaranteeing correctness, and what is more, it is also faster than the untyped XSLT!
• The Xcerpt project uses HaXml to create another rule-based query and transformation language for XML, inspired by logic programming, and based on positional selection rather than navigational selection.
• Ulf Wiger describes an Erlang toolkit for XML: XMerL
• The Java world has adopted the ideas from DtdToHaskell into the Java Architecture for XML Binding (JAXB). JAXB translates an XML Schema Definition into a set of Java classes, and provides the runtime machinery (like XmlContent) for reading and writing objects of those classes to/from XML files.
• There is a comprehensive reading list for XML and web programming in functional languages here.