toys-core 0.3.5 → 0.3.6

data/lib/toys/tool/acceptor.rb

@@ -0,0 +1,190 @@
+# 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
+  class Tool
+    ##
+    # An Acceptor validates and converts arguments. It is designed to be
+    # compatible with the OptionParser accept mechanism.
+    #
+    # First, an acceptor validates an argument via the {#match} method. This
+    # method should determine whether the argument is valid, and return
+    # information that will help with conversion of the argument.
+    #
+    # Second, an acceptor converts the argument from the input string to its
+    # final form via the {#convert} method.
+    #
+    # Finally, an acceptor has a name that may appear in help text for flags
+    # and arguments that use it.
+    #
+    class Acceptor
+      ##
+      # Create a base acceptor.
+      #
+      # The basic acceptor does not do any validation (i.e. it accepts all
+      # arguments). You may subclass this object and implement the {#match}
+      # method to change this behavior.
+      #
+      # The converter should take one or more arguments, the first of which is
+      # the entire argument string, and the others of which may be returned
+      # from validation. The converter should return the final converted value
+      # of the argument. If you do not provide a converter, this acceptor will
+      # set the final value to the input argument string by default.
+      # You may provide a converter either as a proc or a block.
+      #
+      # @param [String] name A visible name for the acceptor, shown in help.
+      # @param [Proc] converter A converter function. May also be given as a
+      #     block.
+      #
+      def initialize(name, converter = nil, &block)
+        @name = name
+        @converter = converter || block
+      end
+
+      ##
+      # Name of the acceptor
+      # @return [String]
+      #
+      attr_reader :name
+
+      ##
+      # Name of the acceptor as a string
+      # @return [String]
+      #
+      def to_s
+        name.to_s
+      end
+
+      ##
+      # Validate the given input.
+      #
+      # You may override this method to specify a validation function. For a
+      # valid input, the function must return either the original argument
+      # string, or an array of which the first element is the original argument
+      # string, and the remaining elements may comprise additional information.
+      # All returned information is then passed to the conversion function.
+      # Note that a MatchInfo object is a legitimate return value since it
+      # duck-types the appropriate array.
+      #
+      # For an invalid input, you should return a falsy value.
+      #
+      # The default implementation simply returns the original argument string,
+      # indicating all inputs are valid.
+      #
+      # @param [String] str Input argument string
+      # @return [String,Array]
+      #
+      def match(str)
+        str
+      end
+
+      ##
+      # Convert the given input.
+      #
+      # @param [String] str Original argument string
+      # @param [Object...] extra Zero or more additional arguments comprising
+      #     additional elements returned from the match function.
+      # @return [Object] The converted argument as it should be stored in the
+      #     context data.
+      #
+      def convert(str, *extra)
+        @converter ? @converter.call(str, *extra) : str
+      end
+    end
+
+    ##
+    # An acceptor that uses a regex to validate input.
+    #
+    class PatternAcceptor < Acceptor
+      ##
+      # Create an acceptor.
+      #
+      # You must provide a regular expression as a validator. You may also
+      # provide a converter.
+      #
+      # @param [String] name A visible name for the acceptor, shown in help.
+      # @param [Regexp] regex Regular expression defining value values.
+      # @param [Proc] converter A converter function. May also be given as a
+      #     block. Note that the converter will be passed all elements of
+      #     the MatchInfo.
+      #
+      def initialize(name, regex, converter = nil, &block)
+        super(name, converter, &block)
+        @regex = regex
+      end
+
+      ##
+      # Overrides match to match from the given regex.
+      #
+      def match(str)
+        @regex.match(str)
+      end
+    end
+
+    ##
+    # An acceptor that recognizes a fixed set of values.
+    #
+    # You provide a list of valid values. The input argument string will be
+    # matched against the string forms of these valid values. If it matches,
+    # the converter will return the actual value.
+    #
+    # For example, you could pass `[:one, :two, 3]` as the set of values. If
+    # an argument of `"two"` is passed in, the converter will yield a final
+    # value of the symbol `:two`. If an argument of "3" is passed in, the
+    # converter will yield the integer `3`. If an argument of "three" is
+    # passed in, the match will fail.
+    #
+    class EnumAcceptor < Acceptor
+      ##
+      # Create an acceptor.
+      #
+      # @param [String] name A visible name for the acceptor, shown in help.
+      # @param [Array] values Valid values.
+      #
+      def initialize(name, values)
+        super(name)
+        @values = Array(values).map { |v| [v.to_s, v] }
+      end
+
+      ##
+      # Overrides match to find the value.
+      #
+      def match(str)
+        @values.find { |s, _e| s == str }
+      end
+
+      ##
+      # Overrides convert to return the original element.
+      #
+      def convert(_str, elem)
+        elem
+      end
+    end
+  end
+end

data/lib/toys/tool/arg_definition.rb

@@ -0,0 +1,130 @@
+# 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.
+;
+
+require "optparse"
+
+require "toys/utils/wrappable_string"
+
+module Toys
+  class Tool
+    ##
+    # Representation of a formal positional argument
+    #
+    class ArgDefinition
+      ##
+      # Create an ArgDefinition
+      # @private
+      #
+      def initialize(key, type, accept, default, desc, long_desc, display_name)
+        @key = key
+        @type = type
+        @accept = accept
+        @default = default
+        @desc = Utils::WrappableString.make(desc)
+        @long_desc = Utils::WrappableString.make_array(long_desc)
+        @display_name = display_name || key.to_s.tr("-", "_").gsub(/\W/, "").upcase
+      end
+
+      ##
+      # Returns the key.
+      # @return [Symbol]
+      #
+      attr_reader :key
+
+      ##
+      # Type of this argument.
+      # @return [:required,:optional,:remaining]
+      #
+      attr_reader :type
+
+      ##
+      # Returns the acceptor, which may be `nil`.
+      # @return [Object]
+      #
+      attr_accessor :accept
+
+      ##
+      # Returns the default value, which may be `nil`.
+      # @return [Object]
+      #
+      attr_reader :default
+
+      ##
+      # 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 the displayable name.
+      # @return [String]
+      #
+      attr_accessor :display_name
+
+      ##
+      # Process the given value through the acceptor.
+      # May raise an exception if the acceptor rejected the input.
+      #
+      # @param [String] input Input value
+      # @return [Object] Accepted value
+      #
+      def process_value(input)
+        return input unless accept
+        result = input
+        optparse = ::OptionParser.new
+        optparse.accept(accept) if accept.is_a?(Acceptor)
+        optparse.on("--abc=VALUE", accept) { |v| result = v }
+        optparse.parse(["--abc", input])
+        result
+      end
+
+      ##
+      # Set description
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
+      #
+      def desc=(desc)
+        @desc = Utils::WrappableString.make(desc)
+      end
+
+      ##
+      # Set long description
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #
+      def long_desc=(long_desc)
+        @long_desc = Utils::WrappableString.make_array(long_desc)
+      end
+    end
+  end
+end

data/lib/toys/tool/flag_definition.rb

@@ -0,0 +1,322 @@
+# 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.
+;
+
+require "optparse"
+
+require "toys/utils/wrappable_string"
+
+module Toys
+  class Tool
+    ##
+    # Representation of a single flag.
+    #
+    class FlagSyntax
+      ##
+      # Parse flag syntax
+      # @param [String] str syntax.
+      #
+      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, :required, $2, $3)
+        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, :required, $2, $3)
+        else
+          raise ToolDefinitionError, "Illegal flag: #{str.inspect}"
+        end
+      end
+
+      attr_reader :original_str
+      attr_reader :flags
+      attr_reader :str_without_value
+      attr_reader :flag_style
+      attr_reader :flag_type
+      attr_reader :value_type
+      attr_reader :value_delim
+      attr_reader :value_label
+      attr_reader :canonical_str
+
+      ## @private
+      def configure_canonical(canonical_flag_type, canonical_value_type,
+                              canonical_value_label, canonical_value_delim)
+        return unless flag_type.nil?
+        @flag_type = canonical_flag_type
+        return unless canonical_flag_type == :value
+        @value_type = canonical_value_type
+        canonical_value_delim = "" if canonical_value_delim == "=" && flag_style == "-"
+        canonical_value_delim = "=" if canonical_value_delim == "" && flag_style == "--"
+        @value_delim = canonical_value_delim
+        @value_label = canonical_value_label
+        label = @value_type == :optional ? "[#{@value_label}]" : @value_label
+        @canonical_str = "#{str_without_value}#{@value_delim}#{label}"
+      end
+
+      private
+
+      def setup(original_str, flags, str_without_value, flag_style, flag_type, value_type,
+                value_delim, value_label)
+        @original_str = original_str
+        @flags = flags
+        @str_without_value = str_without_value
+        @flag_style = flag_style
+        @flag_type = flag_type
+        @value_type = value_type
+        @value_delim = value_delim
+        @value_label = value_label ? value_label.upcase : value_label
+        @canonical_str = original_str
+      end
+    end
+
+    ##
+    # Representation of a formal set of flags that set a particular context
+    # key. The flags within a single FlagDefinition are synonyms.
+    #
+    class FlagDefinition
+      ##
+      # The default handler replaces the previous value.
+      # @return [Proc]
+      #
+      DEFAULT_HANDLER = ->(val, _prev) { val }
+
+      ##
+      # Create a FlagDefinition
+      # @private
+      #
+      def initialize(key, flags, used_flags, report_collisions, accept, handler, default)
+        @key = key
+        @flag_syntax = flags.map { |s| FlagSyntax.new(s) }
+        @accept = accept
+        @handler = handler || DEFAULT_HANDLER
+        @desc = Utils::WrappableString.make(desc)
+        @long_desc = Utils::WrappableString.make_array(long_desc)
+        @default = default
+        needs_val = (!accept.nil? && accept != ::TrueClass && accept != ::FalseClass) ||
+                    (!default.nil? && default != true && default != false)
+        create_default_flag_if_needed(needs_val)
+        remove_used_flags(used_flags, report_collisions)
+        canonicalize(needs_val)
+      end
+
+      ##
+      # Returns the key.
+      # @return [Symbol]
+      #
+      attr_reader :key
+
+      ##
+      # Returns an array of FlagSyntax for the flags.
+      # @return [Array<FlagSyntax>]
+      #
+      attr_reader :flag_syntax
+
+      ##
+      # Returns the acceptor, which may be `nil`.
+      # @return [Object]
+      #
+      attr_reader :accept
+
+      ##
+      # Returns the default value, which may be `nil`.
+      # @return [Object]
+      #
+      attr_reader :default
+
+      ##
+      # 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 the handler for setting/updating the value.
+      # @return [Proc]
+      #
+      attr_reader :handler
+
+      ##
+      # The type of flag. Possible values are `:boolean` for a simple boolean
+      # switch, or `:value` for a flag that sets a value.
+      # @return [:boolean,:value]
+      #
+      attr_reader :flag_type
+
+      ##
+      # The type of value. Set to `:required` or `:optional` if the flag type
+      # is `:value`. Otherwise set to `nil`.
+      # @return [:required,:optional,nil]
+      #
+      attr_reader :value_type
+
+      ##
+      # The string label for the value as it should display in help, or `nil`
+      # if the flag type is not `:value`.
+      # @return [String,nil]
+      #
+      attr_reader :value_label
+
+      ##
+      # The value delimiter, which may be `""`, `" "`, or `"="`. Set to `nil`
+      # if the flag type is not `:value`.
+      # @return [String,nil]
+      #
+      attr_reader :value_delim
+
+      ##
+      # Returns an array of FlagSyntax including only single-dash flags
+      # @return [Array<FlagSyntax>]
+      #
+      def single_flag_syntax
+        @single_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == "-" }
+      end
+
+      ##
+      # Returns an array of FlagSyntax including only double-dash flags
+      # @return [Array<FlagSyntax>]
+      #
+      def double_flag_syntax
+        @double_flag_syntax ||= flag_syntax.find_all { |ss| ss.flag_style == "--" }
+      end
+
+      ##
+      # Returns the list of effective flags used.
+      # @return [Array<String>]
+      #
+      def effective_flags
+        @effective_flags ||= flag_syntax.map(&:flags).flatten
+      end
+
+      ##
+      # All optparser flags and acceptor if present
+      # @return [Array]
+      #
+      def optparser_info
+        @optparser_info ||= flag_syntax.map(&:canonical_str) + Array(accept)
+      end
+
+      ##
+      # Returns true if this flag is active. That is, it has a nonempty
+      # flags list.
+      # @return [Boolean]
+      #
+      def active?
+        !effective_flags.empty?
+      end
+
+      ##
+      # Set description
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
+      #
+      def desc=(desc)
+        @desc = Utils::WrappableString.make(desc)
+      end
+
+      ##
+      # Set long description
+      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      #
+      def long_desc=(long_desc)
+        @long_desc = Utils::WrappableString.make_array(long_desc)
+      end
+
+      private
+
+      def create_default_flag_if_needed(needs_val)
+        return unless @flag_syntax.empty?
+        canonical_flag = key.to_s.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "").sub(/^-+/, "")
+        unless canonical_flag.empty?
+          flag = needs_val ? "--#{canonical_flag} VALUE" : "--#{canonical_flag}"
+          @flag_syntax << FlagSyntax.new(flag)
+        end
+      end
+
+      def remove_used_flags(used_flags, report_collisions)
+        @flag_syntax.select! do |fs|
+          fs.flags.all? do |f|
+            collision = used_flags.include?(f)
+            if collision && report_collisions
+              raise ToolDefinitionError,
+                    "Cannot use flag #{f.inspect} because it is already assigned or reserved."
+            end
+            !collision
+          end
+        end
+        used_flags.concat(effective_flags.uniq)
+      end
+
+      def canonicalize(needs_val)
+        @flag_type = needs_val ? :value : nil
+        @value_type = nil
+        @value_label = needs_val ? "VALUE" : nil
+        @value_delim = " "
+        single_flag_syntax.each do |flag|
+          analyze_flag_syntax(flag)
+        end
+        double_flag_syntax.each do |flag|
+          analyze_flag_syntax(flag)
+        end
+        @flag_type ||= :boolean
+        flag_syntax.each do |flag|
+          flag.configure_canonical(@flag_type, @value_type, @value_label, @value_delim)
+        end
+      end
+
+      def analyze_flag_syntax(flag)
+        return if flag.flag_type.nil?
+        if !@flag_type.nil? && @flag_type != flag.flag_type
+          raise ToolDefinitionError, "Cannot have both value and boolean flags for #{key.inspect}"
+        end
+        @flag_type = flag.flag_type
+        return unless @flag_type == :value
+        if !@value_type.nil? && @value_type != flag.value_type
+          raise ToolDefinitionError,
+                "Cannot have both required and optional values for flag #{key.inspect}"
+        end
+        @value_type = flag.value_type
+        @value_label = flag.value_label
+        @value_delim = flag.value_delim
+      end
+    end
+  end
+end