Module: Thor::Base::ArgumentsConcern

Extended by:
ActiveSupport::Concern
Defined in:
lib/thor/base/arguments_concern.rb

Overview

TODO:

document Arguments module.

Class-Level Argument Class Methods collapse

Method-Specific Argument Class Methods collapse

Class Method Summary collapse

Class Method Details

.arguments(command: nil) ⇒ Object 



49
50
51
 
# File 'lib/thor/base/arguments_concern.rb', line 49

def arguments command: nil
  [*class_arguments, *command&.arguments]
end

.build_argument(name, options, scope) ⇒ Object (protected) 



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/thor/base/arguments_concern.rb', line 57

def build_argument name, options, scope
  name = name.to_s

  is_thor_reserved_word? name, :argument
  no_commands { attr_accessor name }

  required = if options.key?(:optional)
    !options[:optional]
  elsif options.key?(:required)
    options[:required]
  else
    # If neither `:required` or `:optional` options were provided,
    # default to the argument being required if no `:default` was provided.
    options[:default].nil?
  end

  scope.delete_if { |argument| argument.name == name }

  if required
    scope.each do |argument|
      next if argument.required?
      raise ArgumentError,
        "You cannot have #{ name.inspect } as required argument " \
        "after the non-required argument #{ argument.human_name.inspect }."
    end
  end

  options[:required] = required

  scope << Thor::Argument.new( name, options )
end

.class_argument(name, **options) ⇒ Object

Note:

This used to just be called ‘.argument`, and apparently arguments were class-level only. I don’t know why.

Atli switches them to mirror options, with class and command levels.

Adds an argument to the class and creates an attr_accessor for it.

Arguments are different from options in several aspects. The first one is how they are parsed from the command line, arguments are retrieved from position:

thor command NAME

Instead of:

thor command --name=NAME

Besides, arguments are used inside your code as an accessor (self.argument), while options are all kept in a hash (self.options).

Finally, arguments cannot have type :default or :boolean but can be optional (supplying :optional => :true or :required => false), although you cannot have a required argument after a non-required argument. If you try it, an error is raised.

Parameters:

  • name (String | Symbol) —

    The name of the argument.

  • options (Hash)

Options Hash (**options):

  • :desc (String) —

    Description for the argument.

  • :required (Boolean) —

    If the argument is required or not (opposite of ‘:optional`).

  • :optional (Boolean) —

    If the argument is optional or not (opposite of ‘:required`).

  • :type (:string | :hash | :array | :numeric) —

    The type of the argument.

  • :default (Object) —

    Default value for this argument. It cannot be required and have default values.

  • :banner (String) —

    String to show on usage notes.

Raises:

  • (ArgumentError) —

    Raised if you supply a required argument after a non-required one.



168
169
170
 
# File 'lib/thor/base/arguments_concern.rb', line 168

def class_argument name, **options
  build_argument name, options, class_arguments
end

.class_arguments ⇒ Array<Thor::Argument>

Returns this class’ class-level arguments, looking up in the ancestors chain.

Returns:



108
109
110
 
# File 'lib/thor/base/arguments_concern.rb', line 108

def class_arguments
  @class_arguments ||= from_superclass( :class_arguments, [] )
end

.method_argument(name, **options) ⇒ Object Also known as: argument, arg

Note:

This used to just be called ‘.argument`, and apparently arguments were class-level only. I don’t know why.

Atli switches them to mirror options, with class and command levels.

Adds an argument to the class and creates an attr_accessor for it.

Arguments are different from options in several aspects. The first one is how they are parsed from the command line, arguments are retrieved from position:

thor command NAME

Instead of:

thor command --name=NAME

Besides, arguments are used inside your code as an accessor (self.argument), while options are all kept in a hash (self.options).

Finally, arguments cannot have type :default or :boolean but can be optional (supplying :optional => :true or :required => false), although you cannot have a required argument after a non-required argument. If you try it, an error is raised.

Parameters:

  • name (String | Symbol) —

    The name of the argument.

  • options (Hash)

Options Hash (**options):

  • :desc (String) —

    Description for the argument.

  • :required (Boolean) —

    If the argument is required or not (opposite of ‘:optional`).

  • :optional (Boolean) —

    If the argument is optional or not (opposite of ‘:required`).

  • :type (:string | :hash | :array | :numeric) —

    The type of the argument.

  • :default (Object) —

    Default value for this argument. It cannot be required and have default values.

  • :banner (String) —

    String to show on usage notes.

Raises:

  • (ArgumentError) —

    Raised if you supply a required argument after a non-required one.



263
264
265
 
# File 'lib/thor/base/arguments_concern.rb', line 263

def method_argument name, **options
  build_argument( name, options, method_arguments )
end

.method_arguments ⇒ Array<Thor::Argument>

Returns this class’ class-level arguments, looking up in the ancestors chain.

Returns:



203
204
205
 
# File 'lib/thor/base/arguments_concern.rb', line 203

def method_arguments
  @method_arguments ||= []
end

.remove_argument_from(*names, scope:, undefine: false) ⇒ Object (protected) 



90
91
92
93
94
95
 
# File 'lib/thor/base/arguments_concern.rb', line 90

def remove_argument_from *names, scope:, undefine: false
  names.each do |name|
    scope.delete_if { |a| a.name == name.to_s }
    undef_method name, "#{name}=" if undefine
  end
end

.remove_class_argument(*names, undefine: false) ⇒ Object

Removes a previous defined class-level argument. If ‘:undefine` option is given, un-defines accessors as well.

Examples:

remove_class_argument :foo
remove_class_argument :foo, :bar, :baz, :undefine => true

Parameters:

  • *names (Array<String | Symbol>) —

    Arguments to be removed

  • undefine: (Boolean) (defaults to: false) —

    Un-defines the arguments’ setter methods as well.



188
189
190
 
# File 'lib/thor/base/arguments_concern.rb', line 188

def remove_class_argument *names, undefine: false
  remove_argument_from *names, scope: class_arguments, undefine: undefine
end

.remove_method_argument(*names, undefine: false) ⇒ Object

Removes a previous defined class-level argument. If ‘:undefine` option is given, un-defines accessors as well.

Examples:


remove_argument :foo remove_argument :foo, :bar, :baz, :undefine => true

Parameters:

  • *names (Array<String | Symbol>) —

    Arguments to be removed

  • undefine: (Boolean) (defaults to: false) —

    Un-defines the arguments’ setter methods as well.



284
285
286
 
# File 'lib/thor/base/arguments_concern.rb', line 284

def remove_method_argument *names, undefine: false
  remove_argument_from *names, scope: method_arguments, undefine: undefine
end