Added a tutorial, based on graphql-js and servant documentation.

4 files changed, 333 insertions, 0 deletions

diff --git a/docs/tutorial/Makefile b/docs/tutorial/Makefile
new file mode 100644
index 0000000..04d8d71
--- /dev/null
+++ b/docs/tutorial/Makefile
@@ -0,0 +1,4 @@
+default:
+	pandoc -f markdown+lhs+yaml_metadata_block --highlight-style=haddock -S -c "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" --section-divs -c tutorial.css --toc --standalone -t html5 -o tutorial.html tutorial.lhs
+	pandoc -f markdown+lhs+yaml_metadata_block --highlight-style=haddock --toc --standalone -t rst -o tutorial.rst tutorial.lhs
+	pandoc -f markdown+lhs+yaml_metadata_block --highlight-style=haddock --toc --standalone -t latex -o tutorial.pdf tutorial.lhs
diff --git a/docs/tutorial/tutorial.css b/docs/tutorial/tutorial.css
new file mode 100644
index 0000000..831b73d
--- /dev/null
+++ b/docs/tutorial/tutorial.css
@@ -0,0 +1,3 @@
+body {
+    padding: 0 20px;
+}
diff --git a/docs/tutorial/tutorial.lhs b/docs/tutorial/tutorial.lhs
new file mode 100644
index 0000000..387d14d
--- /dev/null
+++ b/docs/tutorial/tutorial.lhs
@@ -0,0 +1,150 @@
+---
+title: GraphQL Haskell Tutorial
+---
+
+
+== Getting started ==
+
+Welcome to graphql-haskell!
+
+We have written a small tutorial to help you (and ourselves) understand the graphql package.
+
+Since this file is a literate haskell file, we start by importing some dependencies.
+
+> {-# LANGUAGE OverloadedStrings #-}
+> {-# LANGUAGE LambdaCase #-}
+> module Main where
+>
+> import Prelude hiding (empty, putStrLn)
+> import Data.GraphQL
+> import Data.GraphQL.Schema
+> import qualified Data.GraphQL.Schema as Schema
+>
+> import Control.Applicative
+> import Data.Text hiding (empty)
+> import Data.Aeson
+> import Data.ByteString.Lazy.Char8 (putStrLn)
+>
+> import Data.Time
+>
+> import Debug.Trace
+
+=== First example ===
+
+Now, as our first example, we are going to look at the
+example from [graphql.js](https://github.com/graphql/graphql-js).
+
+First we build a GraphQL schema.
+
+> schema1 :: Alternative f => Schema f
+> schema1 = Schema [hello]
+>
+> hello :: Alternative f => Resolver f
+> hello = Schema.scalar "hello" ("it's me" :: Text)
+
+This defines a simple schema with one type and one field, that resolves to a fixed value.
+
+Next we define our query.
+
+> query1 :: Text
+> query1 = "{ hello }"
+
+
+To run the query, we call the `graphql` with the schema and the query.
+
+> main1 :: IO ()
+> main1 = putStrLn =<< encode <$> graphql schema1 query1
+
+This runs the query by fetching the one field defined,
+returning
+
+```{"data" : {"hello":"it's me"}}```
+
+
+
+=== Monadic actions ===
+
+For this example, we're going to be using time.
+
+> schema2 :: Schema IO
+> schema2 = Schema [time]
+>
+> time :: Resolver IO
+> time = Schema.scalarA "time" $ \case
+>   [] -> do t <- getCurrentTime
+>            return $ show t
+>   _  -> empty
+
+This defines a simple schema with one type and one field,
+which resolves to the current time.
+
+Next we define our query.
+
+> query2 :: Text
+> query2 = "{ time }"
+>
+> main2 :: IO ()
+> main2 = putStrLn =<< encode <$> graphql schema2 query2
+
+This runs the query, returning the current time
+
+```{"data": {"time":"2016-03-08 23:28:14.546899 UTC"}}```
+
+
+=== Errors ===
+
+Errors are handled according to the spec,
+with fields that cause erros being resolved to `null`,
+and an error being added to the error list.
+
+An example of this is the following query:
+
+> queryShouldFail :: Text
+> queryShouldFail = "{ boyhowdy }"
+
+Since there is no `boyhowdy` field in our schema, it will not resolve,
+and the query will fail, as we can see in the following example.
+
+> mainShouldFail :: IO ()
+> mainShouldFail = do
+>   r <- graphql schema1 query1
+>   putStrLn $ encode r
+>   putStrLn "This will fail"
+>   r <- graphql schema1 queryShouldFail
+>   putStrLn $ encode r
+>
+
+This outputs:
+
+```
+{"data": {"hello": "it's me"}}
+This will fail
+{"data": {"boyhowdy": null}, "errors":[{"message": "the field boyhowdy did not resolve."}]}
+```
+
+=== Combining resolvers ===
+
+Now that we have two resolvers, we can define a schema which uses them both.
+
+> schema3 :: Schema IO
+> schema3 = Schema [hello, time]
+>
+> query3 :: Text
+> query3 = "query timeAndHello { time hello }"
+>
+> main3 :: IO ()
+> main3 = putStrLn =<< encode <$> graphql schema3 query3
+
+This queries for both time and hello, returning
+
+```{ "data": {"hello":"it's me","time":"2016-03-08 23:29:11.62108 UTC"}}```
+
+Notice that we can name our queries, as we did with `timeAndHello`. Since we have only been using single queries, we can use the shorthand `{ time hello}`, as we have been doing in the previous examples.
+
+In GraphQL there can only be one operation per query.
+
+
+== Further examples ==
+
+More examples on queries and a more complex schema can be found in the test directory,
+in the [Test.StarWars](../../tests/Test/StarWars) module. This includes a more complex schema, and more complex queries.
diff --git a/docs/tutorial/tutorial.rst b/docs/tutorial/tutorial.rst
new file mode 100644
index 0000000..1c8b5ff
--- /dev/null
+++ b/docs/tutorial/tutorial.rst
@@ -0,0 +1,176 @@
+========================
+GraphQL Haskell Tutorial
+========================
+
+.. contents::
+   :depth: 3
+..
+
+Getting started
+===============
+
+Welcome to graphql-haskell!
+
+We have written a small tutorial to help you (and ourselves) understand
+the graphql package.
+
+Since this file is a literate haskell file, we start by importing some
+dependencies.
+
+.. code:: haskell
+
+    {-# LANGUAGE OverloadedStrings #-}
+    {-# LANGUAGE LambdaCase #-}
+    module Main where
+
+    import Prelude hiding (empty, putStrLn)
+    import Data.GraphQL
+    import Data.GraphQL.Schema
+    import qualified Data.GraphQL.Schema as Schema
+
+    import Control.Applicative
+    import Data.Text hiding (empty)
+    import Data.Aeson
+    import Data.ByteString.Lazy.Char8 (putStrLn)
+
+    import Data.Time
+
+    import Debug.Trace
+
+First example
+-------------
+
+Now, as our first example, we are going to look at the example from
+`graphql.js <https://github.com/graphql/graphql-js>`__.
+
+First we build a GraphQL schema.
+
+.. code:: haskell
+
+    schema1 :: Alternative f => Schema f
+    schema1 = Schema [hello]
+
+    hello :: Alternative f => Resolver f
+    hello = Schema.scalar "hello" ("it's me" :: Text)
+
+This defines a simple schema with one type and one field, that resolves
+to a fixed value.
+
+Next we define our query.
+
+.. code:: haskell
+
+    query1 :: Text
+    query1 = "{ hello }"
+
+To run the query, we call the ``graphql`` with the schema and the query.
+
+.. code:: haskell
+
+    main1 :: IO ()
+    main1 = putStrLn =<< encode <$> graphql schema1 query1
+
+This runs the query by fetching the one field defined, returning
+
+``{"data" : {"hello":"it's me"}}``
+
+Monadic actions
+---------------
+
+For this example, we're going to be using time.
+
+.. code:: haskell
+
+    schema2 :: Schema IO
+    schema2 = Schema [time]
+
+    time :: Resolver IO
+    time = Schema.scalarA "time" $ \case
+      [] -> do t <- getCurrentTime
+               return $ show t
+      _  -> empty
+
+This defines a simple schema with one type and one field, which resolves
+to the current time.
+
+Next we define our query.
+
+.. code:: haskell
+
+    query2 :: Text
+    query2 = "{ time }"
+
+    main2 :: IO ()
+    main2 = putStrLn =<< encode <$> graphql schema2 query2
+
+This runs the query, returning the current time
+
+``{"data": {"time":"2016-03-08 23:28:14.546899 UTC"}}``
+
+Errors
+------
+
+Errors are handled according to the spec, with fields that cause erros
+being resolved to ``null``, and an error being added to the error list.
+
+An example of this is the following query:
+
+.. code:: haskell
+
+    queryShouldFail :: Text
+    queryShouldFail = "{ boyhowdy }"
+
+Since there is no ``boyhowdy`` field in our schema, it will not resolve,
+and the query will fail, as we can see in the following example.
+
+.. code:: haskell
+
+    mainShouldFail :: IO ()
+    mainShouldFail = do
+      r <- graphql schema1 query1
+      putStrLn $ encode r
+      putStrLn "This will fail"
+      r <- graphql schema1 queryShouldFail
+      putStrLn $ encode r
+
+This outputs:
+
+::
+
+    {"data": {"hello": "it's me"}}
+    This will fail
+    {"data": {"boyhowdy": null}, "errors":[{"message": "the field boyhowdy did not resolve."}]}
+
+Combining resolvers
+-------------------
+
+Now that we have two resolvers, we can define a schema which uses them
+both.
+
+.. code:: haskell
+
+    schema3 :: Schema IO
+    schema3 = Schema [hello, time]
+
+    query3 :: Text
+    query3 = "query timeAndHello { time hello }"
+
+    main3 :: IO ()
+    main3 = putStrLn =<< encode <$> graphql schema3 query3
+
+This queries for both time and hello, returning
+
+``{ "data": {"hello":"it's me","time":"2016-03-08 23:29:11.62108 UTC"}}``
+
+Notice that we can name our queries, as we did with ``timeAndHello``.
+Since we have only been using single queries, we can use the shorthand
+``{ time hello}``, as we have been doing in the previous examples.
+
+In GraphQL there can only be one operation per query.
+
+Further examples
+================
+
+More examples on queries and a more complex schema can be found in the
+test directory, in the `Test.StarWars <../../tests/Test/StarWars>`__
+module. This includes a more complex schema, and more complex queries.