toys-core 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87e34f50eb16af11bc970c170e7750509e026b237ec37352be05198860bfdeae
-  data.tar.gz: 6bdaeaa6577d75c25b0efd17406792c24e3f6dd57326a52badd60495dc9170cc
+  metadata.gz: 5ebb136d89b19617cfdaf8de9c870cce070857748abd208ab8faa4896b7e7b36
+  data.tar.gz: eb079b488d1da544e5f31ab0fe0f9730d77d6878549c673bc6ba4711a5d6c295
 SHA512:
-  metadata.gz: ee18128015b86041547bcdab1e7ec4bea05a41e0eff06c30a4003f032cc1ca335c7e7b593236ea140e65f43b4f31a752ceee5c57c787227b88d3144eac22b147
-  data.tar.gz: e4c7b13f825d6b4131db5e08a56a306652e2f532de1095758fde3be3fe509635629cc7725241b4bd3206ce1b414ed0cc4bd09aa480bbe4f335e8b3abd4ffc7c7
+  metadata.gz: 864c7bc16399227e29e013372611ed70df77339185593d3830a31a5092e7dea6540d62ed83704e23ce5d78410ce2b4e34ae5ce9f709d67d8bb82e5075ed09cc3
+  data.tar.gz: 5eb3e60cefb50d7a289ef2283a91574ede820bf1d2bb5769d8038d60d760e999f36e49882899c06f2de6dd37a23d828ee25bd1e2a0764e11cc0e31553764368c

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+### 0.3.3 / 2018-05-09
+
+* CHANGED: Renamed file_utils helper to fileutils.
+* CHANGED: Renamed doc: parameter to docs:
+* CHANGED: SwitchDefinition has separate fields for acceptor and docs.
+* CHANGED: Description and long description are now arrays of strings.
+* FIXED: Documentation strings that begin with "--" no longer cause problems.
+* ADDED: Highline helper
+* ADDED: Spinner helper
+* ADDED: WrappableString for descriptions and docs
+* IMPROVED: Usage can now customize the left column width and indent
+* IMPROVED: Newlines in documentation are properly indented
+
 ### 0.3.2 / 2018-05-07
 
 * CHANGED: Split core engine out into "toys-core" from the "toys" gem.

data/lib/toys/config_dsl.rb

@@ -164,12 +164,12 @@ module Toys
     # 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.
+    # @param [String,Toys::Utils::WrappableString...] strs The long description
     #
-    def long_desc(desc)
+    def long_desc(*strs)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
-      _cur_tool.long_desc = desc
+      _cur_tool.long_desc = strs
       self
     end
 
@@ -178,12 +178,12 @@ module Toys
     # displayed with the tool in a command list. You may also use the
     # equivalent method `short_desc`.
     #
-    # @param [String] desc The short description string.
+    # @param [String,Toys::Utils::WrappableString...] strs The short description
     #
-    def desc(desc)
+    def desc(*strs)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
-      _cur_tool.desc = desc
+      _cur_tool.desc = strs
       self
     end
     alias short_desc desc
@@ -200,8 +200,9 @@ module Toys
     # @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 [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for
+    #     the switch. Defaults to empty array.
     # @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
@@ -214,11 +215,11 @@ module Toys
     #     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)
+               accept: nil, default: nil, docs: nil, only_unique: false, handler: nil)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
       _cur_tool.add_switch(key, *switches,
-                           accept: accept, default: default, doc: doc,
+                           accept: accept, default: default, docs: docs,
                            only_unique: only_unique, handler: handler)
       self
     end
@@ -231,13 +232,14 @@ module Toys
     # @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.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
+    #     arg. Defaults to empty array.
     #
-    def required_arg(key, accept: nil, doc: nil)
+    def required_arg(key, accept: nil, docs: nil)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
-      _cur_tool.add_required_arg(key, accept: accept, doc: doc)
+      _cur_tool.add_required_arg(key, accept: accept, docs: docs)
       self
     end
 
@@ -253,13 +255,14 @@ module Toys
     # @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.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
+    #     arg. Defaults to empty array.
     #
-    def optional_arg(key, accept: nil, default: nil, doc: nil)
+    def optional_arg(key, accept: nil, default: nil, docs: nil)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
-      _cur_tool.add_optional_arg(key, accept: accept, default: default, doc: doc)
+      _cur_tool.add_optional_arg(key, accept: accept, default: default, docs: docs)
       self
     end
 
@@ -274,14 +277,14 @@ module Toys
     # @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.
+    # @param [String,Toys::Utils::WrappableString,
+    #     Array<String,Toys::Utils::WrappableString>] docs Documentation for the
+    #     args. Defaults to empty array.
     #
-    def remaining_args(key, accept: nil, default: [], doc: nil)
+    def remaining_args(key, accept: nil, default: [], docs: nil)
       return self if _cur_tool.nil?
       _cur_tool.definition_path = @path
-      _cur_tool.set_remaining_args(key, accept: accept, default: default, doc: doc)
+      _cur_tool.set_remaining_args(key, accept: accept, default: default, docs: docs)
       self
     end
 

data/lib/toys/core_version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.2".freeze
+  CORE_VERSION = "0.3.3".freeze
 end

data/lib/toys/helpers.rb

@@ -40,7 +40,9 @@ module Toys
     # Currently recognized module names are:
     #
     # * `:exec` : Methods to help execute subcommands.
-    # * `:file_utils` : The FileUtils standard library methods.
+    # * `:fileutils` : The FileUtils standard library methods.
+    # * `:highline` : Methods from the highline gem.
+    # * `:spinner` : Displays a spinner on the terminal.
     #
     # @param [String,Symbol] name Name of the helper module to return
     # @return [Module,nil] The module, or `nil` if not found

data/lib/toys/helpers/{file_utils.rb → fileutils.rb}

@@ -32,8 +32,13 @@ require "fileutils"
 module Toys
   module Helpers
     ##
-    # File system utilities. See the "fileutils" standard library.
+    # A module that provides all methods in the "fileutils" standard library.
     #
-    FileUtils = ::FileUtils
+    module Fileutils
+      ## @private
+      def self.extend_object(obj)
+        obj.extend(::FileUtils)
+      end
+    end
   end
 end

data/lib/toys/helpers/highline.rb

@@ -0,0 +1,127 @@
+# 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.
+;
+
+gem "highline", "~> 1.7"
+
+require "highline"
+
+module Toys
+  module Helpers
+    ##
+    # A module that provides access to highline.
+    #
+    module Highline
+      ##
+      # Returns a global highline instance
+      # @return [::HighLine]
+      #
+      def self.highline
+        @highline ||= ::HighLine.new
+      end
+
+      ##
+      # Returns a global highline instance
+      # @return [::HighLine]
+      #
+      def highline
+        Highline.highline
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:agree HighLine#agree
+      #
+      def agree(*args, &block)
+        highline.agree(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:ask HighLine#ask
+      #
+      def ask(*args, &block)
+        highline.ask(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:choose HighLine#choose
+      #
+      def choose(*args, &block)
+        highline.choose(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:list HighLine#list
+      #
+      def list(*args, &block)
+        highline.list(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:say HighLine#say
+      #
+      def say(*args, &block)
+        highline.say(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine.color HighLine.color
+      #
+      def color(*args, &block)
+        ::HighLine.color(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine.color_code HighLine.color_code
+      #
+      def color_code(*args, &block)
+        ::HighLine.color_code(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine.uncolor HighLine.uncolor
+      #
+      def uncolor(*args, &block)
+        ::HighLine.uncolor(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:indent HighLine#indent
+      #
+      def indent(*args, &block)
+        highline.indent(*args, &block)
+      end
+
+      ##
+      # @see https://www.rubydoc.info/gems/highline/HighLine:newline HighLine#newline
+      #
+      def newline(*args, &block)
+        highline.newline(*args, &block)
+      end
+    end
+  end
+end

data/lib/toys/helpers/spinner.rb

@@ -0,0 +1,136 @@
+# 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 "monitor"
+
+module Toys
+  module Helpers
+    ##
+    # A module that provides a spinner output.
+    #
+    module Spinner
+      ##
+      # Default length of a single frame, in seconds.
+      # @return [Float]
+      #
+      DEFAULT_FRAME_LENGTH = 0.1
+
+      ##
+      # Default set of frames.
+      # @return [Array<String,Array(String,Integer)>]
+      #
+      DEFAULT_FRAMES = ["-", "\\", "|", "/"].freeze
+
+      ##
+      # 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.
+      #
+      # @param [String] leading_text Optional leading string to display to the
+      #     left of the spinner.
+      # @param [Float] frame_length Length of a single frame, in seconds.
+      #     Defaults to {DEFAULT_FRAME_LENGTH}.
+      # @param [Array<String,Array<String>>] frames An array of frames. Each
+      #     frame should be either a string, or a two-element array of string
+      #     and integer, where the integer is the visible length of the frame
+      #     on screen. The latter form should be used if the frame string
+      #     contains non-printing characters such as ANSI escape codes.
+      #     Defaults to {DEFAULT_FRAMES}.
+      # @param [IO] stream Stream to output the spinner to. Defaults to STDOUT.
+      #     Note the spinner will be disabled if this stream is not a tty.
+      # @param [String] final_text Optional final string to display when the
+      #     spinner is complete.
+      #
+      def spinner(leading_text: "",
+                  frame_length: DEFAULT_FRAME_LENGTH,
+                  frames: DEFAULT_FRAMES,
+                  stream: $stdout,
+                  final_text: "")
+        return nil unless block_given?
+        unless leading_text.empty?
+          stream.write(leading_text)
+          stream.flush
+        end
+        spin = SpinDriver.new(stream, frames, frame_length)
+        begin
+          yield
+        ensure
+          spin.stop
+          unless final_text.empty?
+            stream.write(final_text)
+            stream.flush
+          end
+        end
+      end
+
+      ## @private
+      class SpinDriver
+        include ::MonitorMixin
+
+        def initialize(stream, frames, frame_length)
+          @stream = stream
+          @frames = frames.map { |f| f.is_a?(::Array) ? f : [f, f.size] }
+          @frame_length = frame_length
+          @cur_frame = 0
+          @stopping = false
+          @cond = new_cond
+          super()
+          @thread = @stream.tty? ? start_thread : nil
+        end
+
+        def stop
+          synchronize do
+            @stopping = true
+            @cond.broadcast
+          end
+          @thread.join if @thread
+          self
+        end
+
+        private
+
+        def start_thread
+          ::Thread.new do
+            synchronize do
+              until @stopping
+                @stream.write(@frames[@cur_frame][0])
+                @stream.flush
+                @cond.wait(@frame_length)
+                size = @frames[@cur_frame][1]
+                @stream.write("\b" * size + " " * size + "\b" * size)
+                @cur_frame += 1
+                @cur_frame = 0 if @cur_frame >= @frames.size
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end