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

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

- #option(short, long, desc, params = {}, &block) ⇒ void (also: #opt)

  Adds a new option to the command.

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

  Adds a new option with an optional argument to the command.

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

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

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

    14
    15
    16

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

    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

    6
    7
    8

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

    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

    59
    60
    61

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

    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.

    97
    98
    99

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

    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

    41
    42
    43

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

    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

    77
    78
    79

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

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

  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:

- Cri::CommandDSL.{{#option}

    196
    197
    198
    199

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

    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

    50
    51
    52

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

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

### #option(short, long, desc, params = {}, &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`) (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

- :hidden (`Boolean`) —

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

    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152

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

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

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

      if default && requiredness == :forbidden
        raise ArgumentError, 'a default value cannot be specified for flag options'
      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,
        default: default,
      }
    end

### #optional(short, long, desc, params = {}, &block) ⇒ `void`

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

- :hidden (`Boolean`) —

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

See Also:

- Cri::CommandDSL.{{#option}

    220
    221
    222
    223

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

    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) ⇒ `void`

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

- :hidden (`Boolean`) —

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

See Also:

- Cri::CommandDSL.{{#option}

    173
    174
    175
    176

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

    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

    237
    238
    239
    240
    241
    242
    243
    244

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

    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.

    254
    255
    256
    257
    258

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

    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 OptionParser validation.

    105
    106
    107

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

    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

    26
    27
    28
    29
    30
    31
    32

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

    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

    68
    69
    70

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

    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

    87
    88
    89

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

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