# Class: Cri::CommandDSL

Inherits:
  Object
  - Object
  - Cri::CommandDSL
  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

- #command ⇒ Cri::Command readonly

  The built command.

## Instance Method Summary collapse

- #aliases(*args) ⇒ void

  Sets the command aliases.

- #be_hidden ⇒ void

  Marks the command as hidden.

- #default_subcommand(name) ⇒ void

  Sets the name of the default subcommand, i.e.

- #description(arg) ⇒ void

  Sets the command description.

- #flag(short, long, desc, **params, &block) ⇒ void (also: #forbidden)

  Adds a new option with a forbidden argument to the command.

- #initialize(command = nil) ⇒ CommandDSL constructor

  Creates a new DSL, intended to be used for building a single command.

- #name(arg) ⇒ void

  Sets the command name.

- #no_params ⇒ Object
- #option(short, long, desc, argument: :forbidden, multiple: false, hidden: false, default: nil, transform: nil, &block) ⇒ void (also: #opt)

  Adds a new option to the command.

- #optional(short, long, desc, **params, &block) ⇒ void deprecated Deprecated.
- #param(name, transform: nil) ⇒ Object

  Defines a new parameter for the command.

- #required(short, long, desc, **params, &block) ⇒ void deprecated Deprecated.
- #run {|opts, args| ... } ⇒ void

  Sets the run block to the given block.

- #runner(klass) ⇒ void

  Defines the runner class for this command.

- #skip_option_parsing ⇒ void

  Skips option parsing for the command.

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

  Adds a subcommand to the current command.

- #summary(arg) ⇒ void

  Sets the command summary.

- #usage(arg) ⇒ void

  Sets the command usage.

## 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:

- (`Cri::Command`) —

  The built command

    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:

- #option

    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:

- #option

    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:

- #option

    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:

- klass (`Class<CommandRunner>`) —

  The command runner class (subclass of Cri::CommandRunner) that is used for executing this command.

    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