~singpolyma/xml-types-haskell

9343c145da21e3cf8c4db0503a6f079af9233b77 — John Millikin 11 years ago bd35827
Better documentation
1 files changed, 46 insertions(+), 35 deletions(-)

M Data/XML/Types.hs
M Data/XML/Types.hs => Data/XML/Types.hs +46 -35
@@ 1,26 1,23 @@
-- Copyright (c) 2010 John Millikin
-- |
-- Module: Data.XML.Types
-- Copyright: 2010-2011 John Millikin
-- License: MIT
--
-- Permission is hereby granted, free of charge, to any person
-- obtaining a copy of this software and associated documentation
-- files (the "Software"), to deal in the Software without
-- restriction, including without limitation the rights to use,
-- copy, modify, merge, publish, distribute, sublicense, and/or sell
-- copies of the Software, and to permit persons to whom the
-- Software is furnished to do so, subject to the following
-- conditions:
-- Maintainer: jmillikin@gmail.com
-- Portability: portable
--
-- The above copyright notice and this permission notice shall be
-- included in all copies or substantial portions of the Software.
-- Basic types for representing XML.
--
-- The idea is to have a full set of appropriate types, which various XML
-- libraries can share. Instead of having equivalent-but-incompatible types
-- for every binding, parser, or client, they all share the same types can
-- can thus interoperate easily.
--
-- This library contains complete types for most parts of an XML document,
-- including the prologue, node tree, and doctype. Some basic combinators
-- are included for common tasks, including traversing the node tree and
-- filtering children.
--
-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-- OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-- HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-- WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-- FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-- OTHER DEALINGS IN THE SOFTWARE.

module Data.XML.Types
	( -- * Types
	


@@ 139,12 136,27 @@ instance Typeable Element where

data Content
	= ContentText Text
	| ContentEntity Text
	| ContentEntity Text -- ^ For pass-through parsing
	deriving (Show, Eq)

instance Typeable Content where
	typeOf = typeString "Content"

-- | A fully qualified name.
--
-- Prefixes are not semantically important; they are included only to
-- simplify pass-through parsing. When comparing names with 'Eq' or 'Ord'
-- methods, prefixes are ignored.
--
-- The @IsString@ instance supports Clark notation; see
-- <http://www.jclark.com/xml/xmlns.htm> and
-- <http://infohost.nmt.edu/tcc/help/pubs/pylxml/etree-QName.html>. Use
-- the @OverloadedStrings@ language extension for very simple @Name@
-- construction:
--
-- > myname :: Name
-- > myname = "{http://example.com/ns/my-namespace}my-name"
--
data Name = Name
	{ nameLocalName :: Text
	, nameNamespace :: Maybe Text


@@ 155,20 167,12 @@ data Name = Name
instance Typeable Name where
	typeOf = typeString "Name"

-- | Ignores prefixes
instance Eq Name where
	(==) = (==) `on` (\x -> (nameNamespace x, nameLocalName x))

-- | Ignores prefixes
--
-- Since 0.1.3
instance Ord Name where
	compare = compare `on` (\x -> (nameNamespace x, nameLocalName x))

-- | Supports Clark notation; see <http://www.jclark.com/xml/xmlns.htm> and
-- <http://infohost.nmt.edu/tcc/help/pubs/pylxml/etree-QName.html>
--
-- Since 0.1.2
instance IsString Name where
	fromString "" = Name T.empty Nothing Nothing
	fromString full@('{':rest) = case break (== '}') rest of


@@ 206,7 210,9 @@ data DoctypeNode
instance Typeable DoctypeNode where
	typeOf = typeString "DoctypeNode"

-- TODO
-- | Internal doctype declarations are still largely unimplemented. This
-- type will be populated and published in a later version of @xml-types@.
--
data Declaration
	= DeclareElement Text
	| DeclareAttributeList Text


@@ 218,10 224,17 @@ instance Typeable Declaration where
	typeOf = typeString "Declaration"

-- | Some XML processing tools are incremental, and work in terms of events
-- rather than node trees. Defining the event type here, even though it won't
-- be useful to most users, allows these packages to interoperate more easily.
-- rather than node trees. The 'Event' type allows a document to be fully
-- specified as a sequence of events.
--
-- Event-based XML libraries include:
--
-- * <http://hackage.haskell.org/package/xml-enumerator>
--
-- * <http://hackage.haskell.org/package/libxml-enumerator>
--
-- * <http://hackage.haskell.org/package/expat-enumerator>
--
-- Since: 0.1.1
data Event
	= EventBeginDocument
	| EventEndDocument


@@ 261,7 274,6 @@ isNamed n e = [e | elementName e == n]
elementChildren :: Element -> [Element]
elementChildren = elementNodes >=> isElement

-- | Since 0.1.4
elementContent :: Element -> [Content]
elementContent = elementNodes >=> isContent



@@ 296,4 308,3 @@ contentText = T.concat . map step where

typeString :: String -> a -> TypeRep
typeString str _ = mkTyConApp (mkTyCon ("Data.XML.Types." ++ str)) []