clamp 1.2.0.beta1 → 1.3.2

data/examples/admin

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # An example of options and parameters
 
@@ -6,12 +7,12 @@ require "clamp"
 
 Clamp do
 
-  option "--timeout", "SECONDS", "connection timeout", :default => 5, :environment_variable => "MYAPP_TIMEOUT" do |x|
+  option "--timeout", "SECONDS", "connection timeout", default: 5, environment_variable: "MYAPP_TIMEOUT" do |x|
     Integer(x)
   end
 
   parameter "HOST", "server address"
-  parameter "[PORT]", "server port", :default => 80, :environment_variable => "MYAPP_PORT"
+  parameter "[PORT]", "server port", default: 80, environment_variable: "MYAPP_PORT"
 
   def execute
     puts "trying to connect to #{host} on port #{port} (waiting up to #{timeout} seconds)"

data/examples/defaulted

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # An example of default values and methods
 
@@ -8,10 +9,10 @@ require "highline"
 Clamp do
 
   option ["-U", "--user"], "USER", "user name",
-         :environment_variable => "THE_USER",
-         :default => "bob"
+         environment_variable: "THE_USER",
+         default: "bob"
   option ["-P", "--password"], "PASSWORD", "password",
-         :environment_variable => "THE_PASSWORD"
+         environment_variable: "THE_PASSWORD"
 
   def execute
     puts "User: #{user}, Password: #{password}"

data/examples/flipflop

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # An example of subcommands (including a default subcommand)
 

data/examples/fubar

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # An example of nested subcommands
 

data/examples/gitdown

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # Demonstrate how subcommands can be declared as classes
 
@@ -25,7 +26,7 @@ module GitDown
   class CloneCommand < AbstractCommand
 
     parameter "REPOSITORY", "repository to clone"
-    parameter "[DIR]", "working directory", :default => "."
+    parameter "[DIR]", "working directory", default: "."
 
     def execute
       say "cloning to #{dir}"

data/examples/scoop

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # An example of multi-valued options
 
@@ -7,8 +8,8 @@ require "clamp"
 Clamp do
 
   option ["-f", "--flavour"], "FLAVOUR", "flavour",
-         :multivalued => true, :default => ["chocolate"],
-         :attribute_name => :flavours
+         multivalued: true, default: ["chocolate"],
+         attribute_name: :flavours
 
   def execute
     puts "one #{flavours.join(' and ')} ice-cream"

data/examples/speak

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # A simple Clamp command, with options and parameters
 
@@ -11,11 +12,11 @@ Clamp do
   )
 
   option "--loud", :flag, "say it loud"
-  option ["-n", "--iterations"], "N", "say it N times", :default => 1 do |s|
+  option ["-n", "--iterations"], "N", "say it N times", default: 1 do |s|
     Integer(s)
   end
 
-  parameter "WORDS ...", "the thing to say", :attribute_name => :words
+  parameter "WORDS ...", "the thing to say", attribute_name: :words
 
   def execute
     the_truth = words.join(" ")

data/examples/subcommand_missing

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # Demonstrate subcommand_missing
 

data/examples/word

@@ -1,4 +1,5 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
 
 # Demonstrate "restful" style; parameters precede subcommands
 

data/lib/clamp.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 require "clamp/version"
 
 require "clamp/command"
 
-def Clamp(&block)
+def Clamp(&block) # rubocop:disable Naming/MethodName
   Class.new(Clamp::Command, &block).run
 end

data/lib/clamp/attribute/declaration.rb

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module Clamp
   module Attribute
 
+    # Methods to generate attribute accessors.
+    #
     module Declaration
 
       protected
@@ -25,6 +29,7 @@ module Clamp
       end
 
       def define_default_for(attribute)
+        return false if attribute.default_value.nil?
         define_method(attribute.default_method) do
           attribute.default_value
         end

data/lib/clamp/attribute/definition.rb

@@ -1,25 +1,28 @@
+# frozen_string_literal: true
+
 require "clamp/attribute/instance"
 
 module Clamp
   module Attribute
 
+    # Represents an attribute of a Clamp::Command class.
+    #
     class Definition
 
       def initialize(options)
-        if options.key?(:attribute_name)
-          @attribute_name = options[:attribute_name].to_s
-        end
+        @attribute_name = options[:attribute_name].to_s if options.key?(:attribute_name)
         @default_value = options[:default] if options.key?(:default)
-        if options.key?(:environment_variable)
-          @environment_variable = options[:environment_variable]
-        end
+        @environment_variable = options[:environment_variable] if options.key?(:environment_variable)
         @hidden = options[:hidden] if options.key?(:hidden)
       end
 
       attr_reader :description, :environment_variable
 
       def help_rhs
-        description + default_description
+        rhs = description
+        comments = required_indicator || default_description
+        rhs += " (#{comments})" if comments
+        rhs
       end
 
       def help
@@ -51,11 +54,11 @@ module Clamp
       end
 
       def required?
-        @required
+        @required ||= false
       end
 
       def hidden?
-        @hidden
+        @hidden ||= false
       end
 
       def attribute_name
@@ -74,6 +77,17 @@ module Clamp
         Attribute::Instance.new(self, command)
       end
 
+      def option_missing_message
+        if environment_variable
+          Clamp.message(:option_or_env_required,
+                        option: switches.first,
+                        env: environment_variable)
+        else
+          Clamp.message(:option_required,
+                        option: switches.first)
+        end
+      end
+
       private
 
       def default_description
@@ -81,8 +95,8 @@ module Clamp
           ("$#{@environment_variable}" if defined?(@environment_variable)),
           (@default_value.inspect if defined?(@default_value))
         ].compact
-        return "" if default_sources.empty?
-        " (default: " + default_sources.join(", or ") + ")"
+        return nil if default_sources.empty?
+        "#{Clamp.message(:default)}: " + default_sources.join(", #{Clamp.message(:or)} ")
       end
 
     end

data/lib/clamp/attribute/instance.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Clamp
   module Attribute
 
-    # Represents an option/parameter of a Clamp::Command instance.
+    # Represents an attribute of a Clamp::Command instance.
     #
     class Instance
 
@@ -27,7 +29,7 @@ module Clamp
       end
 
       def default
-        command.send(attribute.default_method)
+        command.send(attribute.default_method) if command.respond_to?(attribute.default_method, true)
       end
 
       # default implementation of read_method
@@ -60,6 +62,10 @@ module Clamp
         end
       end
 
+      def signal_usage_error(*args)
+        command.send(:signal_usage_error, *args)
+      end
+
       def default_from_environment
         return if self.defined?
         return if attribute.environment_variable.nil?
@@ -69,10 +75,26 @@ module Clamp
         begin
           take(value)
         rescue ArgumentError => e
-          command.send(:signal_usage_error, Clamp.message(:env_argument_error, :env => attribute.environment_variable, :message => e.message))
+          signal_usage_error Clamp.message(:env_argument_error, env: attribute.environment_variable, message: e.message)
+        end
+      end
+
+      def unset?
+        if attribute.multivalued?
+          read.empty?
+        else
+          read.nil?
         end
       end
 
+      def missing?
+        attribute.required? && unset?
+      end
+
+      def verify_not_missing
+        signal_usage_error attribute.option_missing_message if missing?
+      end
+
     end
 
   end

data/lib/clamp/command.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "clamp/messages"
 require "clamp/errors"
 require "clamp/help"
@@ -48,6 +50,7 @@ module Clamp
       parse_options
       parse_parameters
       parse_subcommand
+      verify_required_options_are_set
       handle_remaining_arguments
     end
 
@@ -81,7 +84,7 @@ module Clamp
     #
     # @ param [String] name subcommand_name
     def subcommand_missing(name)
-      signal_usage_error(Clamp.message(:no_such_subcommand, :name => name))
+      signal_usage_error(Clamp.message(:no_such_subcommand, name: name))
     end
 
     include Clamp::Option::Parsing
@@ -122,6 +125,11 @@ module Clamp
       include Clamp::Subcommand::Declaration
       include Help
 
+      # An alternative to "def execute"
+      def execute(&block)
+        define_method(:execute, &block)
+      end
+
       # Create an instance of this command class, and run it.
       #
       # @param [String] invocation_path the path used to invoke the command

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,47 +45,66 @@ 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
-        @out = StringIO.new
+        @lines = []
       end
 
       def string
-        @out.string
+        left_column_width = lines.grep(Array).map(&:first).map(&:size).max
+        StringIO.new.tap do |out|
+          lines.each do |line|
+            case line
+            when Array
+              line[0] = line[0].ljust(left_column_width)
+              line.unshift("")
+              out.puts(line.join("    "))
+            else
+              out.puts(line)
+            end
+          end
+        end.string
+      end
+
+      def line(text = "")
+        @lines << text
+      end
+
+      def row(lhs, rhs)
+        @lines << [lhs, rhs]
       end
 
       def add_usage(invocation_path, usage_descriptions)
-        puts Clamp.message(:usage_heading) + ":"
+        line Clamp.message(:usage_heading) + ":"
         usage_descriptions.each do |usage|
-          puts "    #{invocation_path} #{usage}".rstrip
+          line "    #{invocation_path} #{usage}".rstrip
         end
       end
 
       def add_description(description)
         return unless description
-        puts ""
-        puts description.gsub(/^/, "  ")
+        line
+        line description.gsub(/^/, "  ")
       end
 
       DETAIL_FORMAT = "    %-29s %s".freeze
 
       def add_list(heading, items)
-        puts "\n#{heading}:"
+        line
+        line "#{heading}:"
         items.reject { |i| i.respond_to?(:hidden?) && i.hidden? }.each do |item|
           label, description = item.help
           description.each_line do |line|
-            puts format(DETAIL_FORMAT, label, line)
+            row(label, line)
             label = ""
           end
         end
@@ -89,9 +112,7 @@ module Clamp
 
       private
 
-      def puts(*args)
-        @out.puts(*args)
-      end
+      attr_accessor :lines
 
     end