toys 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1303b77289f7e37c45866ec22513df6187556c2d7188b97d2706731b73377c5
-  data.tar.gz: 31c4013f235e7fb83575c9b031798dc410ab0bdee2395303f3f54e54fc870c05
+  metadata.gz: 1dcbd6fabf227072fda60d4acebcc09ae1a8af3d10db580bcea3d4a56a6623fd
+  data.tar.gz: bdc7a717793c190af3cb0c470cfbd97078779478e1528297397303c88af1b6a3
 SHA512:
-  metadata.gz: 8389b529719c6135483a52a65ec2521e90964be02fac0da56fa7016672da8f4f9a8f7ad24c8a0493db8558040c3c80e47553656f3a567524f4a7e310669cd05a
-  data.tar.gz: 708270b18a969b0adb5aa16c9b517966d82a3531a4a88604b7ee3cae27ecb67c839ef40318378c89d6a3347658c6d3fe590a6482177d0a899d96eaf0847f6366
+  metadata.gz: 74b91bdd53c8ca7aec7ba1b1d5ed9d98e2f3a826846ea9d41975391d504e14047d25f6db9551318568fabb81194dd3bf896183316a50e2fe63f92a4e0811ee9c
+  data.tar.gz: 81617b1a8aff51c05cae72cc79e4fffd5030af0176f50f389e3e235334161efbbb9f6ca60e5273f15a9a00cf76bbbfc675aec0a906c87110991e760c9ff1e2da

data/.yardopts

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

data/README.md

@@ -1,5 +1,7 @@
 # Toys
 
+[![Travis-CI Build Status](https://travis-ci.org/dazuma/toys.svg)](https://travis-ci.org/dazuma/toys/)
+
 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
@@ -29,11 +31,12 @@ The source can be found on Github at
 
 ### TODO items
 
-* Document methods
-* Write overall documentation
 * Decide about highline integration
 * Output formats middleware
 * System paths tool
+* Search function in group help
+* Split out toys-core gem
+* Write overall documentation
 
 ## License
 

data/lib/toys.rb

@@ -35,13 +35,13 @@
 #
 module Toys
   ##
-  # Namespace for common utility classes
+  # Namespace for common utility classes.
   #
   module Utils; end
 end
 
-require "toys/builder"
 require "toys/cli"
+require "toys/config_dsl"
 require "toys/context"
 require "toys/errors"
 require "toys/helpers"

data/lib/toys/builtins/system.rb

@@ -43,6 +43,7 @@ tool "update" do
   use :exec
 
   execute do
+    logger.info "Checking rubygems for the latest toys release..."
     version_info = capture("gem query -q -r -e toys")
     if version_info =~ /toys\s\((.+)\)/
       latest_version = ::Gem::Version.new($1)
@@ -50,6 +51,9 @@ tool "update" do
       if latest_version > cur_version
         logger.warn("Updating toys from #{cur_version} to #{latest_version}...")
         sh("gem install toys")
+      elsif latest_version < cur_version
+        logger.warn("Toys is already at experimental version #{cur_version}, which is later than" \
+                    " the latest released version #{latest_version}")
       else
         logger.warn("Toys is already at the latest version: #{latest_version}")
       end

data/lib/toys/cli.rb

@@ -31,7 +31,9 @@ require "logger"
 
 module Toys
   ##
-  # A Toys-based CLI
+  # A Toys-based CLI.
+  #
+  # Use this class to implement a CLI using Toys.
   #
   class CLI
     ##
@@ -75,6 +77,38 @@ module Toys
       " 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,
@@ -97,16 +131,41 @@ module Toys
       @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 = []
@@ -121,6 +180,11 @@ module Toys
       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?
@@ -131,11 +195,19 @@ module Toys
       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,
@@ -152,15 +224,30 @@ module Toys
         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(:group_default).new,
-          Middleware.lookup(:show_tool_help).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|

data/lib/toys/config_dsl.rb

@@ -0,0 +1,432 @@
+# 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.
+;
+
+module Toys
+  ##
+  # This class defines the DSL for a toys configuration file.
+  #
+  # A toys configuration defines one or more named tools. It provides syntax
+  # for setting the description, defining switches and arguments, specifying
+  # how to execute the tool, and requesting helper modules and other services.
+  # It also lets you define subtools, nested arbitrarily deep, using blocks.
+  #
+  # Generally ConfigDSL is invoked from the {Loader}. Applications should not
+  # need to create instances of ConfigDSL directly.
+  #
+  # ## Simple example
+  #
+  # Create a file called `.toys.rb` in the current directory, with the
+  # following contents:
+  #
+  #     tool "greet" do
+  #       desc "Prints a simple greeting"
+  #
+  #       optional_arg :recipient, default: "world"
+  #
+  #       execute do
+  #         puts "Hello, #{self[:recipient]}!"
+  #       end
+  #     end
+  #
+  # Now you can execute it using:
+  #
+  #     toys greet
+  #
+  # or try:
+  #
+  #     toys greet rubyists
+  #
+  class ConfigDSL
+    ##
+    # Create an instance of the DSL.
+    # @private
+    #
+    # @param [String] path The path to the config file being evaluated
+    # @param [Toys::Tool] tool The tool being defined at the top level
+    # @param [Array<String>,nil] remaining_words Arguments remaining in the
+    #     current lookup.
+    # @param [Integer] priority Priority of this configuration
+    # @param [Toys::Loader] loader Current active loader
+    # @param [:tool,:append,:group] type Type of tool being configured
+    #
+    # @return [Toys::ConfigDSL]
+    #
+    def initialize(path, tool, remaining_words, priority, loader, type)
+      @path = path
+      @tool = tool
+      @remaining_words = remaining_words
+      @priority = priority
+      @loader = loader
+      @type = type
+    end
+
+    ##
+    # Create a subtool.
+    #
+    # If the subtool is not an alias, 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.
+    #
+    # @param [String] word The name of the subtool
+    # @param [String,nil] alias_of If set, this subtool is set to be an alias
+    #     of the given subtool name. Defaults to `nil`, indicating the subtool
+    #     is not an alias.
+    #
+    def tool(word, alias_of: nil, &block)
+      word = word.to_s
+      subtool = @loader.get_or_create_tool(@tool.full_name + [word], @priority, assume_parent: true)
+      return self if subtool.nil?
+      if alias_of
+        if block
+          raise ToolDefinitionError, "Cannot take a block with alias_of"
+        end
+        subtool.make_alias_of_word(alias_of.to_s)
+        return self
+      end
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      ConfigDSL.evaluate(@path, subtool, next_remaining, @priority, @loader, :tool, block)
+      self
+    end
+    alias name tool
+
+    ##
+    # Append subtools to an existing group.
+    #
+    # Pass a group name to this method to "reopen" that group. You must provide
+    # a block. In that block, you may not modify any properties of the group
+    # itself, but you may add or replace subtools within the group.
+    #
+    # @param [String] word The name of the group.
+    #
+    def append(word, &block)
+      word = word.to_s
+      subtool = @loader.get_or_create_tool(@tool.full_name + [word], nil, assume_parent: true)
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      ConfigDSL.evaluate(@path, subtool, next_remaining, @priority, @loader, :append, block)
+      self
+    end
+
+    ##
+    # Create a group subtool. You must provide a block defining the group's
+    # properties and contents.
+    #
+    # If the subtool is already defined (either as a tool or a group), the old
+    # definition is discarded and replaced with the new definition.
+    #
+    # @param [String] word The name of the group
+    #
+    def group(word, &block)
+      word = word.to_s
+      subtool = @loader.get_or_create_tool(@tool.full_name + [word], @priority, assume_parent: true)
+      return self if subtool.nil?
+      next_remaining = Loader.next_remaining_words(@remaining_words, word)
+      ConfigDSL.evaluate(@path, subtool, next_remaining, @priority, @loader, :group, block)
+      self
+    end
+
+    ##
+    # Create an alias of the current tool.
+    #
+    # @param [String] word The name of the alias
+    #
+    def alias_as(word)
+      if @tool.root?
+        raise ToolDefinitionError, "Cannot make an alias of the root tool"
+      end
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot make an alias of a group"
+      end
+      alias_name = @tool.full_name.slice(0..-2) + [word.to_s]
+      alias_tool = @loader.get_or_create_tool(alias_name, @priority)
+      alias_tool.make_alias_of(@tool.simple_name) if alias_tool
+      self
+    end
+
+    ##
+    # Make the current tool an alias of the given sibling
+    #
+    # @param [String] word The name of the sibling tool to alias
+    #
+    def alias_of(word)
+      if @tool.root?
+        raise ToolDefinitionError, "Cannot make the root tool an alias"
+      end
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot make a group an alias"
+      end
+      @tool.make_alias_of(word.to_s)
+      self
+    end
+
+    ##
+    # Include another config file or directory at the current location.
+    #
+    # @param [String] path The file or directory to include.
+    #
+    def include(path)
+      @tool.yield_definition do
+        @loader.include_path(path, @tool.full_name, @remaining_words, @priority)
+      end
+      self
+    end
+
+    ##
+    # Expand the given template in the current location.
+    #
+    # The template may be specified as a class or a well-known template name.
+    # You may also provide arguments to pass to the template.
+    #
+    # @param [Class,String,Symbol] template_class The template, either as a
+    #     class or a well-known name.
+    # @param [Object...] args Template arguments
+    #
+    def expand(template_class, *args)
+      unless template_class.is_a?(::Class)
+        name = template_class.to_s
+        template_class = Templates.lookup(name)
+        if template_class.nil?
+          raise ToolDefinitionError, "Template not found: #{name.inspect}"
+        end
+      end
+      template = template_class.new(*args)
+      yield template if block_given?
+      instance_exec(template, &template_class.expander)
+      self
+    end
+
+    ##
+    # Set the long description for the current tool. The long description is
+    # displayed in the usage documentation for the tool itself.
+    #
+    # @param [String] desc The long description string.
+    #
+    def long_desc(desc)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot set the description when appending"
+      end
+      @tool.long_desc = desc
+      self
+    end
+
+    ##
+    # Set the short description for the current tool. The short description is
+    # displayed with the tool in a command list. You may also use the
+    # equivalent method `short_desc`.
+    #
+    # @param [String] desc The short description string.
+    #
+    def desc(desc)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot set the description when appending"
+      end
+      @tool.desc = desc
+      self
+    end
+    alias short_desc desc
+
+    ##
+    # 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.
+    #
+    # @param [Symbol] key The key to use to retrieve the value from the
+    #     execution context.
+    # @param [String...] switches The switches 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
+    #     line. Defaults to `nil`.
+    # @param [String,nil] doc The documentation for the switch, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    # @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.
+    #     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 }`.
+    #
+    def switch(key, *switches,
+               accept: nil, default: nil, doc: nil, only_unique: false, handler: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add a switch when appending"
+      end
+      @tool.add_switch(key, *switches,
+                       accept: accept, default: default, doc: doc,
+                       only_unique: only_unique, handler: handler)
+      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
+    # context.
+    #
+    # @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,nil] doc The documentation for the switch, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    #
+    def required_arg(key, accept: nil, doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
+      @tool.add_required_arg(key, accept: accept, doc: doc)
+      self
+    end
+
+    ##
+    # 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
+    # context. If an optional argument is not given on the command line, the
+    # value is set to the given default.
+    #
+    # @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 [String,nil] doc The documentation for the argument, which appears
+    #     in the usage documentation. Defaults to `nil` for no documentation.
+    #
+    def optional_arg(key, accept: nil, default: nil, doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
+      @tool.add_optional_arg(key, accept: accept, default: default, doc: doc)
+      self
+    end
+
+    ##
+    # 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.
+    #
+    # @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 [String,nil] doc The documentation for the remaining arguments,
+    #     which appears in the usage documentation. Defaults to `nil` for no
+    #     documentation.
+    #
+    def remaining_args(key, accept: nil, default: [], doc: nil)
+      if @type == :append
+        raise ToolDefinitionError, "Cannot add an argument when appending"
+      end
+      @tool.set_remaining_args(key, accept: accept, default: default, doc: doc)
+      self
+    end
+
+    ##
+    # Specify the executor for this tool. This is a block that will be called,
+    # with `self` set to a {Toys::Context}.
+    #
+    def execute(&block)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot set the executor of a group"
+      end
+      @tool.executor = block
+      self
+    end
+
+    ##
+    # Define a helper method that may be called from this tool's executor.
+    # You must provide a name for the method, and a block for the method
+    # definition.
+    #
+    # @param [String,Symbol] name Name of the method. May not begin with an
+    #     underscore.
+    #
+    def helper(name, &block)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot define a helper method to a group"
+      end
+      @tool.add_helper(name, &block)
+      self
+    end
+
+    ##
+    # Specify that the given module should be mixed in to this tool's executor.
+    # 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.
+    #
+    # @param [Module,Symbol] mod Module or name of well-known module.
+    #
+    def use(mod)
+      if @type == :group || @type == :append
+        raise ToolDefinitionError, "Cannot use a helper module in a group"
+      end
+      @tool.use_module(mod)
+      self
+    end
+
+    ## @private
+    def _binding
+      binding
+    end
+
+    ## @private
+    def self.evaluate(path, tool, remaining_words, priority, loader, type, source)
+      dsl = new(path, tool, remaining_words, priority, loader, type)
+      if type == :append
+        eval_source(dsl, path, source)
+      else
+        tool.defining_from(path) do
+          eval_source(dsl, path, source)
+          tool.finish_definition
+        end
+      end
+      tool
+    end
+
+    ## @private
+    def self.eval_source(dsl, path, source)
+      case source
+      when String
+        # rubocop:disable Security/Eval
+        eval(source, dsl._binding, path, 1)
+        # rubocop:enable Security/Eval
+      when ::Proc
+        dsl.instance_eval(&source)
+      end
+    end
+  end
+end