-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Library for parsing epub document metadata
--   
--   Library for parsing and manipulating epub document metadata. Supports
--   epub versions 2 and 3. This library was constructed by studying the
--   IDPF specifications for epub documents found here
--   <a>http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm</a> and here
--   <a>http://www.idpf.org/epub/30/spec/epub30-publications.html</a>
@package epub-metadata
@version 4.5


-- | Data types for working with the metadata of epub documents
--   
--   This module helps to avoid circular imports for definitions needed by
--   two or more other modules in this library.
module Codec.Epub.Data.Common

-- | Attribute value used to relate things to each other in the OPF data
type MFItemId = String


-- | Data types for working with the metadata of epub documents
--   
--   This contains the guide section in an epub2 OPF document. It has been
--   deprecated in the epub3 spec and should not be present in epub3
--   documents.
module Codec.Epub.Data.Guide

-- | package/guide/reference tag
data GuideRef
GuideRef :: String -> Maybe String -> MFItemId -> GuideRef

-- | type attribute. Must follow 13th edition of the Chicago Manual of
--   Style
[grType] :: GuideRef -> String

-- | title attribute
[grTitle] :: GuideRef -> Maybe String

-- | href attribute. Must reference an item in the manifest
[grHref] :: GuideRef -> MFItemId
instance GHC.Show.Show Codec.Epub.Data.Guide.GuideRef
instance GHC.Classes.Eq Codec.Epub.Data.Guide.GuideRef


-- | Data types for working with the metadata of epub documents
--   
--   This contains the manifest information from an epub document.
module Codec.Epub.Data.Manifest
newtype Manifest
Manifest :: [ManifestItem] -> Manifest

-- | package/manifest/item tag
data ManifestItem
ManifestItem :: MFItemId -> MFItemHref -> MFItemMediaType -> ManifestItem

-- | id attribute
[mfiId] :: ManifestItem -> MFItemId

-- | href attribute
[mfiHref] :: ManifestItem -> MFItemHref

-- | media-type attribute
[mfiMediaType] :: ManifestItem -> MFItemMediaType
instance GHC.Show.Show Codec.Epub.Data.Manifest.Manifest
instance GHC.Classes.Eq Codec.Epub.Data.Manifest.Manifest
instance GHC.Show.Show Codec.Epub.Data.Manifest.ManifestItem
instance GHC.Classes.Eq Codec.Epub.Data.Manifest.ManifestItem


-- | Data types for working with the metadata of epub documents
--   
--   This module defines the Metadata structure which contains most of the
--   taxonomic information about the literary work. Metadata is probably
--   the most important data structure in this library.
--   
--   Both commonly-used versions of epub (2.x and 3.x) are supported by
--   these types.
module Codec.Epub.Data.Metadata

-- | package/metadata tag
--   
--   This is perhaps the most useful data structure in this library. It
--   contains most of the information tools will want to use to organize
--   epub documents.
data Metadata
Metadata :: [Identifier] -> [Title] -> [String] -> [Creator] -> [Creator] -> [Date] -> Maybe String -> Maybe String -> Maybe String -> [String] -> [Description] -> [String] -> [String] -> [String] -> [String] -> [String] -> Metadata

-- | at least one required
[metaIds] :: Metadata -> [Identifier]

-- | at least one required
[metaTitles] :: Metadata -> [Title]

-- | dc:language tags, at least one required
[metaLangs] :: Metadata -> [String]
[metaContributors] :: Metadata -> [Creator]
[metaCreators] :: Metadata -> [Creator]
[metaDates] :: Metadata -> [Date]

-- | meta tag with property dcterms:modified, present only in epub3
--   documents
[metaModified] :: Metadata -> Maybe String

-- | dc:source tags
[metaSource] :: Metadata -> Maybe String

-- | dc:type tags
[metaType] :: Metadata -> Maybe String

-- | dc:coverage tags
[metaCoverages] :: Metadata -> [String]
[metaDescriptions] :: Metadata -> [Description]

-- | dc:format tags
[metaFormats] :: Metadata -> [String]

-- | dc:publisher tags
[metaPublishers] :: Metadata -> [String]

-- | dc:relation tags
[metaRelations] :: Metadata -> [String]

-- | dc:rights tags
[metaRights] :: Metadata -> [String]

-- | dc:subject tags
[metaSubjects] :: Metadata -> [String]

-- | package/metadata/dc:identifier tag
data Identifier
Identifier :: Maybe String -> Maybe String -> Maybe String -> String -> Identifier

-- | id attribute
[idId] :: Identifier -> Maybe String

-- | identifier-type property from meta tag
[idType] :: Identifier -> Maybe String

-- | scheme from attribute or meta tag
[idScheme] :: Identifier -> Maybe String

-- | identifier tag text
[idText] :: Identifier -> String

-- | package/metadata/dc:title tag
data Title
Title :: Maybe String -> Maybe String -> Maybe Int -> String -> Title

-- | lang attribute
[titleLang] :: Title -> Maybe String

-- | title-type property from meta tag
[titleType] :: Title -> Maybe String

-- | display-sequence property from meta
[titleSeq] :: Title -> Maybe Int

-- | title tag text
[titleText] :: Title -> String

-- | package/metadata/dc:creator or package/metadata/dc:contributor tags
--   
--   This structure is used for both contributor and creator as they are
--   exactly the same.
data Creator
Creator :: Maybe String -> Maybe String -> Maybe Int -> String -> Creator

-- | role from attribute or meta tag
[creatorRole] :: Creator -> Maybe String

-- | file-as from attribute or meta tag
[creatorFileAs] :: Creator -> Maybe String

-- | display-sequence property from meta
[creatorSeq] :: Creator -> Maybe Int

-- | creator or contributor tag text
[creatorText] :: Creator -> String

-- | package/metadata/dc:date tag, opf:event attribute, text
data Date
Date :: (Maybe String) -> String -> Date

-- | package/metadata/dc:description tag, xml:lang attribute, text
data Description
Description :: (Maybe String) -> String -> Description

-- | Refinements represent meta tags within the metadata section that
--   refine other tags. These are used during the parsing phase and are
--   discarded as their information is slotted into the data they refine
--   (CreatorS, TitleS, IdentifierS, etc..)
--   
--   This is specific to epub3
data Refinement
Refinement :: String -> String -> String -> String -> Refinement

-- | id attribute
[refId] :: Refinement -> String

-- | property attribute
[refProp] :: Refinement -> String

-- | scheme attribute
[refScheme] :: Refinement -> String

-- | meta tag text
[refText] :: Refinement -> String

-- | Note: This isn't valid as-is, some required values are empty lists!
emptyMetadata :: Metadata

-- | Used internally by Codec.Epub.Parse.Metadata to merge epub3 meta tag
--   info into the data gathered from an identifier tag
refineIdentifier :: [Refinement] -> Identifier -> Identifier

-- | Used internally by Codec.Epub.Parse.Metadata to merge epub3 meta tag
--   info into the data gathered from a title tag
refineTitle :: [Refinement] -> (String, Title) -> Title

-- | Used internally by Codec.Epub.Parse.Metadata to populate the metadata
--   modified field with data extracted from the epub3 meta tag with
--   property dcterms:modified
getModified :: [Refinement] -> Maybe String

-- | Used internally by Codec.Epub.Parse.Metadata to merge epub3 meta tag
--   info into the data gathered from contributor and creator tags
refineCreator :: [Refinement] -> (String, Creator) -> Creator
instance GHC.Show.Show Codec.Epub.Data.Metadata.Metadata
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Metadata
instance GHC.Show.Show Codec.Epub.Data.Metadata.Description
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Description
instance GHC.Show.Show Codec.Epub.Data.Metadata.Date
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Date
instance GHC.Show.Show Codec.Epub.Data.Metadata.Creator
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Creator
instance GHC.Show.Show Codec.Epub.Data.Metadata.Title
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Title
instance GHC.Show.Show Codec.Epub.Data.Metadata.Identifier
instance GHC.Classes.Eq Codec.Epub.Data.Metadata.Identifier


-- | Data type for working with epub package info
--   
--   This contains the package section from an epub document. In the OPF
--   XML document, this tag contains the other tags (metadata, manifest...)
module Codec.Epub.Data.Package

-- | package tag
data Package
Package :: String -> String -> Package

-- | version attribute. This contains which epub specification version (2.x
--   or 3.x) this document conforms to.
[pkgVersion] :: Package -> String

-- | unique-identifier attribute. This should relate to one metaIdentifier
--   in the Metadata and is intended to represent this book's unique
--   identifier.
[pkgUniqueId] :: Package -> String
instance GHC.Show.Show Codec.Epub.Data.Package.Package
instance GHC.Classes.Eq Codec.Epub.Data.Package.Package


-- | Data types for working with the metadata of epub documents
--   
--   The spine represents a default ordering of items in the manifest.
module Codec.Epub.Data.Spine

-- | package/spine tag
data Spine
Spine :: MFItemId -> [SpineItemref] -> Spine

-- | toc attribute. Must reference the NCX in the manifest
[spineToc] :: Spine -> MFItemId

-- | at least one required
[spineItemrefs] :: Spine -> [SpineItemref]

-- | package/spine/itemref tag
data SpineItemref
SpineItemref :: MFItemId -> Maybe Bool -> SpineItemref

-- | idref attribute. Must reference an item in the manifest
[siIdRef] :: SpineItemref -> MFItemId

-- | linear attribute
[siLinear] :: SpineItemref -> Maybe Bool
instance GHC.Show.Show Codec.Epub.Data.Spine.Spine
instance GHC.Classes.Eq Codec.Epub.Data.Spine.Spine
instance GHC.Show.Show Codec.Epub.Data.Spine.SpineItemref
instance GHC.Classes.Eq Codec.Epub.Data.Spine.SpineItemref


-- | Utility functions shared by several formatting modules
module Codec.Epub.Format.Util
formatSubline :: String -> Maybe String -> String
tellSeq :: MonadWriter (Seq a) m => [a] -> m ()

-- | General-purpose finite sequences.
data Seq a


-- | Module for pretty-printing epub spine info
--   
--   Used internally by Codec.Epub.Format
module Codec.Epub.Format.Spine

-- | Format an epub Spine structure for pretty printing
formatSpine :: Spine -> String


-- | Module for pretty-printing epub package info
--   
--   Used internally by Codec.Epub.Format
module Codec.Epub.Format.Package

-- | Format an epub Package structure for pretty printing
formatPackage :: Package -> String


-- | Module for pretty-printing epub metadata info
--   
--   Used internally by Codec.Epub.Format
module Codec.Epub.Format.Metadata

-- | Format an epub Metadata structure for pretty printing
formatMetadata :: Metadata -> String


-- | Module for pretty-printing epub manifest info
--   
--   Used internally by Codec.Epub.Format
module Codec.Epub.Format.Manifest

-- | Format an epub Manifest structure for pretty printing
formatManifest :: Manifest -> String


-- | Module for pretty-printing epub guide info
--   
--   Used internally by Codec.Epub.Format
module Codec.Epub.Format.Guide

-- | Format an epub Guide structure for pretty printing
formatGuide :: [GuideRef] -> String


-- | Module for pretty-printing epub meta-information
--   
--   Defined here is the Formattable typeclass and instances for the
--   top-level epub data structures. The intention is that consumers use
--   the format function on any of these otherwise disparate types.
module Codec.Epub.Format
class Formattable a
format :: Formattable a => a -> String
instance Codec.Epub.Format.Formattable [Codec.Epub.Data.Guide.GuideRef]
instance Codec.Epub.Format.Formattable Codec.Epub.Data.Manifest.Manifest
instance Codec.Epub.Format.Formattable Codec.Epub.Data.Metadata.Metadata
instance Codec.Epub.Format.Formattable Codec.Epub.Data.Package.Package
instance Codec.Epub.Format.Formattable Codec.Epub.Data.Spine.Spine


-- | Helper functions used by the other parsing modules
module Codec.Epub.Parse.Util

-- | Shortcut arrow to drill down to a specific namespaced child element
atQTag :: (ArrowXml a) => QName -> a (NTree XNode) XmlTree

-- | Shortcut arrow to retrieve the contents of a namespaced element as a
--   Maybe String
mbQTagText :: (ArrowXml a) => QName -> a (NTree XNode) (Maybe String)

-- | Shortcut arrow to retrieve an attribute of an element as a Maybe
--   String
mbGetAttrValue :: (ArrowXml a) => String -> a XmlTree (Maybe String)

-- | Shortcut arrow to retrieve an attribute of a namespaced element as a
--   Maybe String
mbGetQAttrValue :: (ArrowXml a) => QName -> a XmlTree (Maybe String)

-- | Arrow that succeeds if the input is not the empty list
notNullA :: (ArrowList a) => a [b] [b]

-- | Shortcut arrow to gather up the text part of all child nodes
text :: (ArrowXml a) => a (NTree XNode) String

-- | Construct a qualified name in the Dublin Core namespace
dcName :: String -> QName

-- | Construct a qualified name in the epub OPF namespace
opfName :: String -> QName

-- | Construct a qualified name in the XML namespace
xmlName :: String -> QName


-- | Parsing for the spine section of the OPF Package XML Document
module Codec.Epub.Parse.Spine
spineP :: (ArrowXml a) => a (NTree XNode) Spine


-- | Parsing for meta tags in the metadata section of the OPF Package XML
--   Document
module Codec.Epub.Parse.Refinements
refinementsP :: (ArrowXml a) => a (NTree XNode) [Refinement]


-- | Parsing for the package section of the OPF Package XML Document
module Codec.Epub.Parse.Package
packageP :: (ArrowXml a) => a (NTree XNode) Package


-- | Parsing for the metadata section of the OPF Package XML Document
module Codec.Epub.Parse.Metadata
metadataP :: (ArrowXml a) => [Refinement] -> a (NTree XNode) Metadata


-- | Parsing for the manifest section of the OPF Package XML Document
module Codec.Epub.Parse.Manifest
manifestP :: (ArrowXml a) => a (NTree XNode) Manifest


-- | Parsing for the guide section of the OPF Package XML Document
module Codec.Epub.Parse.Guide
guideP :: (ArrowXml a) => a (NTree XNode) [GuideRef]


-- | Utility functions shared by modules that need to read the contents of
--   XML documents.
module Codec.Epub.Util

-- | An evil hack to remove *ILLEGAL* characters before the XML
--   declaration. Why do people write software that does this? Can't they
--   follow directions?
removeIllegalStartChars :: String -> String

-- | An evil hack to remove encoding from the document
removeEncoding :: String -> String

-- | An evil hack to remove any &lt;!DOCTYPE ...&gt; from the document
removeDoctype :: String -> String


-- | The main parsing interface, these get* functions are intended to be
--   used by consumers of this library
--   
--   This module is called Parse because it invokes the XML parsing
--   machinery of this library, but consumers of the library do not have to
--   interact with HXT, Arrows or XML directly.
module Codec.Epub.Parse

-- | Parse epub guide items from a String representing the epub XML Package
--   Document
getGuide :: (MonadIO m, MonadError String m) => String -> m [GuideRef]

-- | Parse epub manifest data from a String representing the epub XML
--   Package Document
getManifest :: (MonadIO m, MonadError String m) => String -> m Manifest

-- | Parse epub metadata from a String representing the epub XML Package
--   Document
getMetadata :: (MonadIO m, MonadError String m) => String -> m Metadata

-- | Parse epub package info from a String representing the epub XML
--   Package Document
getPackage :: (MonadIO m, MonadError String m) => String -> m Package

-- | Parse epub spine info from a String representing the epub XML Package
--   Document
getSpine :: (MonadIO m, MonadError String m) => String -> m Spine


-- | Functions for performing some IO operations on epub files
module Codec.Epub.IO

-- | Get the contents of the epub Package Document from an epub (zip) file
getPkgXmlFromZip :: (MonadError String m, MonadIO m) => FilePath -> m String

-- | Get the path and contents of the epub Package Document from an epub
--   (zip) file
getPkgPathXmlFromZip :: (MonadError String m, MonadIO m) => FilePath -> m (FilePath, String)

-- | Get the path and contents of the epub Package Document from a
--   ByteString representing an epub (zip) file
getPkgPathXmlFromBS :: (MonadError String m, MonadIO m) => ByteString -> m (FilePath, String)

-- | Get the path and contents of the epub Package Document from a
--   directory containing the files from an epub file (as in: it's been
--   unzipped into a dir)
getPkgPathXmlFromDir :: (MonadError String m, MonadIO m) => FilePath -> m (FilePath, String)

-- | Construct a zip Archive containing epub book data from the specified
--   directory
mkEpubArchive :: FilePath -> IO Archive

-- | Read a zip Archive from disk
readArchive :: FilePath -> IO Archive

-- | Write a zip Archive to disk using the specified filename
writeArchive :: FilePath -> Archive -> IO ()


-- | This is a library for parsing and manipulating epub document metadata.
--   Almost all of the data stored in the epub Package Document can be
--   worked with using this API. This includes the most useful block of
--   data, the epub metadata. This library supports epub versions 2 and 3.
--   
--   This library was constructed by studying the IDPF specifications for
--   epub documents found here
--   <a>http://www.idpf.org/epub/20/spec/OPF_2.0.1_draft.htm</a> and here
--   <a>http://www.idpf.org/epub/30/spec/epub30-publications.html</a>
--   
--   Consumers of epub-metadata will likely need this module, which
--   re-exports the most useful parts concerning disk IO, parsing of the
--   XML into Codec.Epub.Data.* data structures and formatting these data
--   structures to be pretty-printed. Please also see
--   Codec.Epub.Data.Metadata etc.
module Codec.Epub
