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


-- | Basic Atom feed construction
--   
--   <a>atom-basic</a> provides a relatively type-safe <a>RFC4287</a> Atom
--   feed that can be used to generate feed or entry XML using the types of
--   any Haskell XML library. Please see the <a>Web.Atom</a> module
--   documentation for more information.
@package atom-basic
@version 0.2.5


-- | <tt>atom-basic</tt> lets you generate Atom Feeds and Atom Entries. It
--   provides the <a>Feed</a> and <a>Entry</a> types for the respective
--   Atom document. This module is intended to be imported qualified to
--   avoid name clashes:
--   
--   <pre>
--   import qualified Web.Atom as Atom
--   </pre>
--   
--   XML generation is not built in because there are several Haskell XML
--   libraries that you might want to use depending on your circumstances.
--   To allow for this, you need to provide an <a>XMLGen</a> record to the
--   <a>feedXML</a> or <a>entryXML</a> functions. An <a>XMLGen</a> record
--   contains functions that generate XML of the type you prefer. <i>Thanks
--   to <a>Ollie Charles</a> for this suggestion.</i>
--   
--   A minimal example using the <a>xml</a> package looks like this
--   (<a>GitHub</a>):
--   
--   <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   import qualified Data.Text      as T
--   import           Data.Time      (UTCTime (..), fromGregorian)
--   import           Text.XML.Light
--   import qualified Web.Atom       as Atom
--   
--   feed :: Atom.Feed Element
--   feed = Atom.makeFeed
--       (Atom.unsafeURI "https://haskell.org/")
--       (Atom.TextHTML "The &lt;em&gt;Title&lt;/em&gt;")
--       (UTCTime (fromGregorian 2015 7 8) 0)
--   
--   xmlgen :: Atom.XMLGen Element Content QName Attr
--   xmlgen = Atom.XMLGen
--       { Atom.xmlElem     = \n as ns    -&gt; Element n as ns Nothing
--       , Atom.xmlName     = \nsMay name -&gt; QName (T.unpack name)
--                                             (fmap T.unpack nsMay) Nothing
--       , Atom.xmlAttr     = \k v        -&gt; Attr k (T.unpack v)
--       , Atom.xmlTextNode = \t          -&gt; Text $ CData CDataText (T.unpack t) Nothing
--       , Atom.xmlElemNode = Elem
--       }
--   
--   main = putStr $ ppTopElement $ Atom.feedXML xmlgen feed
--   </pre>
--   
--   Another example that uses the <a>xml-conduit</a> package instead is
--   also available <a>in the GitHub repository</a>.
module Web.Atom

-- | Convenience constructor with defaults for all non-required fields.
makeFeed :: URI -> Text e -> UTCTime -> Feed e

-- | Convenience constructor with defaults for all non-required fields.
makeEntry :: URI -> Text e -> UTCTime -> Entry e

-- | Generate an XML value from a <a>Feed</a>.
feedXML :: XMLGen e node name attr -> Feed e -> e

-- | Generate an XML value from an <a>Entry</a>.
entryXML :: XMLGen e node name attr -> Entry e -> e

-- | This record defines what kind of XML we should construct. A valid
--   definition of this record must be provided to the <a>feedXML</a> and
--   <a>entryXML</a> functions. This lets users use the XML library of
--   their choice for the Atom feed XML. A couple of concrete examples are
--   provided at the top of this page. Here's an example that uses the
--   <a>xml-conduit</a> package:
--   
--   <pre>
--   xmlgen :: Atom.XMLGen Element Node Name (Name, T.Text)
--   xmlgen = Atom.XMLGen
--       { Atom.xmlElem     = \n as ns    -&gt; Element n (fromList as) ns
--       , Atom.xmlName     = \nsMay name -&gt; Name name nsMay Nothing
--       , Atom.xmlAttr     = \k v        -&gt; (k, v)
--       , Atom.xmlTextNode = NodeContent
--       , Atom.xmlElemNode = NodeElement
--       }
--   </pre>
data XMLGen elem node name attr
XMLGen :: (name -> [attr] -> [node] -> elem) -> (Maybe Text -> Text -> name) -> (name -> Text -> attr) -> (Text -> node) -> (elem -> node) -> XMLGen elem node name attr

-- | Create element from name, attributes, and nodes/contents.
[xmlElem] :: XMLGen elem node name attr -> name -> [attr] -> [node] -> elem

-- | Create qualified name from optional namespace and name.
[xmlName] :: XMLGen elem node name attr -> Maybe Text -> Text -> name

-- | Create attribute from qualified name and text value.
[xmlAttr] :: XMLGen elem node name attr -> name -> Text -> attr

-- | Create text node/content from text value.
[xmlTextNode] :: XMLGen elem node name attr -> Text -> node

-- | Create element node/content from element.
[xmlElemNode] :: XMLGen elem node name attr -> elem -> node

-- | Top-level element for an Atom Feed Document as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.1.1</a>.
data Feed e
Feed :: URI -> Text e -> UTCTime -> Maybe (Text e) -> Maybe URI -> Maybe URI -> Maybe (Text e) -> Maybe Generator -> [Person] -> [Person] -> [Category] -> [Link] -> [Entry e] -> Feed e
[feedId] :: Feed e -> URI
[feedTitle] :: Feed e -> Text e
[feedUpdated] :: Feed e -> UTCTime
[feedSubtitle] :: Feed e -> Maybe (Text e)
[feedIcon] :: Feed e -> Maybe URI
[feedLogo] :: Feed e -> Maybe URI
[feedRights] :: Feed e -> Maybe (Text e)
[feedGenerator] :: Feed e -> Maybe Generator
[feedAuthors] :: Feed e -> [Person]
[feedContributors] :: Feed e -> [Person]
[feedCategories] :: Feed e -> [Category]
[feedLinks] :: Feed e -> [Link]
[feedEntries] :: Feed e -> [Entry e]

-- | An individual Atom entry that can be used either as a child of
--   <a>Feed</a> or as the top-level element of a stand-alone Atom Entry
--   Document as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.1.2</a>.
data Entry e
Entry :: URI -> (Text e) -> UTCTime -> Maybe UTCTime -> Maybe (Text e) -> Maybe (Content e) -> Maybe (Text e) -> Maybe (Source e) -> [Person] -> [Person] -> [Category] -> [Link] -> Entry e
[entryId] :: Entry e -> URI
[entryTitle] :: Entry e -> (Text e)
[entryUpdated] :: Entry e -> UTCTime
[entryPublished] :: Entry e -> Maybe UTCTime
[entrySummary] :: Entry e -> Maybe (Text e)
[entryContent] :: Entry e -> Maybe (Content e)
[entryRights] :: Entry e -> Maybe (Text e)
[entrySource] :: Entry e -> Maybe (Source e)
[entryAuthors] :: Entry e -> [Person]
[entryContributors] :: Entry e -> [Person]
[entryCategories] :: Entry e -> [Category]
[entryLinks] :: Entry e -> [Link]

-- | If an Atom entry is copied into a different feed, <a>Source</a> can be
--   used to preserve the metadata of the original feed as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.2.11</a>.
data Source e
Source :: Maybe URI -> Maybe (Text e) -> Maybe UTCTime -> Maybe (Text e) -> Maybe URI -> Maybe URI -> Maybe (Text e) -> Maybe Generator -> [Person] -> [Person] -> [Category] -> [Link] -> Source e
[sourceId] :: Source e -> Maybe URI
[sourceTitle] :: Source e -> Maybe (Text e)
[sourceUpdated] :: Source e -> Maybe UTCTime
[sourceSubtitle] :: Source e -> Maybe (Text e)
[sourceIcon] :: Source e -> Maybe URI
[sourceLogo] :: Source e -> Maybe URI
[sourceRights] :: Source e -> Maybe (Text e)
[sourceGenerator] :: Source e -> Maybe Generator
[sourceAuthors] :: Source e -> [Person]
[sourceContributors] :: Source e -> [Person]
[sourceCategories] :: Source e -> [Category]
[sourceLinks] :: Source e -> [Link]

-- | Content or link to content of an Atom entry as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.1.3</a>.
data Content e
InlinePlainContent :: Text -> Content e
InlineHTMLContent :: Text -> Content e
InlineXHTMLContent :: e -> Content e
InlineXMLContent :: e -> (Maybe MediaType) -> Content e
InlineTextContent :: Text -> (Maybe MediaType) -> Content e
InlineBase64Content :: ByteString -> (Maybe MediaType) -> Content e
OutOfLineContent :: URI -> (Maybe MediaType) -> Content e

-- | Information about a feed or entry category as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.2.2</a>.
data Category
Category :: Text -> Maybe URI -> Maybe Text -> Category
[categoryTerm] :: Category -> Text
[categoryScheme] :: Category -> Maybe URI
[categoryLabel] :: Category -> Maybe Text

-- | Identifies the agent used to generate the feed, for debugging and
--   other purposes as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.2.4</a>.
data Generator
Generator :: Text -> Maybe URI -> Maybe Text -> Generator
[generatorName] :: Generator -> Text
[generatorURI] :: Generator -> Maybe URI
[version] :: Generator -> Maybe Text

-- | Describes a person as per
--   <a>https://tools.ietf.org/html/rfc4287#section-3.2</a>.
data Person
Person :: Text -> Maybe URI -> Maybe Email -> Person
[personName] :: Person -> Text
[personURI] :: Person -> Maybe URI
[personEmail] :: Person -> Maybe Email

-- | An email address. <tt>xsd:string { pattern = ".+</tt>.+" }@
data Email
Email :: Text -> Email

-- | <tt>rel</tt> attribute for link elements as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.2.7.2</a>.
data Rel
RelText :: Text -> Rel
RelURI :: URI -> Rel

-- | Human readable text as per
--   <a>https://tools.ietf.org/html/rfc4287#section-3.1</a>.
data Text e
TextPlain :: Text -> Text e
TextHTML :: Text -> Text e
TextXHTML :: e -> Text e

-- | Defines a reference to a web resource as per
--   <a>https://tools.ietf.org/html/rfc4287#section-4.2.7</a>.
data Link
Link :: URI -> Maybe Rel -> Maybe MediaType -> Maybe LanguageTag -> Maybe Text -> Maybe Integer -> Link
[linkHref] :: Link -> URI
[linkRel] :: Link -> Maybe Rel
[linkType] :: Link -> Maybe MediaType
[linkHrefLang] :: Link -> Maybe LanguageTag
[linkTitle] :: Link -> Maybe Text
[linkLength] :: Link -> Maybe Integer

-- | Langauge tag as per <a>https://tools.ietf.org/html/rfc3066</a>.
data LanguageTag
LanguageTag :: Text -> LanguageTag

-- | A media type. <tt>xsd:string { pattern = ".+/.+" }</tt>
data MediaType
MediaType :: ByteString -> MediaType

-- | This is the simplest representation of UTC. It consists of the day
--   number, and a time offset from midnight. Note that if a day has a leap
--   second added to it, it will have 86401 seconds.
data UTCTime :: *

-- | Convenience function to create a URIs from hardcoded strings. /This
--   function is partial so only use this if you're hardcoding the URI
--   string and you're sure that it's valid./
unsafeURI :: String -> URI

-- | Represents a general universal resource identifier using its component
--   parts.
--   
--   For example, for the URI
--   
--   <pre>
--   foo://anonymous@www.haskell.org:42/ghc?query#frag
--   </pre>
--   
--   the components are:
data URI :: *
URI :: String -> Maybe URIAuth -> String -> String -> String -> URI

-- | <pre>
--   foo:
--   </pre>
[uriScheme] :: URI -> String

-- | <pre>
--   //anonymous@www.haskell.org:42
--   </pre>
[uriAuthority] :: URI -> Maybe URIAuth

-- | <pre>
--   /ghc
--   </pre>
[uriPath] :: URI -> String

-- | <pre>
--   ?query
--   </pre>
[uriQuery] :: URI -> String

-- | <pre>
--   #frag
--   </pre>
[uriFragment] :: URI -> String
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Atom.Feed e)
instance GHC.Show.Show e => GHC.Show.Show (Web.Atom.Feed e)
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Atom.Entry e)
instance GHC.Show.Show e => GHC.Show.Show (Web.Atom.Entry e)
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Atom.Source e)
instance GHC.Show.Show e => GHC.Show.Show (Web.Atom.Source e)
instance GHC.Classes.Eq Web.Atom.Link
instance GHC.Show.Show Web.Atom.Link
instance GHC.Classes.Eq Web.Atom.Category
instance GHC.Show.Show Web.Atom.Category
instance GHC.Classes.Eq Web.Atom.Generator
instance GHC.Show.Show Web.Atom.Generator
instance GHC.Classes.Eq Web.Atom.Person
instance GHC.Show.Show Web.Atom.Person
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Atom.Content e)
instance GHC.Show.Show e => GHC.Show.Show (Web.Atom.Content e)
instance GHC.Classes.Eq e => GHC.Classes.Eq (Web.Atom.Text e)
instance GHC.Show.Show e => GHC.Show.Show (Web.Atom.Text e)
instance GHC.Classes.Eq Web.Atom.Rel
instance GHC.Classes.Eq Web.Atom.MediaType
instance GHC.Show.Show Web.Atom.MediaType
instance GHC.Classes.Eq Web.Atom.Email
instance GHC.Show.Show Web.Atom.Email
instance GHC.Classes.Eq Web.Atom.LanguageTag
instance GHC.Show.Show Web.Atom.LanguageTag
instance Web.Atom.ToXML e (Web.Atom.Feed e)
instance Web.Atom.ToXML e (Web.Atom.Entry e)
instance Web.Atom.ToXML e (Web.Atom.Source e)
instance Web.Atom.ToXML e (Web.Atom.Text e)
instance Web.Atom.ToXML e (Web.Atom.Content e)
instance Web.Atom.ToXML e Web.Atom.Person
instance Web.Atom.ToXML e Web.Atom.Category
instance Web.Atom.ToXML e Web.Atom.Generator
instance Web.Atom.ToXML e Web.Atom.Link
instance Web.Atom.ToXML e Network.URI.URI
instance Web.Atom.ToXML e Data.Time.Clock.Internal.UTCTime.UTCTime
instance Data.String.IsString (Web.Atom.Text e)
instance GHC.Show.Show Web.Atom.Rel
instance Data.String.IsString Web.Atom.MediaType
