Clicr

Command Line Interface for Crystal

A simple Command line interface builder which aims to be easy to use.

Installation

Add this block to your application's shard.yml:

dependencies:
  clicr:
    github: j8r/clicr

Usage

This shard consists to one single macro Clicr.create, that expands to recursive while loops and case conditions.

All the CLI, including errors, can be translated in the language of choice, look at the parameters at src/clir.cr.

All the configurations are done in a NamedTuple like follow:

Simple example

require "clicr"

Clicr.create(
  name: "myapp",
  info: "Myapp can do everything",
  commands: {
    talk: {
      alias: 't',
      info: "Talk",
      action: "say",
      arguments: %w(directory),
    },
  },
   variables: {
     name: {
       info: "Your name",
       default: "foo",
     },
   },
   options: {
     yes: {
       short: 'y',
       info: "Print the name",
     }
   }
)

def say(directory, name, yes)
  if yes
    puts "yes, #{name} in #{directory}"
  else
    puts "no, #{name} in #{directory}"
  end
end

Example of commands:

$ myapp --help
Usage: myapp DIRECTORY [VARIABLES] [OPTIONS]

Myapp can do everything

Options:
  -y, --yes      Print the name

Variables:
  name=foo       Your name

Commands:
  t, talk        Talk

'myapp --help' to show the help

$ myapp talk /tmp name=bar
no, bar in /tmp

$ myapp talk home name=bar -y
yes, bar in home

$ myapp talk test
no, foo in test

Advanced example

There can have subcommands that have subcommands indefinitely with their options/variables.

Other parameters can be customized like names of sections, the help_option and unknown errors messages:

ARGV.replace %w(talk -j forename=Jack to_me)

Clicr.create(
  name: "myapp",
  info: "Application default description",
  usage_name: "Usage",
  commands_name: "Commands",
  options_name: "Options",
  variables_name: "Variables",
  help: "to show the help",
  help_option: "help",
  argument_required: "requires at least one argument",
  unknown_option: "Unknown option",
  unknown_command_variable: "Unknown command or variable",
  commands: {
    talk: {
      alias: 't',
      info: "Talk",
      options: {
        joking: {
          short: 'j',
          info: "Joke tone"
        }
      },
      variables: {
        forename: {
          default: "Foo",
          info: "Specify your forename",
        },
        surname: {
          default: "Bar",
          info: "Specify your surname",
        },
      },
      commands: {
        to_me: {
          info: "Hey that's me!",
          action: "tell",
        },
      }
    }
  }
)


def tell(forename, surname, joking)
  if joking
     puts "Yo my best #{forename} #{surname} friend!"
  else
    puts "Hello #{forename} #{surname}."
  end
end

Result: Yo my best Jack Bar friend!

Reference

Commands

Example: s, start

commands: {
  start: {
    alias: 's',
    info: "Starts the server",
    action: "say",
  }
}

alias creates an alias of the command. The alias mustn't already exist

Arguments

Example: name, directory

arguments: %w(directory names...),

list arguments required after the command in the following order
when arguments are specified, they becomes mandatory
if an argument name ends with ..., it isn't mandatory and have a default empty Array(String) value. All following arguments will be appended to it.

Options

Example: -y, --yes

options: {
  yes: {
    short: 'y',
    info: "No confirmations",
  }
}

apply recursively to subcommands
short creates a short alias of one character - must be a Char
concatenating single characters arguments like -Ry1 is possible

Special case, the help_option, which is set to "help" with the options -h, --help by default

Shows the help of the current (sub)command
has the priority over every other arguments including other options, commands and variables

Variables

Example: name=foo

variables: {
  name: {
    info: "This is your name",
    default: "Foobar",
  }
}

apply recursively to subcommands
can only be String (because arguments passed as ARGV are Array(String)) - if others type are needed, the cast must be done after the action method call
if no default value is set, nil will be the default one

Error handling

When the command issued can't be performed, an exception is raised. The cause can correspond to either help, argument_required, unknown_option or unknown_command_variable.

You can catch the exception's causes like this:

begin
  Clicr.create(
  ...
  )
rescue ex
  case ex.cause.to_s
  when "help" then puts ex; exit 0
  when "argument_required", "unknown_option", "unknown_command_variable" then abort ex
  else abort ex
  end
end

CrystalDoc.info

clicr