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


-- | This package enables to write SPARQL queries to remote endpoints.
--   
--   This package enables to write SPARQL queries to remote endpoints. It
--   provides many of the options provided through the SPARQL protocol. It
--   was inspired by HSparql and SPARQL Python Wrapper (Python). For more
--   information see also:
--   http:<i></i>www.w3.org<i>TR</i>rdf-sparql-protocol/
--   http:<i></i>www.w3.org<i>2005</i>sparql-results# TODO list: Add
--   internal conversion to RDFXML, N3, Turtle and JSON. Implement a parser
--   to validate SPARQL queries.
@package hasparql-client
@version 0.1


-- | Type definitions.
module Database.HaSparqlClient.Types

-- | Representation for SELECT query result format.
data BindingValue

-- | URI reference to remote resource.
URI :: String -> BindingValue

-- | Literal string without datatype or lang.
Literal :: String -> BindingValue

-- | Literal with datatype URI.
TypedLiteral :: String -> String -> BindingValue

-- | Literal with language.
LangLiteral :: String -> String -> BindingValue

-- | Blank Node with label.
BNode :: String -> BindingValue

-- | Unbound result value.
Unbound :: BindingValue

-- | Local representation for a SPARQL service.
data Service
Sparql :: Endpoint -> Query -> DefaultGraph -> [NamedGraph] -> [(ExtraParameters)] -> Service
endpoint :: Service -> Endpoint
query :: Service -> Query
defaultgraph :: Service -> DefaultGraph
namedgraph :: Service -> [NamedGraph]
optionalparameters :: Service -> [(ExtraParameters)]

-- | Represents a SPARQL endpoint.
type Endpoint = String

-- | SPARQL query <a>String</a>.
type Query = String

-- | Add a default graph URI. Overrides the default graph from SPARQL
--   queries.
type DefaultGraph = Maybe String

-- | Add a named graph URI. Overrides named graphs from SPARQL queries.
type NamedGraph = String

-- | Some SPARQL endpoints require extra key value pairs. E.g., in Virtuoso
--   Server, one would add should-sponge=soft to the query forcing virtuoso
--   to retrieve graphs that are not stored in its local database. Can be
--   for example, used to try others output formats in <tt>RunQuery</tt>
--   depending on the server.
type ExtraParameters = (Key, Value)

-- | key of the query part.
type Key = String

-- | value of the query part.
type Value = String

-- | Set to HTTP GET or POST request, according to the SPARQL protocol,
--   some endpoints do not yet support POST requests. Some SPARQL queries,
--   perhaps machine generated, may be longer than can be reliably conveyed
--   by way of the HTTP GET. In those cases the POST may be used.
data Method
HGET :: Method
HPOST :: Method
defaultService :: Service
instance Eq BindingValue
instance Show BindingValue
instance Eq Service
instance Show Service
instance Eq Method
instance Show Method


-- | This module provides some convenience functions to get values from
--   BindingValue.
module Database.HaSparqlClient.Values

-- | Get the language value for a <a>BindingValue</a>. Return
--   <a>Nothing</a> if <a>BindingValue</a> is not <a>LangLiteral</a>.
languageValue :: BindingValue -> Maybe String

-- | Get the datatype value for a <a>BindingValue</a>. Return
--   <a>Nothing</a> if <a>BindingValue</a> is not <a>TypedLiteral</a>.
datatypeValue :: BindingValue -> Maybe String

-- | Get the <a>URI</a> value for a BindingValue. Return <a>Nothing</a> if
--   <a>BindingValue</a> is not <a>URI</a>.
uriValue :: BindingValue -> Maybe String

-- | Get the literal value for a <a>BindingValue</a>. Return <a>Nothing</a>
--   if not is of the any literal type.
literalValue :: BindingValue -> Maybe String

-- | Get the <a>BNode</a> value for a <a>BindingValue</a>. Return
--   <a>Nothing</a> if <a>BindingValue</a> is not <a>BNode</a>.
bnodeValue :: BindingValue -> Maybe String

-- | Get the value for a <a>BindingValue</a>. Return <a>Nothing</a> if
--   BindingValue is <a>Unbound</a>.
value :: BindingValue -> Maybe String
showsparql :: ShowQuery a => a -> String
instance ShowQuery BindingValue


-- | This module provides functions to access remote endpoints.
--   <a>runSelectQuery</a> and <a>runAskQuery</a> may not work if you try
--   to override the output format. See also about <a>HGET</a> and
--   <a>HPOST</a>.
module Database.HaSparqlClient.Queries

-- | Execute a service. On success returns a string created from the
--   service. By default, the string is a representation in XML, other
--   formats such as Turtle and N3 could be returned by adding the output
--   format from the list of optional parameters. Returns an error message
--   on failure. SPARUL and SPARQL can be performed.
runQuery :: Service -> Method -> IO (Either String String)

-- | Find all possible values for a query of type SELECT and may return
--   several lists of <a>BindingValue</a>. URI, Literal and Blank Nodes are
--   now types in Haskell. If it fails returns an error message.
runSelectQuery :: Service -> Method -> IO (Either String [[BindingValue]])

-- | Return Right True or Right False for a query of type ASK. If it fails
--   returns an error message.
runAskQuery :: Service -> Method -> IO (Either String Bool)


-- | Main module
module Database.HaSparqlClient