Nexus.CLI provides a macro-based DSL for defining command-line interfaces with commands, flags, and positional arguments using structured ASTs with structs.

Overview

The Nexus.CLI module allows you to build robust command-line applications by defining commands, subcommands, flags, and arguments using a declarative syntax. It handles parsing, validation, and dispatching of commands, so you can focus on implementing your application's logic.

Command Life Cycle

1. Definition: Use the provided macros (defcommand, subcommand, flag, value, etc.) to define your CLI's structure in a clear and organized way.
2. Compilation: During compilation, Nexus processes your definitions, builds an abstract syntax tree (AST), and validates your commands and flags.
3. Parsing: When your application runs, Nexus parses the user input (e.g., command-line arguments) against the defined AST, handling flags, arguments, and subcommands.
4. Dispatching: After successful parsing, Nexus dispatches the command to your handle_input/2 callback, passing the parsed input.
5. Execution: You implement the handle_input/2 function to perform the desired actions based on the command and input.

The handle_input/2 Callback

The handle_input/2 function is the core of your command's execution logic. It receives the command path and an Nexus.CLI.Input struct containing parsed flags and arguments.

Signature

@callback handle_input(cmd :: atom | list(atom), input :: Input.t()) :: :ok | {:error, error}copy

• cmd: The command or command path (list of atoms) representing the executed command or a single atom if no subcommand is provided.
• input: An %Nexus.CLI.Input{} struct containing flags, args, and value.

Return Values

• :ok: Indicates successful execution. The application will exit with a success code (0).
• {:error, {code :: integer, reason :: String.t()}}: Indicates an error occurred. The application will exit with the provided error code.

Running the CLI Application

You can run your CLI application using different methods:

Using mix run

If you're developing and testing your CLI, you can run it directly with mix run:

mix run -e 'MyCLI.execute("file copy source.txt dest.txt --verbose")'copy

Compiling with Escript

Escript allows you to compile your application into a single executable script.

Steps:

1. Add Escript Configuration: In your mix.exs, add the :escript configuration:

def project do
  [
    app: :my_cli,
    version: "0.1.0",
    elixir: "~> 1.12",
    escript: [main_module: MyCLI],
    deps: deps()
  ]
endcopy

2. Build the Escript:

mix escript.build
copy

3. Run the Executable:

./my_cli file copy --verbose source.txt dest.txt
copy

Note that in order to use and distribute escript binaries, the host needs to have Erlang runtime available on $PATH

Compiling with Burrito

Burrito allows you to compile your application into a standalone binary.

Steps:

1. Add Burrito Dependency: Add Burrito to your mix.exs:

defp deps do
  [
    {:burrito, github: "burrito-elixir/burrito"}
  ]
endcopy

2. Configure Releases: Update your mix.exs with Burrito release configuration:

def project do
  [
    app: :my_cli,
    version: "0.1.0",
    elixir: "~> 1.12",
    releases: releases()
  ]
end

def releases do
  [
    my_cli: [
      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]
        ]
      ]
    ]
  ]
endcopy

3. Build the Release:

MIX_ENV=prod mix release
copy

4. Run the Binary:

./burrito_out/my_cli_macos file copy --verbose source.txt dest.txt
copy

Using Mix Tasks

You can also run your CLI as a Mix task.

Steps:

1. Create a Mix Task Module:

defmodule Mix.Tasks.MyCli do
  use Mix.Task

  @shortdoc "Runs the MyCLI application"

  def run(args) do
    MyCLI.execute(args)
  end
endcopy

2. Run the Task:

mix my_cli file copy --verbose source.txt dest.txt
copy

Additional Information

• Version and Description: By default, version/0 and description/0 callbacks fetch information from mix.exs and @moduledoc, respectively. You can override them if needed.
• Error Handling: Use the {:error, {code, reason}} tuple to return errors from handle_input/2. The application will exit with the specified code, and the reason will be printed.