You'll end up with html that looks like:

<em>This text will be put into an <em> tag

External Hyperlinks

If you need to annotate a hyperlink in markdown, you use square brackets that enclose descriptive text surrounded by parentheses that contain the hyperlink.

It looks like the following:

[This link goes to my blog post on nested filter.](http://www.binarywebpark.com/nested-filter/)

Ok, so now you have a brief overview of markdown. It's time to start documenting!

Documenting Your Elixir Code

Erlang has the notion of something called module attributes that applies in Elixir. In Elixir code, module attributes are often used to define constants or as a temporary storage holder for values to be used during code compilation.

When documenting Elixir code, you'll rely a lot on the reserved attributes "@moduledoc" and "@doc".

Documenting Modules

When documenting modules, you'll use the @moduledoc attribute. The following is an example.

defmodule HelloWorld do
  @moduledoc """
  This is the HelloWorld module
  """

  def hello_world, do: "hello_world"
end

What if you didn't wish to document this module?

Then you could set @moduledoc to false. So it would look like this:

defmodule HelloWorld do
  @moduledoc false

  def hello_world, do: "hello_world"
end

Documenting Modules With Style

Believe it or not, there is a proper style to document modules via this community style guide{:target="_blank"}. Right now Elixir is pretty new, so this could change, but I think it serves as good guidance for now.

The basic tenets are:

• The @moduledoc attribute should be included right after the "defmodule" line.
• Separate the @moduledoc documentation with a blank line between the end of the documentation and new code.
• Be sure to use heredocs for the description text for @moduledoc.

Documenting Functions

When documenting functions, you'll use the @doc attribute. We now document the function in the HelloWorld module in the following example.

defmodule HelloWorld do
  @moduledoc """
  This is the HelloWorld module
  """

  @doc """
  Says hello_world

  Returns "hello_world"

  ## Examples

    iex> HelloWorld.hello_world
    hello_world

  """

  def hello_world, do: "hello_world"
end

What if you didn't want to document this function? Similar to module documentation, you can set @doc to false.

A Word on Documenting Private Functions

So the big deal here is that you can't. You'll get a stern warning from Elixir and your documentation description will be ignored.

Typespecs

Remember how I mentioned the Timex library?

Even though Elixir is a dynamically typed language, it still gives you functionality for documenting typed function signatures and declaring custom types.

Declaring custom types is what the Types module in the Timex library did.

@type attribute

To understand the @type attribute for declaring custom data types, let's look at a portion of the Timex.Types module again.

defmodule Timex.Types do
  # Time types
  @type timestamp :: {megaseconds, seconds, microseconds }
  @type megaseconds :: non_neg_integer
  @type seconds :: non_neg_integer
  @type microseconds :: non_neg_integer

  # some code was left out for brevity...
end

Notice the types megaseconds, seconds, and microseconds. They are defined as a "non_neg_integer". Now a "non_neg_integer" is a built-in type specification. You'll find that Elixir steals a lot of its built-in type specifications from Erlang and expresses it the same way.

Now notice the timestamp type. This is the custom day type that is defined. It is a tuple composed of the built-in types.

Basic Types in Elixir Documentation

I'm printing out the basic types in Elixir here as a convenience. I pulled it from the Hex docs{:target="_blank"}.

type :: any()                   # the top type, the set of all terms
     :: none()                  # the bottom type, contains no terms
     :: atom()
     :: map()                   # any map
     :: pid()                   # process identifier
     :: port()
     :: reference()
     :: struct()                # any struct
     :: tuple()                 # tuple of any size

     ::                         ## Numbers
     :: float()
     :: integer()
     :: neg_integer()           # ..., -3, -2, -1
     :: non_neg_integer()       # 0, 1, 2, 3, ...
     :: pos_integer()           # 1, 2, 3, ...

     ::                                             ## Lists
     :: list(type)                                  # proper list ([]-terminated)
     :: nonempty_list(type)                         # non-empty proper list
     :: maybe_improper_list(type1, type2)           # proper or improper list
     :: nonempty_improper_list(type1, type2)        # improper list
     :: nonempty_maybe_improper_list(type1, type2)  # non-empty proper or improper list

     :: Literals                # Described in section "Literals"
     :: Builtin                 # Described in section "Built-in types"
     :: Remotes                 # Described in section "Remote types"
     :: UserDefined             # Described in section "User-defined types"

@spec and @typedoc attributes

Now let's look at how to use @spec and @typedoc.

defmodule HelloWorld do
  @moduledoc """
  This is the HelloWorld module
  """

  @doc """
  Prints a hello message

  ## Parameters

    - number: integer that will be interpolated in the hello message

  ## Examples

    iex> HelloWorld.hello_number(2)
    "hello 2"

  """

  @typedoc "The number to be used with the hello message"
  @type num :: integer() | float()

  @spec hello_number(num) :: String.t
  def hello_number(number), do: "hello #{number}"
end

Note that @typedoc is used to describe the @type you're defining.

The @spec is being used to specify the function specification.

From a proper coding convention perspective, note that we group @typedoc and @type together and separate it from additional code with a blank line and we keep @spec directly above the function definition with no blank line.

@opaque and @typep

So two module attributes worth mentioning that I didn't know about when I first started learning Elixir are @opaque and @typep.

Now any type defined via @typep is considered private.

@opaque is used to define a public facing type while keeping the structure of the type out of the public documentation.

Writing Documentation Tests in Phoenix and Elixir

If you're interested in understanding how to write documentation tests in Elixir, check out this blog post I wrote{:target="_blank"}.

Documentation NestedFilter and Digger

In learning about Elixir I wrote two hex packages. One was nested_filter{:target="_blank"} and the other was digger{:target="_blank"}. They both contain examples on how to document your Elixir code. If you notice an issue, pull requests are welcome!

Summary

Hopefully you now have a feel for how to document your Elixir code. Even though Elixir is a dynamically typed language, it still gives you the ability to specify your data types via documentation. I really like this because I feel like it can help make the intent of your code more clear.

A Tour of The Kernel Module

Where does to_atom come from?

As I dove deeper into Elixir, I started using guard clauses. So I would end up writing functions with guard clauses that looked like the following:

defmodule Example do
  def hello(n) when is_atom(n), do: :hello
  def hello(n) when is_list(n), do: ["h", "e", "l", "l", "o"]
end

One day I started wondering where functions like is_atom were coming from and why I never had to call out a module name to have access to them, the way I would have to do with Enum.map/1 as an example.

For the next few sections, we're going to talk about some interesting Kernel functions and cover guard clauses.

Diving Into Kernel's Interesting Functions

The Kernel module has some useful functions that are handy to know as you're going about your day to day Elixir programming.

The is_* functions

The first set of functions that are handy are what I affectionately term the "is_*" (pronounced "is star") functions.

Here's a list and their description straight from the Elixir documentation:

1. is_atom - Returns true if term is an atom; otherwise returns false.
2. is_binary - Returns true if term is a binary; otherwise returns false.
3. is_bitstring - Returns true if term is a bitstring (including a binary); otherwise returns false.
4. is_boolean - Returns true if term is a floating-point number; otherwise returns false.
5. is_float - Returns true if term is a floating-point number; otherwise returns false.
6. is_function - Returns true if term is a function; otherwise returns false.
7. is_integer - Returns true if term is an integer; otherwise returns false.
8. is_list - Returns true if term is a list with zero or more elements; otherwise returns false.
9. is_number - Returns true if term is either an integer or a floating-point number; otherwise returns false.
10. is_pid - Returns true if term is a PID (process identifier); otherwise returns false.
11. is_port - Returns true if term is a port identifier; otherwise returns false.
12. is_tuple - Returns true if term is a tuple; otherwise returns false.
13. is_map - Returns true if term is a map; otherwise returns false.
14. is_nil - Returns true if term is nil, false otherwise.

Binaries and Bitstrings: A Simple Explanation

One point that deserves a bit of further elaboration is the difference between binaries and bitstrings.

Let's look at an example in code.

  iex> is_bitstring "hello"
  #=> true
  iex> is_bitstring <<1::2>>
  #=> true
  iex> is_bitstring <<1::8>>
  #=> true

  iex> is_binary "hello"
  #=> true
  iex> is_binary <<1::2>>
  #=> false
  iex> is_binary <<1::8>>
  #=> true

  iex> bit_size "hello"
  #=> 40
  iex> bit_size <<1::2>>
  #=> 1
  iex> bit_size <<1::8>>
  #=> 8

There's a wonderful explanation from this forum post that describes this perfectly that I will quote here:

In Elixir, a "bitstring" is anything between <> markers, and it contains a contiguous series of bits in memory. If there happen to be 8 of those bits, or 16, or any other number divisible by 8, we call that bitstring a "binary" - a series of bytes. And if those bytes are valid UTF-8, we call that binary a "string".

What does that mean for our example?

Think of strings as a subset of all binaries, and binaries as a subset of all bitstrings. So from the example, you can see that "hello" is 40 bytes long which is divisible by 8. So it is a binary and since it is also valid UTF-8, it is also a string.

The data structure functions

There's some other interesting functions that have to do with maps and lists, so I call them the "data structure functions". Here they are with a description for your convenience.

1. bit_size - Returns an integer which is the size in bits of bitstring.
2. byte_size - Returns the number of bytes needed to contain bitstring.
3. elem - Gets the element at the zero-based index in tuple.
4. get_in/2 - Gets a value from a nested structure.
5. hd - Returns the head of a list.
6. length - Returns the length of list.
7. pop_in - Pops a key from the given nested structure.
8. put_elem/3 - Inserts value at the given zero-based index in tuple.
9. put_in/3 - Puts a value in a nested structure.
10. tuple_size/1 - Returns the size of a tuple.
11. update_in/3 - Updates a key in a nested structure.
12. map_size/1 - Returns the size of a map.
13. tl - Returns the tail of a list.

The math functions

There's some other interesting functions that have to do with arithmetic, so I call them the "math functions". Here they are with a description for your convenience.

1. div/2 - Performs an integer division.
2. round/1 - Rounds a number to the nearest integer.
3. max/2 - Returns the biggest of the two given terms according to Erlang’s term ordering.
4. min/2 - Returns the smallest of the two given terms according to Erlang’s term ordering.
5. +/2 - Arithmetic addition.
6. */2 - Arithmetic multiplication.
7. //2 - Arithmetic division.
8. abs/1 - Returns an integer or float which is the arithmetical absolute value of number.

Miscellaneous functions

Finally, there are some other interesting miscellaneous functions. Here they are with a description for your convenience.

1. apply/3 - Invokes the given fun from module with the list of arguments.
2. function_exported?/3 - Returns true if module is loaded and contains a public function with the given arity, otherwise false.
3. macro_exported?/3 - Returns true if module is loaded and contains a public macro with the given arity, otherwise false.
4. self/0 - Returns the PID (process identifier) of the calling process.
5. make_ref/0 - Returns an almost unique reference.

Summary

I hope you enjoyed this whirlwind tour of the Kernel module. There's more functions I didn't cover, but I wnated to give you a highlight of some of the ones you would likely use in your coding endeavors.

Digging Into Protocols

Pattern Matching: When You Have a Hammer Everything Looks Like a Nail

So I was coding a new Elixir hex package in the fall of 2017 called Digger{:target="_blank"}. The whole point of this package was to make it easy to ensure any key in a map was a string ("stringify-ing" map keys) or an atom ("atomizing" keys).

At that time, I was familiar enough with Elixir to avoid abusing the "cond" and "case" statements and to use pattern matching.

In atomizing keys, I wound up with a module like the below. Note there is only one public function called "atomize". The rest of the functions are private and support the "atomize" function.

The module to convert map keys to strings had an analogous interface.

defmodule Digger.Atomizer do
  @moduledoc """
  Documentation for Digger.Atomizer.
  """

  @type key :: any
  @type value :: any
  @type pseudo_map :: any

  @doc """
  Take a (nested) map and convert string and integer keys to atoms
  """
  @spec atomize(map) :: map
  def atomize(%{} = map) do
    map
    |> Map.new(fn{key, value} -> {atomize_key(key), atomize_value(value)} end)
  end

  defp atomize_value(value) when is_map(value) do
    atomize(value)
  end

  defp atomize_value(value), do: value

  defp atomize_key(%_{} = struct), do: struct

  defp atomize_key(key) when is_map(key) do
    atomize(key)
  end

  defp atomize_key(key) when is_binary(key) do
    String.to_atom(key)
  end

  defp atomize_key(key) when is_integer(key) do
    key |> to_string |> atomize_key
  end

  defp atomize_key(key), do: key
end

If you look at the above code, you'll notice I started using guards to decide how to atomize a key based on the type of data it was. For example, if it was an integer, the "atomize_key" function used the to_string function to convert the key to a string and then called the. For a struct, I actually wouldn't try and "atomize" it and kept using the struct as the key.

If only there were a mechanism in Elixir so that would let me dynamically call a function depending on a value's type. This would let me more easily extend this module's API for newly defined data types.

Enter Protocols: What Are They?

Before we talk about protocols, we actually have to take a quick detour to talk about polymorphism.

Ok, so what is polymorphism?

From Wikipedia: "In programming languages and type theory, polymorphism (from Greek πολύς, polys, "many, much" and μορφή, morphē, "form, shape") is the provision of a single interface to entities of different types."⁶

More from Wikipedia:

• Ad hoc polymorphism: when a function denotes different and potentially heterogeneous implementations depending on a limited range of individually specified types and combinations. Ad hoc polymorphism is supported in many languages using function overloading.
• Parametric polymorphism: when code is written without mention of any specific type and thus can be used transparently with any number of new types. In the object-oriented programming community, this is often known as generics or generic programming. In the functional programming community, this is often shortened to polymorphism.
• Subtyping (also called subtype polymorphism or inclusion polymorphism): when a name denotes instances of many different classes related by some common superclass.

Apparently, according to Wikipedia, Elixir uses parametric polymorphism and the functional programming community just refers to it as "polymorphism."

Also interestingly enough, while Elixir is a dynamic language, Wikipedia states "parametric polymorphism is a way to make a language more expressive, while still maintaining full static type-safety."⁷

Protocols Defined

So after all that, what are protocols?

The Elixir documentation states "Protocols are a mechanism to achieve polymorphism in Elixir."⁵

In layman's terms that means we depend on function arity and the data types passed in to the function to determine which protocol implementation to dispatch.

Practically speaking, how do you use protocols in Elixir?

You only need to remember 2 syntax keywords when using when working with polymorphism in Elixir: defprotocol and defimpl. As we step through the following case study with the hex package Digger{:target="_blank"}, hopefully it will become more clear.

A Case Study On Using Polymorphism: Rewriting the Digger.Atomizer Module Using Protocols

So now let's step through a small case study by rewriting the Digger.Atomizer module.

Step 1: Define Your Protocol with defprotocol

# file: lib/protocols/atomizer_protocol.ex

defprotocol Digger.Atomizer do
  @moduledoc """
  Documentation for Digger.Atomizer Protocol
  """

  @fallback_to_any true

  alias Digger.Types

  @doc """
  'Atomize' a valid Types.data_type according to the protocol implementation
  """

  @spec atomize(Types.data_type, Types.string) :: Types.valid_return_type
  def atomize(data_type, atomize \\ :atomize)
end

Step 2: Define Your Implementation with defimpl

For string keys, here is the implementation of the protocol.

# file: lib/impl/atomizer/string.ex
defimpl Digger.Atomizer, for: BitString do
  def atomize(string, :atomize) do
    string
    |> String.to_atom
  end
  def atomize(string, _atomize), do: string
end

Step 3: Implement Any as a Fallback

In the following code example, you'll notice we define a protocol implementation for "Any". This is to let Elixir know what to do in case it can't find a function implementation for a particular data type.

In the definition of the protocol itself, we also set the @fallback_to_any attribute to true.

# file: lib/impl/atomizer/any.ex
defimpl Digger.Atomizer, for: Any do
  def atomize(any, _atomize), do: any
end

# file: lib/protocols/atomizer_protocol.ex
defprotocol Digger.Atomizer do
  @moduledoc """
  Documentation for Digger.Atomizer Protocol
  """

  @fallback_to_any true

  alias Digger.Types

  @doc """
  'Atomize' a valid Types.data_type according to the protocol implementation
  """

  @spec atomize(Types.data_type, Types.string) :: Types.valid_return_type
  def atomize(data_type, atomize \\ :atomize)
end

Alternatively, you can use the @derive attribute in a module to tell Elixir to use the "Any" implementation for that module.

What if the implementation of Digger.Atomizer.Protocol had not been applicable to any data type?

From the Elixir documentation:

"That’s one of the reasons why @fallback_to_any is an opt-in behaviour. For the majority of protocols, raising an error when a protocol is not implemented is the proper behaviour." "Which technique is best between deriving and falling back to any depends on the use case but, given Elixir developers prefer explicit over implicit, you may see many libraries pushing towards the @derive approach."

Best practices for organizing protocols and their implementation?

• Apparently, it's still an open issue as of 1/15/18 Monday{:target="_blank"}

Other Tips

• According to this blog post{:target="_blank"}, a protocol implementation can use the @for module attribute as an alias of the current target. It's handy for different protocol implementations.

defprotocol ToString do
  def to_string(term)
end
defimpl ToString, for: [List, Integer] do
  def to_string(term) do
    @for.to_string(term)
  end
end
ToString.to_string(2)
#=> "2"

Summary

Consider using protocols when you find yourself writing functions whose implementation soley depends on the data type(s) being passed in.

Resources:

If you're interested in applying your new knowledge about protocols, check out the Elixir Katas resource I've prepared for you! Just click here to go this web page and sign up with your email to download the free resource

1. More reading on questions about approaching polymorphism in functional programming{:target="_blank"}
2. Some general reading on polymorphism in object-oriented programming{:target="_blank"}

Footnotes:

Behaviors and Protocols

One thing I've always loved is efficiency. I love checklists and templates so I don't have to think about repeatable processes. Templates can help keep you really organized. When I did some freelancing, I had a contract template that I could edit to quickly make changes. It saved a ton of time.

And what does this have to do with behaviors?

In an analogous fashion to the contracting templates I used to use, Elixir defines behaviors for modules. Behaviors let you define a module and specify what functions must be a part of the module.

Defining Behaviors

The way to define a behavior is through a "@behaviour" attribute. The module whose "behavior" you are implementing must use the @callback attribute to define the functions that are part of the contract it will enforce to all modules that wish to use its "behavior".

In coded English, a behavior does the following

defmodule Hello do
  @callback hello(name :: bitstring())::bitstring()
end

defmodule Hello.FirstName do
  @behaviour Hello

   def hello(name), do: IO.puts "hello #{name}!"
end

Use the @callback attribute to specify the functions that are part of the @behavior contract

The @callback attribute in the example above tells Elixir that the "hello" function that takes a bitstring argument must be part of any module that wishes to implement the Hello module behavior.

What happens if you fail to implement the method specified by callback?

I experimented in the iex shell and found I got a warning:

warning: function hello/1 required by behaviour Hello is not implemented (in module Hello.FirstName)
  iex:4

So no one will revoke your license to program, but it looks like not including the contractualy specified behavior is frowned upon.

Dynamic Dispatching

One interesting thing you can do with behaviors is dynamically dispatching to a specific implementation. Let me give you a quick and contrived example.

defmodule Hello do
  @callback hello(name :: bitstring())::bitstring()

  def hello_general!(implementation, name \\ "") do
    hello_message = implementation.hello(name)
    "#{hello_message} You are a General."
  end
end

defmodule Hello.FirstName do
  @behaviour Hello

   def hello(name), do: "hello #{name}!"
end

defmodule Hello.RandomNumber do
  @behavior Hello
  def hello(name), do: "hello #{name}, your lucky number is #{:rand.uniform(100)}"
end

Below is some sample output from an iex shell:

iex(15)> Hello.hello_general!(Hello.FirstName, "Smith")
"hello Smith! You are a General."

iex(16)> Hello.hello_general!(Hello.RandomNumber, "Murphy")
"hello Murphy, your lucky number is 76 You are a General."

Notice how easy it is to dynamically dispatch based on a module.

Relation to Protocols

The following table I pulled from a blog post by a man named Samuel D.⁸ It gives a nice comparison between protocols and behaviors.

The main idea is that protocols can be thought of as "template" functions for handling different data types while behaviors can be thought of as "template" contracts that tell modules what functions to implement.

Summary

Elixir behaviors can be a great tool for helping to organize your code by specifying contracts and keeping your coding intentions clear.

Footnotes

Guards

Sometimes I've found myself wanting to only call a certain function depending on a certain condition. For example, I might only want to call a function when one of the parameters is greater than the other.

I did this in a production Phoenix application recently when I was trying to recursively generate a routing path

What is a guard?

Elixir guards are special little clauses denoted with the keyword when that are used to apply extra checks on pattern matched functions.

Here's a quick concrete code snippet:

def generate_path(path, j, k) when k > j and is_integer(j) and is_integer(k), do: path

So in the above snippet, this function will only be called when the condition "k > j" is met and they are both integers.

Why Use a Guard?

Like I said before, I found myself reaching for guard clauses when I want to apply a check on the parameters I pass into a function.

Types of Functions You Can Use With Guards

So remember in Chapter~\ref{cha:chapter*kernels} A Tour of Kernels, we described the *is** functions like is_integer, is_atom, and so on? Also, do you recall the *data structure functions* such as byte_size, map_size, and so on?

Well those are the functions that are allowed in guards. The complete list is documented in the documentation{:target=_"blank"}.

Why You Can't Use Custom Functions with Guards

You can also use the typical logical operators like &&, ||, and !.

For convenience, I'll quote from the documenation below.

Operators and Functions You Can Use in Guards

Operators

comparison operators (==, !=, ===, !==, >, >=, <, <=)

strictly boolean operators (and, or, not) (the &&, ||, and ! sibling operators are not allowed as they’re not strictly boolean - meaning they don’t require both sides to be booleans)

arithmetic binary operators (+, -, *, /)

arithmetic unary operators (+, -)

binary concatenation operator (<>)

in and not in operators (as long as the right-hand side is a list or a range)

Functions

Below are the built-in Elixir functions you can use with guards.

is_atom/1
is_binary/1
is_bitstring/1
is_boolean/1
is_float/1
is_function/1
is_function/2
is_integer/1
is_list/1
is_map/1
is_nil/1
is_number/1
is_pid/1
is_port/1
is_reference/1
is_tuple/1

abs/1
binary_part/3
bit_size/1
byte_size/1
div/2
elem/2
hd/1
length/1
map_size/1
node/0
node/1
rem/2
round/1
self/0
tl/1
trunc/1
tuple_size/1

The documentation is a quick read that shows you all the details, and I encourage you to give it a read if you're able.

Why You Can't Use Custom Functions With Guards

Once I tried using my custom function as a guard clause. It didn't work.

Why?

With the way Erlang executes functions, each function is tested from top to bottom of the code. If a guard clause were allowed to have a side effect, then you couldn't guarantee functional purity.

To ensure that guard clause functions have no side effects (i.e., "pure functions") and executed quickly, this blog post by Chris Keathley⁹ stated that Erlang's authors decided to limit guard clause functions to Erlang's built-in functions.

Or Can You Use Custom Functions?

Sort of. You can define your own guards using Elixir macros. However, you still must use Elixir's built-in functions and operators for the guards to be valid.

Example Macro Guard

defmodule Hello do
  defmacro is_less_than(m, n) do
    quote do: unquote(m) < unquote(n)
  end
end
defmodule World do
  import Hello
  def output_numbers(m, n) when is_less_than(m, n), do: "Hello #{m} #{n}"
  def output_numbers(m, n), do: "Hello without numbers"
end

Introducing defguard(p) in Elixir 1.6

As of Elixir 1.6¹⁰, you now have defguard/1 (or defguardp/1) to define guard macros. This helps you avoid unnecessarily complicated metaprogramming voodoo depending on whether or not the function is being invoked in a guard or not as described in this github issue{:target="_blank"}.

Resources:

If you're interested in applying your new knowledge about guards, check out the Elixir Katas resource I've prepared for you! Just click here to go this web page and sign up with your email to download the free resource

Summary

Overall, I've found guard clauses to be useful, especially when I need to quickly apply a conditional check on function parameters.

IO and Files

Not too long ago I was working on modifying an endpoint in a Phoenix web application that allowed you to upload a CSV file and insert that data into a database table.

In that code I noticed a reference to File.stream!. And so I began digging further.

File Module and Functions

There's a bit of interplay between the File and IO modules in Elixir. Since files are opened in binary mode by default, developers have to use IO.binwrite/2 and IO.binread/2 functions when reading and writing files.

If you want to tell Elixir to to interpret a file as utf8, you can open it with the :utf8 encoding option.

Bang and Non-Bang Function API

The bang file methods (denoted with a ! after the method name) typically raise an error on failure and return :ok on success.

The non-bang functions typically return an error tuple on failure and return :ok on success.

File Function Examples

So let's take a look at some basic file functions. You'll notice quite a few of the functions in the File module are named after their Unix/Linux cousins.

cd/1

Below I set the current working directory.

iex> File.cd("/Users/bruce")
:ok

stat/2

Next, I get some stats on a file I created in /Users/bruce.

iex(5)> File.stat("toss.txt")
{:ok,
 %File.Stat{
   access: :read_write,
   atime: {{2018, 2, 14}, {17, 49, 50}},
   ctime: {{2018, 2, 14}, {17, 49, 50}},
   gid: 20,
   inode: 18691495,
   links: 1,
   major_device: 16777218,
   minor_device: 0,
   mode: 33188,
   mtime: {{2018, 2, 14}, {17, 49, 50}},
   size: 6,
   type: :regular,
   uid: 501
 }}

atime indicates the last time the file was read. For Unix systems, ctime is the last time the file or inode was changed. In Windows, it is the time of creation. The links field indicates the number of links to the file. The size field gives the size of the file in bytes.

chmod/2

Similar to the analagous Unix command, you can change file permissions. The only difference is you use octal flags.

Below is an example.

iex(1)> File.chmod("toss2.txt", 0o040)
:ok

# these are the permissions before calling File.chmod...

-rw-r--r--    1 bru  staff        6 Feb 14 19:59 toss2.txt

# these are the permissions after calling File.chmod...

----r-----    1 bru  staff        6 Feb 14 20:05 toss2.txt

Here are the flags reprinted from the documentation for your convenience{:target="_blank"}.

0o400 - read permission: owner
0o200 - write permission: owner
0o100 - execute permission: owner
0o040 - read permission: group
0o020 - write permission: group
0o010 - execute permission: group
0o004 - read permission: other
0o002 - write permission: other
0o001 - execute permission: other

dir?

This handy method lets you inquire if a file is a directory.

iex> File.dir?("toss.txt")
false

exists?

You can figure out if the path (or file) exists.

iex(3)> File.exists?("toss.txt")
true

read/1

On success, the read/1 function returns a tuple with a status and binary data object that contains the contents of the file.

iex(5)> File.read("toss.txt")
{:ok, "hello\n"}

rename/2

You can also rename files. :ok is returned on success, otherwise {:error, reason} where reason is the reason for the error.

iex(7)> File.rename("toss2.txt", "toss3.txt")
:ok

regular?

This function checks if a file is "regular". In layman's terms this means it checks to see if it's an executable, a file containing ASCII text, zip file, etc.

You can check on your command line for regularity of a file with:

$ test -f .vimrc && echo regular
regular

As you can see, my .vimrc file is a regular file.

In an Elixir iex shell, you can do:

iex(13)> File.regular?("/Users/bruce")
false
iex(14)> File.regular?(".vimrc")
true

Note that directories in Unix and Linux are "binary files" that locate other files and directories.

write/3

And of course, no File module would be complete without a write function. Below I wrote the word "hello" out to a file called "toss2.txt".

iex(15)> File.write("toss2.txt", "hello", [:write])
:ok

There are different modes which are documented here in the File.open/2 method.

Path Module

If you look at the File documentation, you'll notice it typically takes paths as arguments. So I am jotting down some notes about some useful Path functions I found from reading the documentation.

Path Function Examples

absname/1

This handy function converts the path passed in to an absolute path name. For example:

iex(2)> Path.absname("toss.txt")
"/Users/bruce/toss.txt"

basename/1

The basename function returns the last component of the path, whether it's a file name or folder, or the path if there are no directory separators.

iex(4)> Path.basename("/Users/bruce/toss.txt")
"toss.txt

dirname/1

If a path contains a file name, dirname/1 returns the directory component.

iex(8)> Path.dirname("/Users/bruce/toss.txt")
"/Users/bruce"

join/1

This function takes a list of paths and joins them together, removing any trailing slash on the join.

iex(1)> Path.join(["~", "toss.txt"])
"~/toss.txt"

wildcard/2

One interesting function I found was the wildcard/2 function. It traverses paths according to the "glob" expression passed and the wildchard characters passed as options.

Here are the special characters from the documentation{:target="_blank"}

? - matches one character

* - matches any number of characters up to the end of the filename, the next dot, or the next slash

** - two adjacent *’s used as a single pattern will match all files and zero or more directories and subdirectories

[char1,char2,...] - matches any of the characters listed; two characters separated by a hyphen will match a range of characters. Do not add spaces before and after the comma as it would then match paths containing the space character itself.

{item1,item2,...} - matches one of the alternatives Do not add spaces before and after the comma as it would then match paths containing the space character itself.

IO Module and Functions

I've found myself using the IO module when doing basic debugging when I first started learning Elixir. Namely, I was using IO.puts/2 and IO.inspect/2.

IO Function Examples

But there are also some other handy IO functions.

binread/2

binread/2 lets you read from a "device". If you look at the documentation, this ends up being an atom or pid (process id).

In the example, I read from standard input and pass in the :line option. This lets binread/2 know how to iterate through the device (e.g., line by line or a certain number of bytes).

iex(1)> IO.binread(:stdio, :line)
Hello
"Hello\n"

gets/2

gets/2 lets you read one line from an IO device. :stdio is the default device.

In the below example, I specify :stdio to show you the argument parameter, though I didn't actually need to.

iex(5)> IO.gets(:stdio, "What's your name?\n")
What's your name?
Bruce
"Bruce\n"

puts/2

When I started with Elixir, the first thing I used to debug code was IO.puts/2.

iex(7)> IO.puts :stdio, "hello"
hello
:ok

puts/2 writes an item to a device (the default is :stdio) and adds a newline at the end.

iex(1)> m = %{a: 1, b: 2}
%{a: 1, b: 2}
iex(2)> IO.puts m
** (Protocol.UndefinedError) protocol String.Chars not implemented for %{a: 1, b: 2}
    (elixir) lib/string/chars.ex:3: String.Chars.impl_for!/1
    (elixir) lib/string/chars.ex:22: String.Chars.to_string/1
    (elixir) lib/io.ex:553: IO.puts/2

As you can see from the error above, puts/2 will not work with maps (or tuples).

inspect/2

Fortunately, Elixir also has inspect/2 which can be useful for debugging. inspect/2 doesn't change the argument passed in but returns it unchanged. So you can use it in your code to get a peak at raw values, including maps and tuples (and other pieces of data where IO.puts/2 will throw an error).

A Word on Inspect.Opts for Debugging

You'll notice in the following example Elixir treats the list of integers as ASCII codes and outputs their letter representation.

iex(8)> t=[97, 98, 99]
'abc'
iex(9)> IO.inspect t
'abc'
'abc'

To avoid, this you can turn to the Inspect.Opts module which defines the options used by inspect. To print out numbers, you can pass the :as_lists option as seen below.

iex(10)> IO.inspect t, [charlists: :as_lists]
[97, 98, 99]
'abc'

You can review the other options{:target="_blank"}, but one of the most useful ones I've found is the ability to print out a non-truncated list. In the example below you can see I use the :infinity option to see the whole list of numbers from 1 to 100.

Together with :as_lists, this should make your early debugging life much easier.

iex(16)> b = Enum.to_list 1..100
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22,
 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42,
 43, 44, 45, 46, 47, 48, 49, 50, ...]
iex(17)> IO.inspect b, [limit: :infinity]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22,
 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42,
 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62,
 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82,
 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100]
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22,
 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42,
 43, 44, 45, 46, 47, 48, 49, 50, ...]

write/2

write/2 allows you to write to a specified device (standard output is the default device).

iex(3)> IO.write(:stdio, "hello world\n")
hello world
:ok

Writing Files to Memory

One method I did want to highlight is File.open/2.

iex(1)> {:ok, file_descriptor} = File.open("hello world", [:ram])
{:ok, {:file_descriptor, :ram_file, #Port<0.1181>}}
iex(17)> :file.read(file_descriptor, 12)
{:ok, "hello world"}

Doing it this way lets Elixir operate on the data in memory as if it was a file. You'll notice I call an Erlang :file.read method. This is because I couldn't find anything in Elixir to operate on it.

Summary

There's quite a bit more to the File, IO, and Path modules in Elixir. This section gave you just a small taste. The next section will be a simple case study application to help you randomly open files.

Building a Random Image CLI Loader

The best way I have found to learn new concepts is to try and build something with what you just learned. That's why I do all the katas. So to help ingest our learnings for files, let's write a CLI (command line interface) application that helps us pick a set of files to randomly open.

Case Study: Building a Random Image CLI Loader with EScript

I've previously written a tutorial on building an escript CLI application{:target="_blank"}, but we're going to build another one that does a bit more in this post.

Step 1: Initialize a mix application

The first thing to do is to initialize our mix application. I'm passing in the *--sup arguments. This is to initialize the application with some supervisor and umbrella application defaults. It's more for my own amusement than having anything to do with the application.

Below is the mix command I issued and its associated output.

$ mix new image_loader --sup
* creating README.md
* creating .formatter.exs
* creating .gitignore
* creating mix.exs
* creating config
* creating config/config.exs
* creating lib
* creating lib/image_loader.ex
* creating lib/image_loader/application.ex
* creating test
* creating test/test_helper.exs
* creating test/image_loader_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd image_loader
    mix test

Run "mix help" for more commands.

I also did a git init . command in the image_loader repository so I could use Git version control.

Step 2: Add yaml-elixir and Write Tests

Next, I add a yaml parser via yaml-elixir in my mix.exs file.

# mix.exs
defmodule ImageLoader.MixProject do
  use Mix.Project

  def project do
    [
      app: :image_loader,
      version: "0.1.0",
      elixir: "~> 1.6",
      start_permanent: Mix.env() == :prod,
      deps: deps()
    ]
  end

  # Run "mix help compile.app" to learn about applications.
  def application do
    [
      extra_applications: [:logger, :yaml_elixir],
      mod: {ImageLoader.Application, []}
    ]
  end

  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
      {:yaml_elixir, "~> 1.3.1"}
    ]
  end
end

Test Structure

Below are the tests I wrote. Notice I only test the path generation functionality. I could actually check the status of the images when they're opened, but I chose not to do that.

# image_loader_test.exs
defmodule ImageLoaderTest do
  use ExUnit.Case

  @file_path "/test/fixtures/test.yml"

  test "read yaml from file path into map" do
    assert ImageLoader.read_yaml_from_file_path(@file_path) ==
      %{
         "set_1" => %{
           "base_path" => "/test/fixtures/",
           "directory" => "images/",
           "files" => ["pexels-photo-87065.jpeg", "pexels-photo-274054.jpeg"]
        }
      }
  end

  test "fetch image paths from yaml file" do
    assert ImageLoader.image_paths(@file_path) ==
      %{"set_1" => ["#{File.cwd!}/test/fixtures/images/pexels-photo-87065.jpeg",
          "#{File.cwd!}/test/fixtures/images/pexels-photo-274054.jpeg"]}
  end
end

Step 3: Setup Yaml Structure / File

# fixtures/test.yml

set_1:
  base_path: "/test/fixtures/"
  directory: "images/"
  files: ["pexels-photo-87065.jpeg", "pexels-photo-274054.jpeg"]

Step 4: Open Images

Below is the code used to randomly open up images. The main functions are image_paths, which produce the file paths to the images so the System.cmd can know which files to open, and open_images, which does the actual work of opening the images.

The function read_yaml_from_file_path parses the yaml file into a map to be parsed through by Elixir.

# image_loader.ex
defmodule ImageLoader do
  @moduledoc """
  Documentation for ImageLoader.
  """

  # Boot up iex and type ImageLoader.open_images("/test/fixtures/test.yml")
  def open_images(file_path) do
    image_paths(file_path)
    |> Enum.map(fn{set_key, files} -> System.cmd("open", files) end)
  end

  def image_paths(file_path) do
    read_yaml_from_file_path(file_path)
    |> Enum.reduce(%{}, fn({set, set_info}, acc) -> Map.merge(acc, %{set => assemble_paths_from_set(set_info)}) end)
  end

  defp assemble_paths_from_set(set_map) do
    base_path = Map.get(set_map, "base_path", "")
    dir = Map.get(set_map, "directory", "")
    Map.get(set_map, "files", [])
    |> Enum.map(fn(file) -> Path.join([File.cwd!, base_path, dir, file]) end)
  end

  def read_yaml_from_file_path(file_path) do
    [File.cwd!, file_path]
    |> Path.join
    |> YamlElixir.read_from_file
  end
end

Step 5: Convert to Escript

I've written about building a CLI with Escript before{:target="_blank"}, but I'll reiterate the steps here for convenience.

Step 5a: Configure escript in mix.exs

The first thing to do is to specify the module with a "main" function that serves as the main module in mix.exs.

defmodule ImageLoader.MixProject do
  use Mix.Project

  def project do
    [
      app: :image_loader,
      version: "0.1.0",
      elixir: "~> 1.6",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      escript: escript_config()
    ]
  end

  defp escript_config do
    [main_module: ImageLoader.Cli]
  end

  # Run "mix help compile.app" to learn about applications.
  def application do
    [
      extra_applications: [:logger, :yaml_elixir],
      mod: {ImageLoader.Application, []}
    ]
  end

  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
      {:yaml_elixir, "~> 1.3.1"}
    ]
  end
end

Step 5b: Add a module with a main function

Next, add the module with the main function that you specified in mix.exs.

defmodule ImageLoader.Cli do
  def main(args) do
    args
    |> parse_options
    |> output
  end

  defp parse_options(args) do
    {options, _args}  = OptionParser.parse!(args,
    switches: [path: :string]
    )
    options
  rescue OptionParser.ParseError ->
    [error: "parse error in your arguments"]
  end

  defp output([error: err] = opts) do
    IO.puts "Error in opening files: #{err}"
  end
  defp output(opts) do
    ImageLoader.open_images(path(opts))
    IO.puts "Images opened from #{path(opts)}"
  end

  defp path(opts), do: opts |> Keyword.get(:path, "/test/fixtures/test.yml")
end

Step 5c: Build the escript

Finally, build the escript.

$ mix escript.build

Step 6: Run the CLI program

Now, you can run the CLI program. Below I run the script using the path to the test.yml file that is included in this program.

$ ./image_loader --path="/test/fixtures/test.yml"

Summary

Hopefully this CLI tool has given you a feel for what you can do with some of Elixir's file related modules. Coming up soon, we'll talk about errors in Elixir.

Everyone Makes Mistakes: Errors in Elixir

I once took a class in watercolor painting. The instructor would have us sketch a bit, and then we'd start adding our paint. You had to be very careful not only with the amount of water you used, but also to let certain areas dry before you attempted to paint. Otherwise the colors would run together and there was no going back. There was no such thing as being able to "rescue" errors in watercolor painting.

Fortunately, Elixir does provide error handling.

Elixir Philosophy: Let It Crash

If you hang around the Elixir community long enough, you'll hear phrases like "let it crash." This refers to the fact that Elixir can do things like let an exit message from a dying process be used by a supervisor to decide what to do.

Conventions

In Elixir, the convention is to create a non-bang function such as hello_world/1 that returns a tuple consisting of a status and a result (e.g., {:ok, result} or {:error, reason}).

You also create a bang function that returns the result or raises an exception. For example., hello_world!/1 could return "result" or raise a HelloException.

Error Handling Keywords

Before diving in to error handling, let's go over some of the basic keywords you'll encounter.

try

The try keyword tells Elixir to enter into the block and "try" something that may result in an error.

catch

The catch keyword can be used with try, although as the Elixir documentation points out, it is very uncommon to use it this way. Instead, you'll use it with the throw keyword.

throw

Throw is used in conjunction with catch in situations where it is not possible to get a value without using throw/catch.

rescue

Rescue allows you to specify what happens when a certain exception is raised.

raise

Raise is the keyword that allows you to raise an error in Elixir.

after

The after keyword specifies something that must always happen.

Examples of Try/Rescue

Let's look at using try and rescue in practice.

Example From the Phoenix Framework

Let's say we had a method to fetch a "Car" model in Phoenix. With a bang get!/1 method, an Ecto.NoResultsError is raised.

def get_my_car do
  try do
    car = Repo.get!(Car, 4)
  rescue Ecto.NoResultsError ->
    {:error, "not_found"}
  end
end

You could also omit the "try" block and simply use rescue.

def get_my_car do
  car = Repo.get!(Car, 4)
rescue Ecto.NoResultsError ->
  {:error, "not_found"}
end

This example fits the canonical use case of using raise/rescue for exception handling. This is for unexpected situations your program gets into.

Examples of Throw/Catch

When you have expected failures, it's time for throw/catch. I'll summarize the findings from this StackOverflow answer¹¹ on throws which gives some more interesting insights and you can read if you'd like.

The Elixir documentation¹² says that throw/catch is good to use when interfacing with library code that does not provide a "proper API".

As an example, let's say Elixir didn't provide a way to delete an element(s) from a list.

Then you might use throw this way:

try do
  m = [:t, :u, :v]
  Enum.each m, fn(y) ->
    if y == :u, do: throw([:t, :v])
  end
   "Nothing to catch"
catch
  list -> list
end

One cool example comes from Ecto:

def transaction(_repo, _opts, fun) do
  # Makes transactions "trackable" in tests
  send self, {:transaction, fun}
  try do
    {:ok, fun.()}
  catch
    :throw, {:ecto_rollback, value} ->
      {:error, value}
  end
end

def rollback(_repo, value) do
  send self, {:rollback, value}
  throw {:ecto_rollback, value}
end

Above we can see that we'll catch a rollback when we try a transaction in Ecto.

The StackOverflow post I referenced¹¹ goes on to say that using raise/rescue is good when you want to have a programmer looking at a stacktrace. You can use throw/catch when you don't want to incur the cost of building that stacktrace.

Examples of Try/After

We use try/after when we want to ensure an action occurs no matter what. As an example, we may want to make sure a file gets closed or a status message gets logged.

try do
  IO.inspect "Executing some code..."
rescue
  err in RuntimeError -> IO.puts "Error #{err}"
after
  Logger.info fn -> "We have at least tried to execute some code."
end

Scope in Try/Rescue/Catch/After

Regarding variable scope, one thing to note is that variables defined in the try/rescue/catch/after context are not available in the "outer context". This is in keeping with traditional Elixir semantics.

So if you're trying to capture a value that is set in a try/catch/rescue/after block, you'll want to do something like this:

status =
  try do
    raise "failure"
    :failure_status
  rescue
    _ -> :we_are_rescued
  end

#status is now set to :we_are_rescued

Summary

Unlike watercolor painting, Elixir provides us with a way to handle our errors. Just like watercolor errors do happen, but we can ensure we have some mechanisms to deal with them when they occur.

Footnotes

Sigils: Or What Are Those Squiggly Things?

My first exposure to something similar to Elixir sigils came via the Ruby programming language's way of specifying literals. I was minding my own business reading the source code and came across something similar to the following:

cars = %w(mustang ranger fiesta)
#=> ["mustang", "ranger", "fiesta"]
brand = cars.inject({}) { |r, car| r.merge({car => "Ford"})}
#=> {"mustang"=>"Ford", "ranger"=>"Ford", "fiesta"=>"Ford"}

You can see the %w in Ruby creates an array. But what are sigils and where do they come from?

Sigils: What They Are and a Backstory

Apparently, according to Wikipedia¹³, sigils were actually popularized by the BASIC programming language. BASIC appended the $ to the names of all strings.

The layman's definition of a sigil is a symbol placed in front of a variable name that shows the variable's scope or data type.

Now I mentioned Ruby's way of specifying literals with the "%" symbol because they will closely match Elixir's sigil syntax. But from the canonical definition of sigil, the $ symbol specifying a Ruby global variable would be an actual example of a sigil in Ruby. But I digress.

Why Use Sigils?

With the use of a symbol, sigils immediately tell you the "type" of variable you are dealing with.

Using Sigils in Elixir

In Elixir sigils are used more closely with the Ruby "literals" example I gave above. They help work with representations of text.

Sigils and Regular Expressions

Elixir's regular expression implementation is based on PCRE (Perl Compatible Regular Expressions)¹⁴

The common way to define regular expressions in Elixir is by using "~r". Let's look at the following example.

"World" =~ ~r/world/
#=> false

You can also use other delimiters such as brackets(~r[yo]), single quotes(~r'yo'), double quotes(~r"yo"), parentheses(~r(yo)), braces(~r{yo}), and double angle brackets(~r).

Apparently, you get all these choices of regex delimiters so you can write literals without having to escape delimiters, which as I think about it, is a really nice feature.

Char List/Word List/String Sigils

If you want to generate char lists with single quotes without having to escape them, try the ~c sigil.

~c(John said, 'hi, how are you?')
#=> 'John said, \'hi, how are you?\''

If you recall the example I gave with Ruby literals and "%w(mustang ranger fiesta)", Elixir operates with a similar syntax. Below is an example.

~w(mustang ranger fiesta)

You can also create atomized lists by placing the letter "a" after the closing delimiter of the sigil. Use the letter "c" for character lists.

~w(mustang ranger fiesta)a

Finally, you can also have string sigils.

~s(John said, "hi, how are you?")

Date and Time Sigils

Elixir also provides some handy sigils for initializing Date, Time, NaiveDateTime, and Time structs.

Date Sigil

Below is an example of a sigil for Date.

~D[2001-12-25]

NaiveDateTime Sigil

Below is an example of a sigil for NaiveDateTime.

~N[2001-12-25 14:10:07]

Time Sigil

Below is an example of a sigil for Time.

~T[14:10:00.001]

Escaping in Sigils

Elixir provides lowercase sigils which makes room for interpolation and escape codes. The uppercase sigils do not do this.

Below is a list of escape codes that are allowed in strings and char lists from the Elixir documentation, reprinted here for convenience¹⁵.

null byte - \0

vertical tab - \v

tab - \t

space - \s

carriage return - \r

newline - \n

form feed - \f

escape - \e

delete - \d

backspace - \b

bell/alert - \a

single backslash - \

single hexadecimal byte - \xDD where D is an integer

represents a Unicode codepoint in hexadecimal (such as \u{1F600}) -
\uDDDD and \u{D...} where D is an integer

Writing Custom Sigils

Elixir provides a way for you to write your own custom sigils. You define it by declaring a function header "sigil_{representation}" where representation is a one character identifier.

Notice in the code below the custom sigil function takes 2 arguments, the actual thing that is inside the sigil delimiter and a modifier list.

defmodule CustomSigil do
  def sigil_f(arg, []), do: arg |> String.to_float
  def sigil_f(arg, [?c]), do: arg |> String.to_float |> Float.round(2)
end

To give a more concrete illustration, I'll show you some output from an iex terminal.

iex(20)> import CustomSigil
CustomSigil
iex(21)> ~f(123.456)
123.456
iex(22)> ~f(123.456)c
123.46

Notice how we got to round to 2 places with the "c" modifier.

Summary

Sigils are a handy little tool Elixir gives us for dealing with textual representations of strings. I particularly find them useful when creating Date and Time structs as it means I don't have to type out a whole struct with its arguments.

Footnotes

The Observer and How to Profile Your Memory Usage

When I was first learning Elixir, I built an application that was pulling down statistics from a social media platform via its API. Let's call the application YouTuber to have a name to latch on to. I didn't really understand concepts like tail recursion or even how to use pattern matching all that well.

During the course of building and testing, there was a point where the application started having memory issues and crashing on the Heroku server. I wanted to be able to profile it locally. Fortunately, because Elixir sits on top of Erlang, there is such a tool available to help.

What is observer?

Observer is a great little tool that gives you insight into your whole Elixir application. You can see a graphical representation of your supervision tree, process id numbers, and get a tabular view of all the application processes running.

Why use it?

Once I was at a workshop with a engineer who said he was looking through the code to get an idea of how the supervision tree was setup. If I recall correctly, he said he spent time looking at it, and didn't get too far. Then he opened up the observer and said everything made sense.

Truly, a picture is worth a thousand words.

How to install observer

First, you need to have installed Elixir via the installation guide I wrote in Chapter~\ref{cha:chapter1}.

In 2016, I had trouble starting observer, I would often get errors like:

iex(1)> :observer.start
** (UndefinedFunctionError) function :wx_object.start/3 is undefined (module :wx_object is not available)
    :wx_object.start(:observer_wx, [], [])
    observer_wx.erl:68: :observer_wx.start/0

This was because the Erlang installation I was using was not built with WxWidgets. I recall having to rebuild Erlang with WxWidgets and fiddle around for a few hours with it. On MacOSx, I think I had to install wxmac, the WxWidgets dependency.

Today though, that doesn't seem to be the case. When I installed Elixir/Erlang via the guide I wrote in Chapter~\ref{cha:chapter1}, I didn't need to do this. As an FYI, as I'm writing this, I have Elixir 1.6.x and Erlang 21 installed.

I'd like to say something like YMMV (your mileage may vary), but if you have trouble, feel free to shoot me an email at bruce at binarywebpark dot com with a copy of the error message you're getting, the operating system you're running, and which installation method you tried, and I'll try and debug it.

A Tour of Observer

Ok, so now that you have observer installed, it's time to take a tour of what's available. If you're reading this online and can't see the images in the following section, it's best to grab a PDF copy. This is because the processing software I use isn't compatible with Wordpress at the moment.

Open up an iex shell and type ":observer.start".

Looking at memory

Below is an image of the Memory Usage from the Load Charts tab. You can see the memory usage of your program. This is what I used when I was troubleshooting the memory issues I was having with the Youtuber application.

Applications Tab

Below is an image of the supervision tree from the Applications tab. This is the supervision tree graphic the engineer I had mentioned previously used to visualize his company's Erlang program.

Processes Tab

Below is an image of the running processes from the Processes tab.

Summary

Overall, I found observer to be helpful when I was troubleshooting a memory issue with Youtuber. Hopefully, you find it useful too!

Debugging with IEx

One of my favorite debugging techniques doesn't involve any coding tools at all. It just involves moving my mouth and letting a coworker listen and offer suggestions (and vice versa). It's called "rubber ducking".

But to have something to rubber duck about, I often find it's helpful to do a bit of exploratory digging myself. I like to look at the actual value of a computation and expected value in my programs.

And to do that in Elixir, I like to use a tool called IEx.pry.

What is IEx?

IEx is an interactive shell in Elixir.

Understanding Expressions in IEx

IEx expressions are evaluated (as opposed to compiled like production Elixir code).

Getting Help in IEx

There are 2 ways to get help in IEx. You can use the autocomplete or the shell history.

Using autocomplete

Type in however many letters and hit tab. For example, type "M" and hit tab. You should see:

iex(1)> M
Macro         Map           MapSet        MatchError    Module

If you type in a module name followed by a dot (such as Map.), you'll see:

iex(1)> Map.
delete/2             drop/2               equal?/2
fetch!/2             fetch/2              from_struct/1
get/2                get/3                get_and_update!/3
get_and_update/3     get_lazy/3           has_key?/2
keys/1               merge/2              merge/3
new/0                new/1                new/2
pop/2                pop/3                pop_lazy/3
put/3                put_new/3            put_new_lazy/3
replace!/3           split/2              take/2
to_list/1            update!/3            update/4
values/1

That's right, you can get a list of methods for the module. Pretty cool, right?

Using shell history

If you followed the installation instructions in Chapter~\ref{cha:chapter1}, you probably already have shell history enabled by default. If you can press the up arrow and see what you previously typed in IEx, you're golden!

You can also start it on an as-needed basis with:

iex --erl "-kernel shell_history enabled"

Aborting IEx

To abort the IEx shell, hit the "control" key and the "c" key simultaneously.

Debbuging with IEx

• IO.inspect (with and without binding)- why not IO.puts?
• IEx.pry
• IEx.break!
• respawn()

User Switch

Connecting to Remote Nodes

.iex.exs file

• example 1 - IEx.pry - exercism example
• example 2 - IEx.pry - phoenix example