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.

Instance Method Summary (collapse)

Constructor Details

- (CommandDSL) initialize(command = nil)

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



15
16
17
# File 'lib/cri/command_dsl.rb', line 15

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

Instance Method Details

- (void) aliases(*args)

This method returns an undefined value.

Sets the command aliases.

Parameters:

  • args (String, Symbol, Array)

    The new command aliases



54
55
56
# File 'lib/cri/command_dsl.rb', line 54

def aliases(*args)
  @command.aliases = args.flatten.map { |a| a.to_s }
end

- (void) be_hidden

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.



92
93
94
# File 'lib/cri/command_dsl.rb', line 92

def be_hidden
  @command.hidden = true
end

- (Cri::Command) command

Returns The built command

Returns:



20
21
22
# File 'lib/cri/command_dsl.rb', line 20

def command
  @command
end

- (void) description(arg)

This method returns an undefined value.

Sets the command description.

Parameters:

  • arg (String)

    The new command description



72
73
74
# File 'lib/cri/command_dsl.rb', line 72

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

- (void) flag(short, long, desc, params = {}, &block) 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) (defaults to: {})

    a customizable set of options

Options Hash (params):

  • :multiple (Boolean)

    Whether or not the option should be multi-valued

See Also:

  • Cri::CommandDSL.{{#option}


166
167
168
169
# File 'lib/cri/command_dsl.rb', line 166

def flag(short, long, desc, params={}, &block)
  params = params.merge(:argument => :forbidden)
  self.option(short, long, desc, params, &block)
end

- (void) name(arg)

This method returns an undefined value.

Sets the command name.

Parameters:

  • arg (String)

    The new command name



45
46
47
# File 'lib/cri/command_dsl.rb', line 45

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

- (void) option(short, long, desc, params = {}, &block) 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) (defaults to: {})

    a customizable set of options

Options Hash (params):

  • :argument (:forbidden, :required, :optional)

    Whether the argument is forbidden, required or optional

  • :multiple (Boolean)

    Whether or not the option should be multi-valued



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
# File 'lib/cri/command_dsl.rb', line 112

def option(short, long, desc, params={}, &block)
  requiredness = params.fetch(:argument, :forbidden)
  multiple = params.fetch(:multiple, false)

  if short.nil? && long.nil?
    raise 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,
  }
end

- (void) optional(short, long, desc, params = {}, &block)

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) (defaults to: {})

    a customizable set of options

Options Hash (params):

  • :multiple (Boolean)

    Whether or not the option should be multi-valued

See Also:

  • Cri::CommandDSL.{{#option}


187
188
189
190
# File 'lib/cri/command_dsl.rb', line 187

def optional(short, long, desc, params={}, &block)
  params = params.merge(:argument => :optional)
  self.option(short, long, desc, params, &block)
end

- (void) required(short, long, desc, params = {}, &block)

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) (defaults to: {})

    a customizable set of options

Options Hash (params):

  • :multiple (Boolean)

    Whether or not the option should be multi-valued

See Also:

  • Cri::CommandDSL.{{#option}


146
147
148
149
# File 'lib/cri/command_dsl.rb', line 146

def required(short, long, desc, params={}, &block)
  params = params.merge(:argument => :required)
  self.option(short, long, desc, params, &block)
end

- (void) run {|opts, args| ... }

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



204
205
206
207
208
209
210
211
# File 'lib/cri/command_dsl.rb', line 204

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

- (void) runner(klass)

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:



221
222
223
224
225
# File 'lib/cri/command_dsl.rb', line 221

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

- (void) subcommand(command = nil, &block)

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



32
33
34
35
36
37
38
# File 'lib/cri/command_dsl.rb', line 32

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

  @command.add_command(command)
end

- (void) summary(arg)

This method returns an undefined value.

Sets the command summary.

Parameters:

  • arg (String)

    The new command summary



63
64
65
# File 'lib/cri/command_dsl.rb', line 63

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

- (void) usage(arg)

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



82
83
84
# File 'lib/cri/command_dsl.rb', line 82

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