class Cri::CommandDSL

The command DSL is a class that is used for building and modifying commands.

Attributes

command[R]

@return [Cri::Command] The built command

Public Class Methods

new(command = nil) click to toggle source

Creates a new DSL, intended to be used for building a single command. A {CommandDSL} instance is not reusable; create a new instance if you want to build another command.

@param [Cri::Command, nil] command The command to modify, or nil if a

new command should be created
# File lib/cri/command_dsl.rb, line 15
def initialize(command = nil)
  @command = command || Cri::Command.new
end

Public Instance Methods

aliases(*args) click to toggle source

Sets the command aliases.

@param [String, Symbol, Array] args The new command aliases

@return [void]

# File lib/cri/command_dsl.rb, line 49
def aliases(*args)
  @command.aliases = args.flatten.map { |a| a.to_s }
end
be_hidden() click to toggle source

Marks the command as hidden. Hidden commands do not show up in the list of subcommands of the parent command, unless –verbose is passed (or `:verbose => true` is passed to the {Cri::Command#help} method). This can be used to mark commands as deprecated.

@return [void]

# File lib/cri/command_dsl.rb, line 87
def be_hidden
  @command.hidden = true
end
description(arg) click to toggle source

Sets the command description.

@param [String] arg The new command description

@return [void]

# File lib/cri/command_dsl.rb, line 67
def description(arg)
  @command.description = arg
end
flag(short, long, desc, params = {}, &block) click to toggle source

Adds a new option with a forbidden argument to the command. If a block is given, it will be executed when the option is successfully parsed.

@param [String, Symbol, nil] short The short option name

@param [String, Symbol, nil] long The long option name

@param [String] desc The option description

@option params [Boolean] :multiple Whether or not the option should

be multi-valued

@option params [Boolean] :hidden Whether or not the option should

be printed in the help output

@return [void]

@see {#option}

# File lib/cri/command_dsl.rb, line 172
def flag(short, long, desc, params = {}, &block)
  params = params.merge(:argument => :forbidden)
  option(short, long, desc, params, &block)
end
Also aliased as: forbidden
forbidden(short, long, desc, params = {}, &block)
Alias for: flag
name(arg) click to toggle source

Sets the command name.

@param [String] arg The new command name

@return [void]

# File lib/cri/command_dsl.rb, line 40
def name(arg)
  @command.name = arg
end
opt(short, long, desc, params = {}, &block)
Alias for: option
option(short, long, desc, params = {}, &block) click to toggle source

Adds a new option to the command. If a block is given, it will be executed when the option is successfully parsed.

@param [String, Symbol, nil] short The short option name

@param [String, Symbol, nil] long The long option name

@param [String] desc The option description

@option params [:forbidden, :required, :optional] :argument Whether the

argument is forbidden, required or optional

@option params [Boolean] :multiple Whether or not the option should

be multi-valued

@option params [Boolean] :hidden Whether or not the option should

be printed in the help output

@return [void]

# File lib/cri/command_dsl.rb, line 110
def option(short, long, desc, params = {}, &block)
  requiredness = params.fetch(:argument, :forbidden)
  multiple = params.fetch(:multiple, false)
  hidden = params.fetch(:hidden, false)

  if short.nil? && long.nil?
    fail ArgumentError, 'short and long options cannot both be nil'
  end

  @command.option_definitions << {
    :short    => short.nil? ? nil : short.to_s,
    :long     => long.nil? ? nil : long.to_s,
    :desc     => desc,
    :argument => requiredness,
    :multiple => multiple,
    :block    => block,
    :hidden   => hidden,
  }
end
Also aliased as: opt
optional(short, long, desc, params = {}, &block) click to toggle source

Adds a new option with an optional argument to the command. If a block is given, it will be executed when the option is successfully parsed.

@param [String, Symbol, nil] short The short option name

@param [String, Symbol, nil] long The long option name

@param [String] desc The option description

@option params [Boolean] :multiple Whether or not the option should

be multi-valued

@option params [Boolean] :hidden Whether or not the option should

be printed in the help output

@return [void]

@see {#option}

# File lib/cri/command_dsl.rb, line 196
def optional(short, long, desc, params = {}, &block)
  params = params.merge(:argument => :optional)
  option(short, long, desc, params, &block)
end
required(short, long, desc, params = {}, &block) click to toggle source

Adds a new option with a required argument to the command. If a block is given, it will be executed when the option is successfully parsed.

@param [String, Symbol, nil] short The short option name

@param [String, Symbol, nil] long The long option name

@param [String] desc The option description

@option params [Boolean] :multiple Whether or not the option should

be multi-valued

@option params [Boolean] :hidden Whether or not the option should

be printed in the help output

@return [void]

@see {#option}

# File lib/cri/command_dsl.rb, line 149
def required(short, long, desc, params = {}, &block)
  params = params.merge(:argument => :required)
  option(short, long, desc, params, &block)
end
run(&block) click to toggle source

Sets the run block to the given block. The given block should have two or three arguments (options, arguments, and optionally the command). Calling this will override existing run block or runner declarations (using {#run} and {#runner}, respectively).

@yieldparam [Hash<Symbol,Object>] opts A map of option names, as defined

in the option definitions, onto strings (when single-valued) or arrays
(when multi-valued)

@yieldparam [Array<String>] args A list of arguments

@return [void]

# File lib/cri/command_dsl.rb, line 213
def run(&block)
  unless [2, 3].include?(block.arity)
    fail ArgumentError,
         'The block given to Cri::Command#run expects two or three args'
  end

  @command.block = block
end
runner(klass) click to toggle source

Defines the runner class for this command. Calling this will override existing run block or runner declarations (using {#run} and {#runner}, respectively).

@param [Class<CommandRunner>] klass The command runner class (subclass

of {CommandRunner}) that is used for executing this command.

@return [void]

# File lib/cri/command_dsl.rb, line 230
def runner(klass)
  run do |opts, args, cmd|
    klass.new(opts, args, cmd).call
  end
end
subcommand(command = nil, &block) click to toggle source

Adds a subcommand to the current command. The command can either be given explicitly, or a block can be given that defines the command.

@param [Cri::Command, nil] command The command to add as a subcommand,

or nil if the block should be used to define the command that will be
added as a subcommand

@return [void]

# File lib/cri/command_dsl.rb, line 27
def subcommand(command = nil, &block)
  if command.nil?
    command = Cri::Command.define(&block)
  end

  @command.add_command(command)
end
summary(arg) click to toggle source

Sets the command summary.

@param [String] arg The new command summary

@return [void]

# File lib/cri/command_dsl.rb, line 58
def summary(arg)
  @command.summary = arg
end
usage(arg) click to toggle source

Sets the command usage. The usage should not include the “usage:” prefix, nor should it include the command names of the supercommand.

@param [String] arg The new command usage

@return [void]

# File lib/cri/command_dsl.rb, line 77
def usage(arg)
  @command.usage = arg
end