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

{- |
   Module     : Text.XML.HXT.DTDValidation.Validation
   Copyright  : Copyright (C) 2008 Uwe Schmidt
   License    : MIT

   Maintainer : Uwe Schmidt (uwe@fh-wedel.de)
   Stability  : experimental
   Portability: portable

   This module provides functions for validating XML documents represented as
   XmlTree.

   Unlike other popular XML validation tools the validation functions return
   a list of errors instead of aborting after the first error was found.

   Note: The validation process has been split into validation and transformation!
   If @validate@ did not report any errors, @transform@
   should be called, to change the document the way a validating parser
   is expected to do.

-}

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

module Text.XML.HXT.DTDValidation.Validation
    ( getDTDSubset
    , generalEntitiesDefined
    , validate
    , validateDTD
    , validateDoc
    , removeDoublicateDefs
    , transform
    )

where

import Text.XML.HXT.DTDValidation.TypeDefs

import qualified Text.XML.HXT.DTDValidation.DTDValidation     as DTDValidation
import qualified Text.XML.HXT.DTDValidation.DocValidation     as DocValidation
import qualified Text.XML.HXT.DTDValidation.IdValidation      as IdValidation
import qualified Text.XML.HXT.DTDValidation.DocTransformation as DocTransformation

-- |
-- Main validation filter. Check if the DTD and the document are valid.
--
--
--    - returns : a function which expects a complete document as XmlTree input
--                     and returns a list of all errors found.

validate        :: XmlArrow
validate        = validateDTD <+> validateDoc

-- |
-- Check if the DTD is valid.
--
--
--    - returns : a function which expects an XmlTree from the parser as input
--                     and returns a list of all errors found in the DTD.

validateDTD     :: XmlArrow
validateDTD     = choiceA
                  [ getDTDSubset        :-> DTDValidation.validateDTD
                  , this                :-> err "Can't validate DTD: There is no DOCTYPE declaration in the document."
                  ]
-- |
-- Check if the document corresponds to the given DTD.
--
--
--    - returns : a function which expects a complete document as XmlTree input
--                     and returns a list of all errors found in the content part.

validateDoc     :: XmlArrow
validateDoc
    = validateDoc' $< getDTD
    where
    validateDoc' []             = err "Can't validate document: There is no DOCTYPE declaration in the document."
    validateDoc' (dtdPart:_)    = DocValidation.validateDoc dtdPart
                                  <+>
                                  IdValidation.validateIds  dtdPart

getDTD          :: XmlArrowS
getDTD          = listA ( getDTDSubset
                          >>>
                          removeDoublicateDefs
                        )

-- |
-- filter for transforming a document with respect to the given DTD.
--
-- Validating parsers
-- are expected to  normalize attribute values and add default values.
-- This function should be called after a successful validation.
--
--
--    - returns : a function which expects a complete XML document tree
--                and returns the transformed XmlTree

transform       :: XmlArrow
transform       = choiceA
                  [ isRoot      :-> (transformDoc $< getDTD)
                  , this        :-> fatal "Can't transform document: No document root given"
                  ]
                  where
                  transformDoc []       = this
                  transformDoc dtd      = DocTransformation.transform (head dtd)

-- |
-- Removes doublicate declarations from the DTD which first declaration is
-- binding. This is the case for ATTLIST and ENTITY declarations.
--
--
--    - returns : A function that replaces the children of DOCTYPE nodes by a list
--               where all multiple declarations are removed.

removeDoublicateDefs    :: XmlArrow
removeDoublicateDefs    = DTDValidation.removeDoublicateDefs

--
-- selects the DTD part of a document
-- but only, if there is more than the internal part for the 4 predefined XML entities

getDTDSubset            :: XmlArrow
getDTDSubset            = getChildren
                          >>>
                          ( filterA $ isDTDDoctype >>> getDTDAttrl >>> isA (hasEntry a_name) )

generalEntitiesDefined	:: XmlArrow
generalEntitiesDefined	= getDTDSubset
                          >>>
                          deep isDTDEntity

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