toys 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dcbd6fabf227072fda60d4acebcc09ae1a8af3d10db580bcea3d4a56a6623fd
-  data.tar.gz: bdc7a717793c190af3cb0c470cfbd97078779478e1528297397303c88af1b6a3
+  metadata.gz: 674d3b61ad2be8749dddafed99ab0ad70fbda515157024afd2fb7b3dc3c1108c
+  data.tar.gz: 83f446e5eb534360cbc50f1f032c758d6b457b97a280661887632f1016abd1f5
 SHA512:
-  metadata.gz: 74b91bdd53c8ca7aec7ba1b1d5ed9d98e2f3a826846ea9d41975391d504e14047d25f6db9551318568fabb81194dd3bf896183316a50e2fe63f92a4e0811ee9c
-  data.tar.gz: 81617b1a8aff51c05cae72cc79e4fffd5030af0176f50f389e3e235334161efbbb9f6ca60e5273f15a9a00cf76bbbfc675aec0a906c87110991e760c9ff1e2da
+  metadata.gz: f35911821abba0a114aabf8f6e4a1a5bd1d6727edb3ec8e8eb0f035fac8cb08fecb737ff38c561a9f09caddb5f697219c5a349fa6c4ace63db879df35fb33164
+  data.tar.gz: 6dafe20e17be9816913edd9c498856f01fc3bac19249c11e62836895fc2234aa7231d2ecd322adc825d58f8d1ab4d0c51c756110831e7ece22b0cdf8a155bff2

data/.yardopts

@@ -1,9 +1,7 @@
 --no-private
 --title=Toys
 --markup=markdown
---embed-mixin=ClassMethods
 --main=README.md
---exclude=lib/toys/builtins
 ./lib/**/*.rb
 -
 README.md

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Release History
 
+### 0.3.2 / 2018-05-07
+
+* CHANGED: Split core engine out into separate "toys-core" gem. See the
+  toys-core changelog for additional changes in core.
+* CHANGED: Tools can no longer be alias_of. However, alias_as still works, and
+  it is now possible to create an alias using alias_tool.
+* IMPROVED: The root tool now responds to the "--version" switch.
+* IMPROVED: Group help can now "--search" for subcommands.
+* IMPROVED: Help shows the config file path on "--verbose".
+* IMPROVED: You can now run a sub-instance of toys from an executor.
+
+### 0.3.1 / 2018-05-02
+
+* CHANGED: Subcommand display is now recursive by default.
+* IMPROVED: Improved error messaging for bad switch syntax.
+* FIXED: toys system update now reports experimental versions correctly.
+* FIXED: Subtools of an overridden group are now properly deleted.
+* DOCS: Completed a first pass on class and method documentation.
+* INTERNAL: Adjusted naming of switch-related methods.
+
 ### 0.3.0 / 2018-04-30
 
 * Initial generally usable release

data/README.md

@@ -1,21 +1,10 @@
 # Toys
 
-[![Travis-CI Build Status](https://travis-ci.org/dazuma/toys.svg)](https://travis-ci.org/dazuma/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 Ruby library and command line tool that lets you build your own
-command line suite of tools (with commands and subcommands) using a Ruby DSL.
-You can define commands globally or configure special commands scoped to
-individual directories.
-
-## Installation
-
-This software is distributed as a Ruby gem and may be installed using:
-
-```
-gem install toys
-```
-
-## Usage
+## Quick Start
 
 (TODO)
 
@@ -29,15 +18,6 @@ guidelines will be provided when the software stabilizes further.
 The source can be found on Github at
 [https://github.com/dazuma/toys](https://github.com/dazuma/toys)
 
-### TODO items
-
-* Decide about highline integration
-* Output formats middleware
-* System paths tool
-* Search function in group help
-* Split out toys-core gem
-* Write overall documentation
-
 ## License
 
 Copyright 2018 Daniel Azuma

data/bin/toys

@@ -32,4 +32,4 @@
 $LOAD_PATH.unshift(::File.absolute_path(::File.join(::File.dirname(__dir__), "lib")))
 require "toys"
 
-::Toys::CLI.create_standard.run(::ARGV)
+exit(::Toys::StandardCLI.create.run(::ARGV))

data/{lib/toys/builtins → builtins}/do.rb

@@ -31,7 +31,7 @@ desc "Run multiple tools in order"
 
 switch(:delim, "-d", "--delim=VALUE", default: ",", doc: "Set the delimiter")
 
-remaining_args(:args)
+remaining_args(:args, doc: "Tools to run")
 
 execute do
   delim = self[:delim]

data/lib/toys.rb

@@ -34,20 +34,15 @@
 # individual directories.
 #
 module Toys
-  ##
-  # Namespace for common utility classes.
-  #
-  module Utils; end
 end
 
-require "toys/cli"
-require "toys/config_dsl"
-require "toys/context"
-require "toys/errors"
-require "toys/helpers"
-require "toys/loader"
-require "toys/middleware"
-require "toys/template"
-require "toys/templates"
-require "toys/tool"
 require "toys/version"
+
+if ::ENV["TOYS_CORE_LIB_PATH"]
+  $LOAD_PATH.unshift(::ENV["TOYS_CORE_LIB_PATH"])
+else
+  gem "toys-core", "= #{::Toys::VERSION}"
+end
+require "toys-core"
+
+require "toys/standard_cli"

data/lib/toys/standard_cli.rb

@@ -0,0 +1,151 @@
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * 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.
+;
+
+require "logger"
+
+require "toys/middleware/show_version"
+
+module Toys
+  ##
+  # Helpers that configure the toys-core CLI with the behavior for the
+  # standard Toys binary.
+  #
+  module StandardCLI
+    ##
+    # Path to standard built-in tools
+    # @return [String]
+    #
+    BUILTINS_PATH = ::File.join(::File.dirname(::File.dirname(__dir__)), "builtins").freeze
+
+    ##
+    # Standard toys configuration directory name
+    # @return [String]
+    #
+    CONFIG_DIR_NAME = ".toys".freeze
+
+    ##
+    # Standard toys configuration file name
+    # @return [String]
+    #
+    CONFIG_FILE_NAME = ".toys.rb".freeze
+
+    ##
+    # Standard index file name in a toys configuration
+    # @return [String]
+    #
+    INDEX_FILE_NAME = ".toys.rb".freeze
+
+    ##
+    # Standard toys preload file name
+    # @return [String]
+    #
+    PRELOAD_FILE_NAME = ".preload.rb".freeze
+
+    ##
+    # Name of standard toys binary
+    # @return [String]
+    #
+    BINARY_NAME = "toys".freeze
+
+    ##
+    # Help text for the standard root tool
+    # @return [String]
+    #
+    DEFAULT_ROOT_DESC =
+      "Toys is your personal command line tool. You can add to the list of" \
+      " commands below by writing scripts in Ruby using a simple DSL, and" \
+      " toys will organize and document them, and make them available" \
+      " globally or scoped to specific directories that you choose." \
+      " For detailed information, see https://www.rubydoc.info/gems/toys".freeze
+
+    ##
+    # Create a standard CLI, configured with the appropriate paths and
+    # middleware.
+    #
+    # @param [String,nil] directory Starting search directory for configs.
+    #     Defaults to the current working directory.
+    # @return [Toys::CLI]
+    #
+    def self.create(directory: nil)
+      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: default_middleware_stack
+      )
+      add_standard_paths(cli, directory: directory)
+      cli
+    end
+
+    ##
+    # 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.
+    #
+    # @param [String,nil] directory Starting search directory for configs.
+    #     Defaults to the current working directory.
+    # @param [Toys::CLI] cli Add paths to this CLI
+    #
+    def self.add_standard_paths(cli, directory: nil)
+      cli.add_search_path_hierarchy(start: directory)
+      paths = ::ENV["TOYS_PATH"].to_s.split(::File::PATH_SEPARATOR)
+      if paths.empty?
+        paths << ::ENV["HOME"] if ::ENV["HOME"]
+        paths << "/etc" if ::File.directory?("/etc") && ::File.readable?("/etc")
+      end
+      paths.each { |path| cli.add_search_path(path) }
+      cli.add_config_path(BUILTINS_PATH)
+      cli
+    end
+
+    ##
+    # Returns a the middleware for the standard Toys CLI.
+    #
+    # @return [Array]
+    #
+    def self.default_middleware_stack
+      version_displayer = Middleware::ShowVersion.root_version_displayer(::Toys::VERSION)
+      [
+        [:set_default_descriptions, default_root_desc: DEFAULT_ROOT_DESC],
+        [:handle_usage_errors],
+        [:show_version, version_displayer: version_displayer],
+        [:show_usage],
+        [:add_verbosity_switches]
+      ]
+    end
+  end
+end

data/lib/toys/version.rb

@@ -29,8 +29,8 @@
 
 module Toys
   ##
-  # Current version of Toys
+  # Current version of the Toys command line binary
   # @return [String]
   #
-  VERSION = "0.3.1".freeze
+  VERSION = "0.3.2".freeze
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-02 00:00:00.000000000 Z
+date: 2018-05-07 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: toys-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -93,33 +107,10 @@ files:
 - LICENSE.md
 - README.md
 - bin/toys
+- builtins/do.rb
+- builtins/system.rb
 - lib/toys.rb
-- lib/toys/builtins/do.rb
-- lib/toys/builtins/system.rb
-- lib/toys/cli.rb
-- lib/toys/config_dsl.rb
-- lib/toys/context.rb
-- lib/toys/errors.rb
-- lib/toys/helpers.rb
-- lib/toys/helpers/exec.rb
-- lib/toys/helpers/file_utils.rb
-- lib/toys/loader.rb
-- lib/toys/middleware.rb
-- lib/toys/middleware/base.rb
-- lib/toys/middleware/set_verbosity.rb
-- lib/toys/middleware/show_group_usage.rb
-- lib/toys/middleware/show_tool_usage.rb
-- lib/toys/middleware/show_usage_errors.rb
-- lib/toys/template.rb
-- lib/toys/templates.rb
-- lib/toys/templates/clean.rb
-- lib/toys/templates/gem_build.rb
-- lib/toys/templates/minitest.rb
-- lib/toys/templates/rubocop.rb
-- lib/toys/templates/yardoc.rb
-- lib/toys/tool.rb
-- lib/toys/utils/module_lookup.rb
-- lib/toys/utils/usage.rb
+- lib/toys/standard_cli.rb
 - lib/toys/version.rb
 homepage: https://github.com/dazuma/toys
 licenses:

data/lib/toys/cli.rb

@@ -1,271 +0,0 @@
-# Copyright 2018 Daniel Azuma
-#
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# * 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.
-;
-
-require "logger"
-
-module Toys
-  ##
-  # A Toys-based CLI.
-  #
-  # Use this class to implement a CLI using Toys.
-  #
-  class CLI
-    ##
-    # Path to default builtins
-    # @return [String]
-    #
-    BUILTINS_PATH = ::File.join(__dir__, "builtins").freeze
-
-    ##
-    # Default name of toys configuration directory
-    # @return [String]
-    #
-    DEFAULT_DIR_NAME = ".toys".freeze
-
-    ##
-    # Default name of toys configuration file
-    # @return [String]
-    #
-    DEFAULT_FILE_NAME = ".toys.rb".freeze
-
-    ##
-    # Default name of toys preload file
-    # @return [String]
-    #
-    DEFAULT_PRELOAD_NAME = ".preload.rb".freeze
-
-    ##
-    # Default name of toys binary
-    # @return [String]
-    #
-    DEFAULT_BINARY_NAME = "toys".freeze
-
-    ##
-    # Default help text for the root tool
-    # @return [String]
-    #
-    DEFAULT_ROOT_DESC =
-      "Toys is your personal command line tool. You can add to the list of" \
-      " commands below by writing scripts in Ruby using a simple DSL, and" \
-      " toys will organize and document them, and make them available" \
-      " globally or scoped to specific directories that you choose." \
-      " For detailed information, see https://www.rubydoc.info/gems/toys".freeze
-
-    ##
-    # Create a CLI
-    #
-    # @param [String,nil] binary_name The binary name displayed in help text.
-    #     Optional. Defaults to the ruby program name.
-    # @param [Logger,nil] logger The logger to use. If not provided, a default
-    #     logger that writes to `STDERR` is used.
-    # @param [String,nil] config_dir_name A directory with this name that
-    #     appears in the loader path, is treated as a configuration directory
-    #     whose contents are loaded into the toys configuration. Optional.
-    #     If not provided, toplevel configuration directories are disabled.
-    #     The default toys CLI sets this to `".toys"`.
-    # @param [String,nil] config_file_name A file with this name that appears
-    #     in the loader path, is treated as a toplevel configuration file
-    #     whose contents are loaded into the toys configuration. Optional.
-    #     If not provided, toplevel configuration files are disabled.
-    #     The default toys CLI sets this to `".toys.rb"`.
-    # @param [String,nil] index_file_name A file with this name that appears
-    #     in any configuration directory (not just a toplevel directory) is
-    #     loaded first as a standalone configuration file. If not provided,
-    #     standalone configuration files are disabled.
-    #     The default toys CLI sets this to `".toys.rb"`.
-    # @param [String,nil] preload_file_name A file with this name that appears
-    #     in any configuration directory (not just a toplevel directory) is
-    #     loaded before any configuration files. It is not treated as a
-    #     configuration file in that the configuration DSL is not honored. You
-    #     may use such a file to define auxiliary Ruby modules and classes that
-    #     used by the tools defined in that directory.
-    # @param [Array] middleware An array of middleware that will be used by
-    #     default for all tools loaded by this CLI.
-    # @param [String] root_desc The description of the root tool.
-    #
-    def initialize(
-      binary_name: nil,
-      logger: nil,
-      config_dir_name: nil,
-      config_file_name: nil,
-      index_file_name: nil,
-      preload_file_name: nil,
-      middleware: [],
-      root_desc: nil
-    )
-      logger ||= self.class.default_logger
-      @loader = Loader.new(
-        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: middleware,
-        root_desc: root_desc
-      )
-      @context_base = Context::Base.new(@loader, binary_name, logger)
-    end
-
-    ##
-    # Add one or more configuration files/directories to the loader.
-    #
-    # If a CLI has a default tool set, it might use this to point to the
-    # directory that defines those tools. For example, the default Toys CLI
-    # uses this to load the builtin tools from the `builtins` directory.
-    #
-    # @param [String,Array<String>] paths One or more paths to add.
-    #
-    def add_config_paths(paths)
-      @loader.add_config_paths(paths)
-      self
-    end
-
-    ##
-    # Add one or more path directories to the loader. These directories are
-    # searched for config directories and config files. Typically a CLI may
-    # include the current directory, or the user's home directory, `/etc` or
-    # other configuration-centric directories here.
-    #
-    # @param [String,Array<String>] paths One or more paths to add.
-    #
-    def add_paths(paths)
-      @loader.add_paths(paths)
-      self
-    end
-
-    ##
-    # Add the given path and all ancestor directories to the loader as paths.
-    # You may optionally provide a stopping point using the `base` argument,
-    # which, if present, will be the _last_ directory added.
-    #
-    # @param [String] path The first directory to add
-    # @param [String] base The last directory to add. Defaults to `"/"`.
-    #
-    def add_path_hierarchy(path = nil, base = "/")
-      path ||= ::Dir.pwd
-      paths = []
-      loop do
-        paths << path
-        break if !base || path == base
-        next_path = ::File.dirname(path)
-        break if next_path == path
-        path = next_path
-      end
-      @loader.add_paths(paths)
-      self
-    end
-
-    ##
-    # Add a standard set of paths. This includes the contents of the
-    # `TOYS_PATH` environment variable if present, the current user's home
-    # directory, and any system configuration directories such as `/etc`.
-    #
-    def add_standard_paths
-      toys_path = ::ENV["TOYS_PATH"].to_s.split(::File::PATH_SEPARATOR)
-      if toys_path.empty?
-        toys_path << ::ENV["HOME"] if ::ENV["HOME"]
-        toys_path << "/etc" if ::File.directory?("/etc") && ::File.readable?("/etc")
-      end
-      @loader.add_paths(toys_path)
-      self
-    end
-
-    ##
-    # Run the CLI with the given command line arguments.
-    #
-    def run(*args)
-      exit(@context_base.run(args.flatten, verbosity: 0))
-    end
-
-    class << self
-      ##
-      # Configure and create the standard Toys CLI.
-      #
-      # @return [Toys::CLI]
-      #
-      def create_standard
-        cli = new(
-          binary_name: DEFAULT_BINARY_NAME,
-          config_dir_name: DEFAULT_DIR_NAME,
-          config_file_name: DEFAULT_FILE_NAME,
-          index_file_name: DEFAULT_FILE_NAME,
-          preload_file_name: DEFAULT_PRELOAD_NAME,
-          middleware: default_middleware_stack,
-          root_desc: DEFAULT_ROOT_DESC
-        )
-        cli.add_path_hierarchy
-        cli.add_standard_paths
-        cli.add_config_paths(BUILTINS_PATH)
-        cli
-      end
-
-      ##
-      # Returns a default set of middleware used by the standard Toys CLI.
-      # This middleware handles usage errors, provides a behavior for groups
-      # that displays the group command list, provides a `--help` option for
-      # showing individual tool documentation, and provides `--verbose` and
-      # `--quiet` switches for setting the verbosity, which in turn controls
-      # the logger level.
-      #
-      # @return [Array]
-      #
-      def default_middleware_stack
-        [
-          Middleware.lookup(:show_usage_errors).new,
-          Middleware.lookup(:show_group_usage).new,
-          Middleware.lookup(:show_tool_usage).new,
-          Middleware.lookup(:set_verbosity).new
-        ]
-      end
-
-      ##
-      # Returns a default logger that logs to `STDERR`.
-      #
-      # @return [Logger]
-      #
-      def default_logger
-        logger = ::Logger.new(::STDERR)
-        logger.formatter = proc do |severity, time, _progname, msg|
-          msg_str =
-            case msg
-            when ::String
-              msg
-            when ::Exception
-              "#{msg.message} (#{msg.class})\n" << (msg.backtrace || []).join("\n")
-            else
-              msg.inspect
-            end
-          timestr = time.strftime("%Y-%m-%d %H:%M:%S")
-          format("[%s %5s]  %s\n", timestr, severity, msg_str)
-        end
-        logger.level = ::Logger::WARN
-        logger
-      end
-    end
-  end
-end