clamp 1.2.1 → 1.3.0

data/lib/clamp/errors.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 module Clamp
 
+  # raised to indicate invalid option/parameter declaration
   class DeclarationError < StandardError
   end
 
+  # abstract command runtime error
   class RuntimeError < StandardError
 
     def initialize(message, command)
@@ -14,10 +18,10 @@ module Clamp
 
   end
 
-  # raise to signal incorrect command usage
+  # raised to signal incorrect command usage
   class UsageError < RuntimeError; end
 
-  # raise to request usage help
+  # raised to request usage help
   class HelpWanted < RuntimeError
 
     def initialize(command)
@@ -26,7 +30,7 @@ module Clamp
 
   end
 
-  # raise to signal error during execution
+  # raised to signal error during execution
   class ExecutionError < RuntimeError
 
     def initialize(message, command, status = 1)

data/lib/clamp/help.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require "stringio"
 require "clamp/messages"
 
 module Clamp
 
+  # Command help generation.
+  #
   module Help
 
     def usage(usage)
@@ -41,16 +45,14 @@ module Clamp
       help = builder
       help.add_usage(invocation_path, usage_descriptions)
       help.add_description(description)
-      if has_parameters?
-        help.add_list(Clamp.message(:parameters_heading), parameters)
-      end
-      if has_subcommands?
-        help.add_list(Clamp.message(:subcommands_heading), recognised_subcommands)
-      end
+      help.add_list(Clamp.message(:parameters_heading), parameters) if has_parameters?
+      help.add_list(Clamp.message(:subcommands_heading), recognised_subcommands) if has_subcommands?
       help.add_list(Clamp.message(:options_heading), recognised_options)
       help.string
     end
 
+    # A builder for auto-generated help.
+    #
     class Builder
 
       def initialize

data/lib/clamp/messages.rb

@@ -1,5 +1,9 @@
-module Clamp
+# frozen_string_literal: true
 
+module Clamp #:nodoc:
+
+  # Message lookup, to allow localization.
+  #
   module Messages
 
     def messages=(new_messages)
@@ -17,19 +21,22 @@ module Clamp
     private
 
     DEFAULTS = {
-      :too_many_arguments => "too many arguments",
-      :option_required => "option '%<option>s' is required",
-      :option_or_env_required => "option '%<option>s' (or env %<env>s) is required",
-      :option_argument_error => "option '%<switch>s': %<message>s",
-      :parameter_argument_error => "parameter '%<param>s': %<message>s",
-      :env_argument_error => "$%<env>s: %<message>s",
-      :unrecognised_option => "Unrecognised option '%<switch>s'",
-      :no_such_subcommand => "No such sub-command '%<name>s'",
-      :no_value_provided => "no value provided",
-      :usage_heading => "Usage",
-      :parameters_heading => "Parameters",
-      :subcommands_heading => "Subcommands",
-      :options_heading => "Options"
+      too_many_arguments: "too many arguments",
+      option_required: "option '%<option>s' is required",
+      option_or_env_required: "option '%<option>s' (or env %<env>s) is required",
+      option_argument_error: "option '%<switch>s': %<message>s",
+      parameter_argument_error: "parameter '%<param>s': %<message>s",
+      env_argument_error: "$%<env>s: %<message>s",
+      unrecognised_option: "Unrecognised option '%<switch>s'",
+      no_such_subcommand: "No such sub-command '%<name>s'",
+      no_value_provided: "no value provided",
+      default: "default",
+      or: "or",
+      required: "required",
+      usage_heading: "Usage",
+      parameters_heading: "Parameters",
+      subcommands_heading: "Subcommands",
+      options_heading: "Options"
     }.freeze
 
     def messages

data/lib/clamp/option/declaration.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require "clamp/attribute/declaration"
 require "clamp/option/definition"
 
 module Clamp
   module Option
 
+    # Option declaration methods.
+    #
     module Declaration
 
       include Clamp::Attribute::Declaration

data/lib/clamp/option/definition.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require "clamp/attribute/definition"
 require "clamp/truthy"
 
 module Clamp
   module Option
 
+    # Represents an option of a Clamp::Command class.
+    #
     class Definition < Attribute::Definition
 
       def initialize(switches, type, description, options = {})
@@ -76,14 +80,16 @@ module Clamp
       end
 
       def infer_attribute_name
-        unless long_switch
-          raise Clamp::DeclarationError, "You must specify either a long-switch or an :attribute_value"
-        end
+        raise Clamp::DeclarationError, "You must specify either a long-switch or an :attribute_value" unless long_switch
         inferred_name = long_switch.sub(/^--(\[no-\])?/, "").tr("-", "_")
         inferred_name += "_list" if multivalued?
         inferred_name
       end
 
+      def required_indicator
+        Clamp.message(:required) if required?
+      end
+
     end
 
   end

data/lib/clamp/option/parsing.rb

@@ -1,11 +1,17 @@
-module Clamp
+# frozen_string_literal: true
+
+module Clamp #:nodoc:
 
   class << self
+
     attr_accessor :allow_options_after_parameters
+
   end
 
   module Option
 
+    # Option parsing methods.
+    #
     module Parsing
 
       protected
@@ -13,7 +19,6 @@ module Clamp
       def parse_options
         set_options_from_command_line
         default_options_from_environment
-        verify_required_options_are_set
       end
 
       private
@@ -22,43 +27,43 @@ module Clamp
         argument_buffer = []
         argument_buffer_limit = self.class.parameter_buffer_limit
         until remaining_arguments.empty?
-
           unless remaining_arguments.first.start_with?("-")
-            if argument_buffer.size < argument_buffer_limit
-              argument_buffer << remaining_arguments.shift
-              next
-            else
-              break
-            end
+            break unless argument_buffer.size < argument_buffer_limit
+            argument_buffer << remaining_arguments.shift
+            next
           end
-
           switch = remaining_arguments.shift
           break if switch == "--"
+          handle_switch(switch)
+        end
+        remaining_arguments.unshift(*argument_buffer)
+      end
 
-          case switch
-          when /\A(-\w)(.+)\z/m # combined short options
-            switch = Regexp.last_match(1)
-            if find_option(switch).flag?
-              remaining_arguments.unshift("-" + Regexp.last_match(2))
-            else
-              remaining_arguments.unshift(Regexp.last_match(2))
-            end
-          when /\A(--[^=]+)=(.*)\z/m
-            switch = Regexp.last_match(1)
-            remaining_arguments.unshift(Regexp.last_match(2))
-          end
-
-          option = find_option(switch)
-          value = option.extract_value(switch, remaining_arguments)
+      def handle_switch(switch)
+        switch = split_trailing_switches(switch)
+        option = find_option(switch)
+        value = option.extract_value(switch, remaining_arguments)
+        begin
+          option.of(self).take(value)
+        rescue ArgumentError => e
+          signal_usage_error Clamp.message(:option_argument_error, switch: switch, message: e.message)
+        end
+      end
 
-          begin
-            option.of(self).take(value)
-          rescue ArgumentError => e
-            signal_usage_error Clamp.message(:option_argument_error, :switch => switch, :message => e.message)
+      def split_trailing_switches(switch)
+        case switch
+        when /\A(-\w)(.+)\z/m # combined short options
+          switch = Regexp.last_match(1)
+          if find_option(switch).flag?
+            remaining_arguments.unshift("-" + Regexp.last_match(2))
+          else
+            remaining_arguments.unshift(Regexp.last_match(2))
           end
-
+        when /\A(--[^=]+)=(.*)\z/m
+          switch = Regexp.last_match(1)
+          remaining_arguments.unshift(Regexp.last_match(2))
         end
-        remaining_arguments.unshift(*argument_buffer)
+        switch
       end
 
       def default_options_from_environment
@@ -75,7 +80,7 @@ module Clamp
 
       def find_option(switch)
         self.class.find_option(switch) ||
-          signal_usage_error(Clamp.message(:unrecognised_option, :switch => switch))
+          signal_usage_error(Clamp.message(:unrecognised_option, switch: switch))
       end
 
     end

data/lib/clamp/parameter/declaration.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require "clamp/attribute/declaration"
 require "clamp/parameter/definition"
 
 module Clamp
   module Parameter
 
+    # Parameter declaration methods.
+    #
     module Declaration
 
       include Clamp::Attribute::Declaration

data/lib/clamp/parameter/definition.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require "clamp/attribute/definition"
 
 module Clamp
   module Parameter
 
+    # Represents an parameter of a Clamp::Command class.
+    #
     class Definition < Attribute::Definition
 
       def initialize(name, description, options = {})
@@ -40,13 +44,15 @@ module Clamp
 
       def infer_attribute_name
         inferred_name = name.downcase.tr("-", "_").sub(ELLIPSIS_SUFFIX, "").sub(OPTIONAL) { Regexp.last_match(1) }
-        unless inferred_name =~ VALID_ATTRIBUTE_NAME
-          raise "cannot infer attribute_name from #{name.inspect}"
-        end
+        raise "cannot infer attribute_name from #{name.inspect}" unless inferred_name =~ VALID_ATTRIBUTE_NAME
         inferred_name += "_list" if multivalued?
         inferred_name
       end
 
+      def required_indicator
+        # implied by LHS
+      end
+
     end
 
   end

data/lib/clamp/parameter/parsing.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module Clamp
   module Parameter
 
+    # Parameter parsing methods.
+    #
     module Parsing
 
       protected
@@ -19,7 +23,7 @@ module Clamp
               parameter.of(self).take(value)
             end
           rescue ArgumentError => e
-            signal_usage_error Clamp.message(:parameter_argument_error, :param => parameter.name, :message => e.message)
+            signal_usage_error Clamp.message(:parameter_argument_error, param: parameter.name, message: e.message)
           end
         end
       end

data/lib/clamp/subcommand/declaration.rb

@@ -1,9 +1,13 @@
+# frozen_string_literal: true
+
 require "clamp/errors"
 require "clamp/subcommand/definition"
 
 module Clamp
   module Subcommand
 
+    # Subcommand declaration methods.
+    #
     module Declaration
 
       def recognised_subcommands
@@ -37,9 +41,7 @@ module Clamp
       end
 
       def default_subcommand=(name)
-        if has_subcommands?
-          raise Clamp::DeclarationError, "default_subcommand must be defined before subcommands"
-        end
+        raise Clamp::DeclarationError, "default_subcommand must be defined before subcommands" if has_subcommands?
         @default_subcommand = name
       end
 
@@ -48,7 +50,7 @@ module Clamp
           @default_subcommand
         else
           $stderr.puts "WARNING: Clamp default_subcommand syntax has changed; check the README."
-          $stderr.puts "  (from #{caller.first})"
+          $stderr.puts "  (from #{caller(1..1).first})"
           self.default_subcommand = args.first
           subcommand(*args, &block)
         end
@@ -59,19 +61,19 @@ module Clamp
       def declare_subcommand_parameters
         if @default_subcommand
           parameter "[SUBCOMMAND]", "subcommand",
-                    :attribute_name => :subcommand_name,
-                    :default => @default_subcommand,
-                    :inheritable => false
+                    attribute_name: :subcommand_name,
+                    default: @default_subcommand,
+                    inheritable: false
         else
           parameter "SUBCOMMAND", "subcommand",
-                    :attribute_name => :subcommand_name,
-                    :required => false,
-                    :inheritable => false
+                    attribute_name: :subcommand_name,
+                    required: false,
+                    inheritable: false
         end
-        remove_method :default_subcommand_name
+        remove_method :default_subcommand_name if method_defined?(:default_subcommand_name)
         parameter "[ARG] ...", "subcommand arguments",
-                  :attribute_name => :subcommand_arguments,
-                  :inheritable => false
+                  attribute_name: :subcommand_arguments,
+                  inheritable: false
       end
 
     end

data/lib/clamp/subcommand/definition.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Clamp
   module Subcommand
 

data/lib/clamp/subcommand/execution.rb

@@ -1,6 +1,13 @@
+# frozen_string_literal: true
+
 module Clamp
   module Subcommand
 
+    # Support for subcommand execution.
+    #
+    # This module is mixed into command instances that have subcommands, overriding
+    # default behaviour in {Clamp::Command}.
+    #
     module Execution
 
       # override default Command behaviour
@@ -34,6 +41,10 @@ module Clamp
         subcommand_missing(name)
       end
 
+      def verify_required_options_are_set
+        # not required
+      end
+
     end
 
   end

data/lib/clamp/subcommand/parsing.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require "clamp/subcommand/execution"
 
 module Clamp
   module Subcommand
 
+    # Subcommand parsing methods.
+    #
     module Parsing
 
       protected

data/lib/clamp/truthy.rb

@@ -1,6 +1,8 @@
-module Clamp
+# frozen_string_literal: true
 
-  TRUTHY_VALUES = %w(1 yes enable on true).freeze
+module Clamp #:nodoc:
+
+  TRUTHY_VALUES = %w[1 yes enable on true].freeze
 
   def self.truthy?(arg)
     TRUTHY_VALUES.include?(arg.to_s.downcase)