Class List Method List File List

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

- - (Cri::Command) command readonly

  The built command.

## Instance Method Summary (collapse)

- - (void) aliases(*args)

  Sets the command aliases.

- - (void) be_hidden

  Marks the command as hidden.

- - (void) description(arg)

  Sets the command description.

- - (void) flag(short, long, desc, params = {}, &block) (also: #forbidden)

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

- - (CommandDSL) initialize(command = nil) constructor

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

- - (void) name(arg)

  Sets the command name.

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

  Adds a new option to the command.

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

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

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

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

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

  Sets the run block to the given block.

- - (void) runner(klass)

  Defines the runner class for this command.

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

  Adds a subcommand to the current command.

- - (void) summary(arg)

  Sets the command summary.

- - (void) usage(arg)

  Sets the command usage.

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

    16
    17
    18

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

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

## Instance Attribute Details

### - (`Cri::Command`) command (readonly)

Returns The built command

Returns:

- (`Cri::Command`) —

  The built command

    8
    9
    10

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

    def command
      @command
    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

    50
    51
    52

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

    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.

    88
    89
    90

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

    def be_hidden
      @command.hidden = true
    end

### - (`void`) description(arg)

This method returns an undefined value.

Sets the command description.

Parameters:

- arg (`String`) —

  The new command description

    68
    69
    70

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

    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

- :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 flag(short, long, desc, params = {}, &block)
      params = params.merge(:argument => :forbidden)
      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

    41
    42
    43

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

    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

- :hidden (`Boolean`) —

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

    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129

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

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

      if short.nil? && long.nil?
        fail 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,
        :hidden   => hidden,
      }
    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

- :hidden (`Boolean`) —

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

See Also:

- Cri::CommandDSL.{{#option}

    197
    198
    199
    200

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

    def optional(short, long, desc, params = {}, &block)
      params = params.merge(:argument => :optional)
      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

- :hidden (`Boolean`) —

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

See Also:

- Cri::CommandDSL.{{#option}

    150
    151
    152
    153

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

    def required(short, long, desc, params = {}, &block)
      params = params.merge(:argument => :required)
      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

    214
    215
    216
    217
    218
    219
    220
    221

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

    def run(&block)
      unless [2, 3].include?(block.arity)
        fail 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:

- klass (`Class<CommandRunner>`) —

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

    231
    232
    233
    234
    235

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

    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

    28
    29
    30
    31
    32
    33
    34

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

    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

    59
    60
    61

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

    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

    78
    79
    80

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

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