toys-core 0.7.0 → 0.8.0

data/lib/toys/utils/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.
 ;
 
 require "stringio"
@@ -48,11 +40,11 @@ module Toys
     # This class supports ANSI styled output where supported.
     #
     # Styles may be specified in any of the following forms:
-    # *   A symbol indicating the name of a well-known style, or the name of
+    #  *  A symbol indicating the name of a well-known style, or the name of
     #     a defined style.
-    # *   An rgb string in hex "rgb" or "rrggbb" form.
-    # *   An ANSI code string in `\e[XXm` form.
-    # *   An array of ANSI codes as integers.
+    #  *  An rgb string in hex "rgb" or "rrggbb" form.
+    #  *  An ANSI code string in `\e[XXm` form.
+    #  *  An array of ANSI codes as integers.
     #
     class Terminal
       ##
@@ -61,10 +53,16 @@ module Toys
       class TerminalError < ::StandardError
       end
 
-      ## ANSI style code to clear styles
+      ##
+      # ANSI style code to clear styles
+      # @return [String]
+      #
       CLEAR_CODE = "\e[0m"
 
-      ## Standard ANSI style codes
+      ##
+      # Standard ANSI style codes by name.
+      # @return [Hash{Symbol => Array<Integer>}]
+      #
       BUILTIN_STYLE_NAMES = {
         clear: [0],
         reset: [0],
@@ -105,7 +103,7 @@ module Toys
         on_bright_blue: [104],
         on_bright_magenta: [105],
         on_bright_cyan: [106],
-        on_bright_white: [107]
+        on_bright_white: [107],
       }.freeze
 
       ##
@@ -123,7 +121,7 @@ module Toys
       ##
       # Returns a copy of the given string with all ANSI style codes removed.
       #
-      # @param [String] str Input string
+      # @param str [String] Input string
       # @return [String] String with styles removed
       #
       def self.remove_style_escapes(str)
@@ -133,12 +131,12 @@ module Toys
       ##
       # Create a terminal.
       #
-      # @param [IO,Logger,nil] output Output stream or logger.
-      # @param [IO,nil] input Input stream.
+      # @param input [IO,nil] Input stream.
+      # @param output [IO,Logger,nil] Output stream or logger.
+      # @param styled [Boolean,nil] Whether to output ansi styles. If `nil`, the
+      #     setting is inferred from whether the output has a tty.
       #
-      def initialize(input: $stdin,
-                     output: $stdout,
-                     styled: nil)
+      def initialize(input: $stdin, output: $stdout, styled: nil)
         @input = input
         @output = output
         @styled =
@@ -171,22 +169,24 @@ module Toys
       ##
       # Write a partial line without appending a newline.
       #
-      # @param [String] str The line to write
-      # @param [Symbol,String,Array<Integer>...] styles Styles to apply to the
+      # @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)
-        output.write(apply_styles(str, *styles))
-        output.flush
+        output&.write(apply_styles(str, *styles))
+        output&.flush
         self
       end
 
       ##
       # Write a line, appending a newline if one is not already present.
       #
-      # @param [String] str The line to write
-      # @param [Symbol,String,Array<Integer>...] styles Styles to apply to the
+      # @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)
         str = "#{str}\n" unless str.end_with?("\n")
@@ -197,7 +197,8 @@ module Toys
       ##
       # Write a line, appending a newline if one is not already present.
       #
-      # @param [String] str The line to write
+      # @param str [String] The line to write
+      # @return [self]
       #
       def <<(str)
         puts(str)
@@ -205,6 +206,7 @@ module Toys
 
       ##
       # Write a newline and flush the current line.
+      # @return [self]
       #
       def newline
         puts
@@ -213,12 +215,12 @@ module Toys
       ##
       # Ask a question and get a response.
       #
-      # @param [String] prompt Required prompt string.
-      # @param [Symbol,String,Array<Integer>...] styles Styles to apply to the
+      # @param prompt [String] Required prompt string.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
       #     prompt.
-      # @param [String,nil] default Default value, or `nil` for no default.
+      # @param default [String,nil] Default value, or `nil` for no default.
       #     Uses `nil` if not specified.
-      # @param [:default,String,nil] trailing_text Trailing text appended to
+      # @param trailing_text [:default,String,nil] Trailing text appended to
       #     the prompt, `nil` for none, or `:default` to show the default.
       # @return [String]
       #
@@ -231,17 +233,17 @@ module Toys
           prompt = "#{ptext} #{trailing_text}#{pspaces}"
         end
         write(prompt, *styles)
-        resp = input.gets.to_s.chomp
+        resp = input&.gets.to_s.chomp
         resp.empty? ? default.to_s : resp
       end
 
       ##
       # Confirm with the user.
       #
-      # @param [String] prompt Prompt string. Defaults to `"Proceed?"`.
-      # @param [Symbol,String,Array<Integer>...] styles Styles to apply to the
+      # @param prompt [String] Prompt string. Defaults to `"Proceed?"`.
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply to the
       #     prompt.
-      # @param [Boolean,nil] default Default value, or `nil` for no default.
+      # @param default [Boolean,nil] Default value, or `nil` for no default.
       #     Uses `nil` if not specified.
       # @return [Boolean]
       #
@@ -262,6 +264,9 @@ module Toys
           raise TerminalError, "Cannot confirm because the input stream is at eof."
         end
         if !resp.strip.empty? || default.nil?
+          if input.nil?
+            raise TerminalError, "Cannot confirm because there is no input stream."
+          end
           confirm('Please answer "y" or "n"', default: default)
         else
           default
@@ -273,17 +278,18 @@ module Toys
       # 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
+      # @param leading_text [String] Optional leading string to display to the
       #     left of the spinner. Default is the empty string.
-      # @param [Float] frame_length Length of a single frame, in seconds.
+      # @param frame_length [Float] Length of a single frame, in seconds.
       #     Defaults to {DEFAULT_SPINNER_FRAME_LENGTH}.
-      # @param [Array<String>] frames An array of frames. Defaults to
+      # @param frames [Array<String>] An array of frames. Defaults to
       #     {DEFAULT_SPINNER_FRAMES}.
-      # @param [Symbol,Array<Symbol>] style A terminal style or array of styles
+      # @param style [Symbol,Array<Symbol>] A terminal style or array of styles
       #     to apply to all frames in the spinner. Defaults to empty,
-      # @param [String] final_text Optional final string to display when the
+      # @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)
@@ -338,8 +344,9 @@ module Toys
       # The definition of a style may include any valid style specification,
       # including the symbol names of existing defined styles.
       #
-      # @param [Symbol] name The name for the style
-      # @param [Symbol,String,Array<Integer>...] styles
+      # @param name [Symbol] The name for the style
+      # @param styles [Symbol,String,Array<Integer>...]
+      # @return [self]
       #
       def define_style(name, *styles)
         @named_styles[name] = resolve_styles(*styles)
@@ -352,8 +359,8 @@ module Toys
       # add any ANSI style codes and in fact removes any existing codes. If
       # styles were added, ensures that the string ends with a clear code.
       #
-      # @param [String] str String to style
-      # @param [Symbol,String,Array<Integer>...] styles Styles to apply
+      # @param str [String] String to style
+      # @param styles [Symbol,String,Array<Integer>...] Styles to apply
       # @return [String] The styled string
       #
       def apply_styles(str, *styles)
@@ -409,7 +416,7 @@ module Toys
           rgb = style.to_i(16)
           [38, 2, (rgb >> 8) * 0x11, ((rgb & 0xf0) >> 4) * 0x11, (rgb & 0xf) * 0x11]
         when /^\e\[([\d;]+)m$/
-          $1.split(";").map(&:to_i)
+          ::Regexp.last_match(1).split(";").map(&:to_i)
         end
       end
 

data/lib/toys/wrappable_string.rb

@@ -0,0 +1,162 @@
+# 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
+  ##
+  # A string intended for word-wrapped display.
+  #
+  class WrappableString
+    ##
+    # Create a wrapped string.
+    # @param string [String,Array<String>] The string or array of string
+    #     fragments
+    #
+    def initialize(string = "")
+      @fragments = string.is_a?(::Array) ? string.map(&:to_s) : string.to_s.split
+    end
+
+    ##
+    # Returns the string fragments, i.e. the individual "words" for wrapping.
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :fragments
+
+    ##
+    # Returns a new WrappaableString whose content is the concatenation of this
+    # WrappableString with another WrappableString.
+    #
+    # @param other [WrappableString]
+    # @return [WrappableString]
+    #
+    def +(other)
+      other = WrappableString.new(other) unless other.is_a?(WrappableString)
+      WrappableString.new(fragments + other.fragments)
+    end
+
+    ##
+    # Returns true if the string is empty (i.e. has no fragments)
+    # @return [Boolean]
+    #
+    def empty?
+      @fragments.empty?
+    end
+
+    ##
+    # Returns the string without any wrapping
+    # @return [String]
+    #
+    def string
+      @fragments.join(" ")
+    end
+    alias to_s string
+
+    ## @private
+    def ==(other)
+      return false unless other.is_a?(WrappableString)
+      other.fragments == fragments
+    end
+    alias eql? ==
+
+    ## @private
+    def hash
+      fragments.hash
+    end
+
+    ##
+    # Wraps the string to the given width.
+    #
+    # @param width [Integer,nil] Width in characters, or `nil` for infinite.
+    # @param width2 [Integer,nil] Width in characters for the second and
+    #     subsequent lines, or `nil` to use the same as width.
+    #
+    # @return [Array<String>] Wrapped lines
+    #
+    def wrap(width, width2 = nil)
+      lines = []
+      line = ""
+      line_len = 0
+      fragments.each do |frag|
+        frag_len = frag.gsub(/\e\[\d+(;\d+)*m/, "").size
+        if line_len.zero?
+          line = frag
+          line_len = frag_len
+        elsif width && line_len + 1 + frag_len > width
+          lines << line
+          line = frag
+          line_len = frag_len
+          width = width2 if width2
+        else
+          line_len += frag_len + 1
+          line = "#{line} #{frag}"
+        end
+      end
+      lines << line if line_len.positive?
+      lines
+    end
+
+    ##
+    # Wraps an array of lines to the given width.
+    #
+    # @param strs [Array<WrappableString>] Array of strings to wrap.
+    # @param width [Integer,nil] Width in characters, or `nil` for infinite.
+    # @param width2 [Integer,nil] Width in characters for the second and
+    #     subsequent lines, or `nil` to use the same as width.
+    #
+    # @return [Array<String>] Wrapped lines
+    #
+    def self.wrap_lines(strs, width, width2 = nil)
+      result = Array(strs).map do |s|
+        s = make(s)
+        lines = s.empty? ? [""] : s.wrap(width, width2)
+        width = width2 if width2
+        lines
+      end.flatten
+      result = [] if result.all?(&:empty?)
+      result
+    end
+
+    ##
+    # Make the given object a WrappableString.
+    # If the object is already a WrappableString, return it. Otherwise,
+    # treat it as a string or an array of strings and wrap it in a
+    # WrappableString.
+    #
+    # @param obj [Toys::WrappableString,String,Array<String>]
+    # @return [Toys::WrappableString]
+    #
+    def self.make(obj)
+      obj.is_a?(WrappableString) ? obj : WrappableString.new(obj)
+    end
+
+    ##
+    # Make the given object an array of WrappableString.
+    #
+    # @param objs [Array<Toys::WrappableString,String,Array<String>>]
+    # @return [Array<Toys::WrappableString>]
+    #
+    def self.make_array(objs)
+      Array(objs).map { |obj| make(obj) }
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-01-24 00:00:00.000000000 Z
+date: 2019-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -86,30 +86,30 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.62.0
+        version: 0.71.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.62.0
+        version: 0.71.0
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.16
+        version: 0.9.19
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.16
+        version: 0.9.19
 description: Toys-Core is the command line tool framework underlying Toys. It can
-  be used to create command line binaries using the internal Toys APIs.
+  be used to create command line executables using the internal Toys APIs.
 email:
 - dazuma@gmail.com
 executables: []
@@ -122,26 +122,28 @@ files:
 - README.md
 - docs/guide.md
 - lib/toys-core.rb
+- lib/toys/acceptor.rb
+- lib/toys/alias.rb
+- lib/toys/arg_parser.rb
 - lib/toys/cli.rb
+- lib/toys/compat.rb
+- lib/toys/completion.rb
+- lib/toys/context.rb
 - lib/toys/core_version.rb
-- lib/toys/definition/acceptor.rb
-- lib/toys/definition/alias.rb
-- lib/toys/definition/arg.rb
-- lib/toys/definition/flag.rb
-- lib/toys/definition/flag_group.rb
-- lib/toys/definition/source_info.rb
-- lib/toys/definition/tool.rb
-- lib/toys/dsl/arg.rb
 - lib/toys/dsl/flag.rb
 - lib/toys/dsl/flag_group.rb
+- lib/toys/dsl/positional_arg.rb
 - lib/toys/dsl/tool.rb
 - lib/toys/errors.rb
+- lib/toys/flag.rb
+- lib/toys/flag_group.rb
 - lib/toys/input_file.rb
 - lib/toys/loader.rb
 - lib/toys/middleware.rb
 - lib/toys/mixin.rb
-- lib/toys/runner.rb
-- lib/toys/standard_middleware.rb
+- lib/toys/module_lookup.rb
+- lib/toys/positional_arg.rb
+- lib/toys/source_info.rb
 - lib/toys/standard_middleware/add_verbosity_flags.rb
 - lib/toys/standard_middleware/handle_usage_errors.rb
 - lib/toys/standard_middleware/set_default_descriptions.rb
@@ -154,15 +156,15 @@ files:
 - lib/toys/standard_mixins/terminal.rb
 - lib/toys/template.rb
 - lib/toys/tool.rb
+- lib/toys/utils/completion_engine.rb
 - lib/toys/utils/exec.rb
 - lib/toys/utils/gems.rb
 - lib/toys/utils/help_text.rb
-- lib/toys/utils/module_lookup.rb
 - lib/toys/utils/terminal.rb
-- lib/toys/utils/wrappable_string.rb
+- lib/toys/wrappable_string.rb
 homepage: https://github.com/dazuma/toys
 licenses:
-- BSD-3-Clause
+- MIT
 metadata:
   changelog_uri: https://github.com/dazuma/toys/blob/master/toys-core/CHANGELOG.md
   source_code_uri: https://github.com/dazuma/toys
@@ -183,8 +185,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Framework for creating command line binaries
+summary: Framework for creating command line executables
 test_files: []