toys-core 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88644d1a61c31baed3ea200a6a936f79d5f81227b42c79ceeb949dd7be06d3ad
-  data.tar.gz: 85a9544bd4950250ab0797d1fa0a110d949cf677b6739596a90c75b8d1cf8185
+  metadata.gz: 1552f14b276734b92f59f9c1d4464679ec1facdc6480e8ecb01b7818d7541712
+  data.tar.gz: d8da75bf066fa32de202edc57151a37c20b08a29537e7fbb25e9683d705fe625
 SHA512:
-  metadata.gz: 3f09f94ffd7f77b58981bcd291a46bd354c02b11800d550ee9419b76ea74049efe9aa4833bf8ee4e4d41199f84e926b03577315d61d8512c8808878420453542
-  data.tar.gz: 46e24892810dcb54266bad9647b9d2bbb0dde2c283b7e869183103dad84da238ada3dd37581f4a891c84c95af2fa45e33bb72c25e728281ede6027847bd9e984
+  metadata.gz: b3816d90527525a282e55b534a2c250fd7667b7c4a9c4922dbd9a67c9bea72223eb6e16f2d1a0d035213ce86be013bdce2a073c56b8f35c4e223262a494faaaa
+  data.tar.gz: d73196fce65e1c0cc5904dd93e529bd798cfd10a19a1ac4ac9c138b30c62d516f5e76380502e38306ad91105526fd699dbf41fa20643c2b8bd852dfa1914ce06

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 0.3.6 / 2018-05-21
+
+* CHANGED: Renamed show_version middleware to show_root_version.
+* CHANGED: Reworked set_default_descriptions interface for more flexibility.
+* CHANGED: Renamed Utils::Exec#config_defaults to configure_defaults to match the helper.
+* CHANGED: Removed Context#new_cli and exposed Context#cli instead.
+* CHANGED: Renamed CLI#empty_clone to CLI#child.
+* IMPROVED: show_help middleware lets you control display of the source path section.
+* IMPROVED: Optional parameters are now supported for flags.
+* IMPROVED: Support custom acceptors.
+* IMPROVED: Highline helper automatically sets use_color based on the type of stdout.
+
 ### 0.3.5 / 2018-05-15
 
 * CHANGED: Exec logic now lives in a utils class.

data/lib/toys/cli.rb

@@ -219,19 +219,24 @@ module Toys
 
     ##
     # Make a clone with the same settings but no paths in the loader.
+    # This is sometimes useful for running sub-tools.
     #
     # @return [Toys::CLI]
+    # @yieldparam cli [Toys::CLI] If you pass a block, the new CLI is yielded
+    #     to it so you can add paths and make other modifications.
     #
-    def empty_clone
-      CLI.new(binary_name: @binary_name,
-              config_dir_name: @config_dir_name,
-              config_file_name: @config_file_name,
-              index_file_name: @index_file_name,
-              preload_file_name: @preload_file_name,
-              middleware_stack: @middleware_stack,
-              logger: @logger,
-              base_level: @base_level,
-              error_handler: @error_handler)
+    def child
+      cli = CLI.new(binary_name: @binary_name,
+                    config_dir_name: @config_dir_name,
+                    config_file_name: @config_file_name,
+                    index_file_name: @index_file_name,
+                    preload_file_name: @preload_file_name,
+                    middleware_stack: @middleware_stack,
+                    logger: @logger,
+                    base_level: @base_level,
+                    error_handler: @error_handler)
+      yield cli if block_given?
+      cli
     end
 
     ##

data/lib/toys/config_dsl.rb

@@ -27,6 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
+require "toys/context"
+
 module Toys
   ##
   # This class defines the DSL for a toys configuration file.
@@ -63,6 +65,12 @@ module Toys
   #     toys greet rubyists
   #
   class ConfigDSL
+    # Copy the well-known context key constants here, so that script blocks
+    # inside config DSL files can access them without qualification.
+    ::Toys::Context.constants.each do |const|
+      const_set(const, ::Toys::Context.const_get(const))
+    end
+
     ##
     # Create an instance of the DSL.
     # @private
@@ -84,6 +92,62 @@ module Toys
       @path = path
     end
 
+    ##
+    # Create an acceptor that can be passed into a flag or arg. An acceptor
+    # validates and/or converts a string parameter to a Ruby object. This
+    # acceptor may, for the current tool, be referenced by the name you provide
+    # when you create a flag or arg.
+    #
+    # An acceptor contains a validator, which parses and validates the string
+    # syntax of an argument, and a converter, which takes the validation
+    # results and returns a final value for the context data.
+    #
+    # The validator may be either a regular expression or a list of valid
+    # inputs.
+    #
+    # If the validator is a regular expression, it is matched against the
+    # argument string and succeeds only if the expression covers the *entire*
+    # string. The elements of the MatchData (i.e. the string matched, plus any
+    # captures) are then passed into the conversion function.
+    #
+    # If the validator is an array, the *string form* of the array elements
+    # (i.e. the results of calling to_s on each element) are considered the
+    # valid values for the argument. This is useful for enums, for example.
+    # In this case, the input is converted to the original array element, and
+    # any converter function you provide is ignored.
+    #
+    # If you provide no validator, then no validation takes place and all
+    # argument strings are considered valid. The string itself is passed on to
+    # the converter.
+    #
+    # The converter should be a proc that takes as its arguments the results
+    # of validation. For example, if you use a regular expression validator,
+    # the converter should take a series of strings arguments, the first of
+    # which is the full input string, and the rest of which are captures.
+    # If you provide no converter, no conversion is done and the input string
+    # is considered the final value. You may also provide the converter as a
+    # block.
+    #
+    # @param [String] name The acceptor name.
+    # @param [Regexp,Array,nil] validator The validator.
+    # @param [Proc,nil] converter The validator.
+    #
+    def acceptor(name, validator = nil, converter = nil, &block)
+      accept =
+        case validator
+        when ::Regexp
+          Tool::PatternAcceptor.new(name, validator, converter, &block)
+        when ::Array
+          Tool::EnumAcceptor.new(name, validator)
+        when nil
+          Tool::Acceptor.new(name, converter, &block)
+        else
+          raise ToolDefinitionError, "Illegal validator: #{validator.inspect}"
+        end
+      _cur_tool.add_acceptor(accept)
+      self
+    end
+
     ##
     # Create a subtool. You must provide a block defining the subtool.
     #
@@ -233,7 +297,10 @@ module Toys
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
     # @param [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`.
@@ -242,6 +309,9 @@ module Toys
     #     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 unusable. Default is
+    #     true.
     # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
     #     description for the flag. See {Toys::ConfigDSL#desc} for a description
     #     of the allowed formats. Defaults to the empty string.
@@ -250,22 +320,18 @@ module Toys
     #     description of the allowed formats. (But note that this param takes
     #     an Array of description lines, rather than a series of arguments.)
     #     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.
     # @yieldparam flag_dsl [Toys::ConfigDSL::FlagDSL] An object that lets you
     #     configure this flag in a block.
     #
     def 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)
       return self if _cur_tool.nil?
-      flag_dsl = FlagDSL.new(flags, accept, default, handler, desc, long_desc)
+      flag_dsl = FlagDSL.new(flags, accept, default, handler, report_collisions, desc, long_desc)
       yield flag_dsl if block_given?
       _cur_tool.lock_definition_path(@path)
-      flag_dsl._add_to(_cur_tool, key, only_unique)
+      flag_dsl._add_to(_cur_tool, key)
       self
     end
 
@@ -276,7 +342,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
@@ -311,7 +380,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
@@ -346,7 +418,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
@@ -418,11 +493,12 @@ module Toys
     #
     class FlagDSL
       ## @private
-      def initialize(flags, accept, default, handler, desc, long_desc)
+      def initialize(flags, accept, default, handler, report_collisions, desc, long_desc)
         @flags = flags
         @accept = accept
         @default = default
         @handler = handler
+        @report_collisions = report_collisions
         @desc = desc
         @long_desc = long_desc
       end
@@ -467,6 +543,16 @@ module Toys
         self
       end
 
+      ##
+      # Set whether to raise an exception if a flag is requested that is
+      # already in use or marked as disabled.
+      # @param [Boolean] setting
+      #
+      def report_collisions(setting)
+        @report_collisions = setting
+        self
+      end
+
       ##
       # Set the short description. See {Toys::ConfigDSL#desc} for the allowed
       # formats.
@@ -489,11 +575,11 @@ module Toys
       end
 
       ## @private
-      def _add_to(tool, key, only_unique)
+      def _add_to(tool, key)
         tool.add_flag(key, @flags,
                       accept: @accept, default: @default, handler: @handler,
-                      desc: @desc, long_desc: @long_desc,
-                      only_unique: only_unique)
+                      report_collisions: @report_collisions,
+                      desc: @desc, long_desc: @long_desc)
       end
     end
 

data/lib/toys/context.rb

@@ -31,75 +31,91 @@ require "logger"
 
 module Toys
   ##
-  # The object context in effect during the execution of a tool.
+  # This class manages the object context in effect during the execution of a
+  # tool. The context is a hash of key-value pairs.
   #
-  # The context is generally a hash of key-value pairs.
-  # Keys that begin with two underscores are reserved common elements of the
-  # context such as the tool being executed, or the verbosity level.
-  # Other keys are available for use by your tool. Generally, they are set
-  # by flags and arguments in your tool. Context values may also be set
-  # by middleware. By convention, middleware-set keys begin with a single
-  # underscore.
+  # Flags and arguments defined by your tool normally report their values in
+  # the context, using keys that are strings or symbols.
+  #
+  # Keys that are neither strings nor symbols are by convention used for other
+  # context information, including:
+  # *   Common information such as the {Toys::Tool} object being executed, the
+  #     arguments originally passed to it, or the usage error string. These
+  #     well-known keys can be accessed via constants in the {Toys::Context}
+  #     module.
+  # *   Common settings such as the verbosity level, and whether to exit
+  #     immediately if a subprocess exits with a nonzero result. These keys are
+  #     also present as {Toys::Context} constants.
+  # *   Private information used internally by middleware and helpers.
+  #
+  # This class provides convenience accessors for common keys and settings, and
+  # you can retrieve argument-set keys using the {#options} hash.
   #
   class Context
+    ##
+    # Context key for the currently running CLI.
+    # @return [Object]
+    #
+    CLI = ::Object.new.freeze
+
     ##
     # Context key for the verbosity value. Verbosity is an integer defaulting
     # to 0, with higher values meaning more verbose and lower meaning quieter.
-    # @return [Symbol]
+    # @return [Object]
     #
-    VERBOSITY = :__verbosity
+    VERBOSITY = ::Object.new.freeze
 
     ##
     # Context key for the `Toys::Tool` object being executed.
-    # @return [Symbol]
+    # @return [Object]
     #
-    TOOL = :__tool
+    TOOL = ::Object.new.freeze
 
     ##
     # Context key for the full name of the tool being executed. Value is an
     # array of strings.
-    # @return [Symbol]
+    # @return [Object]
     #
-    TOOL_NAME = :__tool_name
+    TOOL_NAME = ::Object.new.freeze
 
     ##
     # Context key for the active `Toys::Loader` object.
-    # @return [Symbol]
+    # @return [Object]
     #
-    LOADER = :__loader
+    LOADER = ::Object.new.freeze
 
     ##
     # Context key for the active `Logger` object.
-    # @return [Symbol]
+    # @return [Object]
     #
-    LOGGER = :__logger
+    LOGGER = ::Object.new.freeze
 
     ##
     # Context key for the name of the toys binary. Value is a string.
-    # @return [Symbol]
+    # @return [Object]
     #
-    BINARY_NAME = :__binary_name
+    BINARY_NAME = ::Object.new.freeze
 
     ##
     # Context key for the argument list passed to the current tool. Value is
     # an array of strings.
-    # @return [Symbol]
+    # @return [Object]
     #
-    ARGS = :__args
+    ARGS = ::Object.new.freeze
 
     ##
     # Context key for the usage error raised. Value is a string if there was
     # an error, or nil if there was no error.
-    # @return [Symbol]
+    # @return [Object]
     #
-    USAGE_ERROR = :__usage_error
+    USAGE_ERROR = ::Object.new.freeze
 
     ##
     # Context key for whether nonzero exit codes from subprocesses should cause
     # an immediate exit. Value is a truthy or falsy value.
-    # @return [Symbol]
+    # @return [Object]
     #
-    EXIT_ON_NONZERO_STATUS = :__exit_on_nonzero_status
+    EXIT_ON_NONZERO_STATUS = ::Object.new.freeze
 
     ##
     # Create a Context object. Applications generally will not need to create
@@ -111,15 +127,23 @@ module Toys
     # @param [Hash] data
     #
     def initialize(cli, data)
-      @_cli = cli
       @_data = data
+      @_data[CLI] = cli
       @_data[LOADER] = cli.loader
       @_data[BINARY_NAME] = cli.binary_name
       @_data[LOGGER] = cli.logger
     end
 
     ##
-    # Return the verbosity as an integer.
+    # Return the currently running CLI.
+    # @return [Toys::CLI]
+    #
+    def cli
+      @_data[CLI]
+    end
+
+    ##
+    # Return the current verbosity setting as an integer.
     # @return [Integer]
     #
     def verbosity
@@ -196,7 +220,7 @@ module Toys
     alias get []
 
     ##
-    # Set an option or other piece of data by key.
+    # Set an option or other piece of context data by key.
     #
     # @param [Symbol] key
     # @param [Object] value
@@ -206,7 +230,7 @@ module Toys
     end
 
     ##
-    # Set an option or other piece of data by key.
+    # Set an option or other piece of context data by key.
     #
     # @param [Symbol] key
     # @param [Object] value
@@ -221,15 +245,16 @@ module Toys
     end
 
     ##
-    # Returns the subset of the context that does not include well-known keys
-    # such as tool and verbosity. Technically, this includes all keys that do
-    # not begin with two underscores.
+    # Returns the subset of the context that uses string or symbol keys. By
+    # convention, this includes keys that are set by tool flags and arguments,
+    # but does not include well-known context values such as verbosity or
+    # private context values used by middleware or helpers.
     #
     # @return [Hash]
     #
     def options
       @_data.select do |k, _v|
-        !k.is_a?(::Symbol) || !k.to_s.start_with?("__")
+        k.is_a?(::Symbol) || k.is_a?(::String)
       end
     end
 
@@ -245,26 +270,13 @@ module Toys
     # @return [Integer] The resulting status code
     #
     def run(*args, cli: nil, exit_on_nonzero_status: nil)
-      cli ||= @_cli
+      cli ||= @_data[CLI]
       exit_on_nonzero_status = @_data[EXIT_ON_NONZERO_STATUS] if exit_on_nonzero_status.nil?
       code = cli.run(args.flatten, verbosity: @_data[VERBOSITY])
       exit(code) if exit_on_nonzero_status && !code.zero?
       code
     end
 
-    ##
-    # Return a new CLI with the same settings as the currnet CLI but no paths.
-    # This can be used to run a toys "sub-instance". Add any new paths to the
-    # returned CLI, then call {#run}, passing in the CLI, to execute a tool.
-    #
-    # @return [Toys::CLI]
-    #
-    def new_cli
-      cli = @_cli.empty_clone
-      yield cli if block_given?
-      cli
-    end
-
     ##
     # Exit immediately with the given status code
     #