Class: Cri::CommandDSL

Inherits:
Object
  • Object
show all
Defined in:
lib/cri/command_dsl.rb

Overview

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

Defined Under Namespace

Classes: AlreadySpecifiedAsNoParams, AlreadySpecifiedWithParams

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(command = nil) ⇒ CommandDSL

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

Parameters:

  • command (Cri::Command, nil) (defaults to: nil) —

    The command to modify, or nil if a new command should be created



32
33
34
 
# File 'lib/cri/command_dsl.rb', line 32

def initialize(command = nil)
  @command = command || Cri::Command.new
end

Instance Attribute Details

#command ⇒ Cri::Command (readonly)

Returns The built command.

Returns:



24
25
26
 
# File 'lib/cri/command_dsl.rb', line 24

def command
  @command
end

Instance Method Details

#aliases(*args) ⇒ void

This method returns an undefined value.

Sets the command aliases.

Parameters:

  • args (String, Symbol, Array) —

    The new command aliases



77
78
79
 
# File 'lib/cri/command_dsl.rb', line 77

def aliases(*args)
  @command.aliases = args.flatten.map(&:to_s)
end

#be_hidden ⇒ void

This method returns an undefined value.

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.



115
116
117
 
# File 'lib/cri/command_dsl.rb', line 115

def be_hidden
  @command.hidden = true
end

#default_subcommand(name) ⇒ void

This method returns an undefined value.

Sets the name of the default subcommand, i.e. the subcommand that will be executed if no subcommand is explicitly specified. This is ‘nil` by default, and will typically only be set for the root command.

Parameters:

  • name (String, nil) —

    The name of the default subcommand



59
60
61
 
# File 'lib/cri/command_dsl.rb', line 59

def default_subcommand(name)
  @command.default_subcommand_name = name
end

#description(arg) ⇒ void

This method returns an undefined value.

Sets the command description.

Parameters:

  • arg (String) —

    The new command description



95
96
97
 
# File 'lib/cri/command_dsl.rb', line 95

def description(arg)
  @command.description = arg
end

#flag(short, long, desc, **params, &block) ⇒ void Also known as: forbidden

This method returns an undefined value.

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.

Parameters:

  • short (String, Symbol, nil) —

    The short option name

  • long (String, Symbol, nil) —

    The long option name

  • desc (String) —

    The option description

  • params (Hash) —

    a customizable set of options

Options Hash (**params):

  • :multiple (Boolean) —

    Whether or not the option should be multi-valued

  • :hidden (Boolean) —

    Whether or not the option should be printed in the help output

See Also:



232
233
234
235
 
# File 'lib/cri/command_dsl.rb', line 232

def flag(short, long, desc, **params, &block)
  params = params.merge(argument: :forbidden)
  option(short, long, desc, **params, &block)
end

#name(arg) ⇒ void

This method returns an undefined value.

Sets the command name.

Parameters:

  • arg (String) —

    The new command name



68
69
70
 
# File 'lib/cri/command_dsl.rb', line 68

def name(arg)
  @command.name = arg
end

#no_params ⇒ Object 



181
182
183
184
185
186
187
 
# File 'lib/cri/command_dsl.rb', line 181

def no_params
  if @command.parameter_definitions.any?
    raise AlreadySpecifiedWithParams.new(@command)
  end

  @command.explicitly_no_params = true
end

#option(short, long, desc, argument: :forbidden, multiple: false, hidden: false, default: nil, transform: nil, &block) ⇒ void Also known as: opt

This method returns an undefined value.

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

Parameters:

  • short (String, Symbol, nil) —

    The short option name

  • long (String, Symbol, nil) —

    The long option name

  • desc (String) —

    The option description

  • params (Hash) —

    a customizable set of options



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/cri/command_dsl.rb', line 146

def option(short, long, desc,
           argument: :forbidden,
           multiple: false,
           hidden: false,
           default: nil,
           transform: nil,
           &block)
  @command.option_definitions << Cri::OptionDefinition.new(
    short: short&.to_s,
    long: long&.to_s,
    desc: desc,
    argument: argument,
    multiple: multiple,
    hidden: hidden,
    default: default,
    transform: transform,
    block: block,
  )
end

#optional(short, long, desc, **params, &block) ⇒ void

Deprecated.

This method returns an undefined value.

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.

Parameters:

  • short (String, Symbol, nil) —

    The short option name

  • long (String, Symbol, nil) —

    The long option name

  • desc (String) —

    The option description

  • params (Hash) —

    a customizable set of options

Options Hash (**params):

  • :multiple (Boolean) —

    Whether or not the option should be multi-valued

  • :hidden (Boolean) —

    Whether or not the option should be printed in the help output

See Also:



258
259
260
261
 
# File 'lib/cri/command_dsl.rb', line 258

def optional(short, long, desc, **params, &block)
  params = params.merge(argument: :optional)
  option(short, long, desc, **params, &block)
end

#param(name, transform: nil) ⇒ Object

Defines a new parameter for the command.

Parameters:

  • name (Symbol) —

    The name of the parameter



170
171
172
173
174
175
176
177
178
179
 
# File 'lib/cri/command_dsl.rb', line 170

def param(name, transform: nil)
  if @command.explicitly_no_params?
    raise AlreadySpecifiedAsNoParams.new(name, @command)
  end

  @command.parameter_definitions << Cri::ParamDefinition.new(
    name: name,
    transform: transform,
  )
end

#required(short, long, desc, **params, &block) ⇒ void

Deprecated.

This method returns an undefined value.

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.

Parameters:

  • short (String, Symbol, nil) —

    The short option name

  • long (String, Symbol, nil) —

    The long option name

  • desc (String) —

    The option description

  • params (Hash) —

    a customizable set of options

Options Hash (**params):

  • :multiple (Boolean) —

    Whether or not the option should be multi-valued

  • :hidden (Boolean) —

    Whether or not the option should be printed in the help output

See Also:



209
210
211
212
 
# File 'lib/cri/command_dsl.rb', line 209

def required(short, long, desc, **params, &block)
  params = params.merge(argument: :required)
  option(short, long, desc, **params, &block)
end

#run {|opts, args| ... } ⇒ void

This method returns an undefined value.

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).

Yield Parameters:

  • opts (Hash<Symbol,Object>) —

    A map of option names, as defined in the option definitions, onto strings (when single-valued) or arrays (when multi-valued)

  • args (Array<String>) —

    A list of arguments



275
276
277
278
279
280
281
282
 
# File 'lib/cri/command_dsl.rb', line 275

def run(&block)
  unless [2, 3].include?(block.arity)
    raise ArgumentError,
          'The block given to Cri::Command#run expects two or three args'
  end

  @command.block = block
end

#runner(klass) ⇒ void

This method returns an undefined value.

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

Parameters:



292
293
294
295
296
 
# File 'lib/cri/command_dsl.rb', line 292

def runner(klass)
  run do |opts, args, cmd|
    klass.new(opts, args, cmd).call
  end
end

#skip_option_parsing ⇒ void

This method returns an undefined value.

Skips option parsing for the command. Allows option-like arguments to be passed in, avoiding the Parser validation.



123
124
125
 
# File 'lib/cri/command_dsl.rb', line 123

def skip_option_parsing
  @command.all_opts_as_args = true
end

#subcommand(command = nil, &block) ⇒ void

This method returns an undefined value.

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

Parameters:

  • command (Cri::Command, nil) (defaults to: nil) —

    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



44
45
46
47
48
49
50
 
# File 'lib/cri/command_dsl.rb', line 44

def subcommand(command = nil, &block)
  if command.nil?
    command = Cri::Command.define(&block)
  end

  @command.add_command(command)
end

#summary(arg) ⇒ void

This method returns an undefined value.

Sets the command summary.

Parameters:

  • arg (String) —

    The new command summary



86
87
88
 
# File 'lib/cri/command_dsl.rb', line 86

def summary(arg)
  @command.summary = arg
end

#usage(arg) ⇒ void

This method returns an undefined value.

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

Parameters:

  • arg (String) —

    The new command usage



105
106
107
 
# File 'lib/cri/command_dsl.rb', line 105

def usage(arg)
  @command.usage = arg
end