Class: Dry::CLI::Command

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/dry/cli/command.rb

Overview

Base class for commands

Since:

  • 0.1.0

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Class Method Details

.argument(name, options = {}) ⇒ Object

Specify an argument

Examples:

Optional argument

require "dry/cli"

class Hello < Dry::CLI::Command
  argument :name

  def call(name: nil, **)
    if name.nil?
      puts "Hello, stranger"
    else
      puts "Hello, #{name}"
    end
  end
end

# $ foo hello
#   Hello, stranger

# $ foo hello Luca
#   Hello, Luca

Required argument

require "dry/cli"

class Hello < Dry::CLI::Command
  argument :name, required: true

  def call(name:, **)
    puts "Hello, #{name}"
  end
end

# $ foo hello Luca
#   Hello, Luca

# $ foo hello
#   ERROR: "foo hello" was called with no arguments
#   Usage: "foo hello NAME"

Multiple arguments

require "dry/cli"

module Generate
  class Action < Dry::CLI::Command
    argument :app,    required: true
    argument :action, required: true

    def call(app:, action:, **)
      puts "Generating action: #{action} for app: #{app}"
    end
  end
end

# $ foo generate action web home
#   Generating action: home for app: web

# $ foo generate action
#   ERROR: "foo generate action" was called with no arguments
#   Usage: "foo generate action APP ACTION"

Description

require "dry/cli"

class Hello < Dry::CLI::Command
  argument :name, desc: "The name of the person to greet"

  def call(name: nil, **)
    # ...
  end
end

# $ foo hello --help
#   Command:
#     foo hello
#
#   Usage:
#     foo hello [NAME]
#
#   Arguments:
#     NAME                # The name of the person to greet
#
#   Options:
#     --help, -h          # Print this help

Parameters:

  • name (Symbol) —

    the argument name

  • options (Hash) (defaults to: {}) —

    a set of options

Since:

  • 0.1.0



197
198
199
200
201
202
203
204
 
# File 'lib/dry/cli/command.rb', line 197

def self.argument(name, options = {})
  new_arg = Argument.new(name, options)

  duplicate_index = @arguments.find_index { _1.name == new_arg.name }
  @arguments.delete_at(duplicate_index) unless duplicate_index.nil?

  @arguments << new_arg
end

.default_params ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.1.0



335
336
337
338
339
 
# File 'lib/dry/cli/command.rb', line 335

def self.default_params
  params.each_with_object({}) do |param, result|
    result[param.name] = param.default unless param.default.nil?
  end
end

.desc(description) ⇒ Object

Set the description of the command

Examples:

require "dry/cli"

class Echo < Dry::CLI::Command
  desc "Prints given input"

  def call(*)
    # ...
  end
end

Parameters:

  • description (String) —

    the description

Since:

  • 0.1.0



67
68
69
 
# File 'lib/dry/cli/command.rb', line 67

def self.desc(description)
  @description = description
end

.example(*examples) ⇒ Object

Describe the usage of the command

Examples:

require "dry/cli"

class Server < Dry::CLI::Command
  example [
    "                    # Basic usage (it uses the bundled server engine)",
    "--server=webrick    # Force `webrick` server engine",
    "--host=0.0.0.0      # Bind to a host",
    "--port=2306         # Bind to a port",
    "--no-code-reloading # Disable code reloading"
  ]

  def call(*)
    # ...
  end
end

# $ foo server --help
#   # ...
#
#   Examples:
#     foo server                     # Basic usage (it uses the bundled server engine)
#     foo server --server=webrick    # Force `webrick` server engine
#     foo server --host=0.0.0.0      # Bind to a host
#     foo server --port=2306         # Bind to a port
#     foo server --no-code-reloading # Disable code reloading

Parameters:

  • examples (Array<String>) —

    one or more examples

Since:

  • 0.1.0



103
104
105
 
# File 'lib/dry/cli/command.rb', line 103

def self.example(*examples)
  @examples += examples.flatten(1)
end

.inherited(base) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.1.0



14
15
16
17
18
19
20
21
22
23
24
25
 
# File 'lib/dry/cli/command.rb', line 14

def self.inherited(base)
  super
  base.class_eval do
    @_mutex       = Mutex.new
    @description  = nil
    @examples     = []
    @subcommands  = []
    @arguments = base.superclass_arguments || []
    @options = base.superclass_options || []
  end
  base.extend ClassMethods
end

.option(name, options = {}) ⇒ Object

Command line option (aka optional argument)

Examples:

Basic usage

require "dry/cli"

class Console < Dry::CLI::Command
  option :engine

  def call(engine: nil, **)
    puts "starting console (engine: #{engine || :irb})"
  end
end

# $ foo console
# starting console (engine: irb)

# $ foo console --engine=pry
# starting console (engine: pry)

List values

require "dry/cli"

class Console < Dry::CLI::Command
  option :engine, values: %w(irb pry ripl)

  def call(engine: nil, **)
    puts "starting console (engine: #{engine || :irb})"
  end
end

# $ foo console
# starting console (engine: irb)

# $ foo console --engine=pry
# starting console (engine: pry)

# $ foo console --engine=foo
# ERROR: Invalid param provided

Description

require "dry/cli"

class Console < Dry::CLI::Command
  option :engine, desc: "Force a console engine"

  def call(engine: nil, **)
    # ...
  end
end

# $ foo console --help
# # ...
#
# Options:
#   --engine=VALUE                  # Force a console engine: (irb/pry/ripl)
#   --help, -h                      # Print this help

Boolean

require "dry/cli"

class Server < Dry::CLI::Command
  option :code_reloading, type: :boolean, default: true

  def call(code_reloading:, **)
    puts "staring server (code reloading: #{code_reloading})"
  end
end

# $ foo server
# starting server (code reloading: true)

# $ foo server --no-code-reloading
# starting server (code reloading: false)

# $ foo server --help
# # ...
#
# Options:
#   --[no]-code-reloading

Aliases

require "dry/cli"

class Server < Dry::CLI::Command
  option :port, aliases: ["-p"]

  def call(options)
    puts "staring server (port: #{options.fetch(:port, 2300)})"
  end
end

# $ foo server
# starting server (port: 2300)

# $ foo server --port=2306
# starting server (port: 2306)

# $ foo server -p 2306
# starting server (port: 2306)

# $ foo server --help
# # ...
#
# Options:
#   --port=VALUE, -p VALUE

Parameters:

  • name (Symbol) —

    the param name

  • options (Hash) (defaults to: {}) —

    a set of options

Since:

  • 0.1.0



316
317
318
319
320
321
322
323
 
# File 'lib/dry/cli/command.rb', line 316

def self.option(name, options = {})
  new_op = Option.new(name, options)

  duplicate_index = @options.find_index { _1.name == new_op.name }
  @options.delete_at(duplicate_index) unless duplicate_index.nil?

  @options << new_op
end

.optional_arguments ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.1.0



349
350
351
 
# File 'lib/dry/cli/command.rb', line 349

def self.optional_arguments
  arguments.reject(&:required?)
end

.params ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.1.0



327
328
329
330
331
 
# File 'lib/dry/cli/command.rb', line 327

def self.params
  @_mutex.synchronize do
    (@arguments + @options).uniq
  end
end

.required_arguments ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.1.0



343
344
345
 
# File 'lib/dry/cli/command.rb', line 343

def self.required_arguments
  arguments.select(&:required?)
end

.subcommands ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.7.0



355
356
357
 
# File 'lib/dry/cli/command.rb', line 355

def self.subcommands
  subcommands
end

.superclass_arguments ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.7.0



369
370
371
 
# File 'lib/dry/cli/command.rb', line 369

def self.superclass_arguments
  superclass_variable_dup(:@arguments)
end

.superclass_options ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.7.0



375
376
377
 
# File 'lib/dry/cli/command.rb', line 375

def self.superclass_options
  superclass_variable_dup(:@options)
end

.superclass_variable_dup(var) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • 0.7.0



361
362
363
364
365
 
# File 'lib/dry/cli/command.rb', line 361

def self.superclass_variable_dup(var)
  if superclass.instance_variable_defined?(var)
    superclass.instance_variable_get(var).dup
  end
end