toys 0.7.0 → 0.8.0

data/lib/toys.rb

@@ -1,38 +1,30 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 ##
 # Toys is a configurable command line tool. Write commands in config files
-# using a simple DSL, and Toys will provide the command line binary and take
-# care of all the details such as argument parsing, online help, and error
+# using a simple DSL, and Toys will provide the command line executable and
+# take care of all the details such as argument parsing, online help, and error
 # reporting. Toys is designed for software developers, IT professionals, and
 # other power users who want to write and organize scripts to automate their
 # workflows. It can also be used as a Rake replacement, providing a more
@@ -40,10 +32,12 @@
 #
 module Toys
   ##
-  # Path to the Toys binary
-  # @return [String]
+  # Path to the Toys executable.
+  #
+  # @return [String] Absolute path to the executable
+  # @return [nil] if the Toys executable is not running.
   #
-  BINARY_PATH = ::ENV["TOYS_BIN_PATH"] || "toys"
+  EXECUTABLE_PATH = ::ENV["TOYS_BIN_PATH"]
 
   ##
   # Namespace for standard template classes.
@@ -53,11 +47,15 @@ end
 
 require "toys/version"
 
-if ::ENV["TOYS_CORE_LIB_PATH"]
-  $LOAD_PATH.unshift(::ENV["TOYS_CORE_LIB_PATH"])
-else
-  gem "toys-core", "= #{::Toys::VERSION}"
+# Add toys-core to the load path. The Toys debug scripts will set this
+# environment variable explicitly, but in production, we get it from rubygems.
+# We prepend to $LOAD_PATH directly rather than calling Kernel.gem, so that we
+# don't get clobbered in case someone sets up bundler later.
+::ENV["TOYS_CORE_LIB_PATH"] ||= begin
+  dep = Gem::Dependency.new("toys-core", "= #{::Toys::VERSION}")
+  dep.to_spec.full_require_paths.first
 end
-require "toys-core"
+$LOAD_PATH.unshift(::ENV["TOYS_CORE_LIB_PATH"])
 
+require "toys-core"
 require "toys/standard_cli"

data/lib/toys/standard_cli.rb

@@ -1,104 +1,90 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 require "logger"
 
 module Toys
   ##
-  # Helpers that configure the toys-core CLI with the behavior for the
-  # standard Toys binary.
+  # Subclass of `Toys::CLI` configured for the behavior of the standard Toys
+  # executable.
   #
-  module StandardCLI
+  class StandardCLI < CLI
     ##
-    # Path to standard built-in tools
-    # @return [String]
-    #
-    BUILTINS_PATH = ::File.join(::File.dirname(::File.dirname(__dir__)), "builtins").freeze
-
-    ##
-    # Standard toys configuration directory name
+    # Standard toys configuration directory name.
     # @return [String]
     #
     CONFIG_DIR_NAME = ".toys"
 
     ##
-    # Standard toys configuration file name
+    # Standard toys configuration file name.
     # @return [String]
     #
     CONFIG_FILE_NAME = ".toys.rb"
 
     ##
-    # Standard index file name in a toys configuration
+    # Standard index file name in a toys configuration.
     # @return [String]
     #
     INDEX_FILE_NAME = ".toys.rb"
 
     ##
-    # Standard preload directory name in a toys configuration
+    # Standard preload directory name in a toys configuration.
     # @return [String]
     #
-    PRELOAD_DIRECTORY_NAME = ".preload"
+    PRELOAD_DIR_NAME = ".preload"
 
     ##
-    # Standard preload file name in a toys configuration
+    # Standard preload file name in a toys configuration.
     # @return [String]
     #
     PRELOAD_FILE_NAME = ".preload.rb"
 
     ##
-    # Standard data directory name in a toys configuration
+    # Standard data directory name in a toys configuration.
     # @return [String]
     #
-    DATA_DIRECTORY_NAME = ".data"
+    DATA_DIR_NAME = ".data"
 
     ##
-    # Name of standard toys binary
+    # Name of the standard toys executable.
     # @return [String]
     #
-    BINARY_NAME = "toys"
+    EXECUTABLE_NAME = "toys"
 
     ##
-    # Delimiter characters recognized
+    # Delimiter characters recognized.
     # @return [String]
     #
     EXTRA_DELIMITERS = ":."
 
     ##
-    # Short description for the standard root tool
+    # Short description for the standard root tool.
     # @return [String]
     #
     DEFAULT_ROOT_DESC = "Your personal command line tool"
 
     ##
-    # Help text for the standard root tool
+    # Help text for the standard root tool.
     # @return [String]
     #
     DEFAULT_ROOT_LONG_DESC =
@@ -109,13 +95,13 @@ module Toys
       " For detailed information, see https://www.rubydoc.info/gems/toys"
 
     ##
-    # Short description for the verion flag
+    # Short description for the version flag.
     # @return [String]
     #
     DEFAULT_VERSION_FLAG_DESC = "Show the version of Toys."
 
     ##
-    # Name of the toys path environment variable
+    # Name of the toys path environment variable.
     # @return [String]
     #
     TOYS_PATH_ENV = "TOYS_PATH"
@@ -124,51 +110,52 @@ module Toys
     # Create a standard CLI, configured with the appropriate paths and
     # middleware.
     #
-    # @param [String,nil] cur_dir Starting search directory for configs.
+    # @param cur_dir [String,nil] Starting search directory for configs.
     #     Defaults to the current working directory.
-    # @return [Toys::CLI]
     #
-    def self.create(cur_dir: nil)
-      cli = CLI.new(
-        binary_name: BINARY_NAME,
+    def initialize(cur_dir: nil)
+      super(
+        executable_name: EXECUTABLE_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,
-        preload_directory_name: PRELOAD_DIRECTORY_NAME,
-        data_directory_name: DATA_DIRECTORY_NAME,
+        preload_dir_name: PRELOAD_DIR_NAME,
+        data_dir_name: DATA_DIR_NAME,
         extra_delimiters: EXTRA_DELIMITERS,
         middleware_stack: default_middleware_stack,
         template_lookup: default_template_lookup
       )
-      add_standard_paths(cli, cur_dir: cur_dir)
-      cli
+      add_standard_paths(cur_dir: cur_dir)
     end
 
+    private
+
     ##
     # Add paths for a toys standard CLI. Paths added, in order from high to
     # low priority, are:
     #
-    # *  Search the current directory and all ancestors for config files and
-    #    directories.
-    # *  Read the `TOYS_PATH` environment variable and search for config files
-    #    and directories in the given paths. If this variable is empty, use
-    #    `$HOME:/etc` by default.
-    # *  The builtins for the standard toys binary.
+    #  *  Search the current directory and all ancestors for config files and
+    #     directories.
+    #  *  Read the `TOYS_PATH` environment variable and search for config files
+    #     and directories in the given paths. If this variable is empty, use
+    #     `$HOME:/etc` by default.
+    #  *  The builtins for the standard toys executable.
     #
-    # @param [Toys::CLI] cli Add paths to this CLI
-    # @param [String,nil] cur_dir Starting search directory for configs.
+    # @param cur_dir [String,nil] Starting search directory for configs.
     #     Defaults to the current working directory.
-    # @param [Array<String>,nil] global_dirs Optional list of global
+    # @param global_dirs [Array<String>,nil] Optional list of global
     #     directories, or `nil` to use the defaults.
+    # @return [self]
     #
-    def self.add_standard_paths(cli, cur_dir: nil, global_dirs: nil)
+    def add_standard_paths(cur_dir: nil, global_dirs: nil)
       cur_dir ||= ::Dir.pwd
       global_dirs ||= default_global_dirs
-      cli.add_search_path_hierarchy(start: cur_dir, terminate: global_dirs)
-      global_dirs.each { |path| cli.add_search_path(path) }
-      cli.add_config_path(BUILTINS_PATH)
-      cli
+      add_search_path_hierarchy(start: cur_dir, terminate: global_dirs)
+      global_dirs.each { |path| add_search_path(path) }
+      builtins_path = ::File.join(::File.dirname(::File.dirname(__dir__)), "builtins")
+      add_config_path(builtins_path)
+      self
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -178,12 +165,12 @@ module Toys
     #
     # @return [Array]
     #
-    def self.default_middleware_stack
+    def default_middleware_stack
       [
         [
           :set_default_descriptions,
           default_root_desc: DEFAULT_ROOT_DESC,
-          default_root_long_desc: DEFAULT_ROOT_LONG_DESC
+          default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
         ],
         [
           :show_help,
@@ -196,28 +183,20 @@ module Toys
           default_recursive: true,
           allow_root_args: true,
           show_source_path: true,
-          use_less: true
+          use_less: true,
+          fallback_execution: true,
         ],
         [
           :show_root_version,
           version_string: ::Toys::VERSION,
-          version_flag_desc: DEFAULT_VERSION_FLAG_DESC
+          version_flag_desc: DEFAULT_VERSION_FLAG_DESC,
         ],
         [
-          :handle_usage_errors
+          :handle_usage_errors,
         ],
         [
-          :show_help,
-          fallback_execution: true,
-          recursive_flags: true,
-          search_flags: true,
-          default_recursive: true,
-          show_source_path: true,
-          use_less: true
+          :add_verbosity_flags,
         ],
-        [
-          :add_verbosity_flags
-        ]
       ]
     end
 
@@ -228,7 +207,7 @@ module Toys
     #
     # @return [Array<String>]
     #
-    def self.default_global_dirs
+    def default_global_dirs
       paths = ::ENV[TOYS_PATH_ENV].to_s.split(::File::PATH_SEPARATOR)
       paths = [::Dir.home, "/etc"] if paths.empty?
       paths
@@ -241,10 +220,10 @@ module Toys
     ##
     # Returns a ModuleLookup for the default templates.
     #
-    # @return [Toys::Utils::ModuleLookup]
+    # @return [Toys::ModuleLookup]
     #
-    def self.default_template_lookup
-      Utils::ModuleLookup.new.add_path("toys/templates")
+    def default_template_lookup
+      ModuleLookup.new.add_path("toys/templates")
     end
   end
 end

data/lib/toys/templates/clean.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -46,9 +38,9 @@ module Toys
       ##
       # Create the template settings for the Clean template.
       #
-      # @param [String] name Name of the tool to create. Defaults to
+      # @param name [String] Name of the tool to create. Defaults to
       #     {DEFAULT_TOOL_NAME}.
-      # @param [Array<String>] paths An array of glob patterns indicating what
+      # @param paths [Array<String>] An array of glob patterns indicating what
       #     to clean.
       #
       def initialize(name: DEFAULT_TOOL_NAME, paths: [])
@@ -59,7 +51,7 @@ module Toys
       attr_accessor :name
       attr_accessor :paths
 
-      to_expand do |template|
+      on_expand do |template|
         tool(template.name) do
           desc "Clean built files and directories."