toys-core 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac33c1214b7ae27c8ecea97837cd1ba186dfc3715db69ef52ef9dc24e56f8064
-  data.tar.gz: 9e8cc340e38cd320893cf9ee47c31c138ea42f9850c8efebb315a9e60182d791
+  metadata.gz: 9266b9c87907b8844cd20529fd8102391737845d2e85cecc6674d6657a9d0d27
+  data.tar.gz: da4bf58af8136859679ee2d8123e649310af0b82dbe896730af081d4e18c2c5d
 SHA512:
-  metadata.gz: e77ed0de1cc6ee14300c4787c334f3ecd97e338d16df4e9004b303a618163b6cd07709cf1d956e9278b9e52624105cdfd87010c55d111580a164a9a6cddf9b4f
-  data.tar.gz: 02521cfe60b37bb36c7a5550a2c33a42e4de6f74350fa3b852c333642fc7aa0e7e7b4523a94219236f1523ad7a9c3f5297a2467b2a03b5337234fb059eac730c
+  metadata.gz: 511416609364d830a23c27279ddcd545182cbca9fc0fc2727f832c75d4cfedaab0e4faa2d23456c880d202c4fb18e95239948bfbbdbe46035ccc008d0d84996b
+  data.tar.gz: '075912df93384641e0c7b43807571d8ac4873af0906f022265db1483b66258fea88e7026d0a35c4716a5f96ac237ef9965b53398cdcf31d7254c2b5e2fb85895'

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 0.7.0 / 2019-01-23
+
+* ADDED: Flag groups, which enforce policies around which flags are required.
+* CHANGED: Flags within a group are sorted in help screens.
+* CHANGED: Canonical flag within a flag definition is now the first rather than the last.
+
 ### 0.6.1 / 2019-01-07
 
 * FIXED: The presence of aliases caused subtool listing to crash.

data/lib/toys-core.rb

@@ -52,11 +52,6 @@ module Toys
   #
   module StandardMixins; end
 
-  ##
-  # Namespace for standard middleware classes.
-  #
-  module StandardMiddleware; end
-
   ##
   # Namespace for common utility classes.
   #
@@ -69,10 +64,12 @@ require "toys/definition/acceptor"
 require "toys/definition/alias"
 require "toys/definition/arg"
 require "toys/definition/flag"
+require "toys/definition/flag_group"
 require "toys/definition/source_info"
 require "toys/definition/tool"
 require "toys/dsl/arg"
 require "toys/dsl/flag"
+require "toys/dsl/flag_group"
 require "toys/dsl/tool"
 require "toys/errors"
 require "toys/input_file"
@@ -80,6 +77,7 @@ require "toys/loader"
 require "toys/middleware"
 require "toys/mixin"
 require "toys/runner"
+require "toys/standard_middleware"
 require "toys/template"
 require "toys/tool"
 require "toys/utils/exec"

data/lib/toys/core_version.rb

@@ -34,5 +34,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.6.1"
+  CORE_VERSION = "0.7.0"
 end

data/lib/toys/definition/flag.rb

@@ -41,24 +41,24 @@ module Toys
       #
       def initialize(str)
         case str
-        when /^(-[\?\w])$/
-          setup(str, [$1], $1, "-", nil, nil, nil, nil)
-        when /^(-[\?\w])( ?)\[(\w+)\]$/
-          setup(str, [$1], $1, "-", :value, :optional, $2, $3)
-        when /^(-[\?\w])\[( )(\w+)\]$/
-          setup(str, [$1], $1, "-", :value, :optional, $2, $3)
-        when /^(-[\?\w])( ?)(\w+)$/
-          setup(str, [$1], $1, "-", :value, :required, $2, $3)
+        when /^(-([\?\w]))$/
+          setup(str, [$1], $1, $2, "-", nil, nil, nil, nil)
+        when /^(-([\?\w]))( ?)\[(\w+)\]$/
+          setup(str, [$1], $1, $2, "-", :value, :optional, $3, $4)
+        when /^(-([\?\w]))\[( )(\w+)\]$/
+          setup(str, [$1], $1, $2, "-", :value, :optional, $3, $4)
+        when /^(-([\?\w]))( ?)(\w+)$/
+          setup(str, [$1], $1, $2, "-", :value, :required, $3, $4)
         when /^--\[no-\](\w[\?\w-]*)$/
-          setup(str, ["--#{$1}", "--no-#{$1}"], str, "--", :boolean, nil, nil, nil)
-        when /^(--\w[\?\w-]*)$/
-          setup(str, [$1], $1, "--", nil, nil, nil, nil)
-        when /^(--\w[\?\w-]*)([= ])\[(\w+)\]$/
-          setup(str, [$1], $1, "--", :value, :optional, $2, $3)
-        when /^(--\w[\?\w-]*)\[([= ])(\w+)\]$/
-          setup(str, [$1], $1, "--", :value, :optional, $2, $3)
-        when /^(--\w[\?\w-]*)([= ])(\w+)$/
-          setup(str, [$1], $1, "--", :value, :required, $2, $3)
+          setup(str, ["--#{$1}", "--no-#{$1}"], str, $1, "--", :boolean, nil, nil, nil)
+        when /^(--(\w[\?\w-]*))$/
+          setup(str, [$1], $1, $2, "--", nil, nil, nil, nil)
+        when /^(--(\w[\?\w-]*))([= ])\[(\w+)\]$/
+          setup(str, [$1], $1, $2, "--", :value, :optional, $3, $4)
+        when /^(--(\w[\?\w-]*))\[([= ])(\w+)\]$/
+          setup(str, [$1], $1, $2, "--", :value, :optional, $3, $4)
+        when /^(--(\w[\?\w-]*))([= ])(\w+)$/
+          setup(str, [$1], $1, $2, "--", :value, :required, $3, $4)
         else
           raise ToolDefinitionError, "Illegal flag: #{str.inspect}"
         end
@@ -67,6 +67,7 @@ module Toys
       attr_reader :original_str
       attr_reader :flags
       attr_reader :str_without_value
+      attr_reader :sort_str
       attr_reader :flag_style
       attr_reader :flag_type
       attr_reader :value_type
@@ -91,11 +92,12 @@ module Toys
 
       private
 
-      def setup(original_str, flags, str_without_value, flag_style, flag_type, value_type,
-                value_delim, value_label)
+      def setup(original_str, flags, str_without_value, sort_str, flag_style, flag_type,
+                value_type, value_delim, value_label)
         @original_str = original_str
         @flags = flags
         @str_without_value = str_without_value
+        @sort_str = sort_str
         @flag_style = flag_style
         @flag_type = flag_type
         @value_type = value_type
@@ -120,7 +122,9 @@ module Toys
       # Create a Flag definition
       # @private
       #
-      def initialize(key, flags, used_flags, report_collisions, accept, handler, default)
+      def initialize(key, flags, used_flags, report_collisions, accept, handler,
+                     default, display_name, group)
+        @group = group
         @key = key
         @flag_syntax = flags.map { |s| FlagSyntax.new(s) }
         @accept = accept
@@ -133,8 +137,15 @@ module Toys
         create_default_flag_if_needed(needs_val)
         remove_used_flags(used_flags, report_collisions)
         canonicalize(needs_val)
+        summarize(display_name)
       end
 
+      ##
+      # Returns the flag group containing this flag
+      # @return [Toys::Definition::FlagGroup]
+      #
+      attr_reader :group
+
       ##
       # Returns the key.
       # @return [Symbol]
@@ -205,6 +216,18 @@ module Toys
       #
       attr_reader :value_delim
 
+      ##
+      # Returns the display name of this flag.
+      # @return [String]
+      #
+      attr_reader :display_name
+
+      ##
+      # Returns a string that can be used to sort this flag
+      # @return [String]
+      #
+      attr_reader :sort_str
+
       ##
       # Returns an array of FlagSyntax including only single-dash flags
       # @return [Array<FlagSyntax>]
@@ -302,10 +325,10 @@ module Toys
         @value_type = nil
         @value_label = needs_val ? "VALUE" : nil
         @value_delim = " "
-        single_flag_syntax.each do |flag|
+        single_flag_syntax.reverse_each do |flag|
           analyze_flag_syntax(flag)
         end
-        double_flag_syntax.each do |flag|
+        double_flag_syntax.reverse_each do |flag|
           analyze_flag_syntax(flag)
         end
         @flag_type ||= :boolean
@@ -330,6 +353,18 @@ module Toys
         @value_label = flag.value_label
         @value_delim = flag.value_delim
       end
+
+      def summarize(name)
+        @display_name =
+          name ||
+          double_flag_syntax.first&.canonical_str ||
+          single_flag_syntax.first&.canonical_str ||
+          key.to_s
+        @sort_str =
+          double_flag_syntax.first&.sort_str ||
+          single_flag_syntax.first&.sort_str ||
+          ""
+      end
     end
   end
 end

data/lib/toys/definition/flag_group.rb

@@ -0,0 +1,205 @@
+# 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
+  module Definition
+    ##
+    # Representation of a group of flags with the same requirement settings.
+    #
+    class FlagGroup
+      ##
+      # Create a flag group.
+      # @private
+      #
+      def initialize(name, desc, long_desc)
+        @name = name
+        @desc = Utils::WrappableString.make(desc || default_desc)
+        @long_desc = Utils::WrappableString.make_array(long_desc || default_long_desc)
+        @flag_definitions = []
+      end
+
+      ##
+      # Returns the symbolic name for this group
+      # @return [String,Symbol,nil]
+      #
+      attr_reader :name
+
+      ##
+      # Returns the short description string.
+      # @return [Toys::Utils::WrappableString]
+      #
+      attr_reader :desc
+
+      ##
+      # Returns the long description strings as an array.
+      # @return [Array<Toys::Utils::WrappableString>]
+      #
+      attr_reader :long_desc
+
+      ##
+      # Returns an array of flags that are in this group.
+      # Do not modify the returned array.
+      # @return [Array<Toys::Definition::Flag>]
+      #
+      attr_reader :flag_definitions
+
+      ##
+      # Returns true if this group is empty
+      # @return [Boolean]
+      #
+      def empty?
+        flag_definitions.empty?
+      end
+
+      ## @private
+      def <<(flag)
+        flag_definitions << flag
+      end
+
+      ## @private
+      def default_desc
+        "Flags"
+      end
+
+      ## @private
+      def default_long_desc
+        nil
+      end
+
+      ## @private
+      def validation_error(_seen)
+        nil
+      end
+
+      ##
+      # A FlagGroup containing all required flags
+      #
+      class Required < FlagGroup
+        ## @private
+        def validation_error(seen)
+          flag_definitions.each do |flag|
+            unless seen.include?(flag.key)
+              return "Flag \"#{flag.display_name}\" is required"
+            end
+          end
+          nil
+        end
+
+        ## @private
+        def default_desc
+          "Required Flags"
+        end
+
+        ## @private
+        def default_long_desc
+          "These flags are required."
+        end
+      end
+
+      ##
+      # A FlagGroup containing all optional flags
+      #
+      class Optional < FlagGroup
+      end
+
+      ##
+      # A FlagGroup in which exactly one flag must be set
+      #
+      class ExactlyOne < FlagGroup
+        ## @private
+        def validation_error(seen)
+          set_flag = nil
+          flag_definitions.each do |flag|
+            if seen.include?(flag.key)
+              if set_flag
+                return "Exactly one out of group \"#{desc}\" is required, but both" \
+                  " \"#{set_flag.display_name}\" and \"#{flag.display_name}\" were set"
+              else
+                set_flag = flag
+              end
+            end
+          end
+          return "Exactly one out of group \"#{desc}\" is required" unless set_flag
+          nil
+        end
+
+        ## @private
+        def default_long_desc
+          "Exactly one of these flags must be set."
+        end
+      end
+
+      ##
+      # A FlagGroup in which at most one flag must be set
+      #
+      class AtMostOne < FlagGroup
+        ## @private
+        def validation_error(seen)
+          set_flag = nil
+          flag_definitions.each do |flag|
+            if seen.include?(flag.key)
+              if set_flag
+                return "At most one out of group \"#{desc}\" is required, but both" \
+                  " \"#{set_flag.display_name}\" and \"#{flag.display_name}\" were set"
+              else
+                set_flag = flag
+              end
+            end
+          end
+          nil
+        end
+
+        ## @private
+        def default_long_desc
+          "At most one of these flags must be set."
+        end
+      end
+
+      ##
+      # A FlagGroup in which at least one flag must be set
+      #
+      class AtLeastOne < FlagGroup
+        ## @private
+        def validation_error(seen)
+          flag_definitions.each do |flag|
+            return nil if seen.include?(flag.key)
+          end
+          "At least one out of group \"#{desc}\" is required"
+        end
+
+        ## @private
+        def default_long_desc
+          "At least one of these flags must be set."
+        end
+      end
+    end
+  end
+end

data/lib/toys/definition/tool.rb

@@ -101,6 +101,10 @@ module Toys
         @used_flags = []
         @initializers = []
 
+        default_flag_group = Definition::FlagGroup.new(nil, nil, nil)
+        @flag_groups = [default_flag_group]
+        @flag_group_names = {nil => default_flag_group}
+
         @flag_definitions = []
         @required_arg_definitions = []
         @optional_arg_definitions = []
@@ -142,6 +146,12 @@ module Toys
       #
       attr_reader :long_desc
 
+      ##
+      # Return a list of all defined flag groups, in order.
+      # @return [Array<Toys::Definition::FlagGroup>]
+      #
+      attr_reader :flag_groups
+
       ##
       # Return a list of all defined flags.
       # @return [Array<Toys::Definition::Flag>]
@@ -491,6 +501,47 @@ module Toys
         self
       end
 
+      ##
+      # Add a flag group to the group list.
+      #
+      # @param [Symbol] type The type of group. Allowed values: `:required`,
+      #     `:optional`, `:exactly_one`, `:at_most_one`, `:at_least_one`.
+      #     Default is `:optional`.
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      #     description for the group. See {Toys::Definition::Tool#desc=} for a
+      #     description of  allowed formats. Defaults to `"Flags"`.
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #     Long description for the flag group. See
+      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
+      #     formats. Defaults to the empty array.
+      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     name.
+      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      #     the given name is already taken. If `false`, ignore. Default is
+      #     `true`.
+      # @param [Boolean] prepend If `true`, prepend rather than append the
+      #     group to the list. Default is `false`.
+      #
+      def add_flag_group(type: :optional, desc: nil, long_desc: nil,
+                         name: nil, report_collisions: true, prepend: false)
+        if !name.nil? && @flag_group_names.key?(name)
+          return self unless report_collisions
+          raise ToolDefinitionError, "Flag group #{name} already exists"
+        end
+        unless type.is_a?(::Class)
+          type = Utils::ModuleLookup.to_module_name(type)
+          type = Definition::FlagGroup.const_get(type)
+        end
+        group = type.new(name, desc, long_desc)
+        @flag_group_names[name] = group unless name.nil?
+        if prepend
+          @flag_groups.unshift(group)
+        else
+          @flag_groups.push(group)
+        end
+        self
+      end
+
       ##
       # Add a flag to the current tool. Each flag must specify a key which
       # the script may use to obtain the flag value from the context.
@@ -514,6 +565,9 @@ module Toys
       # @param [Boolean] report_collisions Raise an exception if a flag is
       #     requested that is already in use or marked as disabled. Default is
       #     true.
+      # @param [Toys::Definition::FlagGroup,String,Symbol,nil] group Group for
+      #     this flag. You may provide a group name, a FlagGroup object, or
+      #     `nil` which denotes the default group.
       # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
       #     description for the flag. See {Toys::Definition::Tool#desc=} for a
       #     description of  allowed formats. Defaults to the empty string.
@@ -521,18 +575,28 @@ module Toys
       #     Long description for the flag. See
       #     {Toys::Definition::Tool#long_desc=} for a description of allowed
       #     formats. Defaults to the empty array.
+      # @param [String] display_name A display name for this flag, used in help
+      #     text and error messages.
       #
       def add_flag(key, flags = [],
                    accept: nil, default: nil, handler: nil,
-                   report_collisions: true,
-                   desc: nil, long_desc: nil)
+                   report_collisions: true, group: nil,
+                   desc: nil, long_desc: nil, display_name: nil)
+        unless group.is_a?(Definition::FlagGroup)
+          group_name = group
+          group = @flag_group_names[group_name]
+          raise ToolDefinitionError, "No such flag group: #{group_name.inspect}" if group.nil?
+        end
         check_definition_state(is_arg: true)
         accept = resolve_acceptor(accept)
         flag_def = Definition::Flag.new(key, flags, @used_flags, report_collisions,
-                                        accept, handler, default)
+                                        accept, handler, default, display_name, group)
         flag_def.desc = desc if desc
         flag_def.long_desc = long_desc if long_desc
-        @flag_definitions << flag_def if flag_def.active?
+        if flag_def.active?
+          @flag_definitions << flag_def
+          group << flag_def
+        end
         @default_data[key] = default
         self
       end
@@ -732,6 +796,9 @@ module Toys
             end
             config_proc.call
           end
+          flag_groups.each do |flag_group|
+            flag_group.flag_definitions.sort_by!(&:sort_str)
+          end
           @definition_finished = true
         end
         self