clamp 1.2.0.beta1 → 1.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: aec7a5c34695b2517afb8215a0cbe8e9e4b2c8b9
-  data.tar.gz: f20e0d18b9e4be570fc7ae1f349d4d022f0f7644
+SHA256:
+  metadata.gz: c164c63137c57502ad15e11ab471b2607661868298e5330a8a4961dfea629537
+  data.tar.gz: 297e0abb1ead811d567eea7e668a91ba7c99654657a358016abb5cdbfd13168d
 SHA512:
-  metadata.gz: 554f0e8fefe510adeacd74357333302d2f3ae9a4b98f87e0140956e4b35ff6f60b7b3031260b8cba2c2f96079b201ebc4c6256bed160d52038a079e7538defda
-  data.tar.gz: 85d29744e560feb6c06096739df752128bd1df915237da53b1c7ea7150ade1d3516016eb3014c7fc1f2958fdcf2074c35e00d6aa64057a8c8c56c9c82094f879
+  metadata.gz: 3773151ffa64b908d26c569877bb27704bf68efe658d9b6ebd48c009bcbc1a4d0a3fce2c4f16a02ed379e126dd436ef018ff1eac56334fcc8f467402fad6c995
+  data.tar.gz: 8104ea9b1d9a42669234cb0d82cc441efd7a6f94ed5cba542a502ae1cb2797d977530a07bbe649d98dab551e9078b434711e091e9d0b3716799522c04436d8c9

data/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true

data/.gitignore

@@ -1,8 +1,8 @@
 *.gem
 .bundle
+.markdownlint*
 .rvmrc
 .yardoc
 doc
 pkg/*
 Gemfile.lock
- 

data/.rspec

@@ -1 +1,2 @@
 --color
+--warnings

data/.rubocop.yml

@@ -1,17 +1,40 @@
+AllCops:
+  TargetRubyVersion: 2.1
+
 Eval:
   Exclude:
     - "Rakefile"
 
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
 Metrics/AbcSize:
   Enabled: false
 
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+
 Metrics/LineLength:
   Max: 120
 
 Metrics/MethodLength:
   Max: 30
 
-Style/AccessorMethodName:
+Naming/AccessorMethodName:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - "bin/*"
+
+Naming/PredicateName:
   Enabled: false
 
 Style/ClassAndModuleChildren:
@@ -22,35 +45,19 @@ Style/ClassAndModuleChildren:
 Style/Documentation:
   Exclude:
     - "lib/**/version.rb"
+    - "examples/*"
     - "spec/**/*"
 
-Style/EmptyLinesAroundBlockBody:
-  Enabled: false
-
-Style/EmptyLinesAroundClassBody:
-  EnforcedStyle: empty_lines
-
-Style/EmptyLinesAroundModuleBody:
-  Enabled: false
-
 Style/Encoding:
-  EnforcedStyle: when_needed
   Enabled: true
 
-Style/FileName:
-  Exclude:
-    - "bin/*"
-
-Style/HashSyntax:
-  EnforcedStyle: hash_rockets
-
 Style/Lambda:
   Enabled: false
 
 Style/NumericLiterals:
   Enabled: false
 
-Style/PredicateName:
+Style/StderrPuts:
   Enabled: false
 
 Style/StringLiterals:

data/.travis.yml

@@ -1,8 +1,5 @@
 language: ruby
 rvm:
-  - 2.1.8
-  - 2.2.4
-  - 2.3.1
-before_install:
-  - gem update --system
-  - gem install bundler
+  - 2.3
+  - 2.5
+  - 2.6

data/CHANGES.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## PENDING
+## 1.3.2 (2020-08-20)
+
+* Fix Ruby warnings.
+
+## 1.3.1 (2019-07-11)
+
+* Choose a sensible column width in generated help, based on content.
+* Fix issue#99: extraneous parameter names in subcommand help.
+
+## 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", "~> 0.43.0", :require => false
+  gem "guard-rspec", "~> 4.7", require: false
+  gem "highline"
+  gem "listen", "~> 3.0"
+  gem "rake", "~> 12.3"
+  gem "rubocop", "~> 0.57.2", "<= 0.58", 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/README.md

@@ -1,5 +1,4 @@
-Clamp
-=====
+# Clamp
 
 [![Gem Version](https://badge.fury.io/rb/clamp.png)](http://badge.fury.io/rb/clamp)
 [![Build Status](https://secure.travis-ci.org/mdub/clamp.png?branch=master)](http://travis-ci.org/mdub/clamp)
@@ -8,8 +7,7 @@ Clamp
 
 It handles boring stuff like parsing the command-line, and generating help, so you can get on with making your command actually do stuff.
 
-Not another one!
-----------------
+## Not another one!
 
 Yeah, sorry.  There are a bunch of existing command-line parsing libraries out there, and Clamp draws inspiration from a variety of sources, including [Thor], [optparse], and [Clip].  In the end, though, I wanted a slightly rounder wheel.  (Although, Clamp has a _lot_ in common with Ara T. Howard's [main.rb]. Had I been aware of that project at the time, I might not have written Clamp.)
 
@@ -18,8 +16,7 @@ Yeah, sorry.  There are a bunch of existing command-line parsing libraries out t
 [Clip]: http://clip.rubyforge.org/
 [main.rb]: https://github.com/ahoward/main
 
-Quick Start
------------
+## Quick Start
 
 A typical Clamp script looks like this:
 
@@ -29,11 +26,11 @@ require 'clamp'
 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(" ")
@@ -54,11 +51,11 @@ require 'clamp'
 class SpeakCommand < Clamp::Command
 
   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(" ")
@@ -79,8 +76,7 @@ There are more examples demonstrating various features of Clamp [on Github][exam
 
 [examples]: https://github.com/mdub/clamp/tree/master/examples
 
-Declaring options
------------------
+## Declaring options
 
 Options are declared using the `option` method.  The three required arguments are:
 
@@ -105,7 +101,7 @@ end
 If you don't like the inferred attribute name, you can override it:
 
 ```ruby
-option "--type", "TYPE", "type of widget", :attribute_name => :widget_type
+option "--type", "TYPE", "type of widget", attribute_name: :widget_type
                                            # to avoid clobbering Object#type
 ```
 
@@ -140,7 +136,7 @@ Clamp will handle both "`--force`" and "`--no-force`" options, setting the value
 Although "required option" is an oxymoron, Clamp lets you mark an option as required, and will verify that a value is provided:
 
 ```ruby
-option "--password", "PASSWORD", "the secret password", :required => true
+option "--password", "PASSWORD", "the secret password", required: true
 ```
 
 Note that it makes no sense to mark a `:flag` option, or one with a `:default`, as `:required`.
@@ -150,7 +146,7 @@ Note that it makes no sense to mark a `:flag` option, or one with a `:default`,
 Declaring an option "`:multivalued`" allows it to be specified multiple times on the command line.
 
 ```ruby
-option "--format", "FORMAT", "output format", :multivalued => true
+option "--format", "FORMAT", "output format", multivalued: true
 ```
 
 The underlying attribute becomes an Array, and the suffix "`_list`" is appended to the default attribute name.  In this case, an attribute called "`format_list`" would be generated (unless you override the default by specifying an `:attribute_name`).
@@ -160,12 +156,12 @@ The underlying attribute becomes an Array, and the suffix "`_list`" is appended
 Declaring an option "`:hidden`" will cause it to be hidden from `--help` output.
 
 ```ruby
-option "--some-option", "VALUE", "Just a little option", :hidden => true
+option "--some-option", "VALUE", "Just a little option", hidden: true
 ```
 
 ### Version option
 
-A common idiom is to have an option `--version` that outputs the command version and doesn't run any subcommands.  This can be acheived by:
+A common idiom is to have an option `--version` that outputs the command version and doesn't run any subcommands.  This can be achieved by:
 
 ```ruby
 option "--version", :flag, "Show version" do
@@ -174,8 +170,7 @@ option "--version", :flag, "Show version" do
 end
 ```
 
-Declaring parameters
---------------------
+## Declaring parameters
 
 Positional parameters can be declared using `parameter`, specifying
 
@@ -203,13 +198,12 @@ parameter "[TARGET_DIR]", "target directory"
 Three dots at the end of a parameter name makes it "greedy" - it will consume all remaining command-line arguments.  For example:
 
 ```ruby
-parameter "FILE ...", "input files", :attribute_name => :files
+parameter "FILE ...", "input files", attribute_name: :files
 ```
 
 Like multivalued options, greedy parameters are backed by an Array attribute (named with a "`_list`" suffix, by default).
 
-Parsing and validation of options and parameters
-------------------------------------------------
+## Parsing and validation of options and parameters
 
 When you `#run` a command, it will first attempt to `#parse` command-line arguments, and map them onto the declared options and parameters, before invoking your `#execute` method.
 
@@ -265,15 +259,15 @@ end
 Default values can be specified for options, and optional parameters:
 
 ```ruby
-option "--flavour", "FLAVOUR", "ice-cream flavour", :default => "chocolate"
+option "--flavour", "FLAVOUR", "ice-cream flavour", default: "chocolate"
 
-parameter "[HOST]", "server host", :default => "localhost"
+parameter "[HOST]", "server host", default: "localhost"
 ```
 
 For more advanced cases, you can also specify default values by defining a method called "`default_#{attribute_name}`":
 
 ```ruby
-option "--http-port", "PORT", "web-server port", :default => 9000
+option "--http-port", "PORT", "web-server port", default:  9000
 
 option "--admin-port", "PORT", "admin port"
 
@@ -287,29 +281,30 @@ end
 Options (and optional parameters) can also be associated with environment variables:
 
 ```ruby
-option "--port", "PORT", "the port to listen on", :environment_variable => "MYAPP_PORT" do |val|
+option "--port", "PORT", "the port to listen on", environment_variable: "MYAPP_PORT" do |val|
   val.to_i
 end
 
-parameter "[HOST]", "server address", :environment_variable => "MYAPP_HOST"
+parameter "[HOST]", "server address", environment_variable: "MYAPP_HOST"
 ```
 
 Clamp will check the specified envariables in the absence of values supplied on the command line, before looking for a default value.
 
 ### Allowing options after parameters
 
-Many option-parsing libraries - notably [GNU `getopt(3)`](https://www.gnu.org/software/libc/manual/html_node/Using-Getopt.html) - allow option and parameter arguments to appear in any order on the command-line, e.g.
+By default, Clamp only recognises options _before_ positional parameters.
+
+Some other option-parsing libraries - notably [GNU `getopt(3)`](https://www.gnu.org/software/libc/manual/html_node/Using-Getopt.html) - allow option and parameter arguments to appear in any order on the command-line, e.g.
 
     foobar --foo=bar something --fnord=snuffle another-thing
 
-By default, Clamp does not allow options and parameters to be "interspersed" in this way. If you want that behaviour, set:
+If you want Clamp to allow options and parameters to be "interspersed" in this way, set:
 
 ```ruby
 Clamp.allow_options_after_parameters = true
 ```
 
-Declaring Subcommands
----------------------
+## Declaring Subcommands
 
 Subcommand support helps you wrap a number of related commands into a single script (ala tools like "`git`").  Clamp will inspect the first command-line argument (after options are parsed), and delegate to the named subcommand.
 
@@ -400,8 +395,7 @@ Clamp do
 end
 ```
 
-Getting help
-------------
+## Getting help
 
 All Clamp commands support a "`--help`" option, which outputs brief usage documentation, based on those seemingly useless extra parameters that you had to pass to `option` and `parameter`.
 
@@ -419,27 +413,27 @@ Options:
     -h, --help                    print help
 ```
 
-Localization
-------------
+## Localization
 
 Clamp comes with support for overriding strings with custom translations. You can use localization library of your choice and override the strings at startup.
 
 Example usage:
+
 ```ruby
 require 'gettext'
 
 Clamp.messages = {
-  :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")
+  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")
   # ...
 }
 ```
+
 See [messages.rb](https://github.com/mdub/clamp/blob/master/lib/clamp/messages.rb) for full list of available messages.
 
-License
--------
+## License
 
 Copyright (C) 2011 [Mike Williams](mailto:mdub@dogbiscuit.org)
 
@@ -460,7 +454,6 @@ THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-Contributing to Clamp
----------------------
+## Contributing to Clamp
 
 Source-code for Clamp is [on Github](https://github.com/mdub/clamp).

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")