Reading a file

The first thing we're going to take a look at here is how to read a file's contents and then use Elixir to do something with those contents.

Certain files may contain data that we can use in our Elixir programs. Elixir can read any file you throw at it. In this chapter, just for simplicity, we're going to stick to a single file format: text files.

A text file is just a file with a bunch of words in it. You probably have a file like that on your computer right now. You could open one of these files in your text editor and read what was written in that file. If for some weird reason you don't have one of these, you can take this content and put it in a new file called haiku.txt:

rixilE evol I
nrael ot ysae os si tI
edoc lanoitcnuf taerG

I've put this file in a directory on my computer called "Joy of Elixir":

Izzy squints at the haiku. "Um... This haiku looks a little... backwards". Yes, Izzy! Each line is written backwards! The haiku should read:

I love Elixir
It is so easy to learn
Great functional code

We could go in to the file and correct this ourselves, but we're programmers learning a super-duper-awesome programming language and by golly if we aren't going to use it to solve every problem we come across. To solve this problem, we're going to use the power of Elixir.

What we're going to do is to read this haiku into Elixir, and then we're going to reverse the order of words in each line. I make it sound so easy, and that's because it is. Really!

To read this file, we'll need to open an iex prompt where the file is, and then we can use this code to read it:

iex> File.read("haiku.txt")

This code tells Elixir to read a file by calling the File.read/1 function. Calling this function will give us the following output:

{:ok, "I evol rixilE\nnrael ot ysae os si tI\nedoc lanoitcnuf taerG\n"}

In this output, there's not one but two new concepts. You've gotten so far through the book that you're now so great at learning and that means I can introduce things rapid-fire and you'll pick 'em up with no effort.

The first of these is the curly brackets. Did you notice them? They wrap all of the output from the File.read/1. Did you notice that these curly brackets, unlike all the other curly brackets we've seen before, are not prefixed with a percent-sign (%)?

This particular concept in Elixir is called a tuple. You can think of tuples as a fixed-length list and they're used to link a bunch of information together in a particular order. In this case, it's telling us that the file operation was :ok, and then it's giving us a string containing all the file's information.

Izzy pipes up: "What's that :ok thing and why does it have a colon before it?". Good spot, Izzy. That is called an atom. We first saw these back in Chapter 4 when they were used as keys in maps.

We've seen atoms since then, but here's a refresher: Atoms are used to provide informational messages, like in this case. Atoms names are their values. This is unlike strings, maps and lists where we would assign to a variable in order to give a meaningful name to. This atom is telling us that the operation we asked File.read/1 to perform went "ok"; we were able to read the file successfully.

If we specified a file that wasn't present, File.read/1 would give us a different atom in that first place:

iex> File.read("haiboo.txt")
{:error, :enoent}

This cryptic error message uses a tuple containing two atoms, :error and :enoent. The first one is self-explanatory -- there was an error loading this file. The second one gives us a non-regular-human-friendly error message: :enoent. This is computer-lingo for "I couldn't find that file you were looking for, sorry."

The best part about these tuples and atoms being returned from the File.read/1 call is that we can use pattern matching (Chapter 6). If we want to only proceed if our File.read/1 function executes successfully, we can pattern match like this:

iex> {:ok, contents} = File.read("haiku.txt")

Go ahead and try this code out in your iex prompt. Also try it with the wrong path too and see what happens. If you give it the wrong path, you should see it fail like this:

** (MatchError) no match of right hand side value: {:error, :enoent}

This error happens because we're telling Elixir to expect that the tuple returned from this call contains an :ok atom at the start, but it doesn't. Pattern matching can be a useful way of stopping your program in its tracks like this.

Let's look back at the successful read:

iex> {:ok, contents} = File.read("haiku.txt")

You'll see exactly the same values come back as when we did the first File.read/1 invocation:

{:ok, "I evol rixilE\nnrael ot ysae os si tI\nedoc lanoitcnuf taerG\n"}

The difference is: this time, we've got the contents of the file in a contents variable. Oooh, that was sneaky! Let's get back to the task at hand: we still need to correct this haiku back to its proper form. We've now got the contents of this file and we need to reverse each line. To do that, we need some way of splitting apart the string so that we can process each line separately from each other line. To do this, we can use our old friend, String.split/3:

iex> contents |> String.split("\n", trim: true)

This code takes the string stored in contents and passes it as the first argument to String.split/3. The other two arguments are: 2) the string "\n" and 3) the option trim: true. The 2nd argument tells String.split/3 to split the string on the newline characters (\n), and the 3rd argument tells String.split/3 to remove any trailing space at the end.

When this function does its thing, we'll see this output:

["rixilE evol I", "nrael ot ysae os si tI", "edoc lanoitcnuf taerG"]

Yay! We've now got a list of strings here. We need each string here to be reversed. Izzy sticks her hand up and wiggles it around. "Ooh ooh ooh I know how to do this! String.reverse/1!", she says, monospaced font and all. Impressive. Yes, Izzy is correct! We can reverse a string by calling String.reverse/1 as we first saw back in Chapter 8. We know we can do it with a single string like this:

iex> "rixilE evol I" |> String.reverse
"I love Elixir

But we don't have a single string here, we have three strings within a list. But we have knowledge on our side. We have special skills that we built up in Chapter 9, and with those special skills we know that we can call Enum.map/2 to apply a function to multiple elements within a list. We've done exactly this back in Chapter 9:

iex> Enum.map(cities, &String.capitalize/1)

So let's take our list, adapt this code a little bit to use the pipe operator and String.reverse/1 and reverse each string with this code:

iex> contents \
|> String.split("\n", trim: true) \
|> Enum.map(&String.reverse/1)

We're using a multi-line pipe operator chain here to accomplish what we want. Because we're in iex, we need to put a backslash (\) on the end of every line to tell Elixir to treat all these lines as one long line and one chain of operations. If we were writing code in an Elixir file, we wouldn't need to do this. iex is a little special in this regard. Another way we could've written the code is like this:

iex> contents |> String.split("\n", trim: true) |> Enum.map(&String.reverse/1)

But it is considered best practice to split long pipe chains up onto multiple lines when they're really long just to help with readability. Think of it as the same rule that applies when you're writing a book: you split logical breaks into separate paragraphs to make it easier for people to read here. We're applying almost that same rule to our Elixir code.

This code (in either the one-line or three-line form) will give us back a list of strings that now look like proper English:

["I love Elixir", "It is so easy to learn", "Great functional code"]

All we need to do now is to put the file back into a big string, which we can do with a new-to-us function called Enum.join/2:

iex> fixed_contents = contents \
|> String.split("\n", trim: true) \
|> Enum.map(&String.reverse/1) \
|> Enum.join("\n")
"I love Elixir\nIt is so easy to learn\nGreat functional code"

Excellent! We've now got our file's text around the right way. We did this with a combination of quite a few functions and that is really demonstrating the repertoire of things that we know how to do with Elixir now. We have used File.read/1 function to read this file's contents and to bring them into our Elixir code. Once we have the contents there, we can do whatever we wish with them.

Before we move on, I want to show you another way that Elixir has for reading files.

Streaming a file

Elixir provides us at least one very clear way to read a file: File.read/1. We know how this works. But there is another function that Elixir gives us which can also be used to read files. That function is called File.stream!/1.

This function works by reading a file one line at a time. This is useful in cases where we might be reading very large files. If we used File.read/1 to load a large file, it might take a long time for Elixir to read it all in and it might take up a lot of our computer's resources. On the contrary, File.stream! can be used to read an entire file, but will read a file line-by-line.

We call this type of thing in programming parlance "eagerness" or "laziness". The File.read/1 function can be said to be eager: it eagerly loads the whole file without a care in the world if we're going to use the whole lot or not. While the File.stream!/1 function is its more chilled out cousin: it will lazily read a single line at a time from the file.

Think of it in terms of your favourite internet streaming service. When you stream from that service, you don't have to wait for every single episode of your favourite Scandi Noir TV series to download. You don't even have to wait for a single episode to fully download because it only sends through a small part of the episode at a time. This is what File.stream/1 does: gives us the file line-by-line.

Ok, I think we've talked enough about what File.stream/1 does! It's time to see this in action. Let's use this code to start reading our haiku.txt file again:

iex> stream = File.stream!("haiku.txt")
%File.Stream{
  line_or_bytes: :line,
  modes: [:raw, :read_ahead, :binary],
  path: "haiku.txt",
  raw: true
}

This time, we're not given back the contents of the file. We're given back something we've never seen before: a struct.

We can think of structs as maps that follow a particular set of rules. Just like maps, structs have key-value pairs, as we can see from the output here. If we removed the File.Stream part of this output, the syntax would be a map:

iex> %{
  line_or_bytes: :line,
  modes: [:raw, :read_ahead, :binary],
  path: "haiku.txt",
  raw: true
}

What makes a struct different here is that it is named and structs with the same name always have the same keys. Every time we call File.stream!, we'll see a File.Stream struct come back with exactly the same keys.

The keys in this particular struct tell Elixir what this file stream is all about. It tells Elixir that we're going to read from the haiku.txt (path) file line-by-line (line_or_bytes). I won't go into what modes and raw are for here.

At this point, all we have this File.Stream struct. Consider it as an "intent to read" the file. No reading has occurred at this point yet. To trigger this reading, we can pipe this stream into any Enum method. For instance, we could trim all the newline characters (\n) off each line like this:

fixed_contents = stream \
|> Enum.map(&String.trim/1)
["rixilE evol I", "nrael ot ysae os si tI", "edoc lanoitcnuf taerG"]
  

That's a good start. We're not going to be able to peer into exactly what Elixir is doing here, so you'll have to take my word for it that Elixir is now reading each line in this file one at a time and sending it through to Enum.map/2. The output from calling Enum.map/2 is good, but what we really need is a list of sentences the right way around. We can flip these by piping the output again:

fixed_contents = stream \
|> Enum.map(&String.trim/1) \
|> Enum.map(&String.reverse/1)
["I love Elixir", "It is so easy to learn", "Great functional code"]

That's getting better! Now we need to join these back together again and put line breaks in between them with Enum.join/2 again:

fixed_contents = stream \
|> Enum.map(&String.trim/1) \
|> Enum.map(&String.reverse/1) \
|> Enum.join("\n")
"I love Elixir\nIt is so easy to learn\nGreat functional code"

Excellent! We now have the fixed haiku in string form inside Elixir. We could get this through either File.read/1 or File.stream!/1. Normally, we would only use File.stream/1 if the file was really long, but in this section we've used it for illustrative purposes and to prove that there's more than one way to read a file in Elixir.

It would be really handy if we could take this string out of Elixir and put it into a new file so that nobody else has to read a backwards haiku. That's what we'll be looking at next!

Creating and writing to a new file

We now have the re-arranged contents of our haiku stored within a variable called fixed_contents. If you've lost this since the last section, you can use this code to get it back:

iex> fixed_contents = "haiku.txt" \
|> File.stream! \
|> Enum.map(&String.trim/1) \
|> Enum.map(&String.reverse/1) \
|> Enum.join("\n")

The pipe operator makes this code so much easier to read! Now that we most certain have the file contents stored in Elixir and put the right away around, we want to write these contents to a new file. We saw that we could read a file with File.read/1, so it would make sense for there to be a File.write function too. It definitely does exist, and it's called File.write/2. It takes two arguments: 1) the path we want to write to 2) the contents that we want to put in the file. It works like this:

iex> File.write("fixed-haiku.txt", fixed_contents)
:ok

Elixir dutifully takes the file path and the fixed contents and puts them into a file called fixed-haiku.txt. Well, we assume so. All that we know about this operation is that Elixir thought it went OK, as indicated by the atom that it returned: :ok.

If we want to make sure that the fixed-haiku.txt file is definitely there and contains what we expect it to contain, we could simply find that file in the file browser on our computers and double click on it. That would be the easiest way. But, because we're programmers and we've got powerful new skills up our sleeves, we can use what we know to check this. Let's use File.read/1 to see if that file is there:

iex> File.read("fixed-haiku.txt")
{:ok, "I love Elixir\nIt is so easy to learn\nGreat functional code"}

Great! Our file has definitely been written with the right content. Our haiku is in the right order.

Renaming a file

Izzy asks another question: "Why don't we switch these haiku.txt and fixed-haiku.txt files around? If I was opening a file called haiku.txt, I would expect that to be a proper Haiku, not this weird reversed one! I wouldn't think to look in fixed-haiku.txt.

Izzy's right. It's weird that haiku.txt doesn't contain the haiku. We should rename this strange reversed version to reversed-haiku.txt, and then rename fixed-haiku.txt to haiku.txt to ease any confusion people might have.

To read a file there was File.read/1. To write a file there was File.write/2. So it makes sense that in order to rename a file, there is File.rename/2. Elixir is pretty sensible like that, if you haven't realised already. File.rename/2's two arguments are the original name of the file, and then the new name we want.

Let's use this function to first rename haiku.txt to reversed-haiku.txt:

iex> File.rename("haiku.txt", "reversed-haiku.txt")
:ok

Elixir has told us that this operation has succeeded. Well, if that's the case then we should see when we look into that directory again that the haiku.txt file isn't there, but a reversed-haiku.txt file is there instead. Oh, and fixed-haiku.txt exists too. Let's take a peek:

Yes! Our file has been renamed successfully. That's a good start. Let's rename fixed-haiku.txt into haiku.txt with File.rename/2 too:

iex> File.rename("fixed-haiku.txt", "haiku.txt")
:ok

Elixir tells us that the file rename operation was successful yet again. Two for two! Peeking into that directory one more time, we'll see that indeed it was:

Wonderful stuff. Whenever we need to rename a file within Elixir we now know that we can reach for File.rename/2.

So now we've seen how to read existing files, create new ones and rename them. The final file operation that we'll look at this chapter is to delete the files.

Deleting a file

We've all deleted files from our computers in our lifetime. Sometimes even on purpose. The files reach a point where they're no longer useful and we want them gone. The way we might do this is to drag the file to the Recycle Bin, or to right click and choose "Delete", or... well, there's so many ways to delete files.

Elixir provides us a way to delete files too, but it isn't as intuitively named as the operations for reading (File.read/1), writing (File.write/2), and renaming (File.rename/2). To delete a file in Elixir we call the function called File.rm/1.

"RM? Like R.M. Williams, the world famous Australian manufacturer of leather things? What does leather shoes and belts have to do with removing files?", Izzy asks with quite the perplexed look on her face, cork hat bobbling quizzically along. Woah, slow down there Izzy. Elixir's File.rm/1 has nothing to do with boots!

This File.rm/1 file is called rm as a shorthand for "remove". We can use this function to remove any file we like. We would like to keep our haiku files, so let's create a separate file that we can remove later by using File.write/2 first, and then we'll delete it with File.rm/1. Let's do this slow so that we can see that the file definitely does exist before we delete it. Let's start with creating the file:

iex> File.write("delete-me.txt", "delete me")
:ok

If we look in our directory, we can see that this file definitely exists:

Let's try removing this file now:

iex> File.rm("delete-me.txt")
:ok

Elixir says that removing this file was successful. Let's take a look at the directory:

The file is gone!

We've now got our head around some of the essential things that we can do with files with Elixir. We know that we can read existing files with File.read/1, write completely new ones with File.write/2 and delete existing files with File.rm/1. For good measure, we also learned that these functions may return tuples that indicate errors, like {:error, :enoent}, which tells us that files do not exist.

We've now encountered a situation (well, situations) in Elixir where we can call code and get different outcomes depending on external factors like whether files exist or not. The code that we've written so far hasn't been particularly resilient to this sort of thing. We've become accustomed to running code and always seeing the same result.

But the rules have changed. We now will need to account for this sort of thing. In the chapter I will show you a few ways that we can make our code more resilient by making it behave differently, depending on the circumstances.

Exercises

• Can you make Elixir write a program for itself? Put this code into a file called script.ex with File.write/2: IO.puts "This file was generated from Elixir" and then make it run by running elixir that-file.ex.
• Figure out what happens if you try to delete a file that doesn't exist with File.rm/1. Is this what you expected to happen?

case

As we just talked about, we saw a case where file reading could fail. When we call this function, it can have two outcomes:

1. The file exists, and so the file is read successfully. We get back an {:ok, contents} tuple.
2. The file does not exist, and so we get back a {:error, :enoent} tuple instead.

In both cases, we get back a tuple, but what we can do with that tuple is dependent on what's inside. If we get back {:ok, contents} then we can carry on working with that file. But if we get {:error, :enoent} then we will have to make our program stop.

One of the ways to get Elixir to behave this way is to use case:

iex> case File.read("haiku.txt") do
  {:ok, contents} ->
    contents
    |> String.split("\n", trim: true)
    |> Enum.map(&String.reverse/1)
    |> Enum.join("\n")
  {:error, :enoent} ->
    IO.puts "Could not find haiku.txt"
end

This case statement uses much of the same code we saw in the previous chapter, but now goes different routes depending on the output of File.read/1. If File.read/1 returns something that matches the pattern of {:ok, contents}, then our file's code will be parsed and reversed correctly, resulting in this output:

"I love Elixir\nIt is so easy to learn\nGreat functional code"

However, if that File.read/1 call results in something that matches {:error, :enoent}, then we will see an error message telling us that we couldn't find that file.

Could not find haiku.txt

These two "forks in the road" for this case statement are referred to as clauses.

You might recognise this code as being similar to a function we defined back in Chapter 6:

iex> road = fn
  "high" -> "You take the high road!"
  "low" -> "I'll take the low road! (and I'll get there before you)"
  _ -> "Take the 'high' road or the 'low' road, thanks!"
end

This is because it is the same underlying principle. We're using pattern matching inside the case in this chapter to determine what to do, just like we did in that function 6 chapters ago. Before the -> we tell Elixir what we want to match. Then after that, we tell it what we want to do once that match happens. In our case statement, we put that "after" code on separate lines and this is just to increase readability of the code. We could've done the same in our function too:

iex> road = fn
  "high" ->
    "You take the high road!"
  "low" ->
    "I'll take the low road! (and I'll get there before you)"
  _ ->
    "Take the 'high' road or the 'low' road, thanks!"
end

You might notice that in this function block, we have the catch-all clause at the end (_ ->). This is the last-ditch effort for the function to do something. It's worth knowing that we could do the same thing in our case statements too:

iex> case File.read("haiku.txt") do
  {:ok, contents} ->
    contents
    |> String.split("\n", trim: true)
    |> Enum.map(&String.reverse/1)
    |> Enum.join("\n")
  {:error, :enoent} ->
    IO.puts "Could not find haiku.txt"
  _ ->
    IO.puts "Something unexpected happened, please try again."
end

In this code, if Elixir sees something that is not known to the case statement then it will give us a completely different message. While we're on this topic of catch-all clauses, I want to show you one more precise way of doing this too:

iex> case File.read("haiku.txt") do
  {:ok, contents} ->
    contents
    |> String.split("\n", trim: true)
    |> Enum.map(&String.reverse/1)
    |> Enum.join("\n")
  {:error, :enoent} ->
    IO.puts "Could not find haiku.txt"
  {:error, _} ->
    IO.puts "Something unexpected happened, please try again."
end

This time, our last clause will not match everything and anything. It will only match tuples that have exactly two items in them, and the first item must be :error. As we can see here, this is using the pattern matching feature in Elixir that we've seen a few times throughout this book already. The tuple for the last clause isn't exactly {:error, _}, but it is something that is in the same pattern. This pattern matching is why the last clause would match any other error that may be returned from File.read/1.

This is a better approach, because it is clearer to anyone else seeing this code what we might expect when something unexpected happens.

Now we know Elixir has two places where these clauses are used: functions and case blocks. We're about to see another one.

cond

The case statement is good to use if you want to compare the outcome of one particular action and do different things depending on whatever that outcome is. In the last section, that outcome was the output of a File.read/1 function call.

What we'll see in this section is that case has a cousin called cond which provides us a way of checking multiple conditions (cond is short for "condition"), and then running some code for whatever clause is true. Here's a quick example:

iex> num = 50
50
iex> cond do
  num < 50 -> IO.puts "Number is less than 50"
  num > 50 -> IO.puts "Number is greater than 50"
  num == 50 -> IO.puts "Number is exactly 50"
end
Number is exactly 50
:ok

Izzy asks: "What does <, > and == mean? We've never seen those before!" Yes! This is the first time in twelve chapters that we've seen these things. Now is a great time to cover what they do. <, > and == are ways to compare two values in Elixir. You can probably guess from the code that < means "less than", > means "greater than", and that == is "exactly equal to". But what is this code actually doing?

If we take the comparisons out of the cond and run them individually, we'll have a clearer picture of what this code is doing:

iex> num > 50
false
iex> num < 50
false
iex> num == 50
true

These comparisons are going to compare the two values and then tell us if those comparisons are true or false. This is our first exposure to code that outputs either true or false. Think of it like this: if we were to ask the question of "is num equal to 50", what would the answer be? We would normally say "yes, it is equal". Elixir's version of an answer to this question is true.

When we use these comparisons in cond, the first clause where the comparison results in true will execute that clause's code. Go ahead and change the number in the cond code above to see how it might react to those changes.

if, else and unless

Now that we've seen what case and cond can do, let's look at two more related conditional statements: if and unless and their compatriot else.

The cond statement was really helpful if we had multiple conditions to compare against. In the previous code, we wanted to check if the number was less than, greater than or exactly equal to 50:

iex> num = 50
50
iex> cond do
       num < 50 -> IO.puts "Number is less than 50"
       num > 50 -> IO.puts "Number is greater than 50"
       num == 50 -> IO.puts "Number is exactly 50"
     end
Number is exactly 50
:ok

But what if we only wanted to check if the number was exactly 50? Well, we could remove the first two clauses from this cond statement:

iex> cond do
       num == 50 -> IO.puts "Number is exactly 50"
     end
Number is exactly 50
:ok

This is one way of writing this code and it will work perfectly fine. However, if the number was not 50, then we would see an error come from this code:

iex> num = 10
10
iex> cond do
       num == 50 -> IO.puts "Number is exactly 50"
     end
** (CondClauseError) no cond clause evaluated to a true value

This is happening because cond always requires at least one of its conditions to evaluate to a true value. In the code we've just attempted, num == 50 will be false, not true, and because it is the only clause in this cond we will see this error.

If we've got code like this in Elixir where we're running code conditionally and we don't want Elixir to show us big scary error messages like this one, we should be using if instead. Let's look at how we could attempt the same code with if:

iex> num = 10
10
iex> if num == 50 do
        IO.puts "Number is exactly 50"
      end
nil

Because the condition here is not true, nothing happens. The way that Elixir represents nothing is with nil. We asked Elixir to only execute code if the condition is true, but it wasn't. So nil is the outcome.

unless

Now we've seen how to do something if a particular condition is true, but what happens if we want to do something if it is false? For this, Elixir gives us unless:

iex> num = 10
10
iex> unless num == 50 do
        IO.puts "Number is not 50"
      end
Number is not 50
:ok

In this short example, Elixir will output our "Number is not 50" message if the number is not 50. If the number is 50, then nothing (nil) will be the result of this code.

If you're unsure of whether to use if or unless, try reading the code out loud. Does it make more sense to say "unless the number is equal to 50"? In this case, yes it does. But let's try another example:

iex> num = 10
10
iex> unless num != 50 do
        IO.puts "Number is 50"
      end
Number is 50
:ok

This time, the code reads in English as "unless the number is not equal (!=) to 50". This sentence contains a double negative with the use of "unless" and "not", and so using unless in this example is unsuitable. The code should use an if instead:

iex> num = 50
50
iex> if num == 50 do
       IO.puts "Number is 50"
     end
Number is 50
:ok

Now the code reads as "if the number is equal to 50", and that makes a lot more sense!

else

We've now seen if and its opposite unless, but what if we wanted to do if and unless at the same time? What if we wanted Elixir to do some code if a particular condition was true, but then do some other code if it wasn't true?

For this, Elixir gives us else:

iex> num = 10
10
iex> if num == 50 do
       IO.puts "Number is 50"
     else
       IO.puts "Number is not 50"
     end
Number is not 50
:ok

This would read like: "if the number is 50, show 'Number is 50', otherwise, show 'Number is not 50'". In this code, our number is not 50, and so we see Elixir tell us that.

with

There's one more feature of Elixir to do with conditional code that I would love to show you before we finish off this chapter. It is called with. The with feature allows us to chain together multiple operations, and only continue if each of those operations is successful. Before we look at how to use with, let's look at the type of problem it is good at solving.

Let's say that we had somehow came across a map containing this data in our travels:

iex> file_data = %{name: "haiku.txt"}

This map is designed to tell us what file to read our haiku from. This map contains a single key which is the atom :name, and its value is the string "haiku.txt". So we could know by accessing the name key in this map what file to read from. Here's one way we could do it:

iex> File.read(file_data["name"])
{:ok, "rixilE evol I..."}

But what would happen here if the map didn't contain this key, but instead a differently named key? Then our code would break:

iex> file_data = %{filename: "haiku.txt"}
%{filename: "haiku.txt"}
iex> File.read(file_data["name"])
{:error, :enoent}

Our programs need to be written in such a way to protect against this sort of thing. In this particular case, we must make them expect to read a value from a key called :name, not :filename. Once it has done that, then it can try to read that file.

One way to write this would be to use a case statement inside another case statement, like this:

file_data = %{name: "haiku.txt"}
case Map.fetch(file_data, :name) do
  {:ok, name} ->
    case File.read(name) do
      {:ok, contents} ->
        contents
        |> String.split("\n", trim: true)
        |> Enum.map(&String.reverse/1)
        |> Enum.join("\n")
      {:error, :enoent} ->
        IO.puts "Could not find a file called #{name}"
    end
  :error -> "No key called :name in file_data map"
end

In this code, we attempt to find the :name key in file_data with Map.fetch/2. This Map.fetch/2 function is new to us here, and so we'll quickly cover what it does.

The way Map.fetch/2 works is that if there is a key in the map then Map.fetch/2 will return {:ok, name}. If there isn't, it will return the atom :error.

We pattern match on either of these two outcomes during this case statement. In this example, there is going to be a :name key, and so it will match the {:ok, name} part of our case statement. Then the second case statement will come into effect.

This second case statement attempts to read a file using File.read/1. If this file exists, then this function will return {:ok, contents}. If the file does not exist, {:error, :enoent} will be returned instead. In this case, we know that the file exists from our previous attempts at reading it, and so this code will execute successfully.

This code is a little hard to read, as we need to really focus to keep our mind on where we are in the code. A with statement can simplify this code:

with {:ok, name} <- Map.fetch(file_data, :name),
     {:ok, contents} <- File.read(name) do
  contents
  |> String.split("\n", trim: true)
  |> Enum.map(&String.reverse/1)
  |> Enum.join("\n")
  |> IO.puts
else
  :error -> ":name key missing in file_data"
  {:error, :enoent} -> "Couldn't read file"
end

In Elixir, with statements are to be read like a series of instructions of what to do when everything goes right. In this example, if Map.fetch/2 succeeds and returns {:ok, name}, then Elixir will be able to use it in the next step, when it calls File.read/1. After that, our code will work as intended.

However, if Map.fetch/2 fails, then :error will be returned. We handle that in the else inside this with block, telling with that if we see :error returned, that we want to see an error message saying that the :name key was missing. Then if File.read/1 fails and returns {:error, :enoent}, then we want it to tell us that it couldn't read the file.

This code is a little neater than the double-case code because all of our code that deals with the success of our program is grouped neatly at the top, and all the code that deals with the failure is grouped at the bottom.

I would encourage you to play around here with the with statement to get a better understanding of it. What happens if you change file_data so that it doesn't have a :name key? What happens if that haiku.txt file goes missing?

iex helper functions

The iex prompt lets us run Elixir code with ease and to also see the output of that code. We've seen plenty of examples of this throughout the last twelve chapters. But the iex prompt has at least two more tricks up its sleeves.

The h helper

The first of these tricks is the h helper. This helper's name is short for "help", and it will display documentation on whatever you wish. For instance, if you wanted to bring up the documentation for Map.get/2, you can do that by running this command inside of iex:

iex> h Map.get/2

When you run this, you'll see this output:

def get(map, key, default \\ nil)
Gets the value for a specific key in map.

If key is present in map with value value, then value is returned. Otherwise,
default is returned (which is nil unless specified otherwise).

## Examples

    iex> Map.get(%{}, :a)
    nil
    iex> Map.get(%{a: 1}, :a)
    1
    iex> Map.get(%{a: 1}, :b)
    nil
    iex> Map.get(%{a: 1}, :b, 3)
    3

This output shows us the documentation that Elixir has for the Map.get/2 function. It even shows us some examples of how to use this function, which is pretty great!

One thing we didn't learn back in Chapter 10 when we first learned about the Map.get/2 function is that it can take a third argument too, a default argument. This argument will be returned if the key we're trying to get isn't found, as we can see by the examples provided by the very helpful documentation.

"Hold on a minute!", Izzy pipes up. "If this function takes a third argument, then why is it called Map.get/2 and not Map.get/3?". Izzy makes a good point. The number at the end of Map.get/2 signifies how many arguments a function takes. We learned this back in Chapter 9. What we can see with this function is that there's a Map.get variant that takes three arguments, and so there is a Map.get/3 function, as well as the Map.get/2.

We can look up any function's documentation that we've seen so far. Go on, try looking up the documentation for functions that we've seen in the past chapters. They're all documented here!

The arrow and v helpers

Two more little helpers that you should know about are the arrows on your keyboard, and the v helper provided by iex. You might have been using the arrows already to move around in code. The up and down arrows allow us to move through the historical input in our prompt, while the v helper lets us pull values out of particular lines in the output.

Let's say that we've been working in iex and we've written this code:

iex(1)> %{name: "Izzy", age: "30ish", gender: "Female"}
iex(2)> %{name: "Ryan", age: "30ish", gender: "Male"}

Oh drat. We've just realised that wanted to assign these to variables, but forgot to. One way we can get that value again is by pressing the up-arrow on our keyboard. We'll then see this:

iex(1)> %{name: "Izzy", age: "30ish", gender: "Female"}
%{age: "30ish", gender: "Female", name: "Izzy"}
iex(2)> %{name: "Ryan", age: "30ish", gender: "Male"}
%{name: "Ryan", age: "30ish", gender: "Male"}
iex(3)> %{name: "Ryan", age: "30ish", gender: "Male"}

Our terminal helpfully brings back the last value when we push the up-arrow. But if we push the up-arrow again, look what happens:

iex(1)> %{name: "Izzy", age: "30ish", gender: "Female"}
%{age: "30ish", gender: "Female", name: "Izzy"}
iex(2)> %{name: "Ryan", age: "30ish", gender: "Male"}
%{name: "Ryan", age: "30ish", gender: "Male"}
iex(3)> %{age: "30ish", gender: "Female", name: "Izzy"}

We're now back to the first value again! We could then go to the start of this line (by pushing the left-arrow, or Ctrl+A) and assign it to a variable if we wished:

iex(3)> izzy = %{age: "30ish", gender: "Female", name: "Izzy"}
%{age: "30ish", gender: "Female", name: "Izzy"}

If we push the up-arrow again here, we'll get the same as line 3; the line we just had:

iex(4)> izzy = %{age: "30ish", gender: "Female", name: "Izzy"}

If we push it a second time, we'll get the same as line 2.

iex(4)> %{name: "Ryan", age: "30ish", gender: "Male"}

If we push the down-arrow, we'll go back to line 3.

iex(4)> izzy = %{age: "30ish", gender: "Female", name: "Izzy"}

This is how we can navigate up and down, or back and forward (depending your viewpoint) through the history of what we've put into iex.

Now about that v helper. If we want, we can pick a value out of a particular line by using v. For instance, if we wanted the value from the 2nd line of our iex prompt and then to assign that to a variable called ryan we can run this code:

iex(4)> ryan = v(2)
%{name: "Ryan", age: "30ish", gender: "Male"}

This code can be read as: find the 2nd value from the prompt, and assign it to a variable called ryan. As this v helper is a function in Elixir, We can even leave off the brackets if we wish to save us some typing:

iex(5)> ryan = v 2
%{name: "Ryan", age: "30ish", gender: "Male"}

Tab complete

One last iex helper that I want to show you involves another key on your keyboard: the Tab key.

In your iex prompt, you can hit the Tab key to make it autocomplete what you type. For instance, you can type this:

iex> String.rev

And then if you hit tab, iex will autocomplete it into String.reverse:

iex> String.reverse

You can do this with any module name or function you wish. Go on, give it a go with things like En[TAB], and Enum.fil[TAB].

You might realise if you experiment enough that if iex doesn't know what you want, then it will provide some suggestions. For instance, if we type Enum.f and hit tab, we'll see all the functions from the Enum module that start with f:

We've seen the Enum.find/2 and Enum.filter/2 functions back in Chapter 9, but as we can see here Elixir provides a few more functions than the ones we've seen so far.

Keep on exploring here and seeing what other functions you can find. Remember that you can always use the h helper to bring up information about functions you don't know about yet. For instance, we could bring up the documentation for Enum.find_index/2 by writing this:

iex> h Enum.find_index/2

The documentation that we would see is this:

def find_index(enumerable, fun)
@spec find_index(t(), (element() -> any())) :: non_neg_integer() | nil

Similar to find/3, but returns the index (zero-based) of the element instead of
the element itself.

## Examples

    iex> Enum.find_index([2, 4, 6], fn x -> rem(x, 2) == 1 end)
    nil

    iex> Enum.find_index([2, 3, 4], fn x -> rem(x, 2) == 1 end)
    1

There's also one more place where we can go to find documentation.

Elixir's documentation

As we've seen a few times now, we can bring up documentation in the iex prompt with the h helper. There's another place where we can go to find the same documentation, as well as documentation for every other function Elixir provides.

That place is https://elixir-lang.org/docs.html. When you visit that site, you'll see a list of documentation:

The "stable" name at the top indicates that the documentation listed underneath is the for the most recent stable release of Elixir, where "stable" meaning that it's safe for people like us to use, and won't have any nasty bugs in it.

We can see a list of documentation here for the different parts of Elixir. There's "Elixir", which is the documentation for all the functions we've been using so far. You can see documentation for other parts of Elixir too, including "IEx", which gets its own set of documentation. There's also "Mix" which we'll find out about in Chapter 14, and "ExUnit" that we'll find out about in Chapter 15.

If we click that "Elixir" link near the top, we'll be taken to the documentation site for Elixir's standard library. A "standard library" is a set of functions that programming languages provides, and this new page will show you Elixir's.

The default page is a little wordy:

Let's not focus on all the words on the right-hand-side too much. What I want to show you here is the search bar over on the left.

You can type any module or function name into this box to be taken right to its documentation. If we want to find out about Enum.find, we can search for that and then see this page:

If we click on the find/3 function, we'll be taken right to its location in the docs: https://hexdocs.pm/elixir/Enum.html#find/3. The great thing about this URL is that it's shareable, and so if you have friends that are learning Elixir too, you can give them this URL to teach them about Enum.find/3 too.

Here's what we'll see on this page when we visit it.

The great thing here is that we'll be on a page that has all the documentation that Elixir has for the Enum module. We can scroll up (or down!) the page to find out what other functions Elixir provides in this module.

The other great thing about this is that the documentation here will match what we see when we use the h helper in the iex prompt:

def find(enumerable, default \\ nil, fun)
@spec find(t(), default(), (element() -> any())) :: element() | default()

Returns the first item for which fun returns a truthy value. If no such item is
found, returns default.

## Examples

iex> Enum.find([2, 4, 6], fn x -> rem(x, 2) == 1 end)
nil

iex> Enum.find([2, 4, 6], 0, fn x -> rem(x, 2) == 1 end)
0

iex> Enum.find([2, 3, 4], fn x -> rem(x, 2) == 1 end)
3

So now we have two ways of looking at documentation for the functions that we're using within Elixir.

Elixir School

It would be remiss of me to talk about documentation and not to mention the other excellent source of documentation, written by the Elixir community for the Elixir community: Elixir School.

This site covers a lot of the same topics that we've covered -- and will cover in this book -- but in some particular cases it can provide different explanations for things. Now that you're this far into your Elixir journey, you should be able to read this and glean further knowledge from this site to bolster all the knowledge you've gained thus far.

Summary

In this chapter, we've looked at how we can be more productive by reading documentation and learning from that, as well as new tricks for moving around in the iex prompt.

We saw the h helper, which brings up documentation about a particular module or function. We also saw that we can press the up and down arrows on our keyboards to navigate through the history of what we've typed into iex

Lastly, we saw that Elixir has online documentation that we can read too, and we saw that this documentation matches exactly what we can see in our iex prompt.

While we were looking at that documentation, we saw mentions of things called "Mix" and "ExUnit". These are two additional parts of Elixir's tooling that we will be looking at in the 4th and final part of this book: Chapters 14 and 15.

We've now seen lots of examples of functions throughout this book. We've seen how we can define anonymous functions (in Chapter 5):

iex> hello = fn (place) -> "Hello #{place}!" end
hello.("World")
"Hello World!"

And we've seen how we can call functions from already defined modules (in Chapter 8):

iex> String.downcase("HELLO BUT QUIETLY")
"hello but quietly"

But what we haven't seen yet is how to define our own modules, or even why we would want to do that. The why is the simple part: we define functions inside of modules to keep them separate from other functions; modules are a convenient way of grouping functions. Here's a refresher that recycles the description used in Chapter 8:

The functions that Elixir provides are separated into something akin to kitchen drawers or toolboxes, called modules. Whereas in your top kitchen drawer you might have forks, knives, sporks, and spoons (like every sensible person's kitchen does), and in another you might have measuring cups, and in another tea towels.

In Elixir, the functions to work with the different kinds of data are separated into different modules. This makes finding functions to work with particular kinds of data in Elixir very easy.

We haven't yet built a complex enough system to require us to put functions inside of modules, or to even want to write our own functions. That changes in this chapter! A rumbling occurs behind us, and slightly to our left. It's Izzy vibrating with anticipation. It's a weird and unearthly sound, but we'll roll with it.

This chapter will show you how to write new modules for the purpose of grouping together functions, and we'll also cover a special kind of map called a struct. Let's go!

Functions for the people

Way back in Chapter 4, we had maps that looked like this:

%{name: "Izzy", age: "30ish"}

In this chapter, we're going to be working with maps based off these ones, but they're going to be a little more complicated in shape:

iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
}

With our new map shape, what if we wanted to have a function that joined together the person's first and last name into a single string? Well, we could probably write it like this:

iex> full_name = fn (person) -> "#{person.first_name} #{person.last_name}" end

Then we can call this function with this code:

iex> full_name.(person)
"Izzy Bell"

This is wilfully ignoring the fact that some people have mononyms, as well as the falsehoods programmers believe about names. Ignoring both of those things for now, we have a single function that will let us display a combination of a first name and a last name. That's all well and good to have a function that does that.

But what if we had another function that also operated on these people maps? A function called age:

iex> age = fn (person) ->
...> days =  Date.diff(Date.utc_today, person.birthday)
...> days / 365.25
...> end

This new function uses two new functions from Elixir's built-in Date module: Date.utc_today/0 and Date.diff/2. The Date.utc_today/0 function returns the current date in the UTC time zone. The Date.diff/2 function allows us to figure out the difference (in days) between two dates. So we're using this function to find the number of days between today and the person's birthday. We then take that number of days and divide it by the average number of days in a year: 365.25. This should give us a close-enough approximation of somebody's age.

We can call this function with this code:

iex> age.(person)
31.972621492128678

Note that you'll get a different number to the one shown here because Date.utc_today will return a different day for you. This number was correct at the time of writing, I promise!

Now we have two functions that work on this same map. Wouldn't it be nice to have a place where we could group the functions? Similar to how Date.diff/2 and Date.utc_today/0 functions. Those functions are grouped together inside of a module called Date. Let's look at how we can create our own module for these full_name and age functions.

The Person module

Elixir comes with a bunch of built-in modules: List, Map, Enum and Date are a few that we've seen so far. Creating modules is not just for Elixir itself, but we can create our own modules too. The main reason to create a module is to group together functions, which is exactly what we're going to do in this part of this chapter.

To define modules in Elixir we use defmodule. We could write it out in iex:

iex(1)> defmodule Person do
...> ...
...> end

But we're going to be changing this code a lot and so we should write the code in a file instead. Let's create a new file called person.exs inside a directory called ~/code/joy_of_elixir and we'll define the Person module in this file:

defmodule Person do
end

Our module doesn't do very much at the moment. So let's change that by putting our functions inside it. Functions defined in a module must start with the keyword def:

defmodule Person do
  def full_name(person) do
    "#{person.first_name} #{person.last_name}"
  end

  def age(person) do
    days = Date.diff(Date.utc_today, person.birthday)
    days / 365.25
  end
end

To use this module, we need to make sure that we're in the ~/code/joy_of_elixir directory and then we can run iex. Once we're in iex we can compile the module with:

iex> c "person.exs", "."

The c helper's name is short for "compile". Using c like this will load the code from person.exs into our iex session, making the Person module and its functions available to us.

When we run c, it outputs a list of the modules that were loaded by compiling the file, which we see here as [Person], since there's only the Person module in that file.

We're passing a second argument to c here which is a path where our compiled module should go. The dot (.) here means "the current directory", so where we ran the iex command from. When we run this command, Elixir will compile our module to a file called Elixir.Person.beam.

With this file compiled, we can start to use the Person module. Let's try the Person.age/1 function:

iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
}
iex> person |> Person.age
31.975359342915812

Great! That one works. Let's try the full_name function too:

iex> person |> Person.full_name
"Izzy Bell"

Excellent. Both functions work!

One special thing to note here is that if we exit out of iex and re-open it again, our module will still be accessible. We will still be able to run the functions without first having to compile our module:

iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
}
iex> person |> Person.age
31.975359342915812

iex> person |> Person.full_name
"Izzy Bell"

This is because Elixir will load the Elixir.Person.beam file automatically, as it is located in the directory that we're running iex in.

Now that we have got our module running, let's add another two functions to it. These functions will set a person's location to either be "home" or "away". This location value will indicate if the person is at home, or if they're away from home. The functions should go at the bottom of the module definition inside person.exs:

defmodule Person do
  def full_name(person) do
    "#{person.first_name} #{person.last_name}"
  end

  def age(person) do
    days = Date.diff(Date.utc_today, person.birthday)
    days / 365.25
  end

  def home(person) do
    %{person | location: "home"}
  end

  def away(person) do
    %{person | location: "away"}
  end

If we attempt to use these functions right away, they will not work:

iex> person |> Person.away
** (UndefinedFunctionError) function Person.away/1 is undefined or private

This is happening because we have not yet re-compiled the Person module. To do that, we need to use the c helper again:

c "person.exs", "."

With the module now compiled, we will be able to use this function:

iex> person |> Person.away
** (KeyError) key :location not found
person.exs:15: Person.away/1

Well, we thought we could. But this map doesn't have a location key on it, and this means the away function is unable to set that key to a value. We can fix this by providing that key when we define the initial map:

iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
  location: "home",
}
iex> person |> Person.away
%{
  birthday: ~D[1987-12-04],
  first_name: "Izzy",
  last_name: "Bell",
  location: "away"
}

Okay, so what we needed to do here was to provide the location key in the map and then it worked. That's good to see! But how could we prevent this missing key being an issue again? The way to do that is with a struct!

Structs

So far, we have been using maps to represent our people -- well, one person -- and then passing this map through to the functions from the Person module:

iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
  location: "home",
}
iex> person |> Person.away
%{
  birthday: ~D[1987-12-04],
  first_name: "Izzy",
  last_name: "Bell",
  location: "away"
}

We're now going to take the time to look at a data type that is similar to a map, called a struct. The word "struct" is shorted for "structured data"; it's a map, but a particular type of map, where each map of the same type will share the same structure.

A struct has a set of key-value pairs just like a map, but a struct's keys are limited to only a certain set. Let's look at how we would define a struct now within the Person module. At the top of the module, we can use the defstruct keyword to define a struct:

defmodule Person do
  defstruct [
    first_name: nil,
    last_name: nil,
    birthday: nil,
    location: "home"
  ]

  ...
end

Let's start iex and compile our person.exs file:

iex> c "person.exs"

To use this struct, we use a similar syntax to how we would create a new map:

person = %Person{}

The difference is here that we put the name of the module where the struct is defined between the % and the opening curly bracket. In our defstruct call, we have defined a default value for location: "home". So when we've now built this new struct with %Person{}, it will already have a :location key set to "home".

This is one of the advantages of structs over maps: structs can have default values. This will avoid the issue where our away function was failing because there was no location key in our map.

One extra thing that will help here is to match on the struct type in the away and home functions. This will ensure that we always are getting a Person struct before we try to do anything in these functions. To do this, we need to change these functions to this:

def home(%Person{} = person) do
  %{person | location: "home"}
end

def away(%Person{} = person) do
  %{person | location: "away"}
end

This change to these functions will make them always require a Person struct as an argument. They will no longer work with a map. Let's see this in action by re-compiling our module and trying agani:

iex> c "person.exs", "."
iex> person = %{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
  location: "home",
}
iex> person |> Person.away

When we run this code, we'll see this error:

** (FunctionClauseError) no function clause matching in Person.away/1

The following arguments were given to Person.away/1:

    # 1
    %{
      birthday: ~D[1987-12-04],
      first_name: "Izzy",
      last_name: "Bell",
      location: "home"
    }

Attempted function clauses (showing 1 out of 1):

    def away(%Person{} = person)

person.exs:22: Person.away/1

This error is showing us that the function does not match. It shows us that we're passing a plain map to the function as its first argument, but the function is expecting a Person struct instead. So let's pass one of those instead:

person = %Person{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
}
iex> person |> Person.away
%Person{
  birthday: ~D[1987-12-04],
  first_name: "Izzy",
  last_name: "Bell",
  location: "away"
}

That works a lot better! And did you notice that we didn't have to supply a location for our Izzy either? The struct will use the default value if we do not specify it.

By enforcing a Person struct here in this away function, we can be guaranteed that the function will always receive a person argument that is a Person struct, and that means it will always have a location key.

While we're here, we should also make the same changes to the age and full_name functions too, just to make sure that we receive structs for those functions too.

Our module will now look like this:

defmodule Person do
  defstruct [
    first_name: nil,
    last_name: nil,
    birthday: nil,
    location: "home"
  ]

  def full_name(%Person{} = person) do
    "#{person.first_name} #{person.last_name}"
  end

  def age(%Person{} = person) do
    days = Date.diff(Date.utc_today, person.birthday)
    days / 365.25
  end

  def home(%Person{} = person) do
    %{person | location: "home"}
  end

  def away(%Person{} = person) do
    %{person | location: "away"}
  end
end

One final thing to do here is to use pattern matching to pull out the values from the struct that we depend on. Let's change the two functions of full_name and age to this:

def full_name(%Person{first_name: first_name, last_name: last_name} = person) do
  "#{first_name} #{last_name}"
end

def age(%Person{birthday: birthday} = person) do
  days = Date.diff(Date.utc_today, birthday)
  days / 365.25
end

Public and private functions

Before we move on from here, there's one extra concept I would like to share with you. That concept is about public and private functions in modules. Sometimes, we will have functions in modules that we will not want to share with the outside world. Those functions can be kept private so that only other functions inside the module know about it.

Let's say that instead of having two functions called home and a away, we instead wanted to have a function called toggle_location that toggled the person's location between "home" and "away"?

Well, here's how we might write that function:

def toggle_location(%Person{location: "away"} = person) do
  %{person | location: "home"}
end

def toggle_location(%Person{location: "home"} = person) do
  %{person | location: "away"}
end

And now we can compile the module once again, and use this function:

iex> c "person.exs", "."
iex> person = %Person{
  first_name: "Izzy",
  last_name: "Bell",
  birthday: ~D[1987-12-04],
}
iex> person |> Person.toggle_location
%Person{
  birthday: ~D[1987-12-04],
  first_name: "Izzy",
  last_name: "Bell",
  location: "away"
}

This function does exactly what our home and away functions do, and so we can remove those functions.

But this toggle_location function is public -- it's accessible outside of the module still -- and weren't we talking about both public and private functions? You're right! We were. Let's get to that now.

The two function clauses of toggle_location look remarkably similar. They both set a location key to a particular value. This is a clear opportunity for tidying up some of our code, and it's a great opportunity to demonstrate private functions too.

Let's add a new function -- a private function to our module. We add private functions to the bottom of our module, and define them with defp, where the "p" stands for private.

defp set_location(%Person{} = person, location) do
  %{person | location: location}
end

Now back up in toggle_location, we can use this function to set the location:

def toggle_location(%Person{location: "away"} = person) do
  person |> set_location("home")
end

def toggle_location(%Person{location: "home"} = person) do
  person |> set_location("away")
end

This way, the code involved with setting the location can be shared across these toggle_location functions, and any other functions that later on might also set a location. Perhaps there'll come a time where we might want to announce what a particular person's location is each time it changes:

defp set_location(%Person{} = person, location) do
  IO.puts "#{person |> full_name}'s location is now #{location}"
  %{person | location: location}
end

The private function is an ideal place to put that code. It centralises the code in one simple place, and hides internal implementation details about how a location is set.