-- $Id: Traverse.hs,v 1.3 2004/07/13 17:30:53 graham Exp $
--------------------------------------------------------------------------------

-- |This module provides functions for using CFilterI values and combinators
--  with XML documents.
--

module Text.XML.HaXml.Traverse
    ( docReplaceContent
    , docErrorContent
    , xmlTreeElements
    , xmlListElements
    , xmlListTextContent
    , filterSingle
    , docContent
    ) where

import Text.XML.HaXml.Combinators
    ( CTransform, CFilterI
    , elm, txt
    , multi, foldXml
    )

import Text.XML.HaXml.Types
    ( DocumentI(..), Document
    , Prolog(..), emptyST
    , ContentI(..), Content
    , ElementI(..), Element
    , Attribute, AttValue(..)
    , ElementInfoset(..)
    , Namespace(..)
    , QName(..)
    )

import Text.XML.HaXml.QName
    ( makeQN, showQN
    )

------------------------------------------------------------

-- |Apply a filter to the content of an XML document,
--  returning a new document with updated XML content.
docReplaceContent :: CTransform i1 i2 -> DocumentI i1 -> DocumentI i2
docReplaceContent f (Document p s e) = Document p s (newContent . f $ CElem e)
    where
        newContent [CElem e] = e
        newContent [CErr er] = errElem er
        newContent []        = errElem "docReplaceContent: no output"
        newContent _         = errElem "docReplaceContent: output not single element"
        errElem err          = Elem (makeQN "error") undefined [] [CErr err]

-- |Create a document whose content is an error elemment containing an error
--  value with the supplied text
docErrorContent :: String -> DocumentI i
docErrorContent err = Document noProlog emptyST (errElem err)
    where
        noProlog    = Prolog "" Nothing Nothing
        errElem err = Elem (makeQN "error") undefined [] [CErr err]

-- |Return a tree of just the elements in an XML document
xmlTreeElements :: DocumentI i -> ContentI i
xmlTreeElements = filterSingle (foldXml elm) . docContent

-- |Return a list of just the elements in an XML document,
--  in document order.
--  (The result is a list of document subtrees.)
xmlListElements :: DocumentI i -> [ContentI i]
xmlListElements = multi elm . docContent

-- |Return a list of just the text content values in an
--  XML document, in document order.
xmlListTextContent :: DocumentI i -> [ContentI i]
xmlListTextContent = multi txt . docContent

------------------------------------------------------------
--  Utility functions for use with Combinator library

-- |Apply a filter to the content of a document, and return a single
--  ContentI value.
filterSingle :: CTransform i1 i2 -> ContentI i1 -> ContentI i2
filterSingle f = singleContent . f
    where
        singleContent [e] = e
        singleContent []  = CErr "filterSingle: no output"
        singleContent _   = CErr "filterSingle: more than one output"

-- |Obtain document content in the form required for input to a CFilterI
docContent :: DocumentI i -> ContentI i
docContent (Document _ _ e) = CElem e

--------------------------------------------------------------------------------
-- $Log: Traverse.hs,v $
-- Revision 1.3  2004/07/13 17:30:53  graham
-- Add xml:lang processing filter.  Fix some minor bugs.
--
-- Revision 1.2  2004/06/24 17:48:36  graham
-- Include document filename/URI in parsed document prolog,
-- for subsequent use as a base URI.
--
-- Revision 1.1  2004/06/22 15:58:59  graham
-- Basic namespace processing is working.
-- Some problems with attribute handling/normalization still to be fixed.
--