clamp 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7e919d5a5f983e9de93adeccf16090c2ccf673d6
-  data.tar.gz: fcc637ed598db752ac2411970391ff9440e96fcc
+  metadata.gz: a8365dad9e1c1555dfddea4d47c063438af94be5
+  data.tar.gz: b618f175a72f08180fb77315cc1a4ceafbbb134e
 SHA512:
-  metadata.gz: bc3d0c1e9a7172ab3a0f8d09cc0583aec4f03ee8a85db033d2e0c413a03a7455ddc1c1cca622781620a28ab47148ebe9b3245d54ac533278bc0398e767dc558b
-  data.tar.gz: 9551a0bbae48288c19b9ac5a2f1918753620d4deefd8efc1e47fa5206c9911e9ee80aa60223f017133e7ff545d8d61624ff1308fb17a9412d2c1724ee6623c9b
+  metadata.gz: 2bec2151d2344efc7fbcd37709646904d20e7456fa83365484aacfa318bb23207a8e3ae9e813457d26d791f56b8c890eb863ccb59a85724a53b542193af26384
+  data.tar.gz: 0be7bb668484292023495887a581e8e887e0d3f10f2fac89353f6e6a6d091a2f3e9a308902a3f8548c169dd138c0aec7a90e28fac950e36999f9524b1ffab886

data/.rubocop.yml

@@ -1,3 +1,6 @@
+AllCops:
+  TargetRubyVersion: 2.1
+
 Eval:
   Exclude:
     - "Rakefile"
@@ -14,6 +17,10 @@ Layout/EmptyLinesAroundModuleBody:
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
 Metrics/LineLength:
   Max: 120
 
@@ -27,6 +34,9 @@ Naming/FileName:
   Exclude:
     - "bin/*"
 
+Naming/PredicateName:
+  Enabled: false
+
 Style/ClassAndModuleChildren:
   EnforcedStyle: nested
   Exclude:
@@ -35,21 +45,19 @@ Style/ClassAndModuleChildren:
 Style/Documentation:
   Exclude:
     - "lib/**/version.rb"
+    - "examples/*"
     - "spec/**/*"
 
 Style/Encoding:
   Enabled: true
 
-Style/HashSyntax:
-  EnforcedStyle: hash_rockets
-
 Style/Lambda:
   Enabled: false
 
 Style/NumericLiterals:
   Enabled: false
 
-Naming/PredicateName:
+Style/StderrPuts:
   Enabled: false
 
 Style/StringLiterals:

data/.travis.yml

@@ -1,8 +1,6 @@
 language: ruby
 rvm:
-  - 2.1.8
-  - 2.2.4
-  - 2.3.1
-before_install:
-  - gem update --system
-  - gem install bundler
+  - 2.1.9
+  - 2.2.10
+  - 2.3.7
+  - 2.5.1

data/CHANGES.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.3.0 (2018-06-17)
+
+* Add `.execute` DSL method.
+* Append '(required)' to the description of required options.
+* Fix issue#75: don't generate `default_XXX` method unless a default is specified.
+* Fix issue#90: allow required options to be provided after subcommands.
+
 ## 1.2.0 (2018-02-12)
 
 * Add option to `Clamp.allow_options_after_parameters`.

data/Gemfile

@@ -1,15 +1,17 @@
+# frozen_string_literal: true
+
 source "http://rubygems.org"
 
 gemspec
 
 group :development do
-  gem "guard-rspec", "~> 4.6.5", :require => false
-  gem "listen", "~> 3.0.2"
-  gem "rake", "~> 10.4"
-  gem "rubocop", :require => false
+  gem "guard-rspec", "~> 4.7", require: false
+  gem "highline"
+  gem "listen", "~> 3.0"
+  gem "rake", "~> 12.3"
+  gem "rubocop", require: false
 end
 
 group :test do
-  gem "rspec", "~> 3.5.0"
-  gem "rr", "~> 1.2.0"
+  gem "rspec", "~> 3.7"
 end

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # A sample Guardfile
 # More info at https://github.com/guard/guard#readme
 
@@ -24,7 +26,7 @@
 #  * zeus: 'zeus rspec' (requires the server to be started separately)
 #  * 'just' rspec: 'rspec'
 
-guard :rspec, :cmd => "bundle exec rspec" do
+guard :rspec, cmd: "bundle exec rspec" do
   require "guard/rspec/dsl"
   dsl = Guard::RSpec::Dsl.new(self)
 

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler"
 
 Bundler::GemHelper.install_tasks
@@ -10,3 +12,9 @@ RSpec::Core::RakeTask.new do |t|
   t.pattern = "spec/**/*_spec.rb"
   t.rspec_opts = ["--colour", "--format", "documentation"]
 end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task "default" => "rubocop"

data/clamp.gemspec

@@ -1,4 +1,6 @@
-$LOAD_PATH.push File.expand_path("../lib", __FILE__)
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path("lib", __dir__)
 require "clamp/version"
 
 Gem::Specification.new do |s|
@@ -8,15 +10,15 @@ Gem::Specification.new do |s|
   s.platform      = Gem::Platform::RUBY
   s.authors       = ["Mike Williams"]
   s.email         = "mdub@dogbiscuit.org"
-  s.homepage      = "http://github.com/mdub/clamp"
+  s.homepage      = "https://github.com/mdub/clamp"
 
   s.license       = "MIT"
 
   s.summary       = "a minimal framework for command-line utilities"
-  s.description   = <<EOF
-Clamp provides an object-model for command-line utilities.
-It handles parsing of command-line options, and generation of usage help.
-EOF
+  s.description   = <<-TEXT.gsub(/^\s+/, "")
+    Clamp provides an object-model for command-line utilities.
+    It handles parsing of command-line options, and generation of usage help.
+  TEXT
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

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
@@ -77,11 +80,11 @@ module Clamp
       def option_missing_message
         if environment_variable
           Clamp.message(:option_or_env_required,
-                        :option => switches.first,
-                        :env => environment_variable)
+                        option: switches.first,
+                        env: environment_variable)
         else
           Clamp.message(:option_required,
-                        :option => switches.first)
+                        option: switches.first)
         end
       end
 
@@ -92,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
@@ -73,7 +75,7 @@ module Clamp
         begin
           take(value)
         rescue ArgumentError => e
-          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
 

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