Editing HXT/Practical/Simple1 (section)

=== The Code ===

First, a quick overview of the necessary imports and compiler declarations:

The <code>LANGUAGE</code> pragma allows us to specifically enable
certain language extensions.  The <code>Arrows</code> option provides the special Arrow syntax, and the <code>NoMonomorphismRestriction</code> option eliminates the need for explicit type signatures on our filters.

<haskell>
{-# LANGUAGE Arrows, NoMonomorphismRestriction #-}
import Text.XML.HXT.Core
</haskell>

The XML will be parsed directly into this data-structure:

<haskell>
data Guest = Guest { firstName, lastName :: String }
  deriving (Show, Eq)
</haskell>

I find it helpful to get a feel for the combinators at the GHCi
prompt.  At this point, you may want to start GHCi and load
the code so far.  Then you can use commands like:

<haskell>
Main> runX (readDocument [ withValidate no] "simple1.xml" 
               >>> deep (isElem >>> hasName "guest"))
</haskell>

to see the XML structures inside the guest tags.  The <hask>deep</hask>
filter traverses the XML structures recursively and applies the filter
in its parameter to all the underlying structures.  <hask>withValidate no</hask>
turns off validation -- since the XML technically isn't well formed.

With the "guest" structures in hand, the filter can be refined to
pick out the first and last name text and construct a Guest value.
The <hask>proc</hask> syntax is introduced here to show how it can
be done conveniently.

<haskell>
getGuest = deep (isElem >>> hasName "guest") >>> 
  proc x -> do
    fname <- getText <<< getChildren <<< deep (hasName "fname") -< x
    lname <- getText <<< getChildren <<< deep (hasName "lname") -< x
    returnA -< Guest { firstName = fname, lastName = lname }
</haskell>

If you are familiar with monadic do-syntax, you've probably noticed some similarities already.
There is a <hask>do</hask>, and there is a <hask><-</hask>.  But there are some new operators
too: <hask>-<</hask>, <hask>returnA</hask>, and this introduced variable <hask>x</hask>.

If you squint a bit you'll notice that there seems to be a bit of an "arrow" feel to the syntax:

<haskell>
... <- ... <<< ... <<< ... -< ...
</haskell>

That's done purposefully, you can think of the XML structures flowing through the combinators
in the direction the arrow is pointing.  Binding is still done with <hask><-</hask>.  <hask>returnA</hask>
returns the value to the Arrow much like <hask>return</hask> does to a monad.

Test it out in GHCi:

<haskell>
Main> runX (readDocument [withValidate no] "simple1.xml" >>> getGuest)
</haskell>

There is some repetition in the above code.  Let's factor it out into useful combinators.

<haskell>
atTag tag = deep (isElem >>> hasName tag)
text = getChildren >>> getText
</haskell>

And rewrite the example, much cleaner.

<haskell>
getGuest2 = atTag "guest" >>>
  proc x -> do
    fname <- text <<< atTag "fname" -< x
    lname <- text <<< atTag "lname" -< x
    returnA -< Guest { firstName = fname, lastName = lname }
</haskell>

Hopefully, at this point it should be easy to follow the code, with the more appropriately named
functions.

<haskell>
main = do
  guests <- runX (readDocument [withValidate no] "simple1.xml" 
                    >>> getGuest2)
  print guests
</haskell>