Do It - Subcommands and Single Binary CLI

Rodrigo Zampieri Castilho — Fri, 27 Oct 2023 20:00:55 +0000

In the last article, I introduced you to Do It, a library to create CLI tools in Elixir. Now, I'll show you the subcommands feature and how to generate a single binary using burrito-elixir.

Subcommands

Do It now supports subcommands; in this way, you can logically group other commands at any level using the subcomand macro.

For example:

defmodule HelloWorld.Template do
  use DoIt.Command,
    description: "Manage HelloWorld Template"

  subcommand(HelloWorld.Template.Set)
  subcommand(HelloWorld.Template.Unset)
  subcommand(HelloWorld.Template.Show)
end

When a command has subcommands, you cannot define arguments or options and don't need to implement the run callback function.

As I said before, it's just a way to group other commands logically but cleverly when implementing CLIs with many commands.

Calling parent command with the --help option shows all subcommands.

./hello_world template --help 

Usage: hello_world template SUBCOMMAND

Manage HelloWorld Template

Subcommands:
  show      Show default message template
  unset     Remove default message  template
  set       Set default message template

Run 'hello_world template SUBCOMMAND --help' for more information on a subcommand.

Single Binary

Do It supports single binary CLI distribution through burrito-elixir.

To configure the application, add the burrito-elixir dependency in your project, the :mod property in the application function, and the :releases key with the releases configuration to your project properties in your mix.exs file.

defmodule HelloWorld.MixProject do
  use Mix.Project

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

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

  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
      {:do_it, path: "../../"},
      {:burrito, github: "burrito-elixir/burrito"}
    ]
  end

  defp releases do
    [
      hello_world: [
        steps: [:assemble, &Burrito.wrap/1],
        burrito: [
          targets: [
            macos: [os: :darwin, cpu: :x86_64],
            linux: [os: :linux, cpu: :x86_64],
            windows: [os: :windows, cpu: :x86_64]
          ]
        ]
      ]
    ]
  end
end

After configurations, you can build using the mix release command, the binaries will be generated in burrito_out folder.

$ MIX_ENV=prod mix release
...
ls -l burrito_out
total 77208
-rwxr--r--  1 castilho  staff  16729320 Oct 27 16:23 hello_world_linux
-rwxr--r--  1 castilho  staff   6572904 Oct 27 16:22 hello_world_macos
-rwxr--r--  1 castilho  staff  16222208 Oct 27 16:24 hello_world_windows.exe

See the build process and CLI execution in the video below.

Do It - Elixir Command Line Interface Library

Rodrigo Zampieri Castilho — Tue, 08 Aug 2023 02:33:00 +0000

I will introduce you to Do It, an Elixir library to create friendly CLI tools.

With DoIt, you have support to define arguments and options for your commands.

Arguments are required, and options are optional, but you can programmatically require options too.

DoIt generates a help command and a help option for each command automatically.

DoIt supports persisted options through the DoIt.Commfig module.

So, let's do it!!!

First, create a new Elixir project with mix.

mix new hello_world

Add :do_it dependency to mix.exs file, and configure escript main_module with HelloWorld module.

defmodule HelloWorld.MixProject do
  use Mix.Project

  def project do
    [
      app: :hello_world,
      version: "0.1.0",
      elixir: "~> 1.14",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      escript: [main_moodule: HelloWorld]
    ]
  end

  # Run "mix help compile.app" to learn about applications.
  def application do
    [
      extra_applications: [:logger]
    ]
  end

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

Now define the HelloWorld module as the main command. So, edit hello_world.ex file and use the DoIt.MainCommand module with a description key; this description is required.

defmodule HelloWorld do
  use DoIt.MainCommand,
    description: "DoIt Hello World CLI!!!"
end

Next, let's create a command, create a new file named say.ex; in the Say module use the module DoIt.Command, and add the description key to the command, too; it's mandatory.

In this command, declare an argument and two options. The argument is the message, the first option is the message template, and the last is how many times you want to print the message; define default values for the options.

defmodule HelloWorld.Say do
  use DoIt.Command,
    description: "Say something"

  argument(:message, :string, "An awesome message")
  option(:template, :string, "Message template", default: "Hello <%= @message %>!!!")
  option(:repeat, :integer, "Print message n times", default: 1)

  def run(%{message: message}, %{template: template, repeat: repeat}, _) do
    for _ <- 1..repeat, do: IO.puts(EEx.eval_string(template, assigns: [message: message]))
  end

end

Initialize the DoIt configuration and package the CLI with the mix tasks below.

mix do_it.init.config
mix escript.build

Let's try some commands.

If you run the CLI directly, without any command, you'll see an error message followed by the CLI help.

./hello_world
no command provided

Usage: hello_world COMMAND

DoIt Hello World CLI!!!

Commands:
  say     Say hello

Type ./hello_world say and you will get a new error message indicating that you must pass at least an argument and the command's help.

./hello_world say
wrong number of arguments (given 0 expected 1)

Usage: hello_world say [OPTIONS] <message>

Say hello

Arguments:
  message   An awesome message

Options:
      --help       Print this help
  -t, --template   Message template (Default: "Hello <%= @message %>!!!")
      --repeat     Print message n times (Default: 1)

Finally, execute the command passing the message World.

./hello_world say World                                                                                    
Hello World!!!

You can try different option combinations, see the video bellow.

Next time I'll detail argument and option macros and show how to build a single binary using Elixir Burrito.

DEV Community: Rodrigo Zampieri Castilho

Do It - Subcommands and Single Binary CLI

Subcommands

Single Binary

Do It - Elixir Command Line Interface Library