Module: Thor::Base::SharedOptionsConcern

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

Overview

Support for sharing Option declarations among many Command (methods). All class methods.

Class Method Summary collapse

Class Method Details

.find_shared_method_options(*names, groups: nil) ⇒ Hash<Symbol, Thor::SharedOption> Also known as: find_shared_options

Find shared options given names and groups.

Parameters:

  • names (*<Symbol>) —

    Individual shared option names to include.

  • groups: (nil | Symbol | Enumerable<Symbol>) (defaults to: nil) —

    Single or list of shared option groups to include.

Returns:

  • (Hash<Symbol, Thor::SharedOption>) —

    Hash mapping option names (as Symbol) to instances.



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/thor/base/shared_options_concern.rb', line 183

def find_shared_method_options *names, groups: nil
  groups_set = Set[*groups]
  
  shared_method_options.each_with_object( {} ) do |(name, option), results|
    match = {}
    
    if names.include? name
      match[:name] = true
    end
    
    match_groups = option.groups & groups_set
      
    unless match_groups.empty?
      match[:groups] = match_groups
    end
    
    unless match.empty?
      results[name] = {
        option: option,
        match: match,
      }
    end
  end
end

.include_method_options(*names, groups: nil) ⇒ Hash<Symbol, Thor::SharedOption> Also known as: include_options

Add the SharedOption instances with names and in groups to the next defined command method.

Parameters:

  • names (*<Symbol>) —

    Individual shared option names to include.

  • groups: (nil | Symbol | Enumerable<Symbol>) (defaults to: nil) —

    Single or list of shared option groups to include.

Returns:

  • (Hash<Symbol, Thor::SharedOption>) —

    Hash mapping option names (as Symbol) to instances.



217
218
219
220
221
222
 
# File 'lib/thor/base/shared_options_concern.rb', line 217

def include_method_options *names, groups: nil
  find_shared_method_options( *names, groups: groups ).
    each do |name, result|
      method_options[name] = Thor::IncludedOption.new **result
    end
end

.shared_method_option(name, **options) ⇒ Object Also known as: shared_option

Declare a shared method option with an optional groups that can then be added by name or group to commands.

The shared options can then be added to methods individually by name and collectively as groups with Thor.include_method_options.

Examples:

class MyCLI < Thor

  # Declare a shared option:
  shared_option :force,
    groups: :write,
    desc: "Force the operation",
    type: :boolean

  # ...

  desc            "write [OPTIONS] path",
                  "Write to a path"

  # Add the shared options to the method:
  include_options groups: :write

  def write       path

    # Get a slice of `#options` with any of the `:write` group options
    # that were provided and use it in a method call:
    MyModule.write path, **option_kwds( groups: :write )

  end
end

Parameters:

  • name (Symbol) —

    The name of the option.

  • options (**<Symbol, V>) —

    Keyword args used to initialize the SharedOption.

    All **options are optional.

Options Hash (**options):

  • :groups (Symbol | Array<Symbol>) —

    One or more shared option group that the new option will belong to.

    Examples:

    groups: :read
groups: [:read, :write]

    NOTE The keyword is groups with an s! Option already has

    a +group+ string attribute that, as far as I can tell, is only
  • :desc (String) —

    Description for the option for help and feedback.

  • :required (Boolean) —

    If the option is required or not.

  • :default (Object) —

    Default value for this argument.

    It cannot be required and have default values.

  • :aliases (String | Array<String>) —

    Aliases for this option.

    Examples:

    aliases: '-s'
aliases: '--other-name'
aliases: ['-s', '--other-name']
  • :type (:string | :hash | :array | :numeric | :boolean) —

    Type of acceptable values, see types for method options in the Thor wiki.

  • :banner (String) —

    String to show on usage notes.

  • :hide (Boolean) —

    If you want to hide this option from the help.



128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/thor/base/shared_options_concern.rb', line 128

def shared_method_option name, **options
  # Don't think the `:for` option makes sense... that would just be a
  # regular method option, right? I guess `:for` could be an array and
  # apply the option to each command, but it seems like that would just
  # be better as an extension to the {.method_option} behavior.
  # 
  # So, we raise if we see it
  if options.key? :for
    raise ArgumentError,
      ".shared_method_option does not accept the `:for` option"
  end
  
  build_shared_option(name, options)
end

.shared_method_options(options = nil) ⇒ Hash<Symbol, Thor::SharedOption] Get all shared options Also known as: shared_options

Returns Hash<Symbol, Thor::SharedOption] Get all shared options.

Returns:



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/thor/base/shared_options_concern.rb', line 149

def shared_method_options(options = nil)
  @shared_method_options ||= begin
    # Reach up the inheritance chain, if there's anyone there
    if superclass.respond_to? __method__
      superclass.send( __method__ ).dup
    else
      # Or just default to empty
      {}
    end
  end
  
  if options
    # We don't support this (yet at least)
    raise NotImplementedError,
      "Bulk set not supported, use .shared_method_option"
    # build_shared_options(options, @shared_method_options)
  end
  @shared_method_options
end