diff options
Diffstat (limited to 'docs/tutorial/tutorial.html')
| -rw-r--r-- | docs/tutorial/tutorial.html | 165 |
1 files changed, 165 insertions, 0 deletions
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> |