atli 0.1.9 → 0.1.10

data/lib/thor/base.rb

@@ -12,7 +12,6 @@ require 'nrser'
 # -----------------------------------------------------------------------
 require "thor/command"
 require "thor/core_ext/hash_with_indifferent_access"
-require "thor/core_ext/ordered_hash"
 require "thor/error"
 require "thor/invocation"
 require "thor/parser"
@@ -21,6 +20,9 @@ require "thor/line_editor"
 require "thor/util"
 require 'thor/execution'
 require 'thor/base/class_methods'
+require 'thor/base/arguments_concern'
+require 'thor/base/shared_options_concern'
+require 'thor/base/shared_concern'
 
 
 # Refinements
@@ -48,8 +50,75 @@ class Thor
   # Shared base behavior included in {Thor} and {Thor::Group}.
   # 
   module Base
+    
+    # Module Methods
+    # ============================================================================
+    
+    # Hook called when {Thor::Base} is mixed in ({Thor} and {Thor::Group}).
+    # 
+    # Extends `base` with {Thor::Base::ClassMethods}, and includes
+    # {Thor::Invocation} and {Thor::Shell} in `base` as well.
+    # 
+    # @param [Module] base
+    #   Module (or Class) that included {Thor::Base}.
+    # 
+    # @return [void]
+    # 
+    def self.included base
+      base.extend ClassMethods
+      base.send :include, Invocation
+      base.send :include, Shell
+      base.send :include, ArgumentsConcern
+      base.send :include, SharedOptionsConcern
+      base.send :include, SharedConcern
+      
+      base.no_commands {
+        base.send :include, NRSER::Log::Mixin
+      }
+      
+    end
+
+    # Returns the classes that inherits from Thor or Thor::Group.
+    #
+    # ==== Returns
+    # Array[Class]
+    #
+    def self.subclasses
+      @subclasses ||= []
+    end
+
+    # Returns the files where the subclasses are kept.
+    #
+    # ==== Returns
+    # Hash[path<String> => Class]
+    #
+    def self.subclass_files
+      @subclass_files ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Whenever a class inherits from Thor or Thor::Group, we should track the
+    # class and the file on Thor::Base. This is the method responsible for it.
+    #
+    def self.register_klass_file(klass) #:nodoc:
+      file = caller[1].match(/(.*):\d+/)[1]
+      unless Thor::Base.subclasses.include?(klass)
+        Thor::Base.subclasses << klass
+      end
+
+      file_subclasses = Thor::Base.subclass_files[File.expand_path(file)]
+      file_subclasses << klass unless file_subclasses.include?(klass)
+    end
+
+    
+    # Attributes
+    # ========================================================================
+
     attr_accessor :options, :parent_options, :args
 
+
+    # Construction
+    # ========================================================================
+
     # It receives arguments in an Array and two hashes, one for options and
     # other for configuration.
     #
@@ -67,50 +136,92 @@ class Thor
     #
     # config<Hash>:: Configuration for this Thor class.
     #
-    def initialize(args = [], local_options = {}, config = {})
-      logger.debug "#{ self.class.name }#initialize",
-        args:           args,
-        local_options:  local_options
-      
-      parse_options = self.class.class_options
-
-      # The start method splits inbound arguments at the first argument
-      # that looks like an option (starts with - or --). It then calls
-      # new, passing in the two halves of the arguments Array as the
-      # first two parameters.
-
-      command_options = config.delete(:command_options) # hook for start
-      parse_options = parse_options.merge(command_options) if command_options
-      if local_options.is_a?(Array)
-        array_options = local_options
-        hash_options = {}
+    def initialize args = [], options_args_or_defaults = {}, config = {}
+      # Before {#initialize} is called arguments have been split out into
+      # either:
+      # 
+      # 1.  Positional `args` and args that need to be parsed for options.
+      # 
+      # 2.  Positional `args` and already parsed option values that we call
+      #     "defaults".
+
+      if options_args_or_defaults.is_a? Array
+        # Case (1)
+        # 
+        # The start method splits inbound arguments at the first argument
+        # that looks like an option (starts with - or --). It then calls
+        # new, passing in the two halves of the arguments Array as the
+        # first two parameters.
+        # 
+        # In this case the first Array stays as `args` and the second Array
+        # gets assigned to `args_to_parse_for_options` to be parsed for
+        # options:
+        # 
+        args_to_parse_for_options = options_args_or_defaults
+        option_defaults = {}
       else
+        # Case (2)
+        # 
         # Handle the case where the class was explicitly instantiated
         # with pre-parsed options.
-        array_options = []
-        hash_options = local_options
+        # 
+        args_to_parse_for_options = []
+        option_defaults = options_args_or_defaults
       end
 
-      # Let Thor::Options parse the options first, so it can remove
+      logger.debug "#{ self.class.name }#initialize",
+        args:                       args,
+        options_args_or_defaults:   options_args_or_defaults,
+        args_to_parse_for_options:  args_to_parse_for_options,
+        option_defaults:            option_defaults
+
+      # Let {Thor::Options} parse the options first, so it can remove
       # declared options from the array. This will leave us with
       # a list of arguments that weren't declared.
+
+      # Hash of {Thor::Option} that we can parse from the CLI args
+      # keyed by their {Thor::Option#name}.
+      # 
+      # @type [HashWithIndifferentAccess<String, Thor::Option>]
+      # 
+      options_to_parse_by_name = [
+        # Add class-level options
+        self.class.class_options,
+
+        # Options passed in by {Thor.dispatch} for the command to be
+        # invoked. May be `nil`, though I'm not totally sure when... in that
+        # case those options won't be parsed.
+        # 
+        # This was
+        # 
+        #     config.delete( :command_options ),
+        # 
+        # though I can't figure out why. Specs still pass without it..
+        # 
+        config[:command_options],
+      ].compact.reduce( HashWithIndifferentAccess.new, :merge! )
+
       stop_on_unknown = \
         self.class.stop_on_unknown_option? config[:current_command]
+      
       disable_required_check = \
         self.class.disable_required_check? config[:current_command]
+
+      logger.trace "Ready to create options",
+        options_to_parse_by_name:     options_to_parse_by_name,
+        option_defaults:              option_defaults,
+        stop_on_unknown:              stop_on_unknown,
+        disable_required_check:       disable_required_check,
+        args:                         args,
+        args_to_parse_for_options:    args_to_parse_for_options
       
-      logger.debug "Ready to create options",
-        array_options: array_options,
-        hash_options: hash_options,
-        stop_on_unknown: stop_on_unknown,
-        disable_required_check: disable_required_check
-      
-      opts = Thor::Options.new( parse_options,
-                                hash_options,
-                                stop_on_unknown,
-                                disable_required_check )
+      options_parser = Thor::Options.new \
+        options_to_parse_by_name,
+        option_defaults,
+        stop_on_unknown,
+        disable_required_check
       
-      self.options = opts.parse(array_options)
+      self.options = options_parser.parse args_to_parse_for_options
       
       if config[:class_options]
         self.options = config[:class_options].merge(options)
@@ -118,7 +229,9 @@ class Thor
 
       # If unknown options are disallowed, make sure that none of the
       # remaining arguments looks like an option.
-      opts.check_unknown! if self.class.check_unknown_options?(config)
+      if self.class.check_unknown_options? config
+        options_parser.check_unknown!
+      end
 
       # Add the remaining arguments from the options parser to the
       # arguments passed in to initialize. Then remove any positional
@@ -126,16 +239,26 @@ class Thor
       # by Thor::Group). Tis will leave us with the remaining
       # positional arguments.
       to_parse  = args
-      unless self.class.strict_args_position?(config)
-        to_parse += opts.remaining
+      unless self.class.strict_args_position? config
+        to_parse += options_parser.remaining
       end
 
-      thor_args = Thor::Arguments.new(self.class.arguments)
-      thor_args.parse(to_parse).each { |k, v| __send__("#{k}=", v) }
+      thor_args = Thor::Arguments.new [
+        *self.class.class_arguments,
+        *config[:current_command]&.arguments,
+      ]
+
+      # Set the arguments as instance variables.
+      thor_args.parse( to_parse ).each { |k, v| __send__ "#{k}=", v }
+
+      # Set whatever is left as args
       @args = thor_args.remaining
     end
     
     
+    # Instance Methods
+    # ========================================================================
+    
     protected
     # ========================================================================
       
@@ -202,60 +325,5 @@ class Thor
       
     # end protected
     
-    
-    # Module Methods
-    # ============================================================================
-    
-    # Hook called when {Thor::Base} is mixed in ({Thor} and {Thor::Group}).
-    # 
-    # Extends `base` with {Thor::Base::ClassMethods}, and includes
-    # {Thor::Invocation} and {Thor::Shell} in `base` as well.
-    # 
-    # @param [Module] base
-    #   Module (or Class) that included {Thor::Base}.
-    # 
-    # @return [void]
-    # 
-    def self.included base
-      base.extend ClassMethods
-      base.send :include, Invocation
-      base.send :include, Shell
-      
-      base.no_commands {
-        base.send :include, SemanticLogger::Loggable
-      }
-      
-    end
-
-    # Returns the classes that inherits from Thor or Thor::Group.
-    #
-    # ==== Returns
-    # Array[Class]
-    #
-    def self.subclasses
-      @subclasses ||= []
-    end
-
-    # Returns the files where the subclasses are kept.
-    #
-    # ==== Returns
-    # Hash[path<String> => Class]
-    #
-    def self.subclass_files
-      @subclass_files ||= Hash.new { |h, k| h[k] = [] }
-    end
-
-    # Whenever a class inherits from Thor or Thor::Group, we should track the
-    # class and the file on Thor::Base. This is the method responsible for it.
-    #
-    def self.register_klass_file(klass) #:nodoc:
-      file = caller[1].match(/(.*):\d+/)[1]
-      unless Thor::Base.subclasses.include?(klass)
-        Thor::Base.subclasses << klass
-      end
-
-      file_subclasses = Thor::Base.subclass_files[File.expand_path(file)]
-      file_subclasses << klass unless file_subclasses.include?(klass)
-    end
   end # module Base
 end # class Thor

data/lib/thor/base/arguments_concern.rb

@@ -0,0 +1,298 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+##############################################################################
+# Support for {Thor::Argument} in {Thor::Base} Classes
+# ============================================================================
+# 
+# With this file I've started to split the "Thor classes" stuff out by feature
+# to make things easier to find and keep the files shorter.
+# 
+##############################################################################
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+require 'active_support/concern'
+
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+# Namespace
+# =======================================================================
+
+class   Thor
+module  Base
+
+# Definitions
+# =======================================================================
+
+
+# @todo document Arguments module.
+# 
+module ArgumentsConcern
+  extend ActiveSupport::Concern
+  
+  # Instance Methods
+  # ========================================================================
+
+
+  class_methods do
+  # ==========================================================================
+
+    def arguments command: nil
+      [*class_arguments, *command&.arguments]
+    end
+
+    
+    protected
+    # ========================================================================
+
+    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
+
+
+    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
+
+    public # end protected ***************************************************
+
+
+    # @!group Class-Level Argument Class Methods
+    # ------------------------------------------------------------------------
+
+    # Returns this class' class-level arguments, looking up in the ancestors 
+    # chain.
+    #
+    # @return [Array<Thor::Argument>]
+    #
+    def class_arguments
+      @class_arguments ||= from_superclass( :class_arguments, [] )
+    end
+
+
+    # Adds an argument to the class and creates an attr_accessor for it.
+    # 
+    # @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.
+    #
+    # 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.
+    #
+    # @param [String | Symbol] name
+    #   The name of the argument.
+    # 
+    # @param [Hash] options
+    # 
+    # @option options [String] :desc
+    #   Description for the argument.
+    # 
+    # @option options [Boolean] :required
+    #   If the argument is required or not (opposite of `:optional`).
+    # 
+    # @option options [Boolean] :optional
+    #   If the argument is optional or not (opposite of `:required`).
+    # 
+    # @option options [:string | :hash | :array | :numeric] :type
+    #   The type of the argument.
+    # 
+    # @option options [Object] :default
+    #   Default value for this argument. It cannot be required and
+    #   have default values.
+    # 
+    # @option options [String] :banner
+    #   String to show on usage notes.
+    # 
+    # @return (see #class_arguments)
+    # 
+    # @raise [ArgumentError]
+    #   Raised if you supply a required argument after a non-required one.
+    #
+    def class_argument name, **options
+      build_argument name, options, class_arguments
+    end
+
+
+    # Removes a previous defined class-level argument. If `:undefine` option is
+    # given, un-defines accessors as well.
+    #
+    # @param [Array<String | Symbol>] *names
+    #   Arguments to be removed
+    #
+    # @param [Boolean] undefine:
+    #   Un-defines the arguments' setter methods as well.
+    #
+    # @example
+    #   remove_class_argument :foo
+    # 
+    # @example
+    #   remove_class_argument :foo, :bar, :baz, :undefine => true
+    #
+    def remove_class_argument *names, undefine: false
+      remove_argument_from *names, scope: class_arguments, undefine: undefine
+    end
+
+    # @!endgroup Class-Level Argument Class Methods # ************************
+
+
+    # @!group Method-Specific Argument Class Methods
+    # ------------------------------------------------------------------------
+
+    # Returns this class' class-level arguments, looking up in the ancestors 
+    # chain.
+    #
+    # @return [Array<Thor::Argument>]
+    #
+    def method_arguments
+      @method_arguments ||= []
+    end
+
+
+    # Adds an argument to the class and creates an attr_accessor for it.
+    # 
+    # @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.
+    #
+    # 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.
+    #
+    # @param [String | Symbol] name
+    #   The name of the argument.
+    # 
+    # @param [Hash] options
+    # 
+    # @option options [String] :desc
+    #   Description for the argument.
+    # 
+    # @option options [Boolean] :required
+    #   If the argument is required or not (opposite of `:optional`).
+    # 
+    # @option options [Boolean] :optional
+    #   If the argument is optional or not (opposite of `:required`).
+    # 
+    # @option options [:string | :hash | :array | :numeric] :type
+    #   The type of the argument.
+    # 
+    # @option options [Object] :default
+    #   Default value for this argument. It cannot be required and
+    #   have default values.
+    # 
+    # @option options [String] :banner
+    #   String to show on usage notes.
+    # 
+    # @return (see #class_arguments)
+    # 
+    # @raise [ArgumentError]
+    #   Raised if you supply a required argument after a non-required one.
+    #
+    def method_argument name, **options
+      build_argument( name, options, method_arguments )
+    end
+
+    alias_method :argument, :method_argument
+    alias_method :arg,      :method_argument
+
+
+    # Removes a previous defined class-level argument. If `:undefine` option is
+    # given, un-defines accessors as well.
+    #
+    # @param [Array<String | Symbol>] *names
+    #   Arguments to be removed
+    #
+    # @param [Boolean] undefine:
+    #   Un-defines the arguments' setter methods as well.
+    #
+    # @example
+    #
+    #   remove_argument :foo remove_argument :foo, :bar, :baz, :undefine => true
+    #
+    def remove_method_argument *names, undefine: false
+      remove_argument_from *names, scope: method_arguments, undefine: undefine
+    end
+
+    # @!endgroup Method-Specific Argument Class Methods # ********************
+
+  end # class_methods ********************************************************
+  
+end # module ArgumentsConcern
+
+# /Namespace
+# =======================================================================
+
+end # module Base
+end # class Thor