toys-core 0.7.0 → 0.8.0

data/lib/toys/standard_mixins/highline.rb

@@ -1,37 +1,26 @@
 # 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::Utils::Gems.activate("highline", "~> 2.0")
-require "highline"
-
 module Toys
   module StandardMixins
     ##
@@ -68,13 +57,17 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      to_initialize do |*args|
+      on_initialize do |*args|
+        require "toys/utils/gems"
+        Toys::Utils::Gems.activate("highline", "~> 2.0")
+        require "highline"
         self[KEY] = ::HighLine.new(*args)
         self[KEY].use_color = $stdout.tty?
       end
 
       ##
-      # Returns a tool-wide highline instance
+      # A tool-wide [HighLine](https://www.rubydoc.info/gems/highline/HighLine)
+      # instance
       # @return [::HighLine]
       #
       def highline
@@ -82,84 +75,84 @@ module Toys
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:agree HighLine#agree
+      # Calls [HighLine#agree](https://www.rubydoc.info/gems/highline/HighLine:agree)
       #
       def agree(*args, &block)
         highline.agree(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:ask HighLine#ask
+      # Calls [HighLine#ask](https://www.rubydoc.info/gems/highline/HighLine:ask)
       #
       def ask(*args, &block)
         highline.ask(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:choose HighLine#choose
+      # Calls [HighLine#choose](https://www.rubydoc.info/gems/highline/HighLine:choose)
       #
       def choose(*args, &block)
         highline.choose(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:list HighLine#list
+      # Calls [HighLine#list](https://www.rubydoc.info/gems/highline/HighLine:list)
       #
       def list(*args, &block)
         highline.list(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:say HighLine#say
+      # Calls [HighLine#say](https://www.rubydoc.info/gems/highline/HighLine:say)
       #
       def say(*args, &block)
         highline.say(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:indent HighLine#indent
+      # Calls [HighLine#indent](https://www.rubydoc.info/gems/highline/HighLine:indent)
       #
       def indent(*args, &block)
         highline.indent(*args, &block)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:newline HighLine#newline
+      # Calls [HighLine#newline](https://www.rubydoc.info/gems/highline/HighLine:newline)
       #
       def newline
         highline.newline
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:puts HighLine#puts
+      # Calls [HighLine#puts](https://www.rubydoc.info/gems/highline/HighLine:puts)
       #
       def puts(*args)
         highline.puts(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:color HighLine#color
+      # Calls [HighLine#color](https://www.rubydoc.info/gems/highline/HighLine:color)
       #
       def color(*args)
         highline.color(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:color_code HighLine#color_code
+      # Calls [HighLine#color_code](https://www.rubydoc.info/gems/highline/HighLine:color_code)
       #
       def color_code(*args)
         highline.color_code(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:uncolor HighLine#uncolor
+      # Calls [HighLine#uncolor](https://www.rubydoc.info/gems/highline/HighLine:uncolor)
       #
       def uncolor(*args)
         highline.uncolor(*args)
       end
 
       ##
-      # @see https://www.rubydoc.info/gems/highline/HighLine:new_scope HighLine#new_scope
+      # Calls [HighLine#new_scope](https://www.rubydoc.info/gems/highline/HighLine:new_scope)
       #
       def new_scope
         highline.new_scope

data/lib/toys/standard_mixins/terminal.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
@@ -64,12 +56,13 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      to_initialize do |opts = {}|
+      on_initialize do |opts = {}|
+        require "toys/utils/terminal"
         self[KEY] = Utils::Terminal.new(opts)
       end
 
       ##
-      # Returns a tool-wide terminal instance
+      # A tool-wide terminal instance
       # @return [Toys::Utils::Terminal]
       #
       def terminal
@@ -77,37 +70,90 @@ module Toys
       end
 
       ##
+      # Write a line, appending a newline if one is not already present.
+      #
       # @see Toys::Utils::Terminal#puts
       #
+      # @param str [String] The line to write
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     entire line.
+      # @return [self]
+      #
       def puts(str = "", *styles)
         terminal.puts(str, *styles)
+        self
       end
       alias say puts
 
       ##
+      # Write a partial line without appending a newline.
+      #
       # @see Toys::Utils::Terminal#write
       #
+      # @param str [String] The line to write
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     partial line.
+      # @return [self]
+      #
       def write(str = "", *styles)
         terminal.write(str, *styles)
+        self
       end
 
       ##
+      # Ask a question and get a response.
+      #
       # @see Toys::Utils::Terminal#ask
       #
+      # @param prompt [String] Required prompt string.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     prompt.
+      # @param default [String,nil] Default value, or `nil` for no default.
+      #     Uses `nil` if not specified.
+      # @param trailing_text [:default,String,nil] Trailing text appended to
+      #     the prompt, `nil` for none, or `:default` to show the default.
+      # @return [String]
+      #
       def ask(prompt, *styles, default: nil, trailing_text: :default)
         terminal.ask(prompt, *styles, default: default, trailing_text: trailing_text)
       end
 
       ##
+      # Confirm with the user.
+      #
       # @see Toys::Utils::Terminal#confirm
       #
+      # @param prompt [String] Prompt string. Defaults to `"Proceed?"`.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
+      #     prompt.
+      # @param default [Boolean,nil] Default value, or `nil` for no default.
+      #     Uses `nil` if not specified.
+      # @return [Boolean]
+      #
       def confirm(prompt = "Proceed?", *styles, default: nil)
         terminal.confirm(prompt, *styles, default: default)
       end
 
       ##
+      # Display a spinner during a task. You should provide a block that
+      # performs the long-running task. While the block is executing, a
+      # spinner will be displayed.
+      #
       # @see Toys::Utils::Terminal#spinner
       #
+      # @param leading_text [String] Optional leading string to display to the
+      #     left of the spinner. Default is the empty string.
+      # @param frame_length [Float] Length of a single frame, in seconds.
+      #     Defaults to {Toys::Utils::Terminal::DEFAULT_SPINNER_FRAME_LENGTH}.
+      # @param frames [Array<String>] An array of frames. Defaults to
+      #     {Toys::Utils::Terminal::DEFAULT_SPINNER_FRAMES}.
+      # @param style [Symbol,Array<Symbol>] A terminal style or array of styles
+      #     to apply to all frames in the spinner. Defaults to empty,
+      # @param final_text [String] Optional final string to display when the
+      #     spinner is complete. Default is the empty string. A common practice
+      #     is to set this to newline.
+      # @return [Object] The return value of the block.
+      #
       def spinner(leading_text: "", final_text: "",
                   frame_length: nil, frames: nil, style: nil, &block)
         terminal.spinner(leading_text: leading_text, final_text: final_text,

data/lib/toys/template.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
@@ -48,8 +40,8 @@ module Toys
   # {Toys::DSL::Tool#expand} method are passed to your constructor, and your
   # template object is passed to any block given to {Toys::DSL::Tool#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
+  # Next, in your template class, call the `on_expand` method, which is defined
+  # in {Toys::Template::ClassMethods#on_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.
@@ -76,7 +68,7 @@ module Toys
   #       attr_accessor :name
   #
   #       # The following block is inserted when the template is expanded.
-  #       to_expand do |template|
+  #       on_expand do |template|
   #         desc "Prints a greeting to #{template.name}"
   #         tool "templated-greeting" do
   #           to_run do
@@ -99,11 +91,25 @@ module Toys
   # And it will create a tool called "templated-greeting".
   #
   module Template
+    ##
+    # Create a template class with the given block.
+    #
+    # @param block [Proc] Defines the template class.
+    # @return [Class]
+    #
+    def self.create(&block)
+      template_class = ::Class.new do
+        include ::Toys::Template
+      end
+      template_class.class_eval(&block) if block
+      template_class
+    end
+
     ## @private
     def self.included(mod)
-      return if mod.respond_to?(:to_expand)
+      return if mod.respond_to?(:on_expand)
       mod.extend(ClassMethods)
-      mod.include(Tool::Keys)
+      mod.include(Context::Key)
     end
 
     ##
@@ -111,17 +117,27 @@ module Toys
     #
     module ClassMethods
       ##
-      # Provide the block that implements the template.
+      # Define how to expand this template. The given block is passed the
+      # template object, and is evaluated in the tool class. It should invoke
+      # directives to create tools and other objects.
       #
-      def to_expand(&block)
-        self.expander = block
+      # @param block [Proc] The expansion of this template.
+      # @return [self]
+      #
+      def on_expand(&block)
+        self.expansion = block
+        self
       end
+      alias to_expand on_expand
 
       ##
-      # You may alternately set the expander block using this accessor.
-      # @return [Proc]
+      # The template expansion proc. This proc is passed the template object,
+      # and is evaluted in the tool class. It should invoke directives to
+      # create tools and other objects.
+      #
+      # @return [Proc] The expansion of this template.
       #
-      attr_accessor :expander
+      attr_accessor :expansion
     end
   end
 end