clamp 1.3.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a8365dad9e1c1555dfddea4d47c063438af94be5
-  data.tar.gz: b618f175a72f08180fb77315cc1a4ceafbbb134e
+SHA256:
+  metadata.gz: c397bb4c7fbc93ee71f4df0dbeaf3513e0372dcbe12ed0ace0b89ac54bd932de
+  data.tar.gz: 28088d25dd5a855aca74a77caa3172b2b30259e33fc5223a1d302fe4a302ef2a
 SHA512:
-  metadata.gz: 2bec2151d2344efc7fbcd37709646904d20e7456fa83365484aacfa318bb23207a8e3ae9e813457d26d791f56b8c890eb863ccb59a85724a53b542193af26384
-  data.tar.gz: 0be7bb668484292023495887a581e8e887e0d3f10f2fac89353f6e6a6d091a2f3e9a308902a3f8548c169dd138c0aec7a90e28fac950e36999f9524b1ffab886
+  metadata.gz: 4ee42ec998257b428af64d243b0a89f7345bbe9aad098414a9a99a53d53007489036bc7c4c8d7d03bb53f4bbaecf095e1c0d60860faec50b5b5b67bfafe4cf5f
+  data.tar.gz: d7bd94bbea00c26fca7d388411959c92a864399b9c89c907a07008a10cc326c9eedb553091caa0602771a367e81baded339ed6bba5a86da80ee5a116dc977f5b

data/.gitignore

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

data/CHANGES.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## PENDING
+
+* 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.

data/Gemfile

@@ -9,7 +9,7 @@ group :development do
   gem "highline"
   gem "listen", "~> 3.0"
   gem "rake", "~> 12.3"
-  gem "rubocop", require: false
+  gem "rubocop", "~> 0.57.2", "<= 0.58", require: false
 end
 
 group :test do

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,18 +281,18 @@ 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
 
-By default, Clamp only recognises options _before_ positional parameters. 
+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.
 
@@ -310,8 +304,7 @@ If you want Clamp to allow options and parameters to be "interspersed" in this w
 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.
 
@@ -402,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`.
 
@@ -421,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)
 
@@ -462,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/lib/clamp/help.rb

@@ -56,34 +56,55 @@ module Clamp
     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
@@ -91,9 +112,7 @@ module Clamp
 
       private
 
-      def puts(*args)
-        @out.puts(*args)
-      end
+      attr_accessor :lines
 
     end
 

data/lib/clamp/subcommand/execution.rb

@@ -31,7 +31,7 @@ module Clamp
       end
 
       def invocation_path_for(name)
-        param_names = self.class.inheritable_parameters.map(&:name)
+        param_names = self.class.parameters.select(&:inheritable?).map(&:name)
         [invocation_path, *param_names, name].join(" ")
       end
 

data/lib/clamp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clamp
-  VERSION = "1.3.0".freeze
+  VERSION = "1.3.1".freeze
 end

data/spec/clamp/command_group_spec.rb

@@ -261,9 +261,9 @@ describe Clamp::Command do
 
     it "shows parameter in usage help" do
       begin
-        command.run(["stuff", "say", "--help"])
+        command.run(["stuff", "say", "loud", "--help"])
       rescue Clamp::HelpWanted => e
-        expect(e.command.invocation_path).to eql("with THING say")
+        expect(e.command.invocation_path).to eql("with THING say loud")
       end
     end
 

data/spec/clamp/command_spec.rb

@@ -435,6 +435,19 @@ describe Clamp::Command do
 
       end
 
+      context "with option arguments that look like options" do
+
+        before do
+          command.parse(%w[--flavour=-dashing- --scoops -1])
+        end
+
+        it "sets the options" do
+          expect(command.flavour).to eq("-dashing-")
+          expect(command.scoops).to eq(-1)
+        end
+
+      end
+
       context "with option-like things beyond the arguments" do
 
         it "treats them as positional arguments" do

data/spec/clamp/help_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe Clamp::Help::Builder do
+
+  subject(:builder) { described_class.new }
+
+  def output
+    builder.string
+  end
+
+  describe "#line" do
+
+    it "adds a line of text" do
+      builder.line("blah")
+      expect(output).to eq("blah\n")
+    end
+
+  end
+
+  describe "#row" do
+
+    it "adds two strings separated by spaces" do
+      builder.row("LHS", "RHS")
+      expect(output).to eq("    LHS    RHS\n")
+    end
+
+  end
+
+  context "with multiple rows" do
+
+    it "arranges them in two columns" do
+      builder.row("foo", "bar")
+      builder.row("flibble", "blurk")
+      builder.row("x", "y")
+      expect(output.lines).to eq [
+        "    foo        bar\n",
+        "    flibble    blurk\n",
+        "    x          y\n"
+      ]
+    end
+
+  end
+
+  context "with a mixture of lines and rows" do
+
+    it "still arranges them in two columns" do
+      builder.line("ABCDEFGHIJKLMNOP")
+      builder.row("flibble", "blurk")
+      builder.line("Another section heading")
+      builder.row("x", "y")
+      expect(output.lines).to eq [
+        "ABCDEFGHIJKLMNOP\n",
+        "    flibble    blurk\n",
+        "Another section heading\n",
+        "    x          y\n"
+      ]
+    end
+
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.3.1
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-17 00:00:00.000000000 Z
+date: 2019-07-11 00:00:00.000000000 Z
 dependencies: []
 description: |
   Clamp provides an object-model for command-line utilities.
@@ -61,6 +61,7 @@ files:
 - lib/clamp/version.rb
 - spec/clamp/command_group_spec.rb
 - spec/clamp/command_spec.rb
+- spec/clamp/help_spec.rb
 - spec/clamp/messages_spec.rb
 - spec/clamp/option/definition_spec.rb
 - spec/clamp/option_module_spec.rb
@@ -87,13 +88,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.5
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: a minimal framework for command-line utilities
 test_files:
 - spec/clamp/command_group_spec.rb
 - spec/clamp/command_spec.rb
+- spec/clamp/help_spec.rb
 - spec/clamp/messages_spec.rb
 - spec/clamp/option/definition_spec.rb
 - spec/clamp/option_module_spec.rb