CODEWITHSUNDEEP
jsonelm
Cerulean
Cerulean

Reputation: 6013

Elm 'Json.Decode.succeed': how is it used in a decode pipeline if it is supposed to always return the same value?

I'm learning Elm and one thing that has puzzled me is 'Json.Decode.succeed'. According to the docs

succeed : a -> Decoder a

Ignore the JSON and produce a certain Elm value.

decodeString (succeed 42) "true"    == Ok 42
decodeString (succeed 42) "[1,2,3]" == Ok 42
decodeString (succeed 42) "hello"   == Err ...

I understand that (although, as a beginner, I don't yet see its use). But this method is also used in a Decode pipeline, thus:

somethingDecoder : Maybe Wookie -> Decoder Something
somethingDecoder maybeWookie =
    Json.Decode.succeed Something
        |> required "caterpillar" Caterpillar.decoder
        |> required "author" (Author.decoder maybeWookie)

What is going on here? That is, if 'succeed' ignores the JSON that's passed to it, how is it used to read JSON and turn it into Elm values? Any clues appreciated!

Upvotes: 4

Views: 911

Answers (1)

glennsl
glennsl

Reputation: 29106

Just to start, the intuition for a decoder pipeline is that it acts like a curried function where piping with required and optional applies arguments one-by-one. Expect that everything, both the function, its arguments and the return value are all wrapped in Decoders.

So as an example:

succeed Something
  |> required (succeed 42)
  |> required (succeed "foo")

is equivalent to 

succeed (Something 42 "foo")

and

decodeString (succeed (Something 42 "foo")) whatever

will return Ok (Something 42 "foo") as long as whatever is valid JSON.

When everything succeeds it's just a really convoluted function call. The more interesting aspect of decoders, and the reason we use them in the first place, is in the error path. But since 'succeed' is what's of interest here, we'll ignore that and save a lot of time, text and brain cells. Just know that without considering the error path this will all seem very contrived.

Anyway, let's try to recreate this to see how it works.

Decode.map2

The key to the pipelines, apart form the pipe operator, is the Decode.map2 function. You've probably already used it, or its siblings, if you've tried writing JSON decoders without using pipelines. We can implement our example above using map2 like this:

map2 Something
  (succeed 42)
  (succeed "foo")

This will work exactly like the example above. But the problem with this, from a user POV, is that if we need to add another argument we also have to change map2 to map3. And also Something isn't wrapped in a decoder, which is boring.

Calling functions wrapped in Decoders

The reason this is useful anyway is because it gives us access to several values at the same time, and the ability to combine them in whatever way we want. We can use this to call a function inside a Decoder with an argument inside a Decoder and have the result also wrapped in a Decoder:

map2 (\f x -> f x)
  (succeed String.fromInt)
  (succeed 42)

Currying and partial application

Unfortunately this still has the problem of needing to change the map function if we need more arguments. If only there was a way to apply arguments to a function one at a time... like if we had currying and partial application. Since we have a way to call functions wrapped in decoders now, what if we return a partially applied function instead and apply the remaining arguments later?

map2 (\f x -> f x)
  (succeed Something)
  (succeed 42)

will return a Decoder (string -> Something), so now we just have to rinse and repeat with this and the last argument:

map2 (\f x -> f x)
  (map2 (\f x -> f x)
    (succeed Something)
    (succeed 42))
  (succeed "")

Et voila, we have now recreated JSON decode pipelines! Although it might not look like it on the surface.

Ceci n'est pas une pipe

The final trick is to use map2 with the pipe operator. The pipe is essentially defined as \x f -> f x. See how similar this looks to the function we've been using? The only difference is that the arguments are swapped around, so we need to swap the order we pass arguments as well:

map2 (|>)
  (succeed "")
  (map2 (|>)
    (succeed 42)
    (succeed Something))

and then we can use the pipe operator again to reach the final form

succeed Something
  |> map2 (|>)
      (succeed 42)
  |> map2 (|>)
      (succeed "")

It should now be apparent that required is just an alias for map2 (|>).

And that's all there is to it!

Upvotes: 5

Related Questions