toys 0.9.4 → 0.10.0

data/lib/toys/templates/rake.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# 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:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# 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
   module Templates
     ##
@@ -47,24 +26,114 @@ module Toys
       # @param use_flags [Boolean] Generated tools use flags instead of
       #     positional arguments to pass arguments to rake tasks. Default is
       #     false.
+      # @param bundler [Boolean,Hash] If `false` (the default), bundler is not
+      #     enabled for Rake tools. If `true` or a Hash of options, bundler is
+      #     enabled. See the documentation for the
+      #     [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      #     for information on available options.
       #
       def initialize(gem_version: nil,
                      rakefile_path: nil,
                      only_described: false,
-                     use_flags: false)
+                     use_flags: false,
+                     bundler: false)
         @gem_version = gem_version
-        @rakefile_path = rakefile_path || DEFAULT_RAKEFILE_PATH
+        @rakefile_path = rakefile_path
         @only_described = only_described
         @use_flags = use_flags
+        @bundler = bundler
       end
 
-      attr_accessor :gem_version
-      attr_accessor :rakefile_path
-      attr_accessor :only_described
-      attr_accessor :use_flags
+      ##
+      # Version requirements for the minitest gem.
+      # If set to `nil`, has no version requirement (unless one is specified in
+      # the bundle.)
+      #
+      # @param value [String,Array<String>,nil]
+      # @return [String,Array<String>,nil]
+      #
+      attr_writer :gem_version
+
+      ##
+      # Path to the Rakefile.
+      # If set to `nil`, defaults to {DEFAULT_RAKEFILE_PATH}.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :rakefile_path
+
+      ##
+      # Whether to generate tools only for rake tasks with descriptions.
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      #
+      attr_writer :only_described
+
+      ##
+      # Whether generated tools should use flags instead of positional
+      # arguments to pass arguments to rake tasks.
+      #
+      # @param value [Boolean]
+      # @return [Boolean]
+      #
+      attr_writer :use_flags
+
+      ##
+      # Set the bundler state and options for all Rake tools.
+      #
+      # Pass `false` to disable bundler. Pass `true` or a hash of options to
+      # enable bundler. See the documentation for the
+      # [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      # for information on the options that can be passed.
+      #
+      # @param value [Boolean,Hash]
+      # @return [Boolean,Hash]
+      #
+      attr_writer :bundler
+
+      ##
+      # Use bundler for all Rake tools.
+      #
+      # See the documentation for the
+      # [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      # for information on the options that can be passed.
+      #
+      # @param opts [keywords] Options for bundler
+      # @return [self]
+      #
+      def use_bundler(**opts)
+        @bundler = opts
+        self
+      end
+
+      # @private
+      attr_reader :only_described
+      # @private
+      attr_reader :use_flags
+
+      # @private
+      def gem_version
+        Array(@gem_version)
+      end
+
+      # @private
+      def rakefile_path
+        @rakefile_path || DEFAULT_RAKEFILE_PATH
+      end
+
+      # @private
+      def bundler_settings
+        if @bundler && !@bundler.is_a?(::Hash)
+          {}
+        else
+          @bundler
+        end
+      end
 
       on_expand do |template|
-        gem "rake", *Array(template.gem_version)
+        gem "rake", *template.gem_version
         require "rake"
         rakefile_path = Templates::Rake.find_rakefile(template.rakefile_path, context_directory)
         raise "Cannot find #{template.rakefile_path}" unless rakefile_path
@@ -74,6 +143,8 @@ module Toys
           comments = task.full_comment.to_s.split("\n")
           next if comments.empty? && template.only_described
           tool(task.name.split(":"), if_defined: :ignore) do
+            bundler_settings = template.bundler_settings
+            include :bundler, **bundler_settings if bundler_settings
             unless comments.empty?
               desc(comments.first)
               comments << "" << "Defined as a Rake task in #{rakefile_path}"

data/lib/toys/templates/rdoc.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# 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:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# 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
   module Templates
     ##
@@ -33,7 +12,7 @@ module Toys
       # Default version requirements for the rdoc gem.
       # @return [Array<String>]
       #
-      DEFAULT_GEM_VERSION_REQUIREMENTS = ">= 5.0.0"
+      DEFAULT_GEM_VERSION_REQUIREMENTS = ["~> 6.1.0"].freeze
 
       ##
       # Default tool name
@@ -47,6 +26,12 @@ module Toys
       #
       DEFAULT_OUTPUT_DIR = "html"
 
+      ##
+      # Default file globs
+      # @return [Array<String>]
+      #
+      DEFAULT_FILES = ["lib/**/*.rb"].freeze
+
       ##
       # Create the template settings for the Rdoc template.
       #
@@ -55,53 +40,210 @@ module Toys
       # @param gem_version [String,Array<String>] Version requirements for
       #     the rdoc gem. Defaults to {DEFAULT_GEM_VERSION_REQUIREMENTS}.
       # @param files [Array<String>] An array of globs indicating the files
-      #     to document.
+      #     to document. Defaults to {DEFAULT_FILES}.
       # @param output_dir [String] Name of directory to receive html output
       #     files. Defaults to {DEFAULT_OUTPUT_DIR}.
-      # @param markup [String,nil] Markup format. Allowed values include
-      #     "rdoc", "rd", and "tomdoc". Default is "rdoc".
-      # @param title [String,nil] Title of RDoc documentation. If `nil`, RDoc
-      #     will use a default title.
-      # @param main [String,nil] Name of the file to use as the main top level
+      # @param markup [String] Markup format. Allowed values include "rdoc",
+      #     "rd", and "tomdoc". If not specified, RDoc will use its default
+      #     markup, which is "rdoc".
+      # @param title [String] Title of RDoc documentation. If not specified,
+      #     RDoc will use a default title.
+      # @param main [String] Name of the file to use as the main top level
       #     document. Default is none.
-      # @param template [String,nil] Name of the template to use. If `nil`,
+      # @param template [String] Name of the template to use. If not specified,
       #     RDoc will use its default template.
-      # @param generator [String,nil] Name of the format generator. If `nil`,
-      #     RDoc will use its default generator.
+      # @param generator [String] Name of the format generator. If not
+      #     specified, RDoc will use its default generator.
       # @param options [Array<String>] Additional options to pass to RDoc.
+      # @param bundler [Boolean,Hash] If `false` (the default), bundler is not
+      #     enabled for this tool. If `true` or a Hash of options, bundler is
+      #     enabled. See the documentation for the
+      #     [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      #     for information on available options.
       #
       def initialize(name: nil,
                      gem_version: nil,
-                     files: [],
+                     files: nil,
                      output_dir: nil,
                      markup: nil,
                      title: nil,
                      main: nil,
                      template: nil,
                      generator: nil,
-                     options: [])
-        @name = name || DEFAULT_TOOL_NAME
-        @gem_version = gem_version || DEFAULT_GEM_VERSION_REQUIREMENTS
+                     options: [],
+                     bundler: false)
+        @name = name
+        @gem_version = gem_version
         @files = files
-        @output_dir = output_dir || DEFAULT_OUTPUT_DIR
+        @output_dir = output_dir
         @markup = markup
         @title = title
         @main = main
         @template = template
         @generator = generator
         @options = options
+        @bundler = bundler
       end
 
-      attr_accessor :name
-      attr_accessor :gem_version
-      attr_accessor :files
-      attr_accessor :output_dir
-      attr_accessor :markup
-      attr_accessor :title
-      attr_accessor :main
-      attr_accessor :template
-      attr_accessor :generator
-      attr_accessor :options
+      ##
+      # Name of the tool to create.
+      #
+      # @param value [String]
+      # @return [String]
+      #
+      attr_writer :name
+
+      ##
+      # Version requirements for the rdoc gem.
+      # If set to `nil`, uses the bundled version if bundler is enabled, or
+      # defaults to {DEFAULT_GEM_VERSION_REQUIREMENTS} if bundler is not
+      # enabled.
+      #
+      # @param value [String,Array<String>,nil]
+      # @return [String,Array<String>,nil]
+      #
+      attr_writer :gem_version
+
+      ##
+      # An array of globs indicating which files to document.
+      #
+      # @param value [Array<String>]
+      # @return [Array<String>]
+      #
+      attr_writer :files
+
+      ##
+      # Name of directory to receive html output files.
+      # If set to `nil`, defaults to {DEFAULT_OUTPUT_DIR}.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :output_dir
+
+      ##
+      # Markup format. Allowed values include "rdoc", "rd", and "tomdoc".
+      # If set to `nil`, RDoc will use its default markup, which is "rdoc".
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :markup
+
+      ##
+      # Title of RDoc documentation pages.
+      # If set to `nil`, RDoc will use a default title.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :title
+
+      ##
+      # Name of the file to use as the main top level document, or `nil` for
+      # no top level document.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :main
+
+      ##
+      # Name of the template to use.
+      # If set to `nil`, RDoc will choose a default template.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :template
+
+      ##
+      # Name of the format generator.
+      # If set to `nil`, RDoc will use its default generator.
+      #
+      # @param value [String,nil]
+      # @return [String,nil]
+      #
+      attr_writer :generator
+
+      ##
+      # Additional options to pass to RDoc
+      #
+      # @param value [Array<String>]
+      # @return [Array<String>]
+      #
+      attr_writer :options
+
+      ##
+      # Set the bundler state and options for this tool.
+      #
+      # Pass `false` to disable bundler. Pass `true` or a hash of options to
+      # enable bundler. See the documentation for the
+      # [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      # for information on the options that can be passed.
+      #
+      # @param value [Boolean,Hash]
+      # @return [Boolean,Hash]
+      #
+      attr_writer :bundler
+
+      ##
+      # Use bundler for this tool.
+      #
+      # See the documentation for the
+      # [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+      # for information on the options that can be passed.
+      #
+      # @param opts [keywords] Options for bundler
+      # @return [self]
+      #
+      def use_bundler(**opts)
+        @bundler = opts
+        self
+      end
+
+      # @private
+      attr_reader :markup
+      # @private
+      attr_reader :title
+      # @private
+      attr_reader :main
+      # @private
+      attr_reader :template
+      # @private
+      attr_reader :generator
+      # @private
+      attr_reader :options
+
+      # @private
+      def name
+        @name || DEFAULT_TOOL_NAME
+      end
+
+      # @private
+      def gem_version
+        return Array(@gem_version) if @gem_version
+        @bundler ? [] : DEFAULT_GEM_VERSION_REQUIREMENTS
+      end
+
+      # @private
+      def files
+        @files ? Array(@files) : DEFAULT_FILES
+      end
+
+      # @private
+      def output_dir
+        @output_dir || DEFAULT_OUTPUT_DIR
+      end
+
+      # @private
+      def bundler_settings
+        if @bundler && !@bundler.is_a?(::Hash)
+          {}
+        else
+          @bundler
+        end
+      end
 
       on_expand do |template|
         tool(template.name) do
@@ -110,15 +252,16 @@ module Toys
           include :exec, exit_on_nonzero_status: true
           include :gems
 
+          bundler_settings = template.bundler_settings
+          include :bundler, **bundler_settings if bundler_settings
+
           to_run do
             gem_requirements = Array(template.gem_version)
             gem "rdoc", *gem_requirements
 
             ::Dir.chdir(context_directory || ::Dir.getwd) do
               files = []
-              patterns = Array(template.files)
-              patterns = ["lib/**/*.rb"] if patterns.empty?
-              patterns.each do |pattern|
+              template.files.each do |pattern|
                 files.concat(::Dir.glob(pattern))
               end
               files.uniq!
@@ -134,7 +277,7 @@ module Toys
               exec_ruby([], in: :controller) do |controller|
                 controller.in.puts("gem 'rdoc', *#{gem_requirements.inspect}")
                 controller.in.puts("require 'rdoc'")
-                controller.in.puts("::RDoc::RDoc.new.document(*#{(args + files).inspect})")
+                controller.in.puts("::RDoc::RDoc.new.document(#{(args + files).inspect})")
               end
             end
           end