Your First Elixir CLI Application With Escript

Your First Elixir CLI Application With Escript

Functional programming is all the rage these days and Elixir can be a great way to dig into the concept. As I continued to explore Elixir, I wanted to understand how to write an Elixir CLI (command line interface) application.

Normally, I like to read a book about a new programming language and then try doing things with it. If you haven’t setup Elixir on your system, you can read this post for some help.

Step 1: Start an application

mix new choices

Step 2: Adding Choices

We’re going to write an application that prints out a list of choices and prompts you to pick one. It’s simple, but it will give you the idea.

Below is the program I wrote. We’ll walk through it in the next steps.

Example Program

defmodule Choices do
  def main(args) do
    args |> parse_choices |> output
  end

  defp output(opts) do
    case opts[:choice] do
      "Blue" ->
        IO.puts "You pulled the blue lever. That is progressive."
      "Red" ->
        IO.puts "You pulled the red lever. That is conservative."
      _ ->
        IO.puts "You clearly want to waste your choice. That's ok, it's a free country."
    end

  end

  defp parse_choices(args) do
    {options, _, _} = OptionParser.parse(args,
      switches: [choice: :string]
    )
    options
  end
end

Step 3: Add escript to mix.exs

Elixir uses escript to build your executable. This depends on Erlang, which you should have if you’ve already installed Elixir successfully.

Just add escript in your mix.exs file as shown below.

defmodule Choices.Mixfile do
  use Mix.Project

  def project do
    [app: :choices,
     version: "0.1.0",
     elixir: "~> 1.3",
     build_embedded: Mix.env == :prod,
     start_permanent: Mix.env == :prod,
     escript: [main_module: Choices], # <- add this line
     deps: deps()]
  end
  #...more code omitted below for clarity:
end

Step 4: The main function

You really need a main function to get the arguments passed in from the command line as shown in the example code. If you try to call it run or something else, you’ll get an error like the below.

** (UndefinedFunctionError) function Choices.main/1 is undefined or private
    (choices) Choices.main(["--choice=Red"])
    (elixir) lib/kernel/cli.ex:76: anonymous fn/3 in Kernel.CLI.exec_fun/2

Step 5: Build it

Next, you’ll need to build your CLI executable.

$ mix escript.build

Step 6: Run the executable with args

$ ./choices --choice="Red"

It’s pretty straight forward. It passes the arguments form the command line to the private function parse_choices. We use the OptionParser library from Elixir to get the options hash.

This turns the command line argument you wrote into:

[choice: "Red"]

Once this gets passed as an argument into the output method, you then get a message depending on what you chose, so choose wisely!

Summary

As you can getting started writing your own Elixir CLI apps is pretty easy.