Creating an Elixir Escript application with Mix

2.1   Access to command line arguments

System.argv/0 gives us access to any command line arguments.

And, OptionParser.parse helps us process the arguments so that we can capture both the command line options and any additional, positional arguments.

Here is an example:

#!/usr/bin/env elixir
# test01.exs

defmodule Test13.CLI do
  @moduledoc """
  synopsis:
    Prints args, possibly multiple times, possibly upper cased.
  usage:
    $ test01 {options} arg1 arg2 ...
  options:
    --upcase      Convert args to upper case.
    --count=n     Print n times.
  """

  def main([help_opt]) when help_opt == "-h" or help_opt == "--help" do
    IO.puts(@moduledoc)
  end
  def main(args) do
    {opts, cmd_and_args, errors} = parse_args(args)
    case errors do
      [] ->
        process_args(opts, cmd_and_args)
      _ ->
        IO.puts("Bad option:")
        IO.inspect(errors)
        IO.puts(@moduledoc)
    end
  end

  defp parse_args(args) do
    {opts, cmd_and_args, errors} =
      args
      |> OptionParser.parse(strict:
        [upcase: :boolean, help: :boolean, count: :integer])
    {opts, cmd_and_args, errors}
  end

  defp process_args(opts, args) do
    count = Keyword.get(opts, :count, 1)
    convertfn = if Keyword.has_key?(opts, :upcase) do
      fn (arg) -> String.upcase(arg) end
    else
      fn (arg) -> arg end
    end
    Stream.iterate(0, &(&1 + 1))
    |> Stream.take(count)
    |> Enum.each(fn (idx) ->
      if idx > 0 do
        IO.puts("-----------------")
      end
      Stream.with_index(args)
      |> Enum.each(fn ({arg, index}) ->
        arg1 = convertfn.(arg)
        IO.puts("arg #{index + 1}. #{arg1}") end)
    end)
  end

end

Test13.CLI.main(System.argv)

Notes:

• Notice that at the bottom of this script, we call the function that starts it, and we pass the (un-parsed command line arguments).

2.2   The ability to use external modules

In order to use an external module and call a function in it, we'll have to do the following:

1. Get the source code for the module.
2. Compile it.
3. Access it from our Elixir script.

Retrieving and compiling -- I use Mix, the Elixir build tool. So, as an example, it's easy for me to include the following in my mix.exs file:

defp deps do
  [
    {:jason, ">0.0.0"}
  ]
end

I can then compile it and build the ebin files with:

$ mix deps.get
$ mix deps.compile

Next we need to enable Elixir (actually the underlying Erlang system) to find these modules. We can do that in one of the following ways:

• Use the "-pa" or "-pz" command line option to elixir:

  $ elixir -pz /path/to/my/ebin test01.exs arg1 arg2 ...
  

  In my case, the /path/to/my/ebin is a path to a sub-directory of the _build directory under my Mix project. Note that (on Linux) I can use a symbolic link to make it easier to access that directory.

• Set the ERL_LIBS environment variable to include the needed ebin directory. Example:

  export ERL_LIBS=/path/to/my/ebin
  

• Specify locations (directories) from which to load compiled code in your Erlang configuration file: ~/.erlang. For example:

  code:add_pathsz([
      "/home/yourname/a1/Erlang/Elixir/Test/test21/_build/dev/lib/sweet_xml/ebin/",
      "/home/yourname/a1/Erlang/Elixir/Test/test21/_build/dev/lib/jason/ebin/",
      "/home/yourname/a1/Erlang/Elixir/Test/test21/_build/dev/lib/test21/ebin/"
  ]).
  

For information about the use of command line flags "-pa" and "-pz" and for information about ERL_LIBS, see: http://erlang.org/doc/man/erl.html. Note that when you use environment variable ERL_LIBS, subdirectories are also searched. For infomation about code:add_pathsz/1 and other functions in the code module for this purpose see https://erlang.org/doc/man/code.html.

If you decide to use the ERL_LIBS environment variable, then, on Linux, you can set it with something like the following:

# replace
$ export ERL_LIBS=/path/to/my/libs
# append
$ export ERL_LIBS=$ERL_LIBS:/path/to/my/libs

Or, for one time use, set the environment variable and run your script as follows:

$ ERL_LIBS=/the/path/to/my/libs elixir my_script.exs

In our script, we need to make the module available using the require directive. Here is an example:

#!/usr/bin/env elixir

require Jason

elixir_data = [11, 22, 33, 44]
{:ok, jason_data} = Jason.encode(elixir_data)
IO.write("jason_data: ")
IO.inspect(jason_data)
{:ok, elixir_data2} = Jason.decode(jason_data)
IO.write("elixir_data2: ")
IO.inspect(elixir_data2)