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


-- | Representation and Incremental Processing of RDF Data
--   
--   Data structures, parsers, and encoders for RDF data sets based on the
--   RDF 1.1 abstract syntax and RFC 3987. The interface is intended to
--   support incremental graph processing in constant space.
@package rdf
@version 0.1.0.2


-- | This module provides parsers for the primitive terms in the RDF
--   abstract syntax as described in RDF 1.1 Concepts and Abstract Syntax.
--   These should be useful for all RDF host languages.
module Data.RDF.Parser.Common

-- | <a>Subject</a> parser.
parseSubject :: Parser Subject

-- | <a>Predicate</a> parser.
parsePredicate :: Parser Predicate

-- | <a>Object</a> parser.
parseObject :: Parser Object

-- | Parser for graph labels, i.e. either an escaped <a>IRI</a> or the
--   empty string.
parseGraphLabel :: Parser (Maybe IRI)

-- | Parse a blank node label, with the preceeding <tt>_:</tt>.
parseBlankNode :: Parser BlankNode

-- | Parse an RDF <a>Literal</a>, including the <a>LiteralType</a> if
--   present.
parseLiteral :: Parser Literal

-- | <a>IRI</a> parser.
parseIRI :: Parser IRI

-- | Parse an escaped <a>IRI</a>, i.e. an IRI enclosed in angle brackets.
parseEscapedIRI :: Parser IRI


-- | This module provides types for representing RDF data based on the
--   abstract syntax described in RDF 1.1 Concepts and Abstract Syntax.
module Data.RDF.Types

-- | A contiguous RDF graph with optional label. Note that a contiguous
--   graph within an RDF data set will not appear as a single contiguous
--   graph to this library if the graph's constituent triples are not
--   contiguous in the original data set. This strategy allows for
--   incremental processing of RDF data in constant space.
data RDFGraph
RDFGraph :: !(Maybe IRI) -> [Triple] -> RDFGraph

-- | A named RDF graph includes an <a>IRI</a>.
[rdfLabel] :: RDFGraph -> !(Maybe IRI)

-- | The constituent triples. A proper graph is a strict set of triples
--   (i.e. no duplicate nodes or edges), but this guarantee cannot be made
--   if the triples are to be processed incrementally in constant space.
--   Programs using this type for interpreting RDF graphs should ignore any
--   supernumerary triples in this list.
[rdfTriples] :: RDFGraph -> [Triple]

-- | An RDF quad, i.e. a triple belonging to a named graph.
data Quad
Quad :: !Triple -> !(Maybe IRI) -> Quad
[quadTriple] :: Quad -> !Triple
[quadGraph] :: Quad -> !(Maybe IRI)

-- | An RDF triple.
data Triple
Triple :: !Subject -> !Predicate -> !Object -> Triple

-- | An RDF subject, i.e. either an <a>IRI</a> or a <a>BlankNode</a>.
--   
--   This type has an <a>IsString</a> instance, allowing string literals to
--   be interpreted as <a>Subject</a>s with <tt>-XOverloadedStrings</tt>,
--   like so:
--   
--   <pre>
--   &gt;&gt;&gt; "&lt;http://example.com&gt; :: Subject
--   IRISubject (IRI (...))
--   
--   &gt;&gt;&gt; "_:some-node" :: Subject
--   BlankSubject (BlankNode {unBlankNode = "some-node"})
--   </pre>
data Subject
IRISubject :: !IRI -> Subject
BlankSubject :: !BlankNode -> Subject

-- | An RDF predicate.
--   
--   This type has an <a>IsString</a> instance, allowing string literals to
--   be interpreted as <a>Predicate</a>s with <tt>-XOverloadedStrings</tt>,
--   like so:
--   
--   <pre>
--   &gt;&gt;&gt; "&lt;http://example.com&gt;" :: Predicate
--   Predicate {unPredicate = IRI (...)}
--   </pre>
newtype Predicate
Predicate :: IRI -> Predicate
[unPredicate] :: Predicate -> IRI

-- | An RDF object, i.e. either an <a>IRI</a>, a <a>Literal</a>, or a
--   <a>BlankNode</a>.
--   
--   This type has an <a>IsString</a> instance, allowing string literals to
--   be interpreted as <a>Object</a>s with <tt>-XOverloadedStrings</tt>,
--   like so:
--   
--   <pre>
--   &gt;&gt;&gt; "&lt;http://example.com&gt;" :: Object
--   IRIObject (IRI (...))
--   
--   &gt;&gt;&gt; "_:some-node" :: Object
--   BlankObject (BlankNode {unBlankNode = "some-node"})
--   
--   &gt;&gt;&gt; "computer" :: Object
--   LiteralObject (Literal {litString = "computer", litType = LiteralUntyped})
--   </pre>
--   
--   The precedence for literal interpretation is IRI &gt; BlankNode &gt;
--   Literal. To force a literal that is also a valid blank node label or
--   IRI to be interpreted as a <a>LiteralObject</a>, wrap it in an extra
--   set of double quotes:
--   
--   <pre>
--   &gt;&gt;&gt; "\"_:some-node\"" :: Object
--   LiteralObject (Literal {litString = "_:some-node", litType = LiteralUntyped})
--   </pre>
data Object
IRIObject :: !IRI -> Object
BlankObject :: !BlankNode -> Object
LiteralObject :: !Literal -> Object

-- | A blank node with its local label, without the preceeding "_:". Other
--   programs processing RDF are permitted to discard these node labels,
--   i.e. all blank node labels are local to a specific representation of
--   an RDF data set.
--   
--   This type has an <a>IsString</a> instance, allowing string literals to
--   be interpreted as <a>BlankNode</a>s with <tt>-XOverloadedStrings</tt>,
--   like so:
--   
--   <pre>
--   &gt;&gt;&gt; "_:some-node" :: BlankNode
--   BlankNode {unBlankNode = "some-node"}
--   </pre>
newtype BlankNode
BlankNode :: Text -> BlankNode
[unBlankNode] :: BlankNode -> Text

-- | An RDF literal. As stipulated by the RDF standard, the <a>litType</a>
--   is merely metadata; all RDF processing programs must try to handle
--   literals that are ill-typed.
--   
--   This type has an <a>IsString</a> instance, allowing string literals to
--   be interpreted as <a>Literal</a>s with <tt>-XOverloadedStrings</tt>,
--   like so:
--   
--   <pre>
--   &gt;&gt;&gt; "computer" :: Literal
--   Literal {litString = "computer", litType = LiteralUntyped}
--   </pre>
--   
--   For untyped literals the extra double quotes are not required. They
--   are required for typed literals:
--   
--   <pre>
--   &gt;&gt;&gt; "\"computer\"@en" :: Literal
--   Literal {litString = "computer", litType = LiteralLangType "en"}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; "\"computer\"^^&lt;http://computer.machine/machine&gt;" :: Literal
--   Literal { litString = "computer", litType = LiteralIRIType (...)}
--   </pre>
data Literal
Literal :: !Text -> !LiteralType -> Literal
[litString] :: Literal -> !Text
[litType] :: Literal -> !LiteralType

-- | An RDF literal type. As stipulated by the RDF standard, this is merely
--   metadata; all RDF processing programs must try to handle literals that
--   are ill-typed.
data LiteralType
LiteralIRIType :: !IRI -> LiteralType
LiteralLangType :: !Text -> LiteralType
LiteralUntyped :: LiteralType

-- | An Internationalized Resource Identifier. This library preferentially
--   follows RFC 3987 over the RDF 1.1 specification, as the two standards
--   disagree about precisely what constitutes an IRI. A notable exception
--   is the handling of IRI fragments; this library follows the RDF 1.1
--   specification, allowing IRI fragments to occur in absolute IRIs, even
--   though this is expressly prohibited by RFC 3987.
--   
--   Unlike the <tt>network-uri</tt> package's behavior with URI fields,
--   this library does not include the sentinel tokens in the parsed
--   fields. For example, when parsing <tt><a>http://example.com</a></tt>,
--   <tt>network-uri</tt> will provide the string <tt>http:</tt> as the
--   scheme, while this library will provide <tt>http</tt> as the scheme.
--   
--   This type has an <a>IsString</a> instnace, allowing string literals to
--   be interpreted as <a>IRI</a>s with <tt>-XOverloadedStrings</tt>, like
--   so:
--   
--   <pre>
--   &gt;&gt;&gt; "http://example.com" :: IRI
--   IRI { iriScheme = "http"
--       , iriAuth = Just (IRIAuth { iriUser = Nothing
--                                 , iriHost = "example.com"
--                                 , iriPort = Nothing
--                                 })
--       , iriPath = ""
--       , iriQuery = Nothing
--       , iriFragment = Nothing
--       }
--   </pre>
data IRI
IRI :: !Text -> !(Maybe IRIAuth) -> !Text -> !(Maybe Text) -> !(Maybe Text) -> IRI

-- | The IRI scheme, e.g. <tt>http</tt>
[iriScheme] :: IRI -> !Text

-- | The IRI authority, e.g. <tt>example.com</tt>
[iriAuth] :: IRI -> !(Maybe IRIAuth)

-- | The IRI path, e.g. <tt><i>posts</i>/index.html</tt>
[iriPath] :: IRI -> !Text

-- | The IRI query, i.e. the component after the <tt>?</tt> if present.
[iriQuery] :: IRI -> !(Maybe Text)

-- | The IRI fragment, i.e. the component after the <tt>#</tt> if present.
[iriFragment] :: IRI -> !(Maybe Text)

-- | An IRI Authority, as described by RFC 3987.
data IRIAuth
IRIAuth :: !(Maybe Text) -> Text -> !(Maybe Text) -> IRIAuth

-- | The IRI user, i.e. the component before the <tt>@</tt> if present.
[iriUser] :: IRIAuth -> !(Maybe Text)

-- | The IRI host, e.g. <tt>example.com</tt>.
[iriHost] :: IRIAuth -> Text

-- | The IRI port, i.e. the numeral after the <tt>:</tt> if present.
[iriPort] :: IRIAuth -> !(Maybe Text)


-- | This module provides a simple DSL for mapping Haskell data to RDF
--   graphs.
module Data.RDF.ToRDF
class ToRDF a
triples :: ToRDF a => a -> RDFGen Triples
class ToObject a
object :: ToObject a => a -> RDFGen Object
toTriples :: ToRDF a => IRI -> a -> [Triple]
type Triples = DList Triple

-- | RDF generator monad. Provides <a>ReaderT</a> for the base <a>IRI</a>,
--   and <a>StateT</a> for a monotonically increasing blank node
--   identifier.
type RDFGen a = ReaderT IRI (State Word64) a
runRDFGen :: RDFGen a -> IRI -> a
appBaseIRI :: Endo IRI -> RDFGen IRI
newBlankNode :: RDFGen BlankNode
instance Data.RDF.ToRDF.ToObject GHC.Types.Int
instance Data.RDF.ToRDF.ToObject GHC.Integer.Type.Integer
instance Data.RDF.ToRDF.ToObject GHC.Int.Int8
instance Data.RDF.ToRDF.ToObject GHC.Int.Int16
instance Data.RDF.ToRDF.ToObject GHC.Int.Int32
instance Data.RDF.ToRDF.ToObject GHC.Int.Int64
instance Data.RDF.ToRDF.ToObject GHC.Types.Word
instance Data.RDF.ToRDF.ToObject GHC.Word.Word8
instance Data.RDF.ToRDF.ToObject GHC.Word.Word16
instance Data.RDF.ToRDF.ToObject GHC.Word.Word32
instance Data.RDF.ToRDF.ToObject GHC.Word.Word64
instance Data.RDF.ToRDF.ToObject GHC.Base.String
instance Data.RDF.ToRDF.ToObject Data.Text.Internal.Text
instance Data.RDF.ToRDF.ToObject Data.Text.Internal.Lazy.Text
instance Data.RDF.ToRDF.ToObject GHC.Types.Float
instance Data.RDF.ToRDF.ToObject GHC.Types.Double


-- | A parser for <a>RDF 1.1 N-Quads</a>.
module Data.RDF.Parser.NQuads

-- | Either an <a>RDFGraph</a> or a parse error.
type Result = Either String RDFGraph

-- | A parser for <a>RDF 1.1 N-Quads</a>. This parser works incrementally
--   by first lazily splitting the input into lines, then parsing each line
--   of the N-Quads document individually. This allows for incremental
--   processing in constant space, as well as extracting any valid data
--   from an N-Quads document that contains some invalid quads. <a>Text</a>
--   is used because the RDF 1.1 specification stipulates that RDF should
--   always be encoded with Unicode.
--   
--   Due to its incremental nature, this parser will accept some N-Quads
--   documents that are not legal according to the RDF 1.1 specification.
--   Specifically, this parser will provide duplicate <a>Triple</a>s if
--   they exist in the input N-Quads document; a proper graph consists of
--   true sets of nodes and edges, i.e. no duplicate nodes or edges. Any
--   downstream program incrementally consuming this parser's output should
--   take care to ignore any supernumerary triples.
--   
--   Likewise, if a graph's constituent triples are not contiguous in the
--   input N-Quads document, then they will not be folded into contiguous
--   <a>RDFGraph</a>s in this parser's output. Any downstream program
--   incrementally consuming this parser's output and performing graph
--   processing that discriminates based on graph labels will not
--   necessarily be presented each contiguous labeled graph as a single
--   <a>RDFGraph</a> record. For example, something like this could be used
--   to lazily find all <a>RDFGraph</a> records containing a named graph's
--   <a>Triple</a>s. Downstream processing must then be able to handle a
--   single named graph spanning multiple <a>RDFGraph</a> records.
--   
--   <pre>
--   filterGraph :: (Maybe IRI) -&gt; [RDFGraph] -&gt; [RDFGraph]
--   filterGraph gl = filter (\g -&gt; (graphLabel g) == gl)
--   </pre>
parseNQuads :: Text -> [Result]

-- | Parse a single N-Quads <a>Triple</a>.
parseTriple :: Parser Triple

-- | Parse a single N-Quads <a>Quad</a>.
parseQuad :: Parser Quad

-- | Parse a single N-Quads <a>Quad</a> on its own line. This parser is
--   suitable for using Attoparsec's incremental input mechanism
--   'parse'/'feed' instead of a lazy <a>Text</a>.
parseQuadLine :: Parser Quad

-- | Fold a list of <a>Quad</a>s into a list of <a>RDFGraph</a>s, where
--   adjacent <a>Quad</a>s in the input are included in the same
--   <a>RDFGraph</a>.
foldGraphs :: [Quad] -> [RDFGraph]

-- | Fold a list of parsed <a>Quad</a>s into a list of parsed
--   <a>RDFGraph</a>s, where adjacent <a>Quad</a>s in the input are
--   included in the same <a>RDFGraph</a>.
foldResults :: [Either String Quad] -> [Result]


-- | This module provides conversion between RDF triples and <tt>fgl</tt>
--   graphs. Naturally these functions will force the entire graph into
--   memory.
module Data.RDF.Graph

-- | An RDF <a>Subject</a> or <a>Object</a> as a <a>Graph</a> node. This
--   common representation is necessary because the <a>Object</a> of one
--   <a>Triple</a> might be the <a>Subject</a> of another.
data GNode
IRIGNode :: !IRI -> GNode
BlankGNode :: !BlankNode -> GNode
LiteralGNode :: !Literal -> GNode

-- | A <a>Graph</a> edge is an RDF <a>Predicate</a>.
type GEdge = Predicate

-- | Convert an <a>RDFGraph</a> into a <a>DynGraph</a> and <a>NodeMap</a>.
--   The <tt>graphLabel</tt> is discarded.
rdfGraph :: DynGraph g => RDFGraph -> (g GNode GEdge, NodeMap GNode)

-- | Convert a list of <a>Triple</a>s into a <a>DynGraph</a> and a
--   <a>NodeMap</a>.
triplesGraph :: DynGraph g => [Triple] -> (g GNode GEdge, NodeMap GNode)

-- | Convert a <a>Graph</a> into an <a>RDFGraph</a>. This will fail if the
--   graph contains any <a>LiteralGNode</a>s with an outward degree greater
--   than zero, since such a graph is illegal in RDF.
graphRDF :: Graph g => Maybe IRI -> g GNode GEdge -> Either String RDFGraph

-- | Convert a <a>Graph</a> into a list of <a>Triple</a>s. This will fail
--   if the graph contains any <a>LiteralGNode</a>s with an outward degree
--   greater than zero, since such a graph is illegal in RDF.
graphTriples :: Graph g => g GNode GEdge -> Either String [Triple]
instance Control.DeepSeq.NFData Data.RDF.Graph.GNode
instance GHC.Generics.Generic Data.RDF.Graph.GNode
instance GHC.Show.Show Data.RDF.Graph.GNode
instance GHC.Read.Read Data.RDF.Graph.GNode
instance GHC.Classes.Ord Data.RDF.Graph.GNode
instance GHC.Classes.Eq Data.RDF.Graph.GNode


-- | This module provides encoders for the primitive terms in the RDF
--   abstract syntax as described in RDF 1.1 Concepts and Abstract Syntax.
--   These should be useful for all RDF host languages.
module Data.RDF.Encoder.Common

-- | Encode a <a>Subject</a>.
encodeSubject :: Subject -> Builder

-- | Encode a <a>Predicate</a>.
encodePredicate :: Predicate -> Builder

-- | Encode a <a>Object</a>.
encodeObject :: Object -> Builder

-- | Encode a <a>BlankNode</a>.
encodeBlankNode :: BlankNode -> Builder

-- | Encode a <a>Literal</a>, including the <a>LiteralType</a>.
encodeLiteral :: Literal -> Builder

-- | Encode an <a>IRI</a>.
encodeIRI :: IRI -> Builder

-- | Encode an escaped <a>IRI</a>, i.e. between angle brackets.
encodeEscapedIRI :: IRI -> Builder

-- | Escape the double quotes in a quoted string literal.
quoteString :: Text -> Text

-- | Maps <a>Nothing</a> to <a>mempty</a>.
maybeBuilder :: Maybe Builder -> Builder


-- | An encoder for <a>RDF 1.1 N-Quads</a>. <a>Builder</a>s are used to
--   support efficient incremental output.
module Data.RDF.Encoder.NQuads

-- | Encode a single <a>RDFGraph</a> as a <a>Builder</a>.
encodeRDFGraph :: RDFGraph -> Builder

-- | Encode multiple <a>RDFGraph</a>s as a <a>Builder</a>.
encodeRDFGraphs :: Foldable f => f RDFGraph -> Builder

-- | Encodes a <a>Triple</a> as a single line, i.e. with no graph label.
--   Includes the terminating period and newline.
encodeTriple :: Triple -> Builder

-- | Encodes a <a>Quad</a> as a single line. Includes the terminating
--   period and newline.
encodeQuad :: Quad -> Builder
