toys-core 0.3.5 → 0.3.6

data/lib/toys/middleware/{show_version.rb → show_root_version.rb}

@@ -33,11 +33,10 @@ require "toys/utils/line_output"
 module Toys
   module Middleware
     ##
-    # A middleware that displays a version string for certain tools if the
-    # `--version` flag is given. You can specify which tools respond to
-    # this flag, and the string that will be displayed.
+    # A middleware that displays a version string for the root tool if the
+    # `--version` flag is given.
     #
-    class ShowVersion < Base
+    class ShowRootVersion < Base
       ##
       # Default version flags
       # @return [Array<String>]
@@ -45,32 +44,27 @@ module Toys
       DEFAULT_VERSION_FLAGS = ["--version"].freeze
 
       ##
-      # Return a simple version displayer that returns the given string for
-      # the root tool.
+      # Default description for the version flags
+      # @return [String]
       #
-      # @return [Proc]
-      #
-      def self.root_version_displayer(version)
-        proc { |tool| tool.root? ? version : false }
-      end
+      DEFAULT_VERSION_FLAG_DESC = "Display the version".freeze
 
       ##
       # Create a ShowVersion middleware
       #
-      # @param [Proc] version_displayer A proc that takes a tool and returns
-      #     either the version string that should be displayed, or a falsy
-      #     value to indicate the tool should not have a `--version` flag.
-      #     Defaults to a "null" displayer that returns false for all tools.
+      # @param [String] version_string The string that should be displayed.
       # @param [Array<String>] version_flags A list of flags that should
       #     trigger displaying the version. Default is
       #     {DEFAULT_VERSION_FLAGS}.
       # @param [IO] stream Output stream to write to. Default is stdout.
       #
-      def initialize(version_displayer: nil,
+      def initialize(version_string: nil,
                      version_flags: DEFAULT_VERSION_FLAGS,
+                     version_flag_desc: DEFAULT_VERSION_FLAG_DESC,
                      stream: $stdout)
-        @version_displayer = version_displayer || proc { |_| false }
+        @version_string = version_string
         @version_flags = version_flags
+        @version_flag_desc = version_flag_desc
         @output = Utils::LineOutput.new(stream)
       end
 
@@ -78,12 +72,9 @@ module Toys
       # Adds the version flag if requested.
       #
       def config(tool, _loader)
-        version = @version_displayer.call(tool)
-        if version
+        if @version_string && tool.root?
           tool.add_flag(:_show_version, @version_flags,
-                        desc: "Display the version",
-                        handler: ->(_val, _prev) { version },
-                        only_unique: true)
+                        report_collisions: false, desc: @version_flag_desc)
         end
         yield
       end
@@ -93,7 +84,7 @@ module Toys
       #
       def execute(context)
         if context[:_show_version]
-          @output.puts context[:_show_version]
+          @output.puts(@version_string)
         else
           yield
         end

data/lib/toys/tool.rb

@@ -40,6 +40,27 @@ module Toys
   # tool is executed.
   #
   class Tool
+    ##
+    # Built-in acceptors (i.e. those recognized by OptionParser).
+    # You can reference these acceptors directly. Otherwise, you have to add
+    # one explicitly to the tool using {Tool#add_acceptor}.
+    #
+    OPTPARSER_ACCEPTORS = [
+      ::Object,
+      ::NilClass,
+      ::String,
+      ::Integer,
+      ::Float,
+      ::Numeric,
+      ::TrueClass,
+      ::FalseClass,
+      ::Array,
+      ::Regexp,
+      ::OptionParser::DecimalInteger,
+      ::OptionParser::OctalInteger,
+      ::OptionParser::DecimalNumeric
+    ].freeze
+
     ##
     # Create a new tool.
     #
@@ -56,6 +77,10 @@ module Toys
       @long_desc = []
 
       @default_data = {}
+      @acceptors = {}
+      OPTPARSER_ACCEPTORS.each { |a| @acceptors[a] = a }
+      @used_flags = []
+
       @flag_definitions = []
       @required_arg_definitions = []
       @optional_arg_definitions = []
@@ -110,6 +135,12 @@ module Toys
     #
     attr_reader :remaining_args_definition
 
+    ##
+    # Return a list of flags that have been used in the flag definitions.
+    # @return [Array<String>]
+    #
+    attr_reader :used_flags
+
     ##
     # Return the default argument data.
     # @return [Hash]
@@ -234,11 +265,18 @@ module Toys
     end
 
     ##
-    # Returns a list of flags used by this tool.
-    # @return [Array<String>]
+    # Returns a list of all custom acceptors used by this tool.
+    # @return [Array<Toys::Tool::Acceptor>]
     #
-    def used_flags
-      flag_definitions.reduce([]) { |used, fdef| used + fdef.effective_flags }.uniq
+    def custom_acceptors
+      result = []
+      flag_definitions.each do |f|
+        result << f.accept if f.accept.is_a?(Acceptor)
+      end
+      arg_definitions.each do |a|
+        result << a.accept if a.accept.is_a?(Acceptor)
+      end
+      result.uniq
     end
 
     ##
@@ -268,7 +306,7 @@ module Toys
     #
     def desc=(desc)
       check_definition_state
-      @desc = Tool.canonicalize_desc(desc)
+      @desc = Utils::WrappableString.make(desc)
     end
 
     ##
@@ -282,22 +320,7 @@ module Toys
     #
     def long_desc=(descs)
       check_definition_state
-      @long_desc = Tool.canonicalize_long_desc(descs)
-    end
-
-    ##
-    # Set the long description strings.
-    #
-    # Each string may be provided as a {Toys::Utils::WrappableString}, a single
-    # string (which will be wrapped), or an array of strings, which will be
-    # interpreted as string fragments that will be concatenated and wrapped.
-    #
-    # @param [Toys::Utils::WrappableString,String,Array<String>...] descs
-    #
-    def populate_long_desc(*descs)
-      check_definition_state
-      @long_desc = Tool.canonicalize_long_desc(descs)
-      self
+      @long_desc = Utils::WrappableString.make_array(descs)
     end
 
     ##
@@ -340,6 +363,17 @@ module Toys
       self
     end
 
+    ##
+    # Add an acceptor to the tool. This acceptor may be refereneced by name
+    # when adding a flag or an arg.
+    #
+    # @param [Toys::Tool::Acceptor] acceptor The acceptor to add.
+    #
+    def add_acceptor(acceptor)
+      @acceptors[acceptor.name] = acceptor
+      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.
@@ -348,38 +382,60 @@ module Toys
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
     # @param [Array<String>] flags The flags in OptionParser format.
-    # @param [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] accept An acceptor that validates and/or converts the
+    #     value. You may provide either the name of an acceptor you have
+    #     defined, or one of the default acceptors provided by OptionParser.
+    #     Optional. If not specified, accepts any value as a string.
     # @param [Object] default The default value. This is the value that will
     #     be set in the context if this flag is not provided on the command
     #     line. Defaults to `nil`.
+    # @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
+    #     should be set. The default handler simply replaces the previous
+    #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
+    # @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 [String,Array<String>,Toys::Utils::WrappableString] desc Short
     #     description for the flag. See {Toys::Tool#desc=} for a description of
     #     allowed formats. Defaults to the empty string.
     # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
     #     Long description for the flag. See {Toys::Tool#long_desc=} for a
     #     description of allowed formats. Defaults to the empty array.
-    # @param [Boolean] only_unique If true, any flags that are already
-    #     defined in this tool are removed from this flag. For example, if
-    #     an earlier flag uses `-a`, and this flag wants to use both
-    #     `-a` and `-b`, then only `-b` will be assigned to this flag.
-    #     Defaults to false.
-    # @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
-    #     should be set. The default handler simply replaces the previous
-    #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
     #
     def add_flag(key, flags = [],
-                 accept: nil, default: nil, handler: nil, desc: nil, long_desc: nil,
-                 only_unique: false)
+                 accept: nil, default: nil, handler: nil,
+                 report_collisions: true,
+                 desc: nil, long_desc: nil)
       check_definition_state
-      flag_def = FlagDefinition.new(key, flags, accept, handler, desc, long_desc, default)
-      flag_def.remove_flags(used_flags) if only_unique
+      accept = resolve_acceptor(accept)
+      flag_def = FlagDefinition.new(key, flags, @used_flags, report_collisions,
+                                    accept, handler, default)
+      flag_def.desc = desc if desc
+      flag_def.long_desc = long_desc if long_desc
       @flag_definitions << flag_def if flag_def.active?
       @default_data[key] = default
       self
     end
 
+    ##
+    # Mark one or more flags as disabled, preventing their use by any
+    # subsequent flag definition. This may be used to prevent middleware from
+    # defining a particular flag.
+    #
+    # @param [String...] flags The flags to disable
+    #
+    def disable_flag(*flags)
+      flags = flags.uniq
+      intersection = @used_flags & flags
+      unless intersection.empty?
+        raise ToolDefinitionError, "Cannot disable flags already used: #{intersection.inspect}"
+      end
+      @used_flags.concat(flags)
+      self
+    end
+
     ##
     # Add a required positional argument to the current tool. You must specify
     # a key which the script may use to obtain the argument value from the
@@ -387,7 +443,10 @@ 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 [Object] accept An acceptor that validates and/or converts the
+    #     value. You may provide either the name of an acceptor you have
+    #     defined, or one of the default acceptors provided by OptionParser.
+    #     Optional. If not specified, accepts any value as a string.
     # @param [String] display_name A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
@@ -399,7 +458,8 @@ module Toys
     #
     def add_required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
       check_definition_state
-      arg_def = ArgDefinition.new(key, :required, accept, desc, long_desc, display_name)
+      accept = resolve_acceptor(accept)
+      arg_def = ArgDefinition.new(key, :required, accept, nil, desc, long_desc, display_name)
       @required_arg_definitions << arg_def
       self
     end
@@ -415,7 +475,10 @@ 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 [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] accept An acceptor that validates and/or converts the
+    #     value. You may provide either the name of an acceptor you have
+    #     defined, or one of the default acceptors provided by OptionParser.
+    #     Optional. If not specified, accepts any value as a string.
     # @param [String] display_name A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
@@ -428,7 +491,8 @@ module Toys
     def add_optional_arg(key, default: nil, accept: nil, display_name: nil,
                          desc: nil, long_desc: nil)
       check_definition_state
-      arg_def = ArgDefinition.new(key, :optional, accept, desc, long_desc, display_name)
+      accept = resolve_acceptor(accept)
+      arg_def = ArgDefinition.new(key, :optional, accept, default, desc, long_desc, display_name)
       @optional_arg_definitions << arg_def
       @default_data[key] = default
       self
@@ -444,7 +508,10 @@ 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 [Object,nil] accept An OptionParser acceptor. Optional.
+    # @param [Object] accept An acceptor that validates and/or converts the
+    #     value. You may provide either the name of an acceptor you have
+    #     defined, or one of the default acceptors provided by OptionParser.
+    #     Optional. If not specified, accepts any value as a string.
     # @param [String] display_name A name to use for display (in help text and
     #     error reports). Defaults to the key in upper case.
     # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
@@ -457,7 +524,8 @@ module Toys
     def set_remaining_args(key, default: [], accept: nil, display_name: nil,
                            desc: nil, long_desc: nil)
       check_definition_state
-      arg_def = ArgDefinition.new(key, :remaining, accept, desc, long_desc, display_name)
+      accept = resolve_acceptor(accept)
+      arg_def = ArgDefinition.new(key, :remaining, accept, default, desc, long_desc, display_name)
       @remaining_args_definition = arg_def
       @default_data[key] = default
       self
@@ -513,327 +581,6 @@ module Toys
       self
     end
 
-    ##
-    # Representation of a single flag
-    #
-    class FlagSyntax
-      ##
-      # Parse flag syntax
-      # @param [String] str syntax.
-      #
-      def initialize(str)
-        if str =~ /^(-[\?\w])(\s?(\w+))?$/
-          setup(str, [$1], $1, "-", " ", $3)
-        elsif str =~ /^--\[no-\](\w[\?\w-]*)$/
-          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 flag: #{str.inspect}"
-        end
-      end
-
-      attr_reader :original_str
-      attr_reader :str_without_value
-      attr_reader :flags
-      attr_reader :flag_style
-      attr_reader :value_delim
-      attr_reader :value_label
-
-      private
-
-      def setup(original_str, flags, str_without_value, flag_style, value_delim, value_label)
-        @original_str = original_str
-        @flags = flags
-        @str_without_value = str_without_value
-        @flag_style = flag_style
-        @value_delim = value_delim
-        @value_label = value_label ? value_label.upcase : value_label
-      end
-    end
-
-    ##
-    # Representation of a formal set of flags.
-    #
-    class FlagDefinition
-      ##
-      # The default handler replaces the previous value.
-      # @return [Proc]
-      #
-      DEFAULT_HANDLER = ->(val, _prev) { val }
-
-      ##
-      # Create a FlagDefinition
-      # @private
-      #
-      # @param [Symbol] key This flag will set the given context key.
-      #
-      def initialize(key, flags, accept, handler, desc, long_desc, default)
-        @key = key
-        @flag_syntax = flags.map { |s| FlagSyntax.new(s) }
-        @accept = accept
-        @handler = handler || DEFAULT_HANDLER
-        @desc = Tool.canonicalize_desc(desc)
-        @long_desc = Tool.canonicalize_long_desc(long_desc)
-        @needs_val = !@accept.nil? ||
-                     (!default.nil? && default != true && default != false)
-        create_default_flag_if_needed
-        reset_data
-      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 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
-
-      ##
-      # 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 ||= begin
-          flags = flag_syntax.map do |fs|
-            f = fs.str_without_value
-            f = "#{f} #{value_label}" if value_label
-            f
-          end
-          flags + Array(accept)
-        end
-      end
-
-      ##
-      # Returns true if this flag is active. That is, it has a nonempty
-      # flags list.
-      # @return [Boolean]
-      #
-      def active?
-        !effective_flags.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
-
-      ##
-      # Set description
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
-      #
-      def desc=(desc)
-        @desc = Tool.canonicalize_desc(desc)
-      end
-
-      ##
-      # Set long description
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #
-      def long_desc=(long_desc)
-        @long_desc = Tool.canonicalize_long_desc(long_desc)
-      end
-
-      ## @private
-      def remove_flags(flags)
-        flags = flags.map { |f| FlagSyntax.new(f).flags }.flatten
-        @flag_syntax.select! do |ss|
-          ss.flags.all? { |s| !flags.include?(s) }
-        end
-        reset_data
-      end
-
-      private
-
-      def reset_data
-        @effective_flags = nil
-        @optparser_info = nil
-        @single_flag_syntax = nil
-        @double_flag_syntax = nil
-        @value_label = nil
-        @value_delim = nil
-      end
-
-      def create_default_flag_if_needed
-        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 find_canonical_value_label
-        return if @value_delim
-        @value_label = @needs_val ? "VALUE" : nil
-        @value_delim = @needs_val ? " " : ""
-        single_flag_syntax.each do |ss|
-          next unless ss.value_label
-          @value_label = ss.value_label
-          @value_delim = ss.value_delim
-        end
-        double_flag_syntax.each do |ss|
-          next unless ss.value_label
-          @value_label = ss.value_label
-          @value_delim = ss.value_delim
-        end
-      end
-    end
-
-    ##
-    # Representation of a formal positional argument
-    #
-    class ArgDefinition
-      ##
-      # Create an ArgDefinition
-      # @private
-      #
-      # @param [Symbol] key This argument will set the given context key.
-      # @param [:required,:optional,:remaining] type Type of this argument
-      #
-      def initialize(key, type, accept, desc, long_desc, display_name)
-        @key = key
-        @type = type
-        @accept = accept
-        @desc = Tool.canonicalize_desc(desc)
-        @long_desc = Tool.canonicalize_long_desc(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 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.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 = Tool.canonicalize_desc(desc)
-      end
-
-      ##
-      # Set long description
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-      #
-      def long_desc=(long_desc)
-        @long_desc = Tool.canonicalize_long_desc(long_desc)
-      end
-    end
-
     private
 
     def make_config_proc(middleware, loader, next_config)
@@ -847,16 +594,12 @@ module Toys
       end
     end
 
-    class << self
-      ## @private
-      def canonicalize_desc(desc)
-        desc.is_a?(Utils::WrappableString) ? desc : Utils::WrappableString.new(desc)
-      end
-
-      ## @private
-      def canonicalize_long_desc(descs)
-        Array(descs).map { |desc| canonicalize_desc(desc) }.freeze
+    def resolve_acceptor(accept)
+      return accept if accept.nil? || accept.is_a?(Acceptor)
+      unless @acceptors.key?(accept)
+        raise ToolDefinitionError, "Unknown acceptor: #{accept.inspect}"
       end
+      @acceptors[accept]
     end
 
     ##
@@ -911,6 +654,9 @@ module Toys
             @data[flag.key] = flag.handler.call(val, @data[flag.key])
           end
         end
+        @tool.custom_acceptors do |accept|
+          optparse.accept(accept)
+        end
         optparse
       end
 
@@ -986,3 +732,7 @@ module Toys
     end
   end
 end
+
+require "toys/tool/acceptor"
+require "toys/tool/arg_definition"
+require "toys/tool/flag_definition"