toys-core 0.3.3 → 0.3.4

data/lib/toys/middleware/show_version.rb

@@ -28,20 +28,21 @@
 ;
 
 require "toys/middleware/base"
+require "toys/utils/line_output"
 
 module Toys
   module Middleware
     ##
     # A middleware that displays a version string for certain tools if the
-    # `--version` switch is given. You can specify which tools respond to
-    # this switch, and the string that will be displayed.
+    # `--version` flag is given. You can specify which tools respond to
+    # this flag, and the string that will be displayed.
     #
     class ShowVersion < Base
       ##
-      # Default version switches
+      # Default version flags
       # @return [Array<String>]
       #
-      DEFAULT_VERSION_SWITCHES = ["--version"].freeze
+      DEFAULT_VERSION_FLAGS = ["--version"].freeze
 
       ##
       # Return a simple version displayer that returns the given string for
@@ -58,28 +59,31 @@ module Toys
       #
       # @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` switch.
+      #     value to indicate the tool should not have a `--version` flag.
       #     Defaults to a "null" displayer that returns false for all tools.
-      # @param [Array<String>] version_switches A list of switches that should
+      # @param [Array<String>] version_flags A list of flags that should
       #     trigger displaying the version. Default is
-      #     {DEFAULT_VERSION_SWITCHES}.
+      #     {DEFAULT_VERSION_FLAGS}.
+      # @param [IO] stream Output stream to write to. Default is stdout.
       #
       def initialize(version_displayer: nil,
-                     version_switches: DEFAULT_VERSION_SWITCHES)
+                     version_flags: DEFAULT_VERSION_FLAGS,
+                     stream: $stdout)
         @version_displayer = version_displayer || proc { |_| false }
-        @version_switches = version_switches
+        @version_flags = version_flags
+        @output = Utils::LineOutput.new(stream)
       end
 
       ##
-      # Adds the version switch if requested.
+      # Adds the version flag if requested.
       #
-      def config(tool)
+      def config(tool, _loader)
         version = @version_displayer.call(tool)
         if version
-          tool.add_switch(:_show_version, *@version_switches,
-                          docs: "Show version",
-                          handler: ->(_val, _prev) { version },
-                          only_unique: true)
+          tool.add_flag(:_show_version, *@version_flags,
+                        desc: "Display the version",
+                        handler: ->(_val, _prev) { version },
+                        only_unique: true)
         end
         yield
       end
@@ -89,7 +93,7 @@ module Toys
       #
       def execute(context)
         if context[:_show_version]
-          puts context[:_show_version]
+          @output.puts context[:_show_version]
         else
           yield
         end

data/lib/toys/templates/clean.rb

@@ -72,7 +72,10 @@ module Toys
             files.uniq!
 
             files.each do |file|
-              rm_rf file
+              if ::File.exist?(file)
+                rm_rf file
+                puts "Cleaned: #{file}"
+              end
             end
           end
         end

data/lib/toys/templates/gem_build.rb

@@ -88,6 +88,8 @@ module Toys
         tool(template.name) do
           desc "#{task_type} the gem: #{template.gem_name}"
 
+          flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
+
           use :exec
           use :fileutils
           use :highline
@@ -105,7 +107,7 @@ module Toys
                 logger.error "Cannot push the gem when there are uncommited changes"
                 exit(1)
               end
-              exit(1) unless agree("Release #{gemfile}? (y/n) ")
+              exit(1) unless options[:yes] || agree("Release #{gemfile}? (y/n) ")
               sh "gem push pkg/#{gemfile}"
               if template.tag
                 sh "git tag v#{version}"

data/lib/toys/templates/minitest.rb

@@ -86,12 +86,11 @@ module Toys
 
           use :exec
 
-          switch(
-            :warnings, "-w", "--[no-]warnings",
-            default: template.warnings,
-            docs: "Turn on Ruby warnings (defaults to #{template.warnings})"
-          )
-          remaining_args(:tests, docs: "Paths to the tests to run (defaults to all tests)")
+          flag :warnings, "-w", "--[no-]warnings",
+               default: template.warnings,
+               desc: "Turn on Ruby warnings (defaults to #{template.warnings})"
+
+          remaining_args :tests, desc: "Paths to the tests to run (defaults to all tests)"
 
           execute do
             ruby_args = []

data/lib/toys/tool.rb

@@ -35,7 +35,7 @@ module Toys
   ##
   # A Tool is a single command that can be invoked using Toys.
   # It has a name, a series of one or more words that you use to identify
-  # the tool on the command line. It also has a set of formal switches and
+  # the tool on the command line. It also has a set of formal flags and
   # command line arguments supported, and a block that gets run when the
   # tool is executed.
   #
@@ -52,11 +52,11 @@ module Toys
       @definition_path = nil
       @definition_finished = false
 
-      @desc = []
+      @desc = Toys::Utils::WrappableString.new("")
       @long_desc = []
 
       @default_data = {}
-      @switch_definitions = []
+      @flag_definitions = []
       @required_arg_definitions = []
       @optional_arg_definitions = []
       @remaining_args_definition = nil
@@ -74,10 +74,22 @@ module Toys
     attr_reader :full_name
 
     ##
-    # Return a list of all defined switches.
-    # @return [Array<Toys::Tool::SwitchDefinition>]
+    # Returns the short description string.
+    # @return [Toys::Utils::WrappableString]
     #
-    attr_reader :switch_definitions
+    attr_reader :desc
+
+    ##
+    # Returns the long description strings as an array.
+    # @return [Array<Toys::Utils::WrappableString>]
+    #
+    attr_reader :long_desc
+
+    ##
+    # Return a list of all defined flags.
+    # @return [Array<Toys::Tool::FlagDefinition>]
+    #
+    attr_reader :flag_definitions
 
     ##
     # Return a list of all defined required positional arguments.
@@ -167,45 +179,21 @@ module Toys
       executor.is_a?(::Proc)
     end
 
-    ##
-    # Returns the effective short description for this tool. This will be
-    # displayed when this tool is listed in a command list.
-    #
-    # @param [Integer,nil] wrap_width Wrap wrappable strings to the given
-    #     width, or `nil` for no wrapping.
-    # @return [Array<String>]
-    #
-    def effective_desc(wrap_width: nil)
-      Tool.resolve_wrapping(@desc, wrap_width)
-    end
-
-    ##
-    # Returns the effective long description for this tool. This will be
-    # displayed as part of the usage for this particular tool.
-    #
-    # @param [Integer,nil] wrap_width Wrap wrappable strings to the given
-    #     width, or `nil` for no wrapping.
-    # @return [Array<String>]
-    #
-    def effective_long_desc(wrap_width: nil)
-      Tool.resolve_wrapping(@long_desc.empty? ? @desc : @long_desc, wrap_width)
-    end
-
     ##
     # Returns true if there is a specific description set for this tool.
     # @return [Boolean]
     #
     def includes_description?
-      !@long_desc.empty? || !@desc.empty?
+      !long_desc.empty? || !desc.empty?
     end
 
     ##
-    # Returns true if at least one switch or positional argument is defined
+    # Returns true if at least one flag or positional argument is defined
     # for this tool.
     # @return [Boolean]
     #
     def includes_arguments?
-      !default_data.empty? || !switch_definitions.empty? ||
+      !default_data.empty? || !flag_definitions.empty? ||
         !required_arg_definitions.empty? || !optional_arg_definitions.empty? ||
         !remaining_args_definition.nil?
     end
@@ -228,11 +216,29 @@ module Toys
     end
 
     ##
-    # Returns a list of switch flags used by this tool.
+    # Returns true if this tool's definition has been finished and is locked.
+    # @return [Boolean]
+    #
+    def definition_finished?
+      @definition_finished
+    end
+
+    ##
+    # Returns all arg definitions in order: required, optional, remaining.
+    # @return [Array<Toys::Tool::ArgDefinition>]
+    #
+    def arg_definitions
+      result = required_arg_definitions + optional_arg_definitions
+      result << remaining_args_definition if remaining_args_definition
+      result
+    end
+
+    ##
+    # Returns a list of flags used by this tool.
     # @return [Array<String>]
     #
-    def used_switches
-      @switch_definitions.reduce([]) { |used, sdef| used + sdef.effective_switches }.uniq
+    def used_flags
+      flag_definitions.reduce([]) { |used, fdef| used + fdef.effective_flags }.uniq
     end
 
     ##
@@ -242,33 +248,56 @@ module Toys
     #
     # @param [String] path The path to the file defining this tool
     #
-    def definition_path=(path)
-      if @definition_path && @definition_path != path
+    def lock_definition_path(path)
+      if definition_path && definition_path != path
         raise ToolDefinitionError,
               "Cannot redefine tool #{display_name.inspect} in #{path}" \
-              " (already defined in #{@definition_path})"
+              " (already defined in #{definition_path})"
       end
       @definition_path = path
     end
 
     ##
-    # Set the short description.
+    # Set the short description string.
+    #
+    # The description 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 [String,Array<String>] strs The short description
+    # @param [Toys::Utils::WrappableString,String,Array<String>] desc
     #
-    def desc=(strs)
+    def desc=(desc)
       check_definition_state
-      @desc = Tool.canonicalize_desc(strs)
+      @desc = Tool.canonicalize_desc(desc)
     end
 
     ##
-    # Set the long description.
+    # Set the long description strings.
     #
-    # @param [String,Array<String>] strs The long description
+    # 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.
     #
-    def long_desc=(strs)
+    # @param [Array<Toys::Utils::WrappableString,String,Array<String>>] descs
+    #
+    def long_desc=(descs)
       check_definition_state
-      @long_desc = Tool.canonicalize_desc(strs)
+      @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
     end
 
     ##
@@ -312,24 +341,27 @@ module Toys
     end
 
     ##
-    # Add a switch to the current tool. Each switch must specify a key which
-    # the executor may use to obtain the switch value from the context.
-    # You may then provide the switches themselves in `OptionParser` form.
+    # Add a flag to the current tool. Each flag must specify a key which
+    # the executor may use to obtain the flag value from the context.
+    # You may then provide the flags themselves in `OptionParser` form.
     #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
-    # @param [String...] switches The switches in OptionParser format.
+    # @param [String...] flags The flags in OptionParser format.
     # @param [Object,nil] accept An OptionParser acceptor. Optional.
     # @param [Object] default The default value. This is the value that will
-    #     be set in the context if this switch is not provided on the command
+    #     be set in the context if this flag is not provided on the command
     #     line. Defaults to `nil`.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
-    #     the switch. Defaults to empty array.
-    # @param [Boolean] only_unique If true, any switches that are already
-    #     defined in this tool are removed from this switch. For example, if
-    #     an earlier switch uses `-a`, and this switch wants to use both
-    #     `-a` and `-b`, then only `-b` will be assigned to this switch.
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the flag. Defaults to empty array.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the flag. Defaults to 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
@@ -337,17 +369,21 @@ module Toys
     #     should be set. The default handler simply replaces the previous
     #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
     #
-    def add_switch(key, *switches,
-                   accept: nil, default: nil, docs: nil, only_unique: false, handler: nil)
+    def add_flag(key, *flags,
+                 accept: nil, default: nil, desc: nil, long_desc: nil,
+                 only_unique: false, handler: nil)
       check_definition_state
-      switch_info = SwitchDefinition.new(key, switches, accept, docs, handler)
-      if only_unique
-        switch_info.remove_switches(used_switches)
-      end
-      if switch_info.active?
-        @default_data[key] = default
-        @switch_definitions << switch_info
-      end
+      flag_def = FlagDefinition.new(self, key)
+      flag_def.add_flags(flags)
+      flag_def.accept = accept
+      flag_def.handler = handler
+      flag_def.default = default
+      flag_def.desc = desc unless desc.nil?
+      flag_def.long_desc = long_desc unless long_desc.nil?
+      yield flag_def if block_given?
+      flag_def.create_default_flag_if_needed
+      flag_def.remove_flags(used_flags) if only_unique
+      @flag_definitions << flag_def if flag_def.active?
       self
     end
 
@@ -359,14 +395,25 @@ 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 [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
-    #     the arg. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def add_required_arg(key, accept: nil, docs: nil)
+    def add_required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
       check_definition_state
-      @default_data[key] = nil
-      @required_arg_definitions << ArgDefinition.new(key, accept, docs)
+      arg_def = ArgDefinition.new(self, key, :required)
+      arg_def.accept = accept
+      arg_def.default = nil
+      arg_def.display_name = display_name unless display_name.nil?
+      arg_def.desc = desc unless desc.nil?
+      arg_def.long_desc = long_desc unless long_desc.nil?
+      yield arg_def if block_given?
+      @required_arg_definitions << arg_def
       self
     end
 
@@ -378,18 +425,30 @@ 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] 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 [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
-    #     the arg. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def add_optional_arg(key, accept: nil, default: nil, docs: nil)
+    def add_optional_arg(key, default: nil, accept: nil, display_name: nil,
+                         desc: nil, long_desc: nil)
       check_definition_state
-      @default_data[key] = default
-      @optional_arg_definitions << ArgDefinition.new(key, accept, docs)
+      arg_def = ArgDefinition.new(self, key, :optional)
+      arg_def.accept = accept
+      arg_def.default = default
+      arg_def.display_name = display_name unless display_name.nil?
+      arg_def.desc = desc unless desc.nil?
+      arg_def.long_desc = long_desc unless long_desc.nil?
+      yield arg_def if block_given?
+      @optional_arg_definitions << arg_def
       self
     end
 
@@ -400,18 +459,30 @@ 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] 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 [String] display_name A name to use for display (in help text and
+    #     error reports). Defaults to the key in upper case.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] desc Short description
+    #     for the arg. Defaults to empty array.
     # @param [String,Toys::Utils::WrappableString,
-    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
-    #     the args. Defaults to empty array.
+    #     Array<String,Toys::Utils::WrappableString>] long_desc Long
+    #     description for the arg. Defaults to empty array.
     #
-    def set_remaining_args(key, accept: nil, default: [], docs: nil)
+    def set_remaining_args(key, default: [], accept: nil, display_name: nil,
+                           desc: nil, long_desc: nil)
       check_definition_state
-      @default_data[key] = default
-      @remaining_args_definition = ArgDefinition.new(key, accept, docs)
+      arg_def = ArgDefinition.new(self, key, :remaining)
+      arg_def.accept = accept
+      arg_def.default = default
+      arg_def.display_name = display_name unless display_name.nil?
+      arg_def.desc = desc unless desc.nil?
+      arg_def.long_desc = long_desc unless long_desc.nil?
+      yield arg_def if block_given?
+      @remaining_args_definition = arg_def
       self
     end
 
@@ -437,33 +508,40 @@ module Toys
     # @return [Integer] The result code.
     #
     def execute(cli, args, verbosity: 0)
-      finish_definition unless @definition_finished
-      Execution.new(self).execute(cli, args, verbosity: verbosity)
+      ContextualError.capture_path(
+        "Error during tool execution!", definition_path,
+        tool_name: full_name, tool_args: args
+      ) do
+        Execution.new(self).execute(cli, args, verbosity: verbosity)
+      end
     end
 
     ##
     # Complete definition and run middleware configs
+    # @param [Toys::Loader] loader
     #
     # @private
     #
-    def finish_definition
+    def finish_definition(loader)
       unless @definition_finished
-        config_proc = proc {}
-        middleware_stack.reverse.each do |middleware|
-          config_proc = make_config_proc(middleware, config_proc)
+        ContextualError.capture("Error installing tool middleware!", tool_name: full_name) do
+          config_proc = proc {}
+          middleware_stack.reverse.each do |middleware|
+            config_proc = make_config_proc(middleware, loader, config_proc)
+          end
+          config_proc.call
         end
-        config_proc.call
         @definition_finished = true
       end
       self
     end
 
     ##
-    # Representation of a single switch
+    # Representation of a single flag
     #
-    class SwitchSyntax
+    class FlagSyntax
       ##
-      # Parse switch syntax
+      # Parse flag syntax
       # @param [String] str syntax.
       #
       def initialize(str)
@@ -474,58 +552,54 @@ module Toys
         elsif str =~ /^(--\w[\?\w-]*)(([=\s])(\w+))?$/
           setup(str, [$1], $1, "--", $3, $4)
         else
-          raise ToolDefinitionError, "Illegal switch: #{str.inspect}"
+          raise ToolDefinitionError, "Illegal flag: #{str.inspect}"
         end
       end
 
-      attr_reader :str
+      attr_reader :original_str
       attr_reader :str_without_value
-      attr_reader :switches
-      attr_reader :switch_style
+      attr_reader :flags
+      attr_reader :flag_style
       attr_reader :value_delim
       attr_reader :value_label
 
       private
 
-      def setup(str, switches, str_without_value, switch_style, value_delim, value_label)
-        @str = str
-        @switches = switches
+      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
-        @switch_style = switch_style
+        @flag_style = flag_style
         @value_delim = value_delim
-        @value_label = value_label
+        @value_label = value_label ? value_label.upcase : value_label
       end
     end
 
     ##
-    # Representation of a formal set of switches.
+    # Representation of a formal set of flags.
     #
-    class SwitchDefinition
+    class FlagDefinition
+      ##
+      # The default handler replaces the previous value.
+      # @return [Proc]
+      #
+      DEFAULT_HANDLER = ->(val, _prev) { val }
+
       ##
-      # Create a SwitchDefinition
+      # Create a FlagDefinition
       # @private
       #
-      # @param [Symbol] key This switch will set the given context key.
-      # @param [Array<String>] switches Switches in OptionParser format
-      # @param [Object] accept An OptionParser acceptor, or `nil` for none.
-      # @param [String,Toys::Utils::WrappableString,
-      #     Array<String,Toys::Utils::WrappableString>] docs Documentation
-      # @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. If `nil`, uses a default handler that just replaces
-      #     the previous value. i.e. the default is effectively
-      #     `-> (val, _prev) { val }`.
-      #
-      def initialize(key, switches, accept, docs, handler = nil)
+      # @param [Symbol] key This flag will set the given context key.
+      #
+      def initialize(tool, key)
+        @tool = tool
         @key = key
-        switches = ["--#{Tool.canonical_switch(key)}=VALUE"] if switches.empty?
-        @switch_syntax = switches.map { |s| SwitchSyntax.new(s) }
-        @accept = accept
-        @docs = Tool.canonicalize_desc(docs)
-        @handler = handler || ->(val, _prev) { val }
+        @flag_syntax = []
+        @accept = nil
+        @handler = DEFAULT_HANDLER
+        @desc = ""
+        @long_desc = []
         reset_data
-        @effective_switches = nil
       end
 
       ##
@@ -535,10 +609,10 @@ module Toys
       attr_reader :key
 
       ##
-      # Returns an array of SwitchSyntax for the switches.
-      # @return [Array<SwitchSyntax>]
+      # Returns an array of FlagSyntax for the flags.
+      # @return [Array<FlagSyntax>]
       #
-      attr_reader :switch_syntax
+      attr_reader :flag_syntax
 
       ##
       # Returns the acceptor, which may be `nil`.
@@ -547,66 +621,150 @@ module Toys
       attr_reader :accept
 
       ##
-      # Returns the documentation strings, which may be the empty array.
-      # @return [Array<String>]
+      # 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 :docs
+      attr_reader :long_desc
 
       ##
-      # Returns the handler.
+      # Returns the handler for setting/updating the value.
       # @return [Proc]
       #
       attr_reader :handler
 
       ##
-      # Returns an array of SwitchSyntax including only single-dash switches
-      # @return [Array<SwitchSyntax>]
+      # Adds the given flags.
+      # @param [Array<String>] flags Flags in OptionParser format
       #
-      def single_switch_syntax
-        @single_switch_syntax ||= switch_syntax.find_all { |ss| ss.switch_style == "-" }
+      def add_flags(flags)
+        @flag_syntax.concat(flags.map { |s| FlagSyntax.new(s) })
+        reset_data
+        self
       end
 
       ##
-      # Returns an array of SwitchSyntax including only double-dash switches
-      # @return [Array<SwitchSyntax>]
+      # Set the acceptor.
+      # @param [Object] accept Acceptor. May be `nil` for the default.
       #
-      def double_switch_syntax
-        @double_switch_syntax ||= switch_syntax.find_all { |ss| ss.switch_style == "--" }
+      def accept=(accept)
+        @accept = accept
+        reset_data
       end
 
       ##
-      # Returns the list of effective switches used.
-      # @return [Array<String>]
+      # Set the default.
+      # @param [Object] default The default value.
+      #
+      def default=(default)
+        @tool.default_data[@key] = default
+      end
+
+      ##
+      # Set the handler for setting/updating the value.
+      # @param [Proc,nil] handler The handler for setting/updating the value.
+      #     The handler should take two arguments, the new given value and the
+      #     previous value, and it should return the new value that should be
+      #     set. If `nil`, uses {DEFAULT_HANDLER}.
+      #
+      def handler=(handler)
+        @handler = handler || DEFAULT_HANDLER
+      end
+
+      ##
+      # Set the short description string.
+      #
+      # The description 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>] desc
+      #
+      def desc=(desc)
+        @desc = Tool.canonicalize_desc(desc)
+      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.
       #
-      def effective_switches
-        @effective_switches ||= switch_syntax.map(&:switches).flatten
+      # @param [Array<Toys::Utils::WrappableString,String,Array<String>>] descs
+      #
+      def long_desc=(descs)
+        @long_desc = Tool.canonicalize_long_desc(descs)
       end
 
       ##
-      # Returns the documentation strings with wrapping resolved.
+      # 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 [Integer,nil] width Wrapping width, or `nil` to use default.
+      # @param [Toys::Utils::WrappableString,String,Array<String>...] descs
+      #
+      def populate_long_desc(*descs)
+        @long_desc = Tool.canonicalize_long_desc(descs)
+        self
+      end
+
+      ##
+      # 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 wrapped_docs(width)
-        Tool.resolve_wrapping(docs, width)
+      def effective_flags
+        @effective_flags ||= flag_syntax.map(&:flags).flatten
       end
 
       ##
-      # All optparser switches and acceptor if present
+      # All optparser flags and acceptor if present
       # @return [Array]
       #
       def optparser_info
-        @optparser_info ||= switch_syntax.map(&:str) + Array(accept)
+        @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 switch is active. That is, it has a nonempty
-      # switches list.
+      # Returns true if this flag is active. That is, it has a nonempty
+      # flags list.
       # @return [Boolean]
       #
       def active?
-        !effective_switches.empty?
+        !effective_flags.empty?
       end
 
       ##
@@ -627,47 +785,52 @@ module Toys
         @value_delim
       end
 
-      ##
-      # Removes the given switches.
-      # @param [Array<String>] switches
-      #
-      def remove_switches(switches)
-        @switch_syntax.select! do |ss|
-          ss.switches.all? { |s| !switches.include?(s) }
+      ## @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
         self
       end
 
+      ## @private
+      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 = @accept ? "--#{canonical_flag}=VALUE" : "--#{canonical_flag}"
+          @flag_syntax << FlagSyntax.new(flag)
+        end
+        reset_data
+      end
+
       private
 
       def reset_data
-        @effective_switches = nil
+        @effective_flags = nil
         @optparser_info = nil
-        @single_switch_syntax = nil
-        @double_switch_syntax = nil
+        @single_flag_syntax = nil
+        @double_flag_syntax = nil
         @value_label = nil
         @value_delim = nil
       end
 
       def find_canonical_value_label
         return if @value_delim
-        double_switch_syntax.reverse_each do |ss|
+        @value_label = @accept ? "VALUE" : nil
+        @value_delim = @accept ? " " : ""
+        single_flag_syntax.each do |ss|
           next unless ss.value_label
           @value_label = ss.value_label
           @value_delim = ss.value_delim
-          break
         end
-        return if @value_delim
-        single_switch_syntax.reverse_each do |ss|
+        double_flag_syntax.each do |ss|
           next unless ss.value_label
           @value_label = ss.value_label
           @value_delim = ss.value_delim
-          break
         end
-        return if @value_delim
-        @value_label = nil
-        @value_delim = ""
       end
     end
 
@@ -680,14 +843,16 @@ module Toys
       # @private
       #
       # @param [Symbol] key This argument will set the given context key.
-      # @param [Object] accept An OptionParser acceptor, or `nil` for none.
-      # @param [String,Toys::Utils::WrappableString,
-      #     Array<String,Toys::Utils::WrappableString>] docs Documentation
+      # @param [:required,:optional,:remaining] type Type of this argument
       #
-      def initialize(key, accept, docs)
+      def initialize(tool, key, type)
+        @tool = tool
         @key = key
-        @accept = accept
-        @docs = Tool.canonicalize_desc(docs)
+        @type = type
+        @accept = nil
+        @desc = ""
+        @long_desc = []
+        @display_name = key.to_s.tr("-", "_").gsub(/\W/, "").upcase
       end
 
       ##
@@ -696,35 +861,85 @@ module Toys
       #
       attr_reader :key
 
+      ##
+      # Type of this argument.
+      # @return [:required,:optional,:remaining]
+      #
+      attr_reader :type
+
       ##
       # Returns the acceptor, which may be `nil`.
       # @return [Object]
       #
-      attr_reader :accept
+      attr_accessor :accept
 
       ##
-      # Returns the documentation strings, which may be the empty array.
-      # @return [Array<String,Toys::Utils::WrappableString>]
+      # Returns the short description string.
+      # @return [Toys::Utils::WrappableString]
       #
-      attr_reader :docs
+      attr_reader :desc
 
       ##
-      # Return a canonical name for this arg. Used in usage documentation.
+      # Returns the long description strings as an array.
+      # @return [Array<Toys::Utils::WrappableString>]
       #
+      attr_reader :long_desc
+
+      ##
+      # Returns the displayable name.
       # @return [String]
       #
-      def canonical_name
-        Tool.canonical_switch(key)
+      attr_accessor :display_name
+
+      ##
+      # Set the default.
+      # @param [Object] default The default value.
+      #
+      def default=(default)
+        @tool.default_data[@key] = default
       end
 
       ##
-      # Returns the documentation strings with wrapping resolved.
+      # Set the short description string.
       #
-      # @param [Integer,nil] width Wrapping width, or `nil` to use default.
-      # @return [Array<String>]
+      # The description 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.
       #
-      def wrapped_docs(width)
-        Tool.resolve_wrapping(docs, width)
+      # @param [Toys::Utils::WrappableString,String,Array<String>] desc
+      #
+      def desc=(desc)
+        @desc = Tool.canonicalize_desc(desc)
+      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 [Array<Toys::Utils::WrappableString,String,Array<String>>] descs
+      #
+      def long_desc=(descs)
+        @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)
+        @long_desc = Tool.canonicalize_long_desc(descs)
+        self
       end
 
       ##
@@ -736,19 +951,18 @@ module Toys
       #
       def process_value(input)
         return input unless accept
-        n = canonical_name
         result = input
         optparse = ::OptionParser.new
-        optparse.on("--#{n}=VALUE", accept) { |v| result = v }
-        optparse.parse(["--#{n}", input])
+        optparse.on("--abc=VALUE", accept) { |v| result = v }
+        optparse.parse(["--abc", input])
         result
       end
     end
 
     private
 
-    def make_config_proc(middleware, next_config)
-      proc { middleware.config(self, &next_config) }
+    def make_config_proc(middleware, loader, next_config)
+      proc { middleware.config(self, loader, &next_config) }
     end
 
     def check_definition_state
@@ -759,23 +973,14 @@ module Toys
     end
 
     class << self
-      ## @private
-      def canonical_switch(name)
-        name.to_s.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "")
-      end
-
       ## @private
       def canonicalize_desc(desc)
-        Array(desc).map do |d|
-          d.is_a?(Utils::WrappableString) ? d : d.split("\n")
-        end.flatten.freeze
+        desc.is_a?(Utils::WrappableString) ? desc : Utils::WrappableString.new(desc)
       end
 
       ## @private
-      def resolve_wrapping(strs, wrap_width)
-        strs.map do |s|
-          s.is_a?(Utils::WrappableString) && !wrap_width.nil? ? s.wrap(wrap_width) : s.to_s
-        end.flatten
+      def canonicalize_long_desc(descs)
+        Array(descs).map { |desc| canonicalize_desc(desc) }.freeze
       end
     end
 
@@ -821,14 +1026,14 @@ module Toys
 
       def create_option_parser
         optparse = ::OptionParser.new
-        # The following clears out the Officious (hidden default switches).
+        # The following clears out the Officious (hidden default flags).
         optparse.remove
         optparse.remove
         optparse.new
         optparse.new
-        @tool.switch_definitions.each do |switch|
-          optparse.on(*switch.optparser_info) do |val|
-            @data[switch.key] = switch.handler.call(val, @data[switch.key])
+        @tool.flag_definitions.each do |flag|
+          optparse.on(*flag.optparser_info) do |val|
+            @data[flag.key] = flag.handler.call(val, @data[flag.key])
           end
         end
         optparse
@@ -837,7 +1042,7 @@ module Toys
       def parse_required_args(remaining, args)
         @tool.required_arg_definitions.each do |arg_info|
           if remaining.empty?
-            reason = "No value given for required argument named <#{arg_info.canonical_name}>"
+            reason = "No value given for required argument #{arg_info.display_name}"
             raise create_parse_error(args, reason)
           end
           @data[arg_info.key] = arg_info.process_value(remaining.shift)
@@ -887,7 +1092,7 @@ module Toys
           if @tool.includes_executor?
             context.instance_eval(&@tool.executor)
           else
-            context.logger.fatal("No implementation for #{@tool.display_name.inspect}")
+            context.logger.fatal("No implementation for tool #{@tool.display_name.inspect}")
             context.exit(-1)
           end
         end