toys-core 0.6.1 → 0.7.0

data/lib/toys/standard_middleware.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+;
+
+module Toys
+  ##
+  # Namespace for standard middleware classes.
+  #
+  module StandardMiddleware
+    ## @private
+    COMMON_FLAG_GROUP = :__common
+
+    ## @private
+    def self.append_common_flag_group(tool)
+      tool.add_flag_group(type: :optional, name: COMMON_FLAG_GROUP,
+                          desc: "Common Flags", report_collisions: false)
+      COMMON_FLAG_GROUP
+    end
+  end
+end

data/lib/toys/standard_middleware/add_verbosity_flags.rb

@@ -82,6 +82,7 @@ module Toys
       #
       def config(tool_definition, _loader)
         unless tool_definition.argument_parsing_disabled?
+          StandardMiddleware.append_common_flag_group(tool_definition)
           add_verbose_flags(tool_definition)
           add_quiet_flags(tool_definition)
         end
@@ -99,7 +100,8 @@ module Toys
             report_collisions: false,
             handler: ->(_val, cur) { cur + 1 },
             desc: "Increase verbosity",
-            long_desc: "Increase verbosity, causing additional logging levels to display."
+            long_desc: "Increase verbosity, causing additional logging levels to display.",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
       end
@@ -112,7 +114,8 @@ module Toys
             report_collisions: false,
             handler: ->(_val, cur) { cur - 1 },
             desc: "Decrease verbosity",
-            long_desc: "Decrease verbosity, causing fewer logging levels to display."
+            long_desc: "Decrease verbosity, causing fewer logging levels to display.",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
       end

data/lib/toys/standard_middleware/show_help.rb

@@ -232,6 +232,7 @@ module Toys
       #
       def config(tool_definition, loader)
         unless tool_definition.argument_parsing_disabled?
+          StandardMiddleware.append_common_flag_group(tool_definition)
           has_subtools = loader.has_subtools?(tool_definition.full_name)
           help_flags = add_help_flags(tool_definition)
           usage_flags = add_usage_flags(tool_definition)
@@ -323,7 +324,8 @@ module Toys
           tool_definition.add_flag(
             SHOW_HELP_KEY, flags,
             report_collisions: false,
-            desc: "Display help for this tool"
+            desc: "Display help for this tool",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags
@@ -335,7 +337,8 @@ module Toys
           tool_definition.add_flag(
             SHOW_USAGE_KEY, flags,
             report_collisions: false,
-            desc: "Display a brief usage string for this tool"
+            desc: "Display a brief usage string for this tool",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags
@@ -347,7 +350,8 @@ module Toys
           tool_definition.add_flag(
             SHOW_LIST_KEY, flags,
             report_collisions: false,
-            desc: "List the subtools under this tool"
+            desc: "List the subtools under this tool",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags
@@ -362,7 +366,8 @@ module Toys
             RECURSIVE_SUBTOOLS_KEY, flags,
             report_collisions: false, default: @default_recursive,
             desc: "List all subtools recursively when displaying help" \
-                  " (default is #{@default_recursive})"
+                  " (default is #{@default_recursive})",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags
@@ -374,7 +379,8 @@ module Toys
           tool_definition.add_flag(
             SEARCH_STRING_KEY, flags,
             report_collisions: false,
-            desc: "Search subtools for the given regular expression when displaying help"
+            desc: "Search subtools for the given regular expression when displaying help",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags
@@ -390,7 +396,8 @@ module Toys
             SHOW_ALL_SUBTOOLS_KEY, flags,
             report_collisions: false, default: @default_show_all_subtools,
             desc: "List all subtools including hidden subtools and namespaces" \
-                  " (default is #{@default_show_all_subtools})"
+                  " (default is #{@default_show_all_subtools})",
+            group: StandardMiddleware::COMMON_FLAG_GROUP
           )
         end
         flags

data/lib/toys/utils/exec.rb

@@ -48,8 +48,11 @@ module Toys
     # *  **:env** (Hash) Environment variables to pass to the subprocess
     # *  **:logger** (Logger) Logger to use for logging the actual command.
     #    If not present, the command is not logged.
-    # *  **:log_level** (Integer) Log level for logging the actual command.
-    #    Defaults to Logger::INFO if not present.
+    # *  **:log_level** (Integer,false) Level for logging the actual command.
+    #    Defaults to Logger::INFO if not present. You may also pass `false` to
+    #    disable logging of the command.
+    # *  **:log_cmd** (String) The string logged for the actual command.
+    #    Defaults to the `inspect` representation of the command.
     # *  **:background** (Boolean) Runs the process in the background,
     #    returning a controller object instead of a result object.
     # *  **:in** Connects the input stream of the subprocess. See the section
@@ -456,7 +459,7 @@ module Toys
         end
 
         ##
-        # Captures the remaining data in the stdandard output stream.
+        # Captures the remaining data in the standard output stream.
         # After calling this, do not read directly from the stream.
         #
         def capture_out
@@ -464,7 +467,7 @@ module Toys
         end
 
         ##
-        # Captures the remaining data in the stdandard error stream.
+        # Captures the remaining data in the standard error stream.
         # After calling this, do not read directly from the stream.
         #
         def capture_err

data/lib/toys/utils/gems.rb

@@ -129,7 +129,7 @@ module Toys
           if @suppress_confirm
             @default_confirm
           else
-            @terminal.confirm("Gem needed: #{requirements_text}. Install?",
+            @terminal.confirm("Gem needed: #{requirements_text}. Install? ",
                               default: @default_confirm)
           end
         unless response

data/lib/toys/utils/help_text.rb

@@ -193,7 +193,7 @@ module Toys
 
         def assemble
           add_synopsis_section
-          add_flags_section
+          add_flag_group_sections
           add_positional_arguments_section if @tool.runnable?
           add_subtool_list_section
           @result = @lines.join("\n") + "\n"
@@ -224,12 +224,14 @@ module Toys
           ([@binary_name] + @tool.full_name + ["TOOL", "[ARGUMENTS...]"]).join(" ")
         end
 
-        def add_flags_section
-          return if @tool.flag_definitions.empty?
-          @lines << ""
-          @lines << "Flags:"
-          @tool.flag_definitions.each do |flag|
-            add_flag(flag)
+        def add_flag_group_sections
+          @tool.flag_groups.each do |group|
+            next if group.empty?
+            @lines << ""
+            @lines << group.desc.to_s + ":"
+            group.flag_definitions.each do |flag|
+              add_flag(flag)
+            end
           end
         end
 
@@ -328,7 +330,7 @@ module Toys
           add_name_section
           add_synopsis_section
           add_description_section
-          add_flags_section
+          add_flag_group_sections
           add_positional_arguments_section
           add_subtool_list_section
           add_source_section
@@ -358,13 +360,9 @@ module Toys
         def add_synopsis_section
           @lines << ""
           @lines << bold("SYNOPSIS")
-          if !@subtools.empty? && !@tool.runnable?
-            add_synopsis_clause(namespace_synopsis)
-          end
+          add_synopsis_clause(namespace_synopsis) if !@subtools.empty? && !@tool.runnable?
           add_synopsis_clause(tool_synopsis)
-          if !@subtools.empty? && @tool.runnable?
-            add_synopsis_clause(namespace_synopsis)
-          end
+          add_synopsis_clause(namespace_synopsis) if !@subtools.empty? && @tool.runnable?
         end
 
         def add_synopsis_clause(synopsis)
@@ -377,8 +375,19 @@ module Toys
 
         def tool_synopsis
           synopsis = [full_binary_name]
-          @tool.flag_definitions.each do |flag_def|
-            synopsis << "[#{flag_spec_string(flag_def)}]"
+          @tool.flag_groups.each do |flag_group|
+            case flag_group
+            when Definition::FlagGroup::Required
+              add_required_group_to_synopsis(flag_group, synopsis)
+            when Definition::FlagGroup::ExactlyOne
+              add_exactly_one_group_to_synopsis(flag_group, synopsis)
+            when Definition::FlagGroup::AtMostOne
+              add_at_most_one_group_to_synopsis(flag_group, synopsis)
+            when Definition::FlagGroup::AtLeastOne
+              add_at_least_one_group_to_synopsis(flag_group, synopsis)
+            else
+              add_ordinary_group_to_synopsis(flag_group, synopsis)
+            end
           end
           @tool.arg_definitions.each do |arg_info|
             synopsis << arg_name(arg_info)
@@ -386,6 +395,57 @@ module Toys
           wrap_indent_indent2(Utils::WrappableString.new(synopsis))
         end
 
+        def add_ordinary_group_to_synopsis(flag_group, synopsis)
+          flag_group.flag_definitions.each do |flag_def|
+            synopsis << "[#{flag_spec_string(flag_def, true)}]"
+          end
+        end
+
+        def add_required_group_to_synopsis(flag_group, synopsis)
+          flag_group.flag_definitions.each do |flag_def|
+            synopsis << "(#{flag_spec_string(flag_def, true)})"
+          end
+        end
+
+        def add_exactly_one_group_to_synopsis(flag_group, synopsis)
+          return if flag_group.empty?
+          synopsis << "("
+          first = true
+          flag_group.flag_definitions.each do |flag_def|
+            if first
+              first = false
+            else
+              synopsis << "|"
+            end
+            synopsis << flag_spec_string(flag_def, true)
+          end
+          synopsis << ")"
+        end
+
+        def add_at_most_one_group_to_synopsis(flag_group, synopsis)
+          return if flag_group.empty?
+          synopsis << "["
+          first = true
+          flag_group.flag_definitions.each do |flag_def|
+            if first
+              first = false
+            else
+              synopsis << "|"
+            end
+            synopsis << flag_spec_string(flag_def, true)
+          end
+          synopsis << "]"
+        end
+
+        def add_at_least_one_group_to_synopsis(flag_group, synopsis)
+          return if flag_group.empty?
+          synopsis << "("
+          flag_group.flag_definitions.each do |flag_def|
+            synopsis << "[#{flag_spec_string(flag_def, true)}]"
+          end
+          synopsis << ")"
+        end
+
         def namespace_synopsis
           synopsis = [full_binary_name, underline("TOOL"), "[#{underline('ARGUMENTS')}...]"]
           wrap_indent_indent2(Utils::WrappableString.new(synopsis))
@@ -412,18 +472,26 @@ module Toys
           end
         end
 
-        def add_flags_section
-          return if @tool.flag_definitions.empty?
-          @lines << ""
-          @lines << bold("FLAGS")
-          precede_with_blank = false
-          @tool.flag_definitions.each do |flag|
-            add_indented_section(flag_spec_string(flag), flag, precede_with_blank)
-            precede_with_blank = true
+        def add_flag_group_sections
+          @tool.flag_groups.each do |group|
+            next if group.empty?
+            @lines << ""
+            @lines << bold(group.desc.to_s.upcase)
+            precede_with_blank = false
+            unless group.long_desc.empty?
+              wrap_indent(group.long_desc).each do |line|
+                @lines << indent_str(line)
+              end
+              precede_with_blank = true
+            end
+            group.flag_definitions.each do |flag|
+              add_indented_section(flag_spec_string(flag), flag, precede_with_blank)
+              precede_with_blank = true
+            end
           end
         end
 
-        def flag_spec_string(flag)
+        def flag_spec_string(flag, in_synopsis = false)
           flag.flag_syntax.map do |fs|
             str = bold(fs.str_without_value)
             if fs.flag_type != :value
@@ -433,7 +501,7 @@ module Toys
             else
               "#{str}#{fs.value_delim}#{underline(fs.value_label)}"
             end
-          end.join(", ")
+          end.join(in_synopsis ? " | " : ", ")
         end
 
         def add_positional_arguments_section

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-08 00:00:00.000000000 Z
+date: 2019-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -128,10 +128,12 @@ files:
 - lib/toys/definition/alias.rb
 - lib/toys/definition/arg.rb
 - lib/toys/definition/flag.rb
+- lib/toys/definition/flag_group.rb
 - lib/toys/definition/source_info.rb
 - lib/toys/definition/tool.rb
 - lib/toys/dsl/arg.rb
 - lib/toys/dsl/flag.rb
+- lib/toys/dsl/flag_group.rb
 - lib/toys/dsl/tool.rb
 - lib/toys/errors.rb
 - lib/toys/input_file.rb
@@ -139,6 +141,7 @@ files:
 - lib/toys/middleware.rb
 - lib/toys/mixin.rb
 - lib/toys/runner.rb
+- lib/toys/standard_middleware.rb
 - lib/toys/standard_middleware/add_verbosity_flags.rb
 - lib/toys/standard_middleware/handle_usage_errors.rb
 - lib/toys/standard_middleware/set_default_descriptions.rb