clamp 0.6.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8d58bd5db9ac6b414b75d34a947149720909757
-  data.tar.gz: d61add398880941423c32234e2e9c1d57a1c38f3
+  metadata.gz: 2fb0beef002d49c64a0b25483def9f7f462e8798
+  data.tar.gz: f559b2abacf6f5323b7d168760516eb8a44145df
 SHA512:
-  metadata.gz: 7df1c2418b54a047af268ca936cabc828ecc2ac2f24bb9ca7a0b8a83768dd9b03679178d61ae79b18cd5a932626c5ae5da3d98d353d8517f2f668b00f4971cb4
-  data.tar.gz: 9298c454fd95f1ad91e4a852fabf51bc0ebb3b915c6164a0f2e012625b2ed1a8e170244c376ec6a54580583c471d3b7a0bd1cab45d5ac1a0437bc739989b819a
+  metadata.gz: 69b29bbdac7c60a424600633a20fe753bd0fe65d872d07e19bcfb482b9218107ec1bba2912d8daf2778604bdaa36b361a107d895fd45b3d69e0b0686c71f6d88
+  data.tar.gz: 946e33f41aa952bcb9ae955621018f0d91843a2771151ba3d4b38661e107c88a0ee857e81d75f565efa6eced4bac8b29d3a7ceab7de93e9010f097e3b84d31ab

data/CHANGES.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.0.0 (2015-06-08)
+
+* Allow options to be `:hidden`.
+* I18N support.
+
 ## 0.6.5 (2015-05-02)
 
 * Catch signals and exit appropriately.

data/README.md

@@ -155,6 +155,15 @@ 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`).
 
+### Hidden options
+
+Declaring an option "`:hidden`" will cause it to be hidden from `--help` output.
+
+```ruby
+option "--some-option", "VALUE", "Just a little option", :hidden => true
+```
+
+
 Declaring parameters
 --------------------
 
@@ -375,6 +384,25 @@ Options:
     -h, --help                    print help
 ```
 
+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")
+  # ...
+}
+```
+See [messages.rb](https://github.com/mdub/clamp/blob/master/lib/clamp/messages.rb) for full list of available messages.
+
 License
 -------
 

data/lib/clamp/attribute/definition.rb

@@ -15,6 +15,9 @@ module Clamp
         if options.has_key?(:environment_variable)
           @environment_variable = options[:environment_variable]
         end
+        if options.has_key?(:hidden)
+          @hidden = options[:hidden]
+        end
       end
 
       attr_reader :description, :environment_variable
@@ -57,6 +60,10 @@ module Clamp
         @required
       end
 
+      def hidden?
+        @hidden
+      end
+
       def attribute_name
         @attribute_name ||= infer_attribute_name
       end

data/lib/clamp/attribute/instance.rb

@@ -69,7 +69,7 @@ module Clamp
         begin
           take(value)
         rescue ArgumentError => e
-          command.send(:signal_usage_error, "$#{attribute.environment_variable}: #{e.message}")
+          command.send(: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,4 @@
+require 'clamp/messages'
 require 'clamp/errors'
 require 'clamp/help'
 require 'clamp/option/declaration'
@@ -91,7 +92,7 @@ module Clamp
 
     def handle_remaining_arguments
       unless remaining_arguments.empty?
-        signal_usage_error "too many arguments"
+        signal_usage_error Clamp.message(:too_many_arguments)
       end
     end
 

data/lib/clamp/help.rb

@@ -1,4 +1,5 @@
 require 'stringio'
+require 'clamp/messages'
 
 module Clamp
 
@@ -41,12 +42,12 @@ module Clamp
       help.add_usage(invocation_path, usage_descriptions)
       help.add_description(description)
       if has_parameters?
-        help.add_list("Parameters", parameters)
+        help.add_list(Clamp.message(:parameters_heading), parameters)
       end
       if has_subcommands?
-        help.add_list("Subcommands", recognised_subcommands)
+        help.add_list(Clamp.message(:subcommands_heading), recognised_subcommands)
       end
-      help.add_list("Options", recognised_options)
+      help.add_list(Clamp.message(:options_heading), recognised_options)
       help.string
     end
 
@@ -61,7 +62,7 @@ module Clamp
       end
 
       def add_usage(invocation_path, usage_descriptions)
-        puts "Usage:"
+        puts Clamp.message(:usage_heading) + ":"
         usage_descriptions.each do |usage|
           puts "    #{invocation_path} #{usage}".rstrip
         end
@@ -78,7 +79,7 @@ module Clamp
 
       def add_list(heading, items)
         puts "\n#{heading}:"
-        items.each do |item|
+        items.reject { |i| i.respond_to?(:hidden?) && i.hidden? }.each do |item|
           label, description = item.help
           description.each_line do |line|
             puts DETAIL_FORMAT % [label, line]

data/lib/clamp/messages.rb

@@ -0,0 +1,71 @@
+module Clamp
+
+  module Messages
+
+    def messages=(new_messages)
+      messages.merge!(new_messages)
+    end
+
+    def message(key, options={})
+      format_string(messages.fetch(key), options)
+    end
+
+    def clear_messages!
+      init_default_messages
+    end
+
+    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"
+    }
+
+    def messages
+      unless defined?(@messages)
+        init_default_messages
+      end
+      @messages
+    end
+
+    def init_default_messages
+      @messages = DEFAULTS.clone
+    end
+
+    begin
+
+      ("%{foo}" % {:foo => "bar"}) # test Ruby 1.9 string interpolation
+
+      def format_string(format, params = {})
+        format % params
+      end
+
+    rescue ArgumentError
+
+      # string formatting for ruby 1.8
+      def format_string(format, params = {})
+        array_params = format.scan(/%[<{]([^>}]*)[>}]/).collect do |name|
+          name = name[0]
+          params[name.to_s] || params[name.to_sym]
+        end
+        format.gsub(/%[<]([^>]*)[>]/, '%').gsub(/%[{]([^}]*)[}]/, '%s') % array_params
+      end
+
+    end
+
+  end
+
+  extend Messages
+
+end

data/lib/clamp/option/parsing.rb

@@ -31,7 +31,7 @@ module Clamp
           begin
             option.of(self).take(value)
           rescue ArgumentError => e
-            signal_usage_error "option '#{switch}': #{e.message}"
+            signal_usage_error Clamp.message(:option_argument_error, :switch => switch, :message => e.message)
           end
 
         end
@@ -45,11 +45,11 @@ module Clamp
         self.class.recognised_options.each do |option|
           # If this option is required and the value is nil, there's an error.
           if option.required? and send(option.attribute_name).nil?
-            message = "option '#{option.switches.first}'"
             if option.environment_variable
-              message += " (or env #{option.environment_variable})"
+              message = Clamp.message(:option_or_env_required, :option => option.switches.first, :env => option.environment_variable)
+            else
+              message = Clamp.message(:option_required, :option => option.switches.first)
             end
-            message += " is required"
             signal_usage_error message
           end
         end
@@ -59,7 +59,7 @@ module Clamp
 
       def find_option(switch)
         self.class.find_option(switch) ||
-        signal_usage_error("Unrecognised option '#{switch}'")
+        signal_usage_error(Clamp.message(:unrecognised_option, :switch => switch))
       end
 
     end

data/lib/clamp/parameter/definition.rb

@@ -22,7 +22,7 @@ module Clamp
       end
 
       def consume(arguments)
-        raise ArgumentError, "no value provided" if required? && arguments.empty?
+        raise ArgumentError, Clamp.message(:no_value_provided) if required? && arguments.empty?
         arguments.shift(multivalued? ? arguments.length : 1)
       end
 

data/lib/clamp/parameter/parsing.rb

@@ -13,7 +13,7 @@ module Clamp
               parameter.of(self).take(value)
             end
           rescue ArgumentError => e
-            signal_usage_error "parameter '#{parameter.name}': #{e.message}"
+            signal_usage_error Clamp.message(:parameter_argument_error, :param => parameter.name, :message => e.message)
           end
         end
 

data/lib/clamp/subcommand/execution.rb

@@ -25,7 +25,7 @@ module Clamp
       end
 
       def find_subcommand_class(name)
-        subcommand_def = self.class.find_subcommand(name) || signal_usage_error("No such sub-command '#{name}'")
+        subcommand_def = self.class.find_subcommand(name) || signal_usage_error(Clamp.message(:no_such_subcommand, :name => name))
         subcommand_def.subcommand_class
       end
 

data/lib/clamp/version.rb

@@ -1,3 +1,3 @@
 module Clamp
-  VERSION = "0.6.5".freeze
+  VERSION = "1.0.0".freeze
 end

data/spec/clamp/messages_spec.rb

@@ -0,0 +1,44 @@
+
+require 'spec_helper'
+
+describe Clamp::Messages do
+
+  describe "message" do
+    before do
+      Clamp.messages = {
+        :too_many_arguments => "Way too many!",
+        :custom_message => "Say %<what>s to %<whom>s"
+      }
+    end
+
+    after do
+      Clamp.clear_messages!
+    end
+
+    it "allows setting custom messages" do
+      expect(Clamp.message(:too_many_arguments)).to eql "Way too many!"
+    end
+
+    it "fallbacks to a default message" do
+      expect(Clamp.message(:no_value_provided)).to eql "no value provided"
+    end
+
+    it "formats the message" do
+      expect(Clamp.message(:custom_message, :what => "hello", :whom => "Clamp")).to eql "Say hello to Clamp"
+    end
+  end
+
+  describe "clear_messages!" do
+    it "clears messages to the defualt state" do
+      default_msg = Clamp.message(:too_many_arguments).clone
+
+      Clamp.messages = {
+        :too_many_arguments => "Way too many!"
+      }
+      Clamp.clear_messages!
+
+      expect(Clamp.message(:too_many_arguments)).to eql default_msg
+    end
+  end
+
+end

data/spec/clamp/option/definition_spec.rb

@@ -257,4 +257,33 @@ describe Clamp::Option::Definition do
       end.to raise_error(ArgumentError)
     end
   end
+
+  describe "a hidden option" do
+    let(:option) { described_class.new("--unseen", :flag, "Something", :hidden => true) }
+    it "is hidden" do
+      expect(option).to be_hidden
+    end
+  end
+
+  describe "a hidden option in a command" do
+    let(:command_class) do
+      Class.new(Clamp::Command) do
+        option "--unseen", :flag, "Something", :hidden => true
+
+        def execute
+          # this space intentionally left blank
+        end
+      end
+    end
+
+    it "is not shown in the help" do
+      expect(command_class.help("foo")).not_to match /^ +--unseen +Something$/
+    end
+
+    it "sets the expected accessor" do
+      command = command_class.new("foo")
+      command.run(["--unseen"])
+      expect(command.unseen?).to be_truthy
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: clamp
 version: !ruby/object:Gem::Version
-  version: 0.6.5
+  version: 1.0.0
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-02 00:00:00.000000000 Z
+date: 2015-06-08 00:00:00.000000000 Z
 dependencies: []
 description: |
   Clamp provides an object-model for command-line utilities.
@@ -41,6 +41,7 @@ files:
 - lib/clamp/command.rb
 - lib/clamp/errors.rb
 - lib/clamp/help.rb
+- lib/clamp/messages.rb
 - lib/clamp/option/declaration.rb
 - lib/clamp/option/definition.rb
 - lib/clamp/option/parsing.rb
@@ -55,6 +56,7 @@ files:
 - lib/clamp/version.rb
 - spec/clamp/command_group_spec.rb
 - spec/clamp/command_spec.rb
+- spec/clamp/messages_spec.rb
 - spec/clamp/option/definition_spec.rb
 - spec/clamp/option_module_spec.rb
 - spec/clamp/parameter/definition_spec.rb
@@ -79,13 +81,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 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/messages_spec.rb
 - spec/clamp/option/definition_spec.rb
 - spec/clamp/option_module_spec.rb
 - spec/clamp/parameter/definition_spec.rb