toys-core 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26fce1d32fe0161a806a4b6d6d831b546be343290a0d0103c5e6a52e14f2f106
-  data.tar.gz: b57713c9fd6436f5f90007769663340a4df5599bf9c72f0c9eb160ebcdc7ed8a
+  metadata.gz: 88644d1a61c31baed3ea200a6a936f79d5f81227b42c79ceeb949dd7be06d3ad
+  data.tar.gz: 85a9544bd4950250ab0797d1fa0a110d949cf677b6739596a90c75b8d1cf8185
 SHA512:
-  metadata.gz: f2427161dc5f1635473fa09f5e67c6f3ad58f861669de6c909c03fe55a2b44778e2b905f44b0bbeb250019e583d721296eb1a3adccd62c2f76e4abed99bdd860
-  data.tar.gz: c9ab4052480bcbd91e3452eba2d2e425013eba043f4d825b4f5a88f92a248ca780368206a5c06b0bf2ea9a67dea93fda8163babef2c64e4147cb38c650486f6a
+  metadata.gz: 3f09f94ffd7f77b58981bcd291a46bd354c02b11800d550ee9419b76ea74049efe9aa4833bf8ee4e4d41199f84e926b03577315d61d8512c8808878420453542
+  data.tar.gz: 46e24892810dcb54266bad9647b9d2bbb0dde2c283b7e869183103dad84da238ada3dd37581f4a891c84c95af2fa45e33bb72c25e728281ede6027847bd9e984

data/.yardopts

@@ -7,3 +7,4 @@
 README.md
 LICENSE.md
 CHANGELOG.md
+docs/getting-started.md

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Release History
 
+### 0.3.5 / 2018-05-15
+
+* CHANGED: Exec logic now lives in a utils class.
+* CHANGED: Moved flag and arg blocks from Tool into the DSL.
+* CHANGED: Renamed `execute do` to `script do`, and Tool#executor to Tool#script.
+* IMPROVED: Help display can use `less` if available.
+
 ### 0.3.4 / 2018-05-14
 
 * CHANGED: Renamed switch to flag

data/README.md

@@ -1,15 +1,16 @@
 # Toys
 
-Toys is a command line binary that lets you build your own suite of command
-line tools (with commands and subcommands) using a Ruby DSL. Commands can be
-defined globally or scoped to directories.
+Toys is a command line binary that lets you build your own personal suite of
+command line tools using a Ruby DSL. Toys handles argument parsing, error
+reporting, logging, help text, and many other details for you. Toys is designed
+for software developers, IT specialists, and other power users who want to
+write and organize scripts to automate their workflows.
 
 Toys-Core is the command line tool framework underlying Toys. It can be used
-to create command line binaries using the Toys DSL.
+to create command line binaries using the internal Toys APIs.
 
-## Quick Start
-
-(TODO)
+To get started using toys-core for your own command line binary, see the
+{file:docs/getting-started.md Getting Started Guide}.
 
 ## Contributing
 

data/docs/getting-started.md

@@ -0,0 +1,8 @@
+# @title Getting Started
+
+# Getting Started With Toys-Core
+
+Toys-Core is the command line tool framework underlying Toys. It can be used
+to create command line binaries using the internal Toys APIs.
+
+(To be written)

data/lib/toys/cli.rb

@@ -292,7 +292,8 @@ module Toys
       #    description fields
       # *  {Toys::Middleware::ShowHelp} adding the `--help` flag
       # *  {Toys::Middleware::HandleUsageErrors}
-      # *  {Toys::Middleware::ShowHelp} providing default behavior for groups
+      # *  {Toys::Middleware::ShowHelp} providing default behavior for
+      #    namespaces
       # *  {Toys::Middleware::AddVerbosityFlags} adding the `--verbose` and
       #    `--quiet` flags for managing the logger level
       #

data/lib/toys/config_dsl.rb

@@ -49,7 +49,7 @@ module Toys
   #
   #       optional_arg :recipient, default: "world"
   #
-  #       execute do
+  #       script do
   #         puts "Hello, #{self[:recipient]}!"
   #       end
   #     end
@@ -87,9 +87,8 @@ module Toys
     ##
     # Create a subtool. You must provide a block defining the subtool.
     #
-    # If the subtool is already defined (either as a tool or a group), the old
-    # definition is discarded and replaced with the new definition. If the old
-    # tool was a group, all its descendants are also discarded, recursively.
+    # If the subtool is already defined (either as a tool or a namespace), the
+    # old definition is discarded and replaced with the new definition.
     #
     # @param [String] word The name of the subtool
     #
@@ -103,7 +102,7 @@ module Toys
     alias name tool
 
     ##
-    # Create an alias in the current group.
+    # Create an alias in the current namespace.
     #
     # @param [String] word The name of the alias
     # @param [String] target The target of the alias
@@ -165,9 +164,27 @@ module Toys
     # displayed with the tool in a subtool list. You may also use the
     # equivalent method `short_desc`.
     #
-    # 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.
+    # The description is a {Toys::Utils::WrappableString}, which may be word-
+    # wrapped when displayed in a help screen. You may pass a
+    # {Toys::Utils::WrappableString} directly to this method, or you may pass
+    # any input that can be used to construct a wrappable string:
+    #
+    # *   If you pass a String, its whitespace will be compacted (i.e. tabs,
+    #     newlines, and multiple consecutive whitespace will be turned into a
+    #     single space), and it will be word-wrapped on whitespace.
+    # *   If you pass an Array of Strings, each string will be considered a
+    #     literal word that cannot be broken, and wrapping will be done across
+    #     the strings in the array. In this case, whitespace is not compacted.
+    #
+    # For example, if you pass in a sentence as a simple string, it may be
+    # word wrapped when displayed:
+    #
+    #     desc "This sentence may be wrapped."
+    #
+    # To specify a sentence that should never be word-wrapped, pass it as the
+    # sole element of a string array:
+    #
+    #     desc ["This sentence will not be wrapped."]
     #
     # @param [Toys::Utils::WrappableString,String,Array<String>] str
     #
@@ -183,9 +200,18 @@ module Toys
     # Set the long description for the current tool. The long description is
     # displayed in the usage documentation for the tool itself.
     #
-    # 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.
+    # A long description is a series of descriptions, which are generally
+    # displayed in a series of lines/paragraphs. Each individual description
+    # uses the form described in the {Toys::ConfigDSL#desc} documentation, and
+    # may be word-wrapped when displayed. To insert a blank line, include an
+    # empty string as one of the descriptions.
+    #
+    # Example:
+    #
+    #     long_desc "This is an initial paragraph that might be word wrapped.",
+    #               "This next paragraph is followed by a blank line.",
+    #               "",
+    #               ["This line will not be wrapped."]
     #
     # @param [Toys::Utils::WrappableString,String,Array<String>...] strs
     #
@@ -198,9 +224,12 @@ module Toys
 
     ##
     # 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.
+    # the script may use to obtain the flag value from the context.
     # You may then provide the flags themselves in `OptionParser` form.
     #
+    # Attributes of the flag may be passed in as arguments to this method, or
+    # set in a block passed to this method.
+    #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
     # @param [String...] flags The flags in OptionParser format.
@@ -208,40 +237,41 @@ module Toys
     # @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 [String,Toys::Utils::WrappableString,
-    #     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
     #     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 [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.
+    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+    #     Long description for the flag. See {Toys::ConfigDSL#long_desc} for a
+    #     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, desc: nil, long_desc: nil,
-             only_unique: false, handler: nil,
-             &block)
+             accept: nil, default: nil, handler: nil, desc: nil, long_desc: nil,
+             only_unique: false)
       return self if _cur_tool.nil?
+      flag_dsl = FlagDSL.new(flags, accept, default, handler, desc, long_desc)
+      yield flag_dsl if block_given?
       _cur_tool.lock_definition_path(@path)
-      _cur_tool.add_flag(key, *flags,
-                         accept: accept, default: default,
-                         desc: desc, long_desc: long_desc,
-                         only_unique: only_unique, handler: handler,
-                         &block)
+      flag_dsl._add_to(_cur_tool, key, only_unique)
       self
     end
 
     ##
     # Add a required positional argument to the current tool. You must specify
-    # a key which the executor may use to obtain the argument value from the
+    # a key which the script may use to obtain the argument value from the
     # context.
     #
     # @param [Symbol] key The key to use to retrieve the value from the
@@ -249,27 +279,30 @@ module Toys
     # @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>] long_desc Long
-    #     description for the arg. Defaults to empty array.
-    #
-    def required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil, &block)
+    # @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.
+    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+    #     Long description for the flag. See {Toys::ConfigDSL#long_desc} for a
+    #     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.
+    # @yieldparam arg_dsl [Toys::ConfigDSL::ArgDSL] An object that lets you
+    #     configure this argument in a block.
+    #
+    def required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
       return self if _cur_tool.nil?
+      arg_dsl = ArgDSL.new(accept, nil, display_name, desc, long_desc)
+      yield arg_dsl if block_given?
       _cur_tool.lock_definition_path(@path)
-      _cur_tool.add_required_arg(key,
-                                 accept: accept, display_name: display_name,
-                                 desc: desc, long_desc: long_desc,
-                                 &block)
+      arg_dsl._add_required_to(_cur_tool, key)
       self
     end
     alias required required_arg
 
     ##
     # Add an optional positional argument to the current tool. You must specify
-    # a key which the executor may use to obtain the argument value from the
+    # a key which the script may use to obtain the argument value from the
     # context. If an optional argument is not given on the command line, the
     # value is set to the given default.
     #
@@ -281,29 +314,32 @@ module Toys
     # @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>] long_desc Long
-    #     description for the arg. Defaults to empty array.
+    # @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.
+    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+    #     Long description for the flag. See {Toys::ConfigDSL#long_desc} for a
+    #     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.
+    # @yieldparam arg_dsl [Toys::ConfigDSL::ArgDSL] An object that lets you
+    #     configure this argument in a block.
     #
     def optional_arg(key, default: nil, accept: nil, display_name: nil,
-                     desc: nil, long_desc: nil, &block)
+                     desc: nil, long_desc: nil)
       return self if _cur_tool.nil?
+      arg_dsl = ArgDSL.new(accept, default, display_name, desc, long_desc)
+      yield arg_dsl if block_given?
       _cur_tool.lock_definition_path(@path)
-      _cur_tool.add_optional_arg(key,
-                                 accept: accept, default: default, display_name: display_name,
-                                 desc: desc, long_desc: long_desc,
-                                 &block)
+      arg_dsl._add_optional_to(_cur_tool, key)
       self
     end
     alias optional optional_arg
 
     ##
     # Specify what should be done with unmatched positional arguments. You must
-    # specify a key which the executor may use to obtain the remaining args
-    # from the context.
+    # specify a key which the script may use to obtain the remaining args from
+    # the context.
     #
     # @param [Symbol] key The key to use to retrieve the value from the
     #     execution context.
@@ -313,38 +349,41 @@ module Toys
     # @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>] long_desc Long
-    #     description for the arg. Defaults to empty array.
+    # @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.
+    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+    #     Long description for the flag. See {Toys::ConfigDSL#long_desc} for a
+    #     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.
+    # @yieldparam arg_dsl [Toys::ConfigDSL::ArgDSL] An object that lets you
+    #     configure this argument in a block.
     #
     def remaining_args(key, default: [], accept: nil, display_name: nil,
-                       desc: nil, long_desc: nil, &block)
+                       desc: nil, long_desc: nil)
       return self if _cur_tool.nil?
+      arg_dsl = ArgDSL.new(accept, default, display_name, desc, long_desc)
+      yield arg_dsl if block_given?
       _cur_tool.lock_definition_path(@path)
-      _cur_tool.set_remaining_args(key,
-                                   accept: accept, default: default, display_name: display_name,
-                                   desc: desc, long_desc: long_desc,
-                                   &block)
+      arg_dsl._set_remaining_on(_cur_tool, key)
       self
     end
     alias remaining remaining_args
 
     ##
-    # Specify the executor for this tool. This is a block that will be called,
+    # Specify the script for this tool. This is a block that will be called,
     # with `self` set to a {Toys::Context}.
     #
-    def execute(&block)
+    def script(&block)
       return self if _cur_tool.nil?
       _cur_tool.lock_definition_path(@path)
-      _cur_tool.executor = block
+      _cur_tool.script = block
       self
     end
 
     ##
-    # Define a helper method that may be called from this tool's executor.
+    # Define a helper method that may be called from this tool's script.
     # You must provide a name for the method, and a block for the method
     # definition.
     #
@@ -359,7 +398,7 @@ module Toys
     end
 
     ##
-    # Specify that the given module should be mixed in to this tool's executor.
+    # Specify that the given module should be mixed in to this tool's script.
     # Effectively, the module is added to the {Toys::Context} object.
     # You may either provide a module directly, or specify the name of a
     # well-known module.
@@ -373,6 +412,175 @@ module Toys
       self
     end
 
+    ##
+    # DSL for a flag definition block. Lets you set flag attributes in a block
+    # instead of a long series of keyword arguments.
+    #
+    class FlagDSL
+      ## @private
+      def initialize(flags, accept, default, handler, desc, long_desc)
+        @flags = flags
+        @accept = accept
+        @default = default
+        @handler = handler
+        @desc = desc
+        @long_desc = long_desc
+      end
+
+      ##
+      # Add flags in OptionParser format. This may be called multiple times,
+      # and the results are cumulative.
+      # @param [String...] flags
+      #
+      def flags(*flags)
+        @flags += flags
+        self
+      end
+
+      ##
+      # Set the OptionParser acceptor.
+      # @param [Object] accept
+      #
+      def accept(accept)
+        @accept = accept
+        self
+      end
+
+      ##
+      # Set the default value.
+      # @param [Object] default
+      #
+      def default(default)
+        @default = default
+        self
+      end
+
+      ##
+      # Set the optional handler for setting/updating the value when a flag is
+      # parsed. It should be a Proc taking two arguments, the new given value
+      # and the previous value, and it should return the new value that should
+      # be set.
+      # @param [Proc] handler
+      #
+      def handler(handler)
+        @handler = handler
+        self
+      end
+
+      ##
+      # Set the short description. See {Toys::ConfigDSL#desc} for the allowed
+      # formats.
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
+      #
+      def desc(desc)
+        @desc = desc
+        self
+      end
+
+      ##
+      # Adds to the long description. This may be called multiple times, and
+      # the results are cumulative. See {Toys::ConfigDSL#long_desc} for the
+      # allowed formats.
+      # @param [String,Array<String>,Toys::Utils::WrappableString...] long_desc
+      #
+      def long_desc(*long_desc)
+        @long_desc += long_desc
+        self
+      end
+
+      ## @private
+      def _add_to(tool, key, only_unique)
+        tool.add_flag(key, @flags,
+                      accept: @accept, default: @default, handler: @handler,
+                      desc: @desc, long_desc: @long_desc,
+                      only_unique: only_unique)
+      end
+    end
+
+    ##
+    # DSL for an arg definition block. Lets you set arg attributes in a block
+    # instead of a long series of keyword arguments.
+    #
+    class ArgDSL
+      ## @private
+      def initialize(accept, default, display_name, desc, long_desc)
+        @accept = accept
+        @default = default
+        @display_name = display_name
+        @desc = desc
+        @long_desc = long_desc
+      end
+
+      ##
+      # Set the OptionParser acceptor.
+      # @param [Object] accept
+      #
+      def accept(accept)
+        @accept = accept
+        self
+      end
+
+      ##
+      # Set the default value.
+      # @param [Object] default
+      #
+      def default(default)
+        @default = default
+        self
+      end
+
+      ##
+      # Set the name of this arg as it appears in help screens.
+      # @param [String] display_name
+      #
+      def display_name(display_name)
+        @handler = display_name
+        self
+      end
+
+      ##
+      # Set the short description. See {Toys::ConfigDSL#desc} for the allowed
+      # formats.
+      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
+      #
+      def desc(desc)
+        @desc = desc
+        self
+      end
+
+      ##
+      # Adds to the long description. This may be called multiple times, and
+      # the results are cumulative. See {Toys::ConfigDSL#long_desc} for the
+      # allowed formats.
+      # @param [String,Array<String>,Toys::Utils::WrappableString...] long_desc
+      #
+      def long_desc(*long_desc)
+        @long_desc += long_desc
+        self
+      end
+
+      ## @private
+      def _add_required_to(tool, key)
+        tool.add_required_arg(key,
+                              accept: @accept, display_name: @display_name,
+                              desc: @desc, long_desc: @long_desc)
+      end
+
+      ## @private
+      def _add_optional_to(tool, key)
+        tool.add_optional_arg(key,
+                              accept: @accept, default: @default, display_name: @display_name,
+                              desc: @desc, long_desc: @long_desc)
+      end
+
+      ## @private
+      def _set_remaining_on(tool, key)
+        tool.set_remaining_args(key,
+                                accept: @accept, default: @default, display_name: @display_name,
+                                desc: @desc, long_desc: @long_desc)
+      end
+    end
+
     ## @private
     def _binding
       binding