vxml, my attempt to create a validating xml library
====================================================

What does already work ?
------------------------
vxml already can fail on
* elements (tags) in the wrong order and place
* missing duplicate or required attribues

ensuring that required attributes are added
-> TODO file

installation notes:
-------------------
  targets:
  a) library: That's the piece of code you're interested in
  b) testSimple: basic test showing how the library can be used
  c) testXHML: the same (vdo notation only, you'lln need HaXmL darcs version to
                read dtds/xhtml1-20020801/DTD/xhtml1-strict_onefile.dtd )
  d) run-testcases: 
        usage: dist/build/runt-testcases/run-testcases test/testcases [x]
                x = optional name or prefix of testcases to run
        will override /tmp/{test.hs,dtd.dtd,xml.xml,ghc.log,xmllint.log} 
  e) run-benchpress-test:
        vxml scaling speed test.. (will creat /tmp/vxml-benchpress/*)

  c-e are not built out by default (then you don't need the dependencies
      benchpress and HUnit). Enable them by passing eg by --fflags BuildTestSimple
      to configure

usage:
-----
  see testSimple.hs
  you can use a different name generator if you don't like the default function
  names

Validation errors are indicated by missing instances. Examples:
---------------------------------------------------------------

  * wrong element (1):
    "No instance for (Consume State4 (Elem B_T) st')"

  * more elements expected (1):
    "No instance for (ElEndable Root_T State4)"

  * invalid attribute:
    "No instance for (AttrOk Root_T AAttr_A)"

  * duplicate attribute:
    "No instance for (Text.XML.Validated.Types.DuplicateAttribute A_T AAttr_A)"

  * missing required attributes:
    "No instance for (Text.XML.Validated.Types.RequiredAttributesMissing
                            Root_T (HCons (A RootAttr_A) HNil))"

  (1):
    Go down to the last "no instance for" message where no st or st' appears
    (but something like State22). You can then look all valid elements up in the
    autogenerated-code/*.dtd  debugStates output (it must have been enabled in TH.hs)
    This looks like this: 
     dtd:
          <!ELEMENT root (y*,z)*>
          <!ELEMENT y EMPTY>
          <!ELEMENT z EMPTY>

     states:
          id :1
            endable : True
            y -> St 7
            z -> St 1

          id :7
            endable : False
            y -> St 7
            z -> St 1
     Example taken from testcase star_in_seq_in_star.txt)

Known problems:
---------------
Some things can't be done easily yet. Take this example from testSimple.hs;
  vxmlMapSeqPlus_ (\n -> d e ) [1..10] 

the corresponding real world example rendering a list of numbers:
  ul $ vdo
    vxmlMapSeqPlus_ (\n -> li . text . show ) [1..10]

The problem here is that the XHTML dtd says an ul item must have at least one li.
Thus there must be two states to represent this: the first not endable and the
second which is valid endable.
That's why you can't use mp for all elements, but only for all starting from
the second.
And there is the case that you really don't want any element (eg because you're
using JavaScript to let the user add them interactively).
That's where weak validation is of benefit: You can use
the corresponding real world example rendering a list of numbers:
  ul weakValidation

or
  ul $ vdo
    forceElements -- make the type look like elements have been added already 
    weakValidation -- replace the state by the special state WeakValidation. 
    vxmlSeq_ $ map (\n -> li . text . show ) [1..10]

If you're tired of adding weakValidation you can compile with flag WeakValidation on
WeakValidation will only check that an element may be added but does neither
care about amount nor order of childs.

attrubtes are not validated yet..
see and enhance TODO.

Credits to:
-----------
  * Saizan for helping me figuring out why ghc didn't find the right instance more
    than once (ThankS!)
  * Oleg Kiselyov for telling me about the fastest TypeEq implementation. Before
    that typechecking a minimal xhtml document took hours, it takes 10sec now
    After his second suggestion I was able to bring down compilation time to acceptable 4 secs.
    (has been 30secs before for 12 lines of xml) (ThankS!)
  * Igloo, dcoutts and quicksilver for listening to my questions they had no
    chance to solve because I've missed the problem somewhere else
  * You for reading this README and giving some feedback
  * Peter Thiemann for his inspiring papers and work about and on WASH
  * the ghc team, but you all know this
  * Daniel Fischer