toys 0.12.2 → 0.13.0

data/core-docs/toys/standard_mixins/gems.rb

@@ -0,0 +1,48 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # Provides methods for installing and activating third-party gems. When
+    # this mixin is included, it provides a `gem` method that has the same
+    # effect as {Toys::Utils::Gems#activate}, so you can ensure a gem is
+    # present when running a tool. A `gem` directive is likewise added to the
+    # tool DSL itself, so you can also ensure a gem is present when defining a
+    # tool.
+    #
+    # You may make these methods available to your tool by including the
+    # following directive in your tool configuration:
+    #
+    #     include :gems
+    #
+    # If you pass additional options to the include directive, those are used
+    # to initialize settings for the gem install process. For example:
+    #
+    #     include :gems, on_missing: :error
+    #
+    # See {Toys::Utils::Gems#initialize} for a list of supported options.
+    #
+    module Gems
+      include Mixin
+
+      ##
+      # A tool-wide instance of {Toys::Utils::Gems}.
+      # @return [Toys::Utils::Gems]
+      #
+      def gems
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Activate the given gem.
+      #
+      # @param name [String] Name of the gem
+      # @param requirements [String...] Version requirements
+      # @return [void]
+      #
+      def gem(name, *requirements)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys/standard_mixins/git_cache.rb

@@ -0,0 +1,41 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A mixin that provides a git cache.
+    #
+    # This mixin provides an instance of {Toys::Utils::GitCache}, providing
+    # cached access to files from a remote git repo.
+    #
+    # Example usage:
+    #
+    #     include :git_cache
+    #
+    #     def run
+    #       # Pull and cache the HEAD commit from the Toys repo.
+    #       dir = git_cache.find("https://github.com/dazuma/toys.git")
+    #       # Display the contents of the readme file.
+    #       puts File.read(File.join(dir, "README.md"))
+    #     end
+    #
+    module GitCache
+      include Mixin
+
+      ##
+      # Context key for the GitCache object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      ##
+      # Access the builtin GitCache.
+      #
+      # @return [Toys::Utils::GitCache]
+      #
+      def git_cache
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys/standard_mixins/highline.rb

@@ -0,0 +1,133 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A mixin that provides access to the capabilities of the highline gem.
+    #
+    # This mixin requires the highline gem, version 2.0 or later. It will
+    # attempt to install the gem if it is not available.
+    #
+    # You may make these methods available to your tool by including the
+    # following directive in your tool configuration:
+    #
+    #     include :highline
+    #
+    # A HighLine object will then be available by calling the {#highline}
+    # method. For information on using this object, see the
+    # [Highline documentation](https://www.rubydoc.info/gems/highline). Some of
+    # the most common HighLine methods, such as `say`, are also mixed into the
+    # tool and can be called directly.
+    #
+    # You can configure the HighLine object by passing options to the `include`
+    # directive. For example:
+    #
+    #     include :highline, my_stdin, my_stdout
+    #
+    # The arguments will be passed on to the
+    # [HighLine constructor](https://www.rubydoc.info/gems/highline/HighLine:initialize).
+    #
+    module Highline
+      include Mixin
+
+      ##
+      # Context key for the highline object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      ##
+      # A tool-wide [HighLine](https://www.rubydoc.info/gems/highline/HighLine)
+      # instance
+      # @return [::HighLine]
+      #
+      def highline
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#agree](https://www.rubydoc.info/gems/highline/HighLine:agree)
+      #
+      def agree(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#ask](https://www.rubydoc.info/gems/highline/HighLine:ask)
+      #
+      def ask(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#choose](https://www.rubydoc.info/gems/highline/HighLine:choose)
+      #
+      def choose(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#list](https://www.rubydoc.info/gems/highline/HighLine:list)
+      #
+      def list(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#say](https://www.rubydoc.info/gems/highline/HighLine:say)
+      #
+      def say(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#indent](https://www.rubydoc.info/gems/highline/HighLine:indent)
+      #
+      def indent(*args, &block)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#newline](https://www.rubydoc.info/gems/highline/HighLine:newline)
+      #
+      def newline
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#puts](https://www.rubydoc.info/gems/highline/HighLine:puts)
+      #
+      def puts(*args)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#color](https://www.rubydoc.info/gems/highline/HighLine:color)
+      #
+      def color(*args)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#color_code](https://www.rubydoc.info/gems/highline/HighLine:color_code)
+      #
+      def color_code(*args)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#uncolor](https://www.rubydoc.info/gems/highline/HighLine:uncolor)
+      #
+      def uncolor(*args)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Calls [HighLine#new_scope](https://www.rubydoc.info/gems/highline/HighLine:new_scope)
+      #
+      def new_scope
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys/standard_mixins/terminal.rb

@@ -0,0 +1,135 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A mixin that provides a simple terminal. It includes a set of methods
+    # that produce styled output, get user input, and otherwise interact with
+    # the user's terminal. This mixin is not as richly featured as other mixins
+    # such as Highline, but it has no gem dependencies so is ideal for basic
+    # cases.
+    #
+    # You may make these methods available to your tool by including the
+    # following directive in your tool configuration:
+    #
+    #     include :terminal
+    #
+    # A Terminal object will then be available by calling the {#terminal}
+    # method. For information on using this object, see the documentation for
+    # {Toys::Utils::Terminal}. Some of the most useful methods are also mixed
+    # into the tool and can be called directly.
+    #
+    # You can configure the Terminal object by passing options to the `include`
+    # directive. For example:
+    #
+    #     include :terminal, styled: true
+    #
+    # The arguments will be passed on to {Toys::Utils::Terminal#initialize}.
+    #
+    module Terminal
+      include Mixin
+
+      ##
+      # Context key for the terminal object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      ##
+      # A tool-wide terminal instance
+      # @return [Toys::Utils::Terminal]
+      #
+      def terminal
+        # Source available in the toys-core gem
+      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)
+        # Source available in the toys-core gem
+      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)
+        # Source available in the toys-core gem
+      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)
+        # Source available in the toys-core gem
+      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)
+        # Source available in the toys-core gem
+      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)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys/standard_mixins/xdg.rb

@@ -0,0 +1,49 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A mixin that provides tools for working with the XDG Base Directory
+    # Specification.
+    #
+    # This mixin provides an instance of {Toys::Utils::XDG}, which includes
+    # utility methods that locate base directories and search paths for
+    # application state, configuration, caches, and other data, according to
+    # the [XDG Base Directory Spec version
+    # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
+    #
+    # Example usage:
+    #
+    #     include :xdg
+    #
+    #     def run
+    #       # Get config file paths, in order from most to least inportant
+    #       config_files = xdg.lookup_config("my-config.toml")
+    #       config_files.each { |path| read_my_config(path) }
+    #     end
+    #
+    module XDG
+      include Mixin
+
+      ##
+      # Context key for the XDG object.
+      # @return [Object]
+      #
+      KEY = ::Object.new.freeze
+
+      ##
+      # Access XDG utility methods.
+      #
+      # @return [Toys::Utils::XDG]
+      #
+      def xdg
+        # Source available in the toys-core gem
+      end
+    end
+
+    ##
+    # An alternate name for the {XDG} module
+    #
+    Xdg = XDG
+  end
+end

data/core-docs/toys/template.rb

@@ -0,0 +1,112 @@
+module Toys
+  ##
+  # **_Defined in the toys-core gem_**
+  #
+  # 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::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 `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.
+  #
+  # ### 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.
+  #       on_expand do |template|
+  #         desc "Prints a greeting to #{template.name}"
+  #         tool "templated-greeting" do
+  #           to_run 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
+    ##
+    # Create a template class with the given block.
+    #
+    # @param block [Proc] Defines the template class.
+    # @return [Class]
+    #
+    def self.create(&block)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # Class methods that will be added to a template class.
+    #
+    module ClassMethods
+      ##
+      # 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.
+      #
+      # @param block [Proc] The expansion of this template.
+      # @return [self]
+      #
+      def on_expand(&block)
+        # Source available in the toys-core gem
+      end
+      alias to_expand on_expand
+
+      ##
+      # 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 :expansion
+    end
+  end
+end