toys-core 0.3.2 → 0.3.3

data/lib/toys/middleware/add_verbosity_switches.rb

@@ -80,7 +80,7 @@ module Toys
                                                             DEFAULT_VERBOSE_SWITCHES)
         unless verbose_switches.empty?
           tool.add_switch(Context::VERBOSITY, *verbose_switches,
-                          doc: "Increase verbosity",
+                          docs: "Increase verbosity",
                           handler: ->(_val, cur) { cur + 1 },
                           only_unique: true)
         end
@@ -88,7 +88,7 @@ module Toys
                                                           DEFAULT_QUIET_SWITCHES)
         unless quiet_switches.empty?
           tool.add_switch(Context::VERBOSITY, *quiet_switches,
-                          doc: "Decrease verbosity",
+                          docs: "Decrease verbosity",
                           handler: ->(_val, cur) { cur - 1 },
                           only_unique: true)
         end

data/lib/toys/middleware/handle_usage_errors.rb

@@ -27,6 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
+require "highline"
+
 require "toys/middleware/base"
 require "toys/utils/usage"
 
@@ -54,9 +56,11 @@ module Toys
       #
       def execute(context)
         if context[Context::USAGE_ERROR]
+          width = ::HighLine.new.output_cols
+          usage = Utils::Usage.from_context(context)
           puts(context[Context::USAGE_ERROR])
           puts("")
-          puts(Utils::Usage.from_context(context).string(show_path: true))
+          puts(usage.string(show_path: true, wrap_width: width))
           context.exit(@exit_code)
         else
           yield

data/lib/toys/middleware/show_usage.rb

@@ -27,6 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
+require "highline"
+
 require "toys/middleware/base"
 require "toys/utils/usage"
 
@@ -112,10 +114,10 @@ module Toys
                                                          DEFAULT_HELP_SWITCHES)
         is_default = !tool.includes_executor? && @fallback_execution
         if !help_switches.empty?
-          doc = "Show help message"
-          doc << " (default for groups)" if is_default
+          docs = "Show help message"
+          docs << " (default for groups)" if is_default
           tool.add_switch(:_help, *help_switches,
-                          doc: doc,
+                          docs: docs,
                           default: is_default,
                           only_unique: true)
         elsif is_default
@@ -134,9 +136,11 @@ module Toys
       def execute(context)
         if context[:_help]
           usage = Utils::Usage.from_context(context)
+          width = ::HighLine.new.output_cols
           puts(usage.string(recursive: context[:_recursive_subcommands],
                             search: context[:_search_subcommands],
-                            show_path: context.verbosity > 0))
+                            show_path: context.verbosity > 0,
+                            wrap_width: width))
         else
           yield
         end
@@ -150,8 +154,8 @@ module Toys
         unless recursive_switches.empty?
           tool.add_switch(:_recursive_subcommands, *recursive_switches,
                           default: @default_recursive,
-                          doc: "Show all subcommands recursively" \
-                               " (default is #{@default_recursive})",
+                          docs: "Show all subcommands recursively" \
+                                " (default is #{@default_recursive})",
                           only_unique: true)
         end
       end
@@ -161,7 +165,7 @@ module Toys
                                                            DEFAULT_SEARCH_SWITCHES)
         unless search_switches.empty?
           tool.add_switch(:_search_subcommands, *search_switches,
-                          doc: "Search subcommands for the given term",
+                          docs: "Search subcommands for the given term",
                           only_unique: true)
         end
       end

data/lib/toys/middleware/show_version.rb

@@ -77,7 +77,7 @@ module Toys
         version = @version_displayer.call(tool)
         if version
           tool.add_switch(:_show_version, *@version_switches,
-                          doc: "Show version",
+                          docs: "Show version",
                           handler: ->(_val, _prev) { version },
                           only_unique: true)
         end

data/lib/toys/templates/clean.rb

@@ -61,7 +61,7 @@ module Toys
         tool(template.name) do
           desc "Clean built files and directories."
 
-          use :file_utils
+          use :fileutils
 
           execute do
             files = []

data/lib/toys/templates/gem_build.rb

@@ -88,8 +88,9 @@ module Toys
         tool(template.name) do
           desc "#{task_type} the gem: #{template.gem_name}"
 
-          use :file_utils
           use :exec
+          use :fileutils
+          use :highline
 
           execute do
             configure_exec(exit_on_nonzero_status: true)
@@ -104,6 +105,7 @@ module Toys
                 logger.error "Cannot push the gem when there are uncommited changes"
                 exit(1)
               end
+              exit(1) unless agree("Release #{gemfile}? (y/n) ")
               sh "gem push pkg/#{gemfile}"
               if template.tag
                 sh "git tag v#{version}"

data/lib/toys/templates/minitest.rb

@@ -89,9 +89,9 @@ module Toys
           switch(
             :warnings, "-w", "--[no-]warnings",
             default: template.warnings,
-            doc: "Turn on Ruby warnings (defaults to #{template.warnings})"
+            docs: "Turn on Ruby warnings (defaults to #{template.warnings})"
           )
-          remaining_args(:tests, doc: "Paths to the tests to run (defaults to all tests)")
+          remaining_args(:tests, docs: "Paths to the tests to run (defaults to all tests)")
 
           execute do
             ruby_args = []

data/lib/toys/tool.rb

@@ -29,6 +29,8 @@
 
 require "optparse"
 
+require "toys/utils/wrappable_string"
+
 module Toys
   ##
   # A Tool is a single command that can be invoked using Toys.
@@ -50,8 +52,8 @@ module Toys
       @definition_path = nil
       @definition_finished = false
 
-      @desc = nil
-      @long_desc = nil
+      @desc = []
+      @long_desc = []
 
       @default_data = {}
       @switch_definitions = []
@@ -168,19 +170,25 @@ module Toys
     ##
     # Returns the effective short description for this tool. This will be
     # displayed when this tool is listed in a command list.
-    # @return [String]
     #
-    def effective_desc
-      @desc || ""
+    # @param [Integer,nil] wrap_width Wrap wrappable strings to the given
+    #     width, or `nil` for no wrapping.
+    # @return [Array<String>]
+    #
+    def effective_desc(wrap_width: nil)
+      Tool.resolve_wrapping(@desc, wrap_width)
     end
 
     ##
     # Returns the effective long description for this tool. This will be
     # displayed as part of the usage for this particular tool.
-    # @return [String]
     #
-    def effective_long_desc
-      @long_desc || @desc || ""
+    # @param [Integer,nil] wrap_width Wrap wrappable strings to the given
+    #     width, or `nil` for no wrapping.
+    # @return [Array<String>]
+    #
+    def effective_long_desc(wrap_width: nil)
+      Tool.resolve_wrapping(@long_desc.empty? ? @desc : @long_desc, wrap_width)
     end
 
     ##
@@ -188,7 +196,7 @@ module Toys
     # @return [Boolean]
     #
     def includes_description?
-      !@long_desc.nil? || !@desc.nil?
+      !@long_desc.empty? || !@desc.empty?
     end
 
     ##
@@ -224,7 +232,7 @@ module Toys
     # @return [Array<String>]
     #
     def used_switches
-      @switch_definitions.reduce([]) { |used, sdef| used + sdef.switches }.uniq
+      @switch_definitions.reduce([]) { |used, sdef| used + sdef.effective_switches }.uniq
     end
 
     ##
@@ -246,21 +254,21 @@ module Toys
     ##
     # Set the short description.
     #
-    # @param [String] str The short description
+    # @param [String,Array<String>] strs The short description
     #
-    def desc=(str)
+    def desc=(strs)
       check_definition_state
-      @desc = str
+      @desc = Tool.canonicalize_desc(strs)
     end
 
     ##
     # Set the long description.
     #
-    # @param [String] str The long description
+    # @param [String,Array<String>] strs The long description
     #
-    def long_desc=(str)
+    def long_desc=(strs)
       check_definition_state
-      @long_desc = str
+      @long_desc = Tool.canonicalize_desc(strs)
     end
 
     ##
@@ -315,8 +323,9 @@ module Toys
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if this switch is not provided on the command
     #     line. Defaults to `nil`.
-    # @param [String,nil] doc The documentation for the switch, which appears
-    #     in the usage documentation. Defaults to `nil` for no documentation.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
+    #     the switch. Defaults to empty array.
     # @param [Boolean] only_unique If true, any switches that are already
     #     defined in this tool are removed from this switch. For example, if
     #     an earlier switch uses `-a`, and this switch wants to use both
@@ -329,14 +338,9 @@ module Toys
     #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
     #
     def add_switch(key, *switches,
-                   accept: nil, default: nil, doc: nil, only_unique: false, handler: nil)
+                   accept: nil, default: nil, docs: nil, only_unique: false, handler: nil)
       check_definition_state
-      switches << "--#{Tool.canonical_switch(key)}=VALUE" if switches.empty?
-      bad_switch = switches.find { |s| Tool.extract_switch(s).empty? }
-      if bad_switch
-        raise ToolDefinitionError, "Illegal switch: #{bad_switch.inspect}"
-      end
-      switch_info = SwitchDefinition.new(key, switches + Array(accept) + Array(doc), handler)
+      switch_info = SwitchDefinition.new(key, switches, accept, docs, handler)
       if only_unique
         switch_info.remove_switches(used_switches)
       end
@@ -355,13 +359,14 @@ module Toys
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
     # @param [Object,nil] accept An OptionParser acceptor. Optional.
-    # @param [String,nil] doc The documentation for the switch, which appears
-    #     in the usage documentation. Defaults to `nil` for no documentation.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
+    #     the arg. Defaults to empty array.
     #
-    def add_required_arg(key, accept: nil, doc: nil)
+    def add_required_arg(key, accept: nil, docs: nil)
       check_definition_state
       @default_data[key] = nil
-      @required_arg_definitions << ArgDefinition.new(key, accept, Array(doc))
+      @required_arg_definitions << ArgDefinition.new(key, accept, docs)
       self
     end
 
@@ -377,13 +382,14 @@ module Toys
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if this argument is not provided on the command
     #     line. Defaults to `nil`.
-    # @param [String,nil] doc The documentation for the argument, which appears
-    #     in the usage documentation. Defaults to `nil` for no documentation.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
+    #     the arg. Defaults to empty array.
     #
-    def add_optional_arg(key, accept: nil, default: nil, doc: nil)
+    def add_optional_arg(key, accept: nil, default: nil, docs: nil)
       check_definition_state
       @default_data[key] = default
-      @optional_arg_definitions << ArgDefinition.new(key, accept, Array(doc))
+      @optional_arg_definitions << ArgDefinition.new(key, accept, docs)
       self
     end
 
@@ -398,14 +404,14 @@ module Toys
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if no unmatched arguments are provided on the
     #     command line. Defaults to the empty array `[]`.
-    # @param [String,nil] doc The documentation for the remaining arguments,
-    #     which appears in the usage documentation. Defaults to `nil` for no
-    #     documentation.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
+    #     the args. Defaults to empty array.
     #
-    def set_remaining_args(key, accept: nil, default: [], doc: nil)
+    def set_remaining_args(key, accept: nil, default: [], docs: nil)
       check_definition_state
       @default_data[key] = default
-      @remaining_args_definition = ArgDefinition.new(key, accept, Array(doc))
+      @remaining_args_definition = ArgDefinition.new(key, accept, docs)
       self
     end
 
@@ -452,51 +458,58 @@ module Toys
       self
     end
 
-    private
-
-    def make_config_proc(middleware, next_config)
-      proc { middleware.config(self, &next_config) }
-    end
-
-    def check_definition_state
-      if @definition_finished
-        raise ToolDefinitionError,
-              "Defintion of tool #{display_name.inspect} is already finished"
-      end
-    end
-
-    class << self
-      ## @private
-      def canonical_switch(name)
-        name.to_s.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "")
-      end
-
-      ## @private
-      def extract_switch(str)
-        if !str.is_a?(String)
-          []
-        elsif str =~ /^(-[\?\w])(\s?\w+)?$/
-          [$1]
+    ##
+    # Representation of a single switch
+    #
+    class SwitchSyntax
+      ##
+      # Parse switch syntax
+      # @param [String] str syntax.
+      #
+      def initialize(str)
+        if str =~ /^(-[\?\w])(\s?(\w+))?$/
+          setup(str, [$1], $1, "-", " ", $3)
         elsif str =~ /^--\[no-\](\w[\?\w-]*)$/
-          ["--#{$1}", "--no-#{$1}"]
-        elsif str =~ /^(--\w[\?\w-]*)([=\s]\w+)?$/
-          [$1]
+          setup(str, ["--#{$1}", "--no-#{$1}"], "--[no-]#{$1}", "--", nil, nil)
+        elsif str =~ /^(--\w[\?\w-]*)(([=\s])(\w+))?$/
+          setup(str, [$1], $1, "--", $3, $4)
         else
-          []
+          raise ToolDefinitionError, "Illegal switch: #{str.inspect}"
         end
       end
+
+      attr_reader :str
+      attr_reader :str_without_value
+      attr_reader :switches
+      attr_reader :switch_style
+      attr_reader :value_delim
+      attr_reader :value_label
+
+      private
+
+      def setup(str, switches, str_without_value, switch_style, value_delim, value_label)
+        @str = str
+        @switches = switches
+        @str_without_value = str_without_value
+        @switch_style = switch_style
+        @value_delim = value_delim
+        @value_label = value_label
+      end
     end
 
     ##
-    # Representation of a formal switch.
+    # Representation of a formal set of switches.
     #
     class SwitchDefinition
       ##
       # Create a SwitchDefinition
+      # @private
       #
       # @param [Symbol] key This switch will set the given context key.
-      # @param [Array<String>] optparse_info The switch definition in
-      #     OptionParser format
+      # @param [Array<String>] switches Switches in OptionParser format
+      # @param [Object] accept An OptionParser acceptor, or `nil` for none.
+      # @param [String,Toys::Utils::WrappableString,
+      #     Array<String,Toys::Utils::WrappableString>] docs Documentation
       # @param [Proc,nil] handler An optional handler for setting/updating the
       #     value. If given, it should take two arguments, the new given value
       #     and the previous value, and it should return the new value that
@@ -504,11 +517,15 @@ module Toys
       #     the previous value. i.e. the default is effectively
       #     `-> (val, _prev) { val }`.
       #
-      def initialize(key, optparse_info, handler = nil)
+      def initialize(key, switches, accept, docs, handler = nil)
         @key = key
-        @optparse_info = optparse_info
+        switches = ["--#{Tool.canonical_switch(key)}=VALUE"] if switches.empty?
+        @switch_syntax = switches.map { |s| SwitchSyntax.new(s) }
+        @accept = accept
+        @docs = Tool.canonicalize_desc(docs)
         @handler = handler || ->(val, _prev) { val }
-        @switches = nil
+        reset_data
+        @effective_switches = nil
       end
 
       ##
@@ -518,10 +535,22 @@ module Toys
       attr_reader :key
 
       ##
-      # Returns the OptionParser definition.
+      # Returns an array of SwitchSyntax for the switches.
+      # @return [Array<SwitchSyntax>]
+      #
+      attr_reader :switch_syntax
+
+      ##
+      # Returns the acceptor, which may be `nil`.
+      # @return [Object]
+      #
+      attr_reader :accept
+
+      ##
+      # Returns the documentation strings, which may be the empty array.
       # @return [Array<String>]
       #
-      attr_reader :optparse_info
+      attr_reader :docs
 
       ##
       # Returns the handler.
@@ -530,11 +559,45 @@ module Toys
       attr_reader :handler
 
       ##
-      # Returns the list of switches used.
+      # Returns an array of SwitchSyntax including only single-dash switches
+      # @return [Array<SwitchSyntax>]
+      #
+      def single_switch_syntax
+        @single_switch_syntax ||= switch_syntax.find_all { |ss| ss.switch_style == "-" }
+      end
+
+      ##
+      # Returns an array of SwitchSyntax including only double-dash switches
+      # @return [Array<SwitchSyntax>]
+      #
+      def double_switch_syntax
+        @double_switch_syntax ||= switch_syntax.find_all { |ss| ss.switch_style == "--" }
+      end
+
+      ##
+      # Returns the list of effective switches used.
       # @return [Array<String>]
       #
-      def switches
-        @switches ||= optparse_info.map { |s| Tool.extract_switch(s) }.flatten
+      def effective_switches
+        @effective_switches ||= switch_syntax.map(&:switches).flatten
+      end
+
+      ##
+      # Returns the documentation strings with wrapping resolved.
+      #
+      # @param [Integer,nil] width Wrapping width, or `nil` to use default.
+      # @return [Array<String>]
+      #
+      def wrapped_docs(width)
+        Tool.resolve_wrapping(docs, width)
+      end
+
+      ##
+      # All optparser switches and acceptor if present
+      # @return [Array]
+      #
+      def optparser_info
+        @optparser_info ||= switch_syntax.map(&:str) + Array(accept)
       end
 
       ##
@@ -543,7 +606,25 @@ module Toys
       # @return [Boolean]
       #
       def active?
-        !switches.empty?
+        !effective_switches.empty?
+      end
+
+      ##
+      # Return the value label if one exists
+      # @return [String,nil]
+      #
+      def value_label
+        find_canonical_value_label
+        @value_label
+      end
+
+      ##
+      # Return the value delimiter if one exists
+      # @return [String,nil]
+      #
+      def value_delim
+        find_canonical_value_label
+        @value_delim
       end
 
       ##
@@ -551,12 +632,43 @@ module Toys
       # @param [Array<String>] switches
       #
       def remove_switches(switches)
-        @optparse_info.select! do |s|
-          Tool.extract_switch(s).all? { |ss| !switches.include?(ss) }
+        @switch_syntax.select! do |ss|
+          ss.switches.all? { |s| !switches.include?(s) }
         end
-        @switches = nil
+        reset_data
         self
       end
+
+      private
+
+      def reset_data
+        @effective_switches = nil
+        @optparser_info = nil
+        @single_switch_syntax = nil
+        @double_switch_syntax = nil
+        @value_label = nil
+        @value_delim = nil
+      end
+
+      def find_canonical_value_label
+        return if @value_delim
+        double_switch_syntax.reverse_each do |ss|
+          next unless ss.value_label
+          @value_label = ss.value_label
+          @value_delim = ss.value_delim
+          break
+        end
+        return if @value_delim
+        single_switch_syntax.reverse_each do |ss|
+          next unless ss.value_label
+          @value_label = ss.value_label
+          @value_delim = ss.value_delim
+          break
+        end
+        return if @value_delim
+        @value_label = nil
+        @value_delim = ""
+      end
     end
 
     ##
@@ -565,15 +677,17 @@ module Toys
     class ArgDefinition
       ##
       # Create an ArgDefinition
+      # @private
       #
       # @param [Symbol] key This argument will set the given context key.
-      # @param [Object] accept An OptionParser acceptor
-      # @param [Array<String>] doc An array of documentation strings
+      # @param [Object] accept An OptionParser acceptor, or `nil` for none.
+      # @param [String,Toys::Utils::WrappableString,
+      #     Array<String,Toys::Utils::WrappableString>] docs Documentation
       #
-      def initialize(key, accept, doc)
+      def initialize(key, accept, docs)
         @key = key
         @accept = accept
-        @doc = doc
+        @docs = Tool.canonicalize_desc(docs)
       end
 
       ##
@@ -583,16 +697,16 @@ module Toys
       attr_reader :key
 
       ##
-      # Returns the acceptor.
+      # Returns the acceptor, which may be `nil`.
       # @return [Object]
       #
       attr_reader :accept
 
       ##
-      # Returns the documentation strings.
-      # @return [Array<String>]
+      # Returns the documentation strings, which may be the empty array.
+      # @return [Array<String,Toys::Utils::WrappableString>]
       #
-      attr_reader :doc
+      attr_reader :docs
 
       ##
       # Return a canonical name for this arg. Used in usage documentation.
@@ -603,22 +717,68 @@ module Toys
         Tool.canonical_switch(key)
       end
 
+      ##
+      # Returns the documentation strings with wrapping resolved.
+      #
+      # @param [Integer,nil] width Wrapping width, or `nil` to use default.
+      # @return [Array<String>]
+      #
+      def wrapped_docs(width)
+        Tool.resolve_wrapping(docs, width)
+      end
+
       ##
       # Process the given value through the acceptor.
+      # May raise an exception if the acceptor rejected the input.
       #
-      # @private
+      # @param [String] input Input value
+      # @return [Object] Accepted value
       #
-      def process_value(val)
-        return val unless accept
+      def process_value(input)
+        return input unless accept
         n = canonical_name
-        result = val
+        result = input
         optparse = ::OptionParser.new
         optparse.on("--#{n}=VALUE", accept) { |v| result = v }
-        optparse.parse(["--#{n}", val])
+        optparse.parse(["--#{n}", input])
         result
       end
     end
 
+    private
+
+    def make_config_proc(middleware, next_config)
+      proc { middleware.config(self, &next_config) }
+    end
+
+    def check_definition_state
+      if @definition_finished
+        raise ToolDefinitionError,
+              "Defintion of tool #{display_name.inspect} is already finished"
+      end
+    end
+
+    class << self
+      ## @private
+      def canonical_switch(name)
+        name.to_s.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "")
+      end
+
+      ## @private
+      def canonicalize_desc(desc)
+        Array(desc).map do |d|
+          d.is_a?(Utils::WrappableString) ? d : d.split("\n")
+        end.flatten.freeze
+      end
+
+      ## @private
+      def resolve_wrapping(strs, wrap_width)
+        strs.map do |s|
+          s.is_a?(Utils::WrappableString) && !wrap_width.nil? ? s.wrap(wrap_width) : s.to_s
+        end.flatten
+      end
+    end
+
     ##
     # An internal class that manages execution of a tool
     # @private
@@ -667,7 +827,7 @@ module Toys
         optparse.new
         optparse.new
         @tool.switch_definitions.each do |switch|
-          optparse.on(*switch.optparse_info) do |val|
+          optparse.on(*switch.optparser_info) do |val|
             @data[switch.key] = switch.handler.call(val, @data[switch.key])
           end
         end
@@ -714,9 +874,8 @@ module Toys
 
       def create_child_context(cli)
         context = Context.new(cli, @data)
-        @tool.modules.each do |mod|
-          context.extend(mod)
-        end
+        modules = @tool.modules
+        context.extend(*modules) unless modules.empty?
         @tool.helpers.each do |name, block|
           context.define_singleton_method(name, &block)
         end