toys 0.3.1 → 0.3.2

data/lib/toys/middleware.rb

@@ -1,55 +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 "toys/utils/module_lookup"
-
-module Toys
-  ##
-  # Namespace for common middleware
-  #
-  module Middleware
-    ##
-    # Return a middleware class by name.
-    #
-    # Currently recognized middleware names are:
-    #
-    # *  `:group_default` : Provides a default implementation for a group.
-    # *  `:set_verbosity` : Switches for affecting log verbosity.
-    # *  `:show_tool_help` : A switch that causes a tool to print its usage
-    #    documentation.
-    # *  `:show_usage_errors` : Displays the usage error if one occurs.
-    #
-    # @param [String,Symbol] name Name of the middleware class to return
-    # @return [Class,nil] The class, or `nil` if not found
-    #
-    def self.lookup(name)
-      Utils::ModuleLookup.lookup(:middleware, name)
-    end
-  end
-end

data/lib/toys/middleware/base.rb

@@ -1,51 +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.
-;
-
-module Toys
-  module Middleware
-    ##
-    # A base middleware with a no-op implementation.
-    #
-    class Base
-      ##
-      # The base middleware does not affect tool configuration.
-      #
-      def config(_tool)
-        yield
-      end
-
-      ##
-      # The base middleware does not affect tool execution.
-      #
-      def execute(_context)
-        yield
-      end
-    end
-  end
-end

data/lib/toys/middleware/set_verbosity.rb

@@ -1,54 +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 "toys/middleware/base"
-
-module Toys
-  module Middleware
-    ##
-    # A middleware that provides switches for editing the verbosity
-    #
-    class SetVerbosity < Base
-      ##
-      # This middleware adds `--verbose` and `--quiet` flags.
-      #
-      def config(tool)
-        tool.add_switch(Context::VERBOSITY, "-v", "--verbose",
-                        doc: "Increase verbosity",
-                        handler: ->(_val, cur) { cur + 1 },
-                        only_unique: true)
-        tool.add_switch(Context::VERBOSITY, "-q", "--quiet",
-                        doc: "Decrease verbosity",
-                        handler: ->(_val, cur) { cur - 1 },
-                        only_unique: true)
-        yield
-      end
-    end
-  end
-end

data/lib/toys/middleware/show_group_usage.rb

@@ -1,68 +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 "toys/middleware/base"
-require "toys/utils/usage"
-
-module Toys
-  module Middleware
-    ##
-    # A middleware that provides a default implementation for groups. If a
-    # tool has no executor, this middleware assumes it to be a group, and it
-    # provides a default executor that displays group usage documentation.
-    #
-    class ShowGroupUsage < Base
-      ##
-      # This middleware adds a "--no-recursive" flag to groups. This flag, when
-      # set, shows only immediate subcommands rather than all recursively.
-      #
-      def config(tool)
-        if tool.includes_executor?
-          yield
-        else
-          tool.add_switch(:_no_recursive, "--no-recursive",
-                          doc: "Show immediate rather than all subcommands",
-                          only_unique: true)
-        end
-      end
-
-      ##
-      # This middleware displays the usage documentation for groups. It has
-      # no effect on tools that have their own executor.
-      #
-      def execute(context)
-        if context[Context::TOOL].includes_executor?
-          yield
-        else
-          puts(Utils::Usage.from_context(context).string(recursive: !context[:_no_recursive]))
-        end
-      end
-    end
-  end
-end

data/lib/toys/middleware/show_tool_usage.rb

@@ -1,64 +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 "toys/middleware/base"
-require "toys/utils/usage"
-
-module Toys
-  module Middleware
-    ##
-    # A middleware that shows usage documentation
-    #
-    class ShowToolUsage < Base
-      ##
-      # This middleware adds a `--help` flag that triggers display of help.
-      #
-      def config(tool)
-        if tool.includes_executor?
-          tool.add_switch(:_help, "-?", "--help",
-                          doc: "Show help message",
-                          only_unique: true)
-        end
-        yield
-      end
-
-      ##
-      # If the `--help` flag is present, this middleware causes the tool to
-      # display its usage documentation and exit, rather than executing.
-      #
-      def execute(context)
-        if context[:_help]
-          puts(Utils::Usage.from_context(context).string(recursive: context[:_recursive]))
-        else
-          yield
-        end
-      end
-    end
-  end
-end

data/lib/toys/middleware/show_usage_errors.rb

@@ -1,57 +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 "toys/middleware/base"
-require "toys/utils/usage"
-
-module Toys
-  module Middleware
-    ##
-    # A middleware that shows usage errors
-    #
-    class ShowUsageErrors < Base
-      ##
-      # If a usage error happens, e.g. an unrecognized switch or an unfulfilled
-      # required argument, this middleware causes the tool to display the error
-      # and usage documentation and exit with a nonzero result. Otherwise, it
-      # does nothing.
-      #
-      def execute(context)
-        if context[Context::USAGE_ERROR]
-          puts(context[Context::USAGE_ERROR])
-          puts("")
-          puts(Utils::Usage.from_context(context).string)
-          context.exit(-1)
-        else
-          yield
-        end
-      end
-    end
-  end
-end

data/lib/toys/template.rb

@@ -1,123 +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.
-;
-
-module Toys
-  ##
-  # A template definition. Template classes should include this module.
-  #
-  # A template is a configurable set of DSL code that can be run in a toys
-  # configuration to automate tool defintion. For example, toys provides a
-  # "minitest" template that generates a "test" tool that invokes minitest.
-  # Templates will often support configuration; for example the minitest
-  # template lets you configure the paths to the test files.
-  #
-  # ## Usage
-  #
-  # To create a template, define a class and include this module.
-  # The class defines the "configuration" of the template. If your template
-  # has options/parameters, you should provide a constructor, and methods
-  # appropriate to edit those options. The arguments given to the
-  # {Toys::ConfigDSL#expand} method are passed to your constructor, and your
-  # template object is passed to any block given to {Toys::ConfigDSL#expand}.
-  #
-  # Next, in your template class, call the `to_expand` method, which is defined
-  # in {Toys::Template::ClassMethods#to_expand}. Pass this a block which
-  # defines the implementation of the template. Effectively, the contents of
-  # this block are "inserted" into the user's configuration. The template
-  # object is passed to the block so you have access to the template options.
-  #
-  # ## Example
-  #
-  # This is a simple template that generates a "hello" tool. The tool simply
-  # prints a `"Hello, #{name}!"` greeting. The name is set as a template
-  # option; it is defined when the template is expanded in a toys
-  # configuration.
-  #
-  #     # Define a template by creating a class that includes Toys::Template.
-  #     class MyHelloTemplate
-  #       include Toys::Template
-  #
-  #       # A user of the template may pass an optional name as a parameter to
-  #       # `expand`, or leave it as the default of "world".
-  #       def initialize(name: "world")
-  #         @name = name
-  #       end
-  #
-  #       # The template is passed to the expand block, so a user of the
-  #       # template may also call this method to set the name.
-  #       attr_accessor :name
-  #
-  #       # The following block is inserted when the template is expanded.
-  #       to_expand do |template|
-  #         desc "Prints a greeting to #{template.name}"
-  #         tool "templated-greeting" do
-  #           execute do
-  #             puts "Hello, #{template.name}!"
-  #           end
-  #         end
-  #       end
-  #     end
-  #
-  # Now you can use the template in your `.toys.rb` file like this:
-  #
-  #     expand(MyHelloTemplate, name: "rubyists")
-  #
-  # or alternately:
-  #
-  #     expand(MyHelloTemplate) do |template|
-  #       template.name = "rubyists"
-  #     end
-  #
-  # And it will create a tool called "templated-greeting".
-  #
-  module Template
-    ## @private
-    def self.included(mod)
-      mod.extend(ClassMethods)
-    end
-
-    ##
-    # Class methods that will be added to a template class.
-    #
-    module ClassMethods
-      ##
-      # Provide the block that implements the template.
-      #
-      def to_expand(&block)
-        @expander = block
-      end
-
-      ##
-      # You may alternately set the expander block using this accessor.
-      # @return [Proc]
-      #
-      attr_accessor :expander
-    end
-  end
-end