diff options
| -rw-r--r-- | Data/GraphQL.hs | 25 | ||||
| -rw-r--r-- | Data/GraphQL/AST.hs | 64 | ||||
| -rw-r--r-- | Data/GraphQL/Encoder.hs | 3 | ||||
| -rw-r--r-- | Data/GraphQL/Error.hs | 21 | ||||
| -rw-r--r-- | Data/GraphQL/Execute.hs | 33 | ||||
| -rw-r--r-- | Data/GraphQL/Parser.hs | 3 | ||||
| -rw-r--r-- | Data/GraphQL/Schema.hs | 68 | ||||
| -rw-r--r-- | docs/tutorial/tutorial.html | 165 | ||||
| -rw-r--r-- | docs/tutorial/tutorial.pdf | bin | 0 -> 140420 bytes |
9 files changed, 266 insertions, 116 deletions
diff --git a/Data/GraphQL.hs b/Data/GraphQL.hs index a5dac4d..dfe9362 100644 --- a/Data/GraphQL.hs +++ b/Data/GraphQL.hs @@ -1,6 +1,4 @@ --- | The module Data.GraphQl provides the --- functions graphql and graphqlSubs to parse --- and execute GraphQL queries. +-- | This module provides the functions to parse and execute @GraphQL@ queries. module Data.GraphQL where import Control.Applicative (Alternative) @@ -16,19 +14,20 @@ import Data.GraphQL.Schema import Data.GraphQL.Error --- | graphql takes a schema and text representing a GraphQL request document. --- If the text parses correctly as a GraphQl query --- the query is executed according to the given schema. --- Returns the response to the query wrapped in an Aeson.Value. +-- | Takes a 'Schema' and text representing a @GraphQL@ request document. +-- If the text parses correctly as a @GraphQL@ query the query is +-- executed according to the given 'Schema'. +-- +-- Returns the response as an @Aeson.@'Aeson.Value'. graphql :: (Alternative m, Monad m) => Schema m -> Text -> m Aeson.Value graphql = flip graphqlSubs $ const Nothing --- | graphqlsubs takes in a schema, a substitution and text representing --- a GraphQL request document. --- If the text parses correctly as a GraphQl query --- the substitution is applied to the query and --- the query is then executed according to the given schema. --- Returns the response to the query wrapped in an Aeson.Value. +-- | Takes a 'Schema', a variable substitution function and text +-- representing a @GraphQL@ request document. If the text parses +-- correctly as a @GraphQL@ query the substitution is applied to the +-- query and the query is then executed according to the given 'Schema'. +-- +-- Returns the response as an @Aeson.@'Aeson.Value'. graphqlSubs :: (Alternative m, Monad m) => Schema m -> Subs -> Text -> m Aeson.Value graphqlSubs schema f = either parseError (execute schema f) diff --git a/Data/GraphQL/AST.hs b/Data/GraphQL/AST.hs index 5fdd146..99eaa79 100644 --- a/Data/GraphQL/AST.hs +++ b/Data/GraphQL/AST.hs @@ -1,7 +1,5 @@ -{- | This module defines an - abstract syntax tree for the GraphQL language, based on - <https://facebook.github.io/graphql/ Facebook's GraphQL Specification>. --} +-- | This module defines an abstract syntax tree for the @GraphQL@ language based on +-- <https://facebook.github.io/graphql/ Facebook's GraphQL Specification>. module Data.GraphQL.AST where @@ -44,33 +42,26 @@ data Selection = SelectionField Field | SelectionInlineFragment InlineFragment deriving (Eq,Show) -{- | <https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields Field Specification> - - A selection set is primarily composed of fields. - A field describes one discrete piece of information - available to request within a selection set. - - Some fields describe complex data or relationships to other data. - In order to further explore this data, a field may itself contain - a selection set, allowing for deeply nested requests. - All GraphQL operations must specify their selections down to - fields which return scalar values to ensure an unambiguously - shaped response. - --} +-- | A 'SelectionSet' is primarily composed of 'Field's. A 'Field' describes one +-- discrete piece of information available to request within a 'SelectionSet'. +-- +-- Some 'Field's describe complex data or relationships to other data. In +-- order to further explore this data, a 'Field' may itself contain a +-- 'SelectionSet', allowing for deeply nested requests. All @GraphQL@ operations +-- must specify their 'Selection's down to 'Field's which return scalar values to +-- ensure an unambiguously shaped response. +-- +-- <https://facebook.github.io/graphql/#sec-Language.Query-Document.Fields Field Specification> data Field = Field Alias Name [Argument] [Directive] SelectionSet deriving (Eq,Show) type Alias = Name -{- | <https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments Argument Specification> - - Fields are conceptually functions which return values, - and occasionally accept arguments which alter their behavior. - These arguments often map directly to function arguments within a - GraphQL server’s implementation. - --} +-- | 'Field's are conceptually functions which return values, and occasionally accept +-- 'Argument's which alter their behavior. These 'Argument's often map directly to +-- function arguments within a @GraphQL@ server’s implementation. +-- +-- <https://facebook.github.io/graphql/#sec-Language.Query-Document.Arguments Argument Specification> data Argument = Argument Name Value deriving (Eq,Show) -- * Fragments @@ -90,18 +81,15 @@ type TypeCondition = NamedType -- * Values -{- | <https://facebook.github.io/graphql/#sec-Input-Values Input Value Specification> - - Field and directive arguments accept input values - of various literal primitives; input values can be scalars, - enumeration values, lists, or input objects. - - If not defined as constant (for example, in DefaultValue), - input values can be specified as a variable. - List and inputs objects may also contain - variables (unless defined to be constant). - --} +-- | 'Field' and 'Directive' 'Arguments' accept input values of various literal +-- primitives; input values can be scalars, enumeration values, lists, or input +-- objects. +-- +-- If not defined as constant (for example, in 'DefaultValue'), input values +-- can be specified as a 'Variable'. List and inputs objects may also contain +-- 'Variable's (unless defined to be constant). +-- +-- <https://facebook.github.io/graphql/#sec-Input-Values Input Value Specification> data Value = ValueVariable Variable | ValueInt Int32 -- GraphQL Float is double precison diff --git a/Data/GraphQL/Encoder.hs b/Data/GraphQL/Encoder.hs index 6245bb0..86f090b 100644 --- a/Data/GraphQL/Encoder.hs +++ b/Data/GraphQL/Encoder.hs @@ -1,7 +1,6 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE OverloadedStrings #-} --- | This module defines a printer --- for the GraphQL language. +-- | This module defines a printer for the @GraphQL@ language. module Data.GraphQL.Encoder where #if !MIN_VERSION_base(4,8,0) diff --git a/Data/GraphQL/Error.hs b/Data/GraphQL/Error.hs index 25632b4..74f08e4 100644 --- a/Data/GraphQL/Error.hs +++ b/Data/GraphQL/Error.hs @@ -26,17 +26,17 @@ parseError :: Applicative f => String -> f Aeson.Value parseError s = pure $ Aeson.object [("errors", Aeson.toJSON [makeErrorMsg $ pack s])] --- | A wrapper for an applicative functor, for passing around error messages. +-- | A wrapper for an 'Applicative' to pass error messages around. type CollectErrsT f a = f (a,[Aeson.Value]) --- | Takes a (wrapped) list (foldable functor) of values and errors and +-- | Takes a (wrapped) list (foldable functor) of values and errors, -- joins the values into a list and concatenates the errors. joinErrs :: (Functor m, Functor f, Foldable f) => m (f (a,[Aeson.Value])) -> CollectErrsT m (f a) joinErrs = fmap $ fmap fst &&& concatMap snd --- | Wraps the given applicative to handle errors +-- | Wraps the given 'Applicative' to handle errors errWrap :: Functor f => f a -> f (a, [Aeson.Value]) errWrap = fmap (flip (,) []) @@ -51,12 +51,13 @@ makeErrorMsg s = Aeson.object [("message",Aeson.toJSON s)] addErrMsg :: Functor f => Text -> CollectErrsT f a -> CollectErrsT f a addErrMsg = addErr . makeErrorMsg --- | Runs the given query computation, but collects the errors into an error --- list, which is then sent back with the data. +-- | Runs the given query, but collects the errors into an error +-- list which is then sent back with the data. runCollectErrs :: Functor f => CollectErrsT f Aeson.Value -> f Aeson.Value runCollectErrs = fmap finalD - where finalD (dat,errs) = - Aeson.object $ - if null errs - then [("data",dat)] - else [("data",dat),("errors",Aeson.toJSON $ reverse errs)] + where + finalD (dat,errs) = + Aeson.object + $ if null errs + then [("data",dat)] + else [("data",dat),("errors",Aeson.toJSON $ reverse errs)] diff --git a/Data/GraphQL/Execute.hs b/Data/GraphQL/Execute.hs index a0436f6..86887ff 100644 --- a/Data/GraphQL/Execute.hs +++ b/Data/GraphQL/Execute.hs @@ -1,6 +1,6 @@ {-# LANGUAGE CPP #-} --- | This module provides the function execute which executes a GraphQL --- request according to a given GraphQL schema. +-- | This module provides the function to execute a @GraphQL@ request -- +-- according to a 'Schema'. module Data.GraphQL.Execute (execute) where #if !MIN_VERSION_base(4,8,0) @@ -17,18 +17,18 @@ import qualified Data.GraphQL.Schema as Schema import Data.GraphQL.Error -{- | Takes a schema, a substitution and a GraphQL document. - The substition is applied to the document using rootFields, and - the schema's resolvers are applied to the resulting fields. - Returns the result of the query against the schema wrapped in a - "data" field, or errors wrapped in a "errors field". --} +-- | Takes a 'Schema', a variable substitution function ('Schema.Subs'), and a +-- @GraphQL@ 'document'. The substitution is applied to the document using +-- 'rootFields', and the 'Schema''s resolvers are applied to the resulting fields. +-- +-- Returns the result of the query against the 'Schema' wrapped in a /data/ field, or +-- errors wrapped in an /errors/ field. execute :: Alternative f => Schema.Schema f -> Schema.Subs -> Document -> f Aeson.Value execute (Schema resolvs) subs doc = runCollectErrs res where res = Schema.resolvers resolvs $ rootFields subs doc --- | rootFields takes in a substitution and a GraphQL document. +-- | Takes a variable substitution function and a @GraphQL@ document. -- If the document contains one query (and no other definitions) -- it applies the substitution to the query's set of selections -- and then returns their fields. @@ -37,11 +37,10 @@ rootFields subs (Document [DefinitionOperation (Query (Node _varDefs _ _ sels))] Schema.fields $ substitute subs <$> sels rootFields _ _ = [] --- | substitute takes in a substitution and a selection. --- If the selection is a field it applies the substitution to the --- field's arguments using subsArg, --- and recursively applies the substitution to the arguments of fields --- nested in the primary field. +-- | Takes a variable substitution function and a selection. If the +-- selection is a field it applies the substitution to the field's +-- arguments using 'subsArg', and recursively applies the substitution to +-- the arguments of fields nested in the primary field. substitute :: Schema.Subs -> Selection -> Selection substitute subs (SelectionField (Field alias name args directives sels)) = SelectionField $ Field @@ -54,9 +53,9 @@ substitute subs (SelectionField (Field alias name args directives sels)) = substitute _ sel = sel -- TODO: Support different value types --- | subsArg takes in a substitution and an argument. --- If the argument's value is a variable the substitution --- is applied to the variable's name. +-- | Takes a variable substitution function and an argument. If the +-- argument's value is a variable the substitution is applied to the +-- variable's name. subsArg :: Schema.Subs -> Argument -> Maybe Argument subsArg subs (Argument n (ValueVariable (Variable v))) = Argument n . ValueString <$> subs v diff --git a/Data/GraphQL/Parser.hs b/Data/GraphQL/Parser.hs index ed9df80..227c9a8 100644 --- a/Data/GraphQL/Parser.hs +++ b/Data/GraphQL/Parser.hs @@ -1,7 +1,6 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE OverloadedStrings #-} --- | This module defines a parser --- for GraphQl request documents. +-- | This module defines a parser for @GraphQL@ request documents. module Data.GraphQL.Parser where import Prelude hiding (takeWhile) diff --git a/Data/GraphQL/Schema.hs b/Data/GraphQL/Schema.hs index 0a30eb9..7966392 100644 --- a/Data/GraphQL/Schema.hs +++ b/Data/GraphQL/Schema.hs @@ -1,9 +1,8 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE LambdaCase #-} --- | This module provides the type Schema, --- representing a GraphQL schema, and functions for defining --- a schema. +-- | This module provides a representation of a @GraphQL@ Schema in addition to +-- functions for defining and manipulating Schemas. module Data.GraphQL.Schema ( Schema(..) , Resolver @@ -25,14 +24,16 @@ module Data.GraphQL.Schema ) where #if !MIN_VERSION_base(4,8,0) -import Control.Applicative (pure, (<|>)) +import Control.Applicative (pure) +import Control.Arrow (first) import Data.Foldable (foldMap) import Data.Traversable (traverse) import Data.Monoid (Monoid(mempty,mappend)) #else +import Data.Bifunctor (first) import Data.Monoid (Alt(Alt,getAlt)) #endif -import Control.Applicative (Alternative(..)) +import Control.Applicative (Alternative((<|>), empty)) import Data.Maybe (catMaybes) import Data.Foldable (fold) @@ -42,30 +43,27 @@ import qualified Data.HashMap.Strict as HashMap import Data.Text (Text) import qualified Data.Text as T (null, unwords) -import Control.Arrow - import Data.GraphQL.AST import Data.GraphQL.Error --- | Schema represents a GraphQL schema. --- f usually has to be an instance of Alternative. +-- | A GraphQL schema. +-- @f@ is usually expected to be an instance of 'Alternative'. data Schema f = Schema [Resolver f] --- | Resolver resolves a field in to a wrapped Aeson.Object with error information --- (or empty). The wrapped f usually has to be an instance of Alternative. +-- | Resolves a 'Field' into an @Aeson.@'Aeson.Object' with error information +-- (or 'empty'). @f@ is usually expected to be an instance of 'Alternative'. type Resolver f = Field -> CollectErrsT f Aeson.Object --- | Subs represents a substitution. +-- | Variable substitution function. type Subs = Text -> Maybe Text --- | Objects represent a list of named fields, each of which --- yield a value of a specific type. +-- | Create a named 'Resolver' from a list of 'Resolver's. object :: Alternative f => Text -> [Resolver f] -> Resolver f object name resolvs = objectA name $ \case [] -> resolvs _ -> empty --- | Fields can accept arguments to further specify the return value. +-- | Like 'object' but also taking 'Argument's. objectA :: Alternative f => Text -> ([Argument] -> [Resolver f]) -> Resolver f @@ -78,39 +76,39 @@ scalar name s = scalarA name $ \case [] -> pure s _ -> empty --- | Arguments can be used to further specify a scalar's return value. +-- | Like 'scalar' but also taking 'Argument's. scalarA :: (Alternative f, Aeson.ToJSON a) => Text -> ([Argument] -> f a) -> Resolver f scalarA name f fld@(Field _ _ args _ []) = withField name (errWrap $ f args) fld scalarA _ _ _ = empty --- | Arrays are like objects but have an array of resolvers instead of a list. +-- | Like 'object' but taking lists of 'Resolver's instead of a single list. array :: Alternative f => Text -> [[Resolver f]] -> Resolver f array name resolvs = arrayA name $ \case [] -> resolvs _ -> empty --- | Arguments can be used to further specify an array's return values. +-- | Like 'array' but also taking 'Argument's. arrayA :: Alternative f => Text -> ([Argument] -> [[Resolver f]]) -> Resolver f arrayA name f fld@(Field _ _ args _ sels) = withField name (joinErrs $ traverse (flip resolvers $ fields sels) $ f args) fld --- | An enum represents one of a finite set of possible values. --- Used in place of a scalar when the possible responses are easily enumerable. +-- | Represents one of a finite set of possible values. +-- Used in place of a 'scalar' when the possible responses are easily enumerable. enum :: Alternative f => Text -> f [Text] -> Resolver f enum name enums = enumA name $ \case [] -> enums _ -> empty --- | Arguments can be used to further specify an enum's return values. +-- | Like 'enum' but also taking 'Argument's. enumA :: Alternative f => Text -> ([Argument] -> f [Text]) -> Resolver f enumA name f fld@(Field _ _ args _ []) = withField name (errWrap $ f args) fld enumA _ _ _ = empty --- | Used to implement a resolver with arguments. +-- | Helper function to facilitate 'Argument' handling. withField :: (Alternative f, Aeson.ToJSON a) => Text -> CollectErrsT f a -> Field -> CollectErrsT f (HashMap Text Aeson.Value) @@ -121,25 +119,27 @@ withField name f (Field alias name' _ _ _) = where aliasOrName = if T.null alias then name' else alias --- | resolvers takes a list of resolvers and a list of fields, --- and applies each resolver to each field. Resolves into a value --- containing the resolved field, or a null value and error information. +-- | Takes a list of 'Resolver's and a list of 'Field's and applies each +-- 'Resolver' to each 'Field'. Resolves into a value containing the +-- resolved 'Field', or a null value and error information. resolvers :: Alternative f => [Resolver f] -> [Field] -> CollectErrsT f Aeson.Value resolvers resolvs = fmap (first Aeson.toJSON . fold) - . traverse (\fld -> (getAlt $ foldMap (Alt . ($ fld)) resolvs) <|> errmsg fld) - where errmsg (Field alias name _ _ _) = addErrMsg msg $ (errWrap . pure) val - where val = HashMap.singleton aliasOrName Aeson.Null - msg = T.unwords ["field", name, "not resolved."] - aliasOrName = if T.null alias then name else alias - --- | Checks whether the given selection contains a field and --- returns the field if so, else returns Nothing. + . traverse (\fld -> getAlt (foldMap (Alt . ($ fld)) resolvs) <|> errmsg fld) + where + errmsg (Field alias name _ _ _) = addErrMsg msg $ (errWrap . pure) val + where + val = HashMap.singleton aliasOrName Aeson.Null + msg = T.unwords ["field", name, "not resolved."] + aliasOrName = if T.null alias then name else alias + +-- | Checks whether the given 'Selection' contains a 'Field' and +-- returns the 'Field' if so, else returns 'Nothing'. field :: Selection -> Maybe Field field (SelectionField x) = Just x field _ = Nothing --- | Returns a list of the fields contained in the given selection set. +-- | Returns a list of the 'Field's contained in the given 'SelectionSet'. fields :: SelectionSet -> [Field] fields = catMaybes . fmap field diff --git a/docs/tutorial/tutorial.html b/docs/tutorial/tutorial.html new file mode 100644 index 0000000..fab66c2 --- /dev/null +++ b/docs/tutorial/tutorial.html @@ -0,0 +1,165 @@ +<!DOCTYPE html> +<html> +<head> + <meta charset="utf-8"> + <meta name="generator" content="pandoc"> + <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> + <title>GraphQL Haskell Tutorial</title> + <style type="text/css">code{white-space: pre;}</style> + <style type="text/css"> +div.sourceCode { overflow-x: auto; } +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } +td.sourceCode { padding-left: 5px; } +code > span.kw { color: #0000ff; } /* Keyword */ +code > span.ch { color: #008080; } /* Char */ +code > span.st { color: #008080; } /* String */ +code > span.co { color: #008000; } /* Comment */ +code > span.ot { color: #ff4000; } /* Other */ +code > span.al { color: #ff0000; } /* Alert */ +code > span.er { color: #ff0000; font-weight: bold; } /* Error */ +code > span.wa { color: #008000; font-weight: bold; } /* Warning */ +code > span.cn { } /* Constant */ +code > span.sc { color: #008080; } /* SpecialChar */ +code > span.vs { color: #008080; } /* VerbatimString */ +code > span.ss { color: #008080; } /* SpecialString */ +code > span.im { } /* Import */ +code > span.va { } /* Variable */ +code > span.cf { color: #0000ff; } /* ControlFlow */ +code > span.op { } /* Operator */ +code > span.bu { } /* BuiltIn */ +code > span.ex { } /* Extension */ +code > span.pp { color: #ff4000; } /* Preprocessor */ +code > span.do { color: #008000; } /* Documentation */ +code > span.an { color: #008000; } /* Annotation */ +code > span.cv { color: #008000; } /* CommentVar */ +code > span.at { } /* Attribute */ +code > span.in { color: #008000; } /* Information */ + </style> + <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css"> + <link rel="stylesheet" href="tutorial.css"> + <!--[if lt IE 9]> + <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script> + <![endif]--> +</head> +<body> +<header> +<h1 class="title">GraphQL Haskell Tutorial</h1> +</header> +<nav id="TOC"> +<ul> +<li><a href="#getting-started">Getting started</a><ul> +<li><a href="#first-example">First example</a></li> +<li><a href="#monadic-actions">Monadic actions</a></li> +<li><a href="#errors">Errors</a></li> +<li><a href="#combining-resolvers">Combining resolvers</a></li> +</ul></li> +<li><a href="#further-examples">Further examples</a></li> +</ul> +</nav> +<section id="getting-started" class="level2"> +<h2>Getting started</h2> +<p>Welcome to graphql-haskell!</p> +<p>We have written a small tutorial to help you (and ourselves) understand the graphql package.</p> +<p>Since this file is a literate haskell file, we start by importing some dependencies.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">{-# LANGUAGE OverloadedStrings #-}</span> +<span class="ot">{-# LANGUAGE LambdaCase #-}</span> +<span class="kw">module</span> <span class="dt">Main</span> <span class="kw">where</span> + +<span class="kw">import </span><span class="dt">Prelude</span> <span class="kw">hiding</span> (empty, putStrLn) +<span class="kw">import </span><span class="dt">Data.GraphQL</span> +<span class="kw">import </span><span class="dt">Data.GraphQL.Schema</span> +<span class="kw">import qualified</span> <span class="dt">Data.GraphQL.Schema</span> <span class="kw">as</span> <span class="dt">Schema</span> + +<span class="kw">import </span><span class="dt">Control.Applicative</span> +<span class="kw">import </span><span class="dt">Data.Text</span> <span class="kw">hiding</span> (empty) +<span class="kw">import </span><span class="dt">Data.Aeson</span> +<span class="kw">import </span><span class="dt">Data.ByteString.Lazy.Char8</span> (putStrLn) + +<span class="kw">import </span><span class="dt">Data.Time</span> + +<span class="kw">import </span><span class="dt">Debug.Trace</span></code></pre></div> +<section id="first-example" class="level3"> +<h3>First example</h3> +<p>Now, as our first example, we are going to look at the example from <a href="https://github.com/graphql/graphql-js">graphql.js</a>.</p> +<p>First we build a GraphQL schema.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema1 ::</span> <span class="dt">Alternative</span> f <span class="ot">=></span> <span class="dt">Schema</span> f +schema1 <span class="fu">=</span> <span class="dt">Schema</span> [hello] + +<span class="ot">hello ::</span> <span class="dt">Alternative</span> f <span class="ot">=></span> <span class="dt">Resolver</span> f +hello <span class="fu">=</span> Schema.scalar <span class="st">"hello"</span> (<span class="st">"it's me"</span><span class="ot"> ::</span> <span class="dt">Text</span>)</code></pre></div> +<p>This defines a simple schema with one type and one field, that resolves to a fixed value.</p> +<p>Next we define our query.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">query1 ::</span> <span class="dt">Text</span> +query1 <span class="fu">=</span> <span class="st">"{ hello }"</span></code></pre></div> +<p>To run the query, we call the <code>graphql</code> with the schema and the query.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">main1 ::</span> <span class="dt">IO</span> () +main1 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema1 query1</code></pre></div> +<p>This runs the query by fetching the one field defined, returning</p> +<p><code>{"data" : {"hello":"it's me"}}</code></p> +</section> +<section id="monadic-actions" class="level3"> +<h3>Monadic actions</h3> +<p>For this example, we’re going to be using time.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema2 ::</span> <span class="dt">Schema</span> <span class="dt">IO</span> +schema2 <span class="fu">=</span> <span class="dt">Schema</span> [time] + +<span class="ot">time ::</span> <span class="dt">Resolver</span> <span class="dt">IO</span> +time <span class="fu">=</span> Schema.scalarA <span class="st">"time"</span> <span class="fu">$</span> \<span class="kw">case</span> + [] <span class="ot">-></span> <span class="kw">do</span> t <span class="ot"><-</span> getCurrentTime + return <span class="fu">$</span> show t + _ <span class="ot">-></span> empty</code></pre></div> +<p>This defines a simple schema with one type and one field, which resolves to the current time.</p> +<p>Next we define our query.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">query2 ::</span> <span class="dt">Text</span> +query2 <span class="fu">=</span> <span class="st">"{ time }"</span> + +<span class="ot">main2 ::</span> <span class="dt">IO</span> () +main2 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema2 query2</code></pre></div> +<p>This runs the query, returning the current time</p> +<p><code>{"data": {"time":"2016-03-08 23:28:14.546899 UTC"}}</code></p> +</section> +<section id="errors" class="level3"> +<h3>Errors</h3> +<p>Errors are handled according to the spec, with fields that cause erros being resolved to <code>null</code>, and an error being added to the error list.</p> +<p>An example of this is the following query:</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">queryShouldFail ::</span> <span class="dt">Text</span> +queryShouldFail <span class="fu">=</span> <span class="st">"{ boyhowdy }"</span></code></pre></div> +<p>Since there is no <code>boyhowdy</code> field in our schema, it will not resolve, and the query will fail, as we can see in the following example.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">mainShouldFail ::</span> <span class="dt">IO</span> () +mainShouldFail <span class="fu">=</span> <span class="kw">do</span> + r <span class="ot"><-</span> graphql schema1 query1 + putStrLn <span class="fu">$</span> encode r + putStrLn <span class="st">"This will fail"</span> + r <span class="ot"><-</span> graphql schema1 queryShouldFail + putStrLn <span class="fu">$</span> encode r</code></pre></div> +<p>This outputs:</p> +<pre><code>{"data": {"hello": "it's me"}} +This will fail +{"data": {"boyhowdy": null}, "errors":[{"message": "the field boyhowdy did not resolve."}]}</code></pre> +</section> +<section id="combining-resolvers" class="level3"> +<h3>Combining resolvers</h3> +<p>Now that we have two resolvers, we can define a schema which uses them both.</p> +<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema3 ::</span> <span class="dt">Schema</span> <span class="dt">IO</span> +schema3 <span class="fu">=</span> <span class="dt">Schema</span> [hello, time] + +<span class="ot">query3 ::</span> <span class="dt">Text</span> +query3 <span class="fu">=</span> <span class="st">"query timeAndHello { time hello }"</span> + +<span class="ot">main3 ::</span> <span class="dt">IO</span> () +main3 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema3 query3</code></pre></div> +<p>This queries for both time and hello, returning</p> +<p><code>{ "data": {"hello":"it's me","time":"2016-03-08 23:29:11.62108 UTC"}}</code></p> +<p>Notice that we can name our queries, as we did with <code>timeAndHello</code>. Since we have only been using single queries, we can use the shorthand <code>{ time hello}</code>, as we have been doing in the previous examples.</p> +<p>In GraphQL there can only be one operation per query.</p> +</section> +</section> +<section id="further-examples" class="level2"> +<h2>Further examples</h2> +<p>More examples on queries and a more complex schema can be found in the test directory, in the <a href="../../tests/Test/StarWars">Test.StarWars</a> module. This includes a more complex schema, and more complex queries.</p> +</section> +</body> +</html> diff --git a/docs/tutorial/tutorial.pdf b/docs/tutorial/tutorial.pdf Binary files differnew file mode 100644 index 0000000..6295ee8 --- /dev/null +++ b/docs/tutorial/tutorial.pdf |