Decode a List of Numbers From a JSON String in Elm

[00:00] Here I am at elmlang.org/try. This is a nice little online interpreter that'll let us execute basic Elm code, as long as it doesn't use any third-party libraries from package.elmlang.org. As you can see here, I've imported the text function from HTML so that I can render strings to the screen.

[00:17] Here I call text with a string, and I get something out on the other side, "Hello there." Now right above main, I'm going to define a new constant called num. I'm going to set it to a string containing a number. I'd like to figure out how to get an actual number out of this string.

[00:34] We can do that using JSON decoding. Elm comes with some libraries built-in that are made to do just that. We can get access to those by importing json.decode, exposing decode string, and int. Now in order to explain these two things, I need to explain that Elm does JSON decoding in two steps.

[00:56] The first step is to define a recipe, if you will, which we call a decoder. The second step is to execute the recipe, or the decoder. Int, right here, that we've just imported from JSON decode, is a recipe. It's a recipe that tells Elm how to get a number or an integer out of a string.

[01:19] Decode string is a function that takes a decoder, like int, and a string, like num right here. Either it'll return an error string, if something went wrong in the decoding, or it'll return the type that the decoder was meant for, in this case an int.

[01:34] Let's use these two things now to see if we can get this number out of the string. Down here below num, let's make a new constant that'll be the result of running the decoder. I'm going to call it decoded. Just for sanity's sake, I'm going to give it the type I expect so that the compiler can help us in case we write incorrect code.

[01:52] I'm expecting decoded to be a result, string int. This means that what I'm expecting to get out of running decode string is something that's either a string of an error, or the value that we were looking for, an int.

[02:04] Now let's fill in the definition for the declaration. Decoded equal, I'm going to call decode string, and I'm going to pass in the decoder, which in this case, is going to be int. Then I'm going to pass in the string I want to decode. In this case, it's going to be num.

[02:20] Then let's pass the result of decoded into text. It failed. That's because text is expecting to get a string, and what we've passed in instead is a result string, int. We can solve this pretty easily by passing our decoded value into toString which is an Elm global function that'll turn it into a string before passing it along to text.

[02:43] Here you'll see OK 4. That's because result is a type that looks like this. Result XA equals error X or OK A. Here result is a parameterized type, meaning that it can take two different types, depending upon the situation that you're working with.

[03:02] In this case, we're going to be using error string, and OK int. Since our decoding succeeded, you see here that we've got OK4. Let's say we put in here S, and then try to recompile. We get an error, given invalid JSON, unexpected token S at position one.

[03:21] That means that we took the branch of error from our result instead of the OK branch. Let's put things back how they were when they were working. This is fine and dandy but let's do something a little bit more complex.

[03:31] Let's decode a list. Let's make a new constant, nums. Let's give it a whole slew of numbers here, one through five. We need a recipe that will tell Elm how to decode a list of integers, instead of just an integer.

[03:47] We're in luck, because the JSON decode library has a built-in decoder called list. Down here, we can type numbers decoder, make that of type decoder list int. Remember, I'm just filling in types here so that the compiler can help me in case I mess up.

[04:05] The definition is going to be numbers decoder equals list int. List is a function which takes in a decoder, and it returns a decoder that expects a list of the things that the other decoder was. In this case, we're making a decoder that decodes a list of integers.

[04:24] Now down in our decoded statement, instead of passing in int num, let's pass in numbers decoder, nums, and run it. Looks like I haven't imported the decoder type yet. Let's do that at the top here, decoder.

[04:41] It looks like I also forgot to update the type of my decoded constant. Let's fix that by wrapping our int in a list. We've successfully decoded a list of numbers from a string containing a list of numbers. Let's recap.

[04:53] In order to decode JSON in Elm, we first have to define a recipe for the thing we want to decode. Then we have to actually run the decoder. We're using some built-in libraries, containing a function for decoding strings, and other decoders that are premade.

[05:06] We can use these built-in decoders to decode things from strings, or we can compose them together to make more complex decoders. Then we can run them, and get back a result, which can either be an error, or it can be OK. We can do something with that result, in this case, rendering it to the screen.