# 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

    41
    42
    43

    # File 'lib/cri/command_dsl.rb', line 41

    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

    33
    34
    35

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

    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

    86
    87
    88

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

    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.

    124
    125
    126

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

    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

    68
    69
    70

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

    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

    104
    105
    106

    # File 'lib/cri/command_dsl.rb', line 104

    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

    241
    242
    243
    244

    # File 'lib/cri/command_dsl.rb', line 241

    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

    77
    78
    79

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

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

### #no_params ⇒ `Object`

    190
    191
    192
    193
    194
    195
    196

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

    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

    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173

    # File 'lib/cri/command_dsl.rb', line 155

    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

    267
    268
    269
    270

    # File 'lib/cri/command_dsl.rb', line 267

    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

    179
    180
    181
    182
    183
    184
    185
    186
    187
    188

    # File 'lib/cri/command_dsl.rb', line 179

    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

    218
    219
    220
    221

    # File 'lib/cri/command_dsl.rb', line 218

    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

    284
    285
    286
    287
    288
    289
    290
    291

    # File 'lib/cri/command_dsl.rb', line 284

    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.

    301
    302
    303
    304
    305

    # File 'lib/cri/command_dsl.rb', line 301

    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.

    132
    133
    134

    # File 'lib/cri/command_dsl.rb', line 132

    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

    53
    54
    55
    56
    57
    58
    59

    # File 'lib/cri/command_dsl.rb', line 53

    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

    95
    96
    97

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

    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

    114
    115
    116

    # File 'lib/cri/command_dsl.rb', line 114

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