Cuprum::Cli

Cuprum::Cli is a command-line utility powered by Cuprum that provides tools and utilities for defining command-line tools. It allows developers to define custom CLI commands and register them with integrated command line tools such as Thor.

• Documentation
• Getting Started
• Reference

Documentation

This is the documentation for the current development build of Cuprum::Cli.

• For previous releases, see the Versions page.

Back to Top

Getting Started

Add the gem to your Gemfile or gemspec:

group :development, :test do
  gem 'cuprum-cli'
end

To ensure that dependent libraries are loaded, call the Cuprum::Cli initializer:

• In the initializer for your project:

  module Space
    @initializer = SleepingKingStudios::Tools::Toolbox::Initializer.new do
      Cuprum::Cli.initializer.call
    end
  end
  

• Or, in the entry points of your application (such as a bin script or spec_helper.rb).

Set up a CLI integration and register your commands:

# In tasks.thor:
require 'cuprum/cli/integrations/thor/registry'

Cuprum::Cli.initializer.call

registry = Cuprum::Cli::Integrations::Thor::Registry.new

registry.register Cuprum::Cli::Commands::Ci::RSpecCommand
registry.register Cuprum::Cli::Commands::Ci::RSpecCommand,
  full_name:   'ci:rspec:sinatra4',
  description: 'Runs the RSpec tests against Sinatra 4.X',
  options:     { gemfile: 'gemfiles/sinatra_4.gemfile' }

Finally, you can call the commands from your CLI tool:

% bundle exec thor list
ci
--
thor ci:rspec ...FILE_PATTERNS       # Runs an RSpec command.
thor ci:rspec:sinatra4 ...FILE_PATTERNS  # Runs the RSpec tests against Sinatra 4.X

Defining Commands

You can also define custom CLI commands using the Cuprum::Cli::Command class. Cuprum::Cli defines a powerful DSL for quickly defining and configuring commands.

class PingCommand < Cuprum::Cli::Command
  dependency :system_command

  argument :service_url,
    default:     'www.example.com',
    description: 'The URL of the remote service',
    type:        String

  option :interval,
    aliases:     'i',
    default:     0.1,
    description: 'The interval between pings',
    type:        Float

  option :max_count,
    aliases:     %w[c],
    default:     5,
    description: 'The total number of pings sent to the server',
    type:        Integer

  private

  def format_options
    # The ping command uses a non-standard options format.
    options = +''

    options << "-c#{max_count}"
    options << "-i#{interval}"
    options << '-q' # Only display the summary line.
  end

  def process
    system_command.capture(
      'ping',
      arguments: [format_options, service_url]
    )
  end
end

Now that we’ve defined a custom command, we can register it in our CLI integration:

registry.register PingCommand
registry.register PingCommand,
  full_name: 'ping:github',
  options:   { service_url: 'github.com' }

For more information on defining commands, see the commands documentation.

Back to Top

Reference

The core component in Cuprum::Cli is the Command.

• Commands
  A command defines an action or sequence of actions that can be called from the command line.
  • Arguments
    Commands can accept positional arguments from the command line, such as file names.
  • Options
    Commands can accept flags or keyword options from the command line.
• Command Dependencies
  Cuprum::Cli commands use dependencies to interact with external functions in a consistent and testable fashion. Defined dependencies include reading from and writing to the file system, interacting with the standard IO streams, and calling system commands.

Built-In Commands

Cuprum::Cli provides some pre-defined commands for building CLI applications and tools.

• CI Commands
  Commands for testing your application.
  • RSpec Command
    A command for running RSpec tests, with configurable options including format, environment and custom gemfile.
  • RSpec Each Command
    A command for running each RSpec spec file as an isolated test. Useful for identifying missing require statements or other dependencies that would not be surfaced when running the entire test suite.
• File Commands
  Commands for managing your application's files.
  • New File Command
    A command for generating a new source file or files based on defined templates. Automatically handles intermediate directories and supports multiple file generation (such as spec files or view component templates).

Integrations

Once a command is defined, Cuprum::Cli integrates with an external CLI provider to call the command from the command line.

• Integrations
  Third-party tools that Cuprum::Cli can use to call commands from the command line.
  • Thor
    Using Cuprum::Cli commands with the Thor toolkit.

For a full list of defined classes and objects, see Reference.

Back to Top