class Cri::CommandDSL
The command DSL is a class that is used for building and modifying commands.
Attributes
@return [Cri::Command] The built command
Public Class Methods
Creates a new DSL, intended to be used for building a single command. A {CommandDSL} instance is not reusable; create a new instance if you want to build another command.
@param [Cri::Command, nil] command The command to modify, or nil if a
new command should be created
# File lib/cri/command_dsl.rb, line 41 def initialize(command = nil) @command = command || Cri::Command.new end
Public Instance Methods
Sets the command aliases.
@param [String, Symbol, Array] args The new command aliases
@return [void]
# File lib/cri/command_dsl.rb, line 86 def aliases(*args) @command.aliases = args.flatten.map(&:to_s) end
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.
@param [String, nil] name The name of the default subcommand
@return [void]
# File lib/cri/command_dsl.rb, line 68 def default_subcommand(name) @command.default_subcommand_name = name end
Sets the command description.
@param [String] arg The new command description
@return [void]
# File lib/cri/command_dsl.rb, line 104 def description(arg) @command.description = arg end
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.
@param [String, Symbol, nil] short The short option name
@param [String, Symbol, nil] long The long option name
@param [String] desc The option description
@option params [Boolean] :multiple Whether or not the option should
be multi-valued
@option params [Boolean] :hidden Whether or not the option should
be printed in the help output
@return [void]
@see option
# 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
Sets the command name.
@param [String] arg The new command name
@return [void]
# File lib/cri/command_dsl.rb, line 77 def name(arg) @command.name = arg end
# 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
Adds a new option to the command. If a block is given, it will be executed when the option is successfully parsed.
@param [String, Symbol, nil] short The short option name
@param [String, Symbol, nil] long The long option name
@param [String] desc The option description
@option params [:forbidden, :required, :optional] :argument Whether the
argument is forbidden, required or optional
@option params [Boolean] :multiple Whether or not the option should
be multi-valued
@option params [Boolean] :hidden Whether or not the option should
be printed in the help output
@return [void]
# 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
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.
@param [String, Symbol, nil] short The short option name
@param [String, Symbol, nil] long The long option name
@param [String] desc The option description
@option params [Boolean] :multiple Whether or not the option should
be multi-valued
@option params [Boolean] :hidden Whether or not the option should
be printed in the help output
@return [void]
@deprecated
@see option
# 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
Defines a new parameter for the command.
@param [Symbol] name The name of the parameter
# 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
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.
@param [String, Symbol, nil] short The short option name
@param [String, Symbol, nil] long The long option name
@param [String] desc The option description
@option params [Boolean] :multiple Whether or not the option should
be multi-valued
@option params [Boolean] :hidden Whether or not the option should
be printed in the help output
@return [void]
@deprecated
@see option
# 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
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).
@yieldparam [Hash<Symbol,Object>] opts A map of option names, as defined
in the option definitions, onto strings (when single-valued) or arrays (when multi-valued)
@yieldparam [Array<String>] args A list of arguments
@return [void]
# 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
Defines the runner class for this command. Calling this will override existing run block or runner declarations (using {#run} and {#runner}, respectively).
@param [Class<CommandRunner>] klass The command runner class (subclass
of {CommandRunner}) that is used for executing this command.
@return [void]
# File lib/cri/command_dsl.rb, line 301 def runner(klass) run do |opts, args, cmd| klass.new(opts, args, cmd).call end end
Skips option parsing for the command. Allows option-like arguments to be passed in, avoiding the {Cri::Parser} validation.
@return [void]
# File lib/cri/command_dsl.rb, line 132 def skip_option_parsing @command.all_opts_as_args = true end
Adds a subcommand to the current command. The command can either be given explicitly, or a block can be given that defines the command.
@param [Cri::Command, nil] command 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
@return [void]
# 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
Sets the command summary.
@param [String] arg The new command summary
@return [void]
# File lib/cri/command_dsl.rb, line 95 def summary(arg) @command.summary = arg end
Sets the command usage. The usage should not include the “usage:” prefix, nor should it include the command names of the supercommand.
@param [String] arg The new command usage
@return [void]
# File lib/cri/command_dsl.rb, line 114 def usage(arg) @command.usage = arg end