<commit_before>import Graphics.Element exposing (..)
import Markdown
import Website.Skeleton exposing (skeleton)
import Website.Tiles as Tile
import Window

port title : String
port title = "Elm 0.15"


main =
  Signal.map (skeleton "Blog" everything) Window.dimensions


everything wid =
  let w = min 600 wid
  in
    flow down
      [ width w content
      ]

content = Markdown.toElement """

# Tasks

Tasks make it easy to describe asynchronous operations that may fail, like
HTTP requests or writing to a database. Tons of browser APIs are described as
tasks in Elm:

  * [elm-http][] &mdash; talk to servers
  * [elm-history][] &mdash; navigate browser history
  * [elm-storage][] &mdash; save info in the users browser

[elm-http]: http://package.elm-lang.org/packages/evancz/elm-http/latest/
[elm-history]: https://github.com/TheSeamau5/elm-history/
[elm-storage]: https://github.com/TheSeamau5/elm-storage/

Tasks also work like light-weight threads in Elm, so you can have a bunch of
tasks running at the same time and the [runtime][rts] will hop between them if
they are blocked.

[rts]: http://en.wikipedia.org/wiki/Runtime_system

This tutorial is going to slowly build up to some realistic examples of HTTP
requests. The first few sections are explaining the building blocks, so stick
with it until we start putting it all together!


## Basic Example

Let’s start out with a very simple function for printing values out to the
console:

```haskell
print : a -> Task x ()
```

We give the `print` function a value, and it gives back a `Task` that can
be performed at some point and will print that value out. The `x` is a
placeholder that normally says what kind of errors can happen, but try not to
get hung up on it too much at this point. We will come back to it! The
important thing is that we have a task for printing stuff out.

To actually make the task happen, we give it to a [port][], which looks like
this.

[port]: /learn/Ports.elm

```haskell
module Counter where

import Time exposing (second)


-- A signal that updates to the current time every second
clock : Signal Time
clock =
  Time.every second


-- Turn the clock into a signal of tasks
printTasks : Signal (Task x ())
printTasks =
  Signal.map print clock


-- Actually perform all those tasks
port runner : Signal (Task x ())
port runner =
  printTasks
```

When we initialize the `Counter` module we will see the current time printed
out every second. The `printTasks` signal is creating a bunch of tasks, but
that does not do anything on its own. Just like in real life, creating a task
does not mean the task magically happens. I can write &ldquo;buy more
milk&rdquo; on my todo list as many times as I want, but I still need to go to
the grocery store and buy it if I want the milk to appear in my refrigerator.

So in Elm, tasks are not run until we hand them to the runtime through a port.
This is similar to sending a record or list out a port, but instead of handing
it to some JavaScript callback, the runtime just performs the task.


## Chaining Tasks

In the example above we used `print` but what if we want to create a more
complex task? Something with many steps. It is possible to chain many tasks
together with the `andThen` function. In the following example, to get the
current time *and then* print it out.

```haskell
-- task that succeeds with the current time
getCurrentTime : Task x Time


port runner : Task x ()
port runner =
  getCurrentTime `andThen` print
```

This means we try to get the current time *and then* when that succeeds we
print the time out. The key to chaining tasks together like this is the
`andThen` function.

```haskell
andThen : Task x a -> (a -> Task x b) -> Task x b
```

The first argument is a task that we want to happen, in our example this is
`getCurrentTime`. The second argument is a callback that creates a brand new
task. In our case this means taking the current time and printing it.

It may be helpful to see the slightly more verbose version of our task chain:

```haskell
printTime : Task x ()
printTime =
  getCurrentTime `andThen` print


printTimeVerbose : Task x ()
printTimeVerbose =
  getCurrentTime `andThen` \\time -> print time
```

These are both exactly the same, but in the second one, it is a bit more
explicit that we are waiting for a `time` and then printing it out.


## Communicating with Mailboxes

So far we have just been performing tasks and throwing away the result. But
what if we are getting some information from a server and need to bring that
back into our program? We can use a [`Mailbox`][mb], just like when
[constructing UIs][arch] that need to talk back!

[mb]: http://package.elm-lang.org/packages/elm-lang/core/latest/Signal#Mailbox
[arch]: https://github.com/evancz/elm-architecture-tutorial/

```haskell
type alias Mailbox a =<commit_msg>Bring task-tutorial package into the written tutorial<commit_after>import Graphics.Element exposing (..)
import Markdown
import Website.Skeleton exposing (skeleton)
import Website.Tiles as Tile
import Window

port title : String
port title = "Elm 0.15"


main =
  Signal.map (skeleton "Blog" everything) Window.dimensions


everything wid =
  let w = min 600 wid
  in
    flow down
      [ width w content
      ]

content = Markdown.toElement """

# Tasks

Tasks make it easy to describe asynchronous operations that may fail, like
HTTP requests or writing to a database. Tons of browser APIs are described as
tasks in Elm:

  * [elm-http][] &mdash; talk to servers
  * [elm-history][] &mdash; navigate browser history
  * [elm-storage][] &mdash; save info in the users browser

[elm-http]: http://package.elm-lang.org/packages/evancz/elm-http/latest/
[elm-history]: https://github.com/TheSeamau5/elm-history/
[elm-storage]: https://github.com/TheSeamau5/elm-storage/

Tasks also work like light-weight threads in Elm, so you can have a bunch of
tasks running at the same time and the [runtime][rts] will hop between them if
they are blocked.

[rts]: http://en.wikipedia.org/wiki/Runtime_system

This tutorial is going to slowly build up to some realistic examples of HTTP
requests. To get started, install the `evancz/task-tutorial` package in your
working directory by running the following command:

```bash
elm-package install evancz/task-tutorial
```

This exposes the `TaskTutorial` module which has [a friendly
values][task-tutorial] that will help build a foundation for working with
tasks.

[task-tutorial]: http://package.elm-lang.org/packages/evancz/task-tutorial/latest/TaskTutorial

## Basic Example

Let’s start out with a very simple function for printing values out to the
console:

```haskell
print : a -> Task x ()
```

We give the [`print`][print] function a value, and it gives back a `Task` that
can be performed at some point and will print that value out. The `x` is a
placeholder that normally says what kind of errors can happen, but try not to
get hung up on it too much at this point. We will come back to it! The
important thing is that we have a task for printing stuff out.

[print]: http://package.elm-lang.org/packages/evancz/task-tutorial/latest/TaskTutorial#print

To actually make the task happen, we give it to a [port][], which looks like
this.

[port]: /learn/Ports.elm

```haskell
import TaskTutorial exposing (print)
import Time exposing (second)


-- A signal that updates to the current time every second
clock : Signal Time
clock =
  Time.every second


-- Turn the clock into a signal of tasks
printTasks : Signal (Task x ())
printTasks =
  Signal.map print clock


-- Actually perform all those tasks
port runner : Signal (Task x ())
port runner =
  printTasks
```

When we initialize this module we will see the current time printed out every
second. The `printTasks` signal is creating a bunch of tasks, but that does not
do anything on its own. Just like in real life, creating a task does not mean
the task magically happens. I can write &ldquo;buy more milk&rdquo; on my todo
list as many times as I want, but I still need to go to the grocery store and
buy it if I want the milk to appear in my refrigerator.

So in Elm, tasks are not run until we hand them to the runtime through a port.
This is similar to sending a record or list out a port, but instead of handing
it to some JavaScript callback, the runtime just performs the task.


## Chaining Tasks

In the example above we used [`print`][print] but what if we want to create a
more complex task? Something with many steps.

First let’s introduce [`getCurrentTime`][now] so we can do more than print!

[now]: http://package.elm-lang.org/packages/evancz/task-tutorial/latest/TaskTutorial#getCurrentTime


```haskell
getCurrentTime : Task x Time
```

This is a task that just gives you the current time. You run it, it tells you
what time it is. Now what we want to do is run [`getCurrentTime`][now] and
then [`print`][print] it out. Let’s look at the finished product and then
work through all the new parts.

```haskell
import TaskTutorial exposing (getCurrentTime, print)

port runner : Task x ()
port runner =
  getCurrentTime `andThen` print
```

First, notice the infrequently-used backtick syntax which let’s us treat normal
functions as infix operators. As another example, `(add 3 4)` is the same as
``(3 `add` 4)``. So saying ``(getCurrentTime `andThen` print)`` is the same as
saying `(andThen getCurrentTime print)` but it does not read as nicely!

Okay, now that we know that [`andThen`][andThen] is a normal function that
takes two arguments, let’s see the type.

[andThen]: http://package.elm-lang.org/packages/elm-lang/core/latest/Task#andThen

```haskell
andThen : Task x a -> (a -> Task x b) -> Task x b
```

The first argument is a task that we want to happen, in our example this is
`getCurrentTime`. The second argument is a callback that creates a brand new
task. In our case this means taking the current time and printing it.

It may be helpful to see the slightly more verbose version of our task chain:

```haskell
printTime : Task x ()
printTime =
  getCurrentTime `andThen` print


printTimeVerbose : Task x ()
printTimeVerbose =
  getCurrentTime `andThen` \\time -> print time
```

These are both exactly the same, but in the second one, it is a bit more
explicit that we are waiting for a `time` and then printing it out.

The [`andThen`][andThen] function is extremely important when using tasks
because it let’s us build complex chains. We will be seeing more of it in
future examples!


## Communicating with Mailboxes

So far we have just been performing tasks and throwing away the result. But
what if we are getting some information from a server and need to bring that
back into our program? We can use a [`Mailbox`][mb], just like when
[constructing UIs][arch] that need to talk back!

[mb]: http://package.elm-lang.org/packages/elm-lang/core/latest/Signal#Mailbox
[arch]: https://github.com/evancz/elm-architecture-tutorial/

```haskell
type alias Mailbox a =
{'fraction_non_alphanumeric': 0.07754915409236397, 'fraction_numerical': 0.001828989483310471, 'mean_word_length': 4.025735294117647, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 13, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2339443', 'n_tokens_mistral': 3201, 'n_tokens_neox': 3065, 'n_words': 1609}