natty-ui 0.5.0

data/lib/natty-ui/wrapper/task.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative 'section'
+require_relative 'mixins'
+
+module NattyUI
+  module Features
+    # Creates task section implementing additional {ProgressAttributes}.
+    #
+    # A task section has additional states and can be closed with {#completed}
+    # or {#failed}.
+    #
+    # @param (see #information)
+    # @yieldparam [Wrapper::Task] section the created section
+    # @return [Object] the result of the code block
+    # @return [Wrapper::Task] itself, when no code block is given
+    def task(title, *args, &block)
+      _section(:Task, args, title: title, &block)
+    end
+  end
+
+  module TaskMethods
+    protected
+
+    def initialize(parent, title:, **opts)
+      @parent = parent
+      @temp = wrapper.temporary
+      @final_text = [title]
+      super(parent, title: title, symbol: :task, **opts)
+    end
+
+    def finish
+      unless failed?
+        @status = :completed if @status == :closed
+        @temp.call
+      end
+      __section(
+        @parent,
+        :Message,
+        @final_text,
+        title: @final_text.shift,
+        symbol: @status
+      )
+    end
+  end
+  private_constant :TaskMethods
+
+  class Wrapper
+    #
+    # A {Message} container to visualize the progression of a task.
+    #
+    # @see Features.task
+    class Task < Message
+      include ProgressAttributes
+      include TaskMethods
+    end
+  end
+end

data/lib/natty-ui/wrapper.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require_relative 'wrapper/ask'
+require_relative 'wrapper/framed'
+require_relative 'wrapper/heading'
+require_relative 'wrapper/message'
+require_relative 'wrapper/progress'
+require_relative 'wrapper/query'
+require_relative 'wrapper/section'
+require_relative 'wrapper/task'
+
+module NattyUI
+  #
+  # Helper class to wrap an output stream and implement all {Features}.
+  #
+  class Wrapper
+    include Features
+
+    # @return [IO] IO stream used for output
+    attr_reader :stream
+
+    # @attribute [r] ansi?
+    # @return [Boolean] whether ANSI is supported
+    def ansi? = false
+
+    # @attribute [r] screen_size
+    # @return [[Integer, Integer]] screen size as rows and columns
+    def screen_size
+      return @stream.winsize if @ws
+      [ENV['LINES'].to_i.nonzero? || 25, ENV['COLUMNS'].to_i.nonzero? || 80]
+    end
+
+    # @attribute [r] screen_rows
+    # @return [Integer] number of screen rows
+    def screen_rows
+      @ws ? @stream.winsize[0] : (ENV['LINES'].to_i.nonzero? || 25)
+    end
+
+    # @attribute [r] screen_columns
+    # @return [Integer] number of screen columns
+    def screen_columns
+      @ws ? @stream.winsize[-1] : (ENV['COLUMNS'].to_i.nonzero? || 80)
+    end
+
+    # @!group Tool functions
+
+    # Print given arguments as lines to the output stream.
+    #
+    # @overload puts(...)
+    #   @param [#to_s] ... objects to print
+    #   @comment @param [#to_s, nil] prefix line prefix
+    #   @comment @param [#to_s, nil] suffix line suffix
+    #   @return [Wrapper] itself
+    def puts(*args, prefix: nil, suffix: nil)
+      if args.empty?
+        @stream.puts(embellish("#{prefix}#{suffix}"))
+        @lines_written += 1
+      else
+        StringIO.open do |io|
+          io.puts(*args)
+          io.rewind
+          io.each(chomp: true) do |line|
+            @stream.puts(embellish("#{prefix}#{line}#{suffix}"))
+            @lines_written += 1
+          end
+        end
+      end
+      @stream.flush
+      self
+    end
+    alias add puts
+
+    # Add at least one empty line
+    #
+    # @param [#to_i] lines count of lines
+    # @return [Wrapper] itself
+    def space(lines = 1)
+      lines = [lines.to_i, 1].max
+      @stream.puts(*Array.new(lines))
+      @lines_written += lines
+      @stream.flush
+      self
+    end
+
+    # @note The screen manipulation is only available in ANSI mode see {#ansi?}
+    #
+    # Saves current screen, deletes all screen content and moves the cursor
+    # to the top left screen corner. It restores the screen after the block.
+    #
+    # @example
+    #   UI.page do |page|
+    #     page.info('This message will disappear in 5 seconds!')
+    #     sleep 5
+    #   end
+    #
+    # @yield [Wrapper] itself
+    # @return [Object] block result
+    def page
+      block_given? ? yield(self) : self
+    ensure
+      @stream.flush
+    end
+
+    # @note The screen manipulation is only available in ANSI mode see {#ansi?}
+    #
+    # Resets the part of the screen written below the current output line when
+    # the given block ended.
+    #
+    # @example
+    #   UI.temporary do |temp|
+    #     temp.info('This message will disappear in 5 seconds!')
+    #     sleep 5
+    #   end
+    #
+    # @overload temporary
+    #   @return [Proc] a function to reset the screen
+    #
+    # @overload temporary
+    #   @yield [Wrapper] itself
+    #   @return [Object] block result
+    def temporary
+      func = temp_func
+      return func unless block_given?
+      begin
+        yield(self)
+      ensure
+        func.call
+      end
+    end
+
+    # @!endgroup
+
+    # @!visibility private
+    attr_reader :lines_written
+
+    # @!visibility private
+    alias inspect to_s
+
+    protected
+
+    def embellish(obj)
+      obj = NattyUI.plain(obj)
+      obj.empty? ? nil : obj
+    end
+
+    def temp_func
+      lambda do
+        @stream.flush
+        self
+      end
+    end
+
+    def initialize(stream)
+      @stream = stream
+      @lines_written = 0
+      @ws = stream.respond_to?(:winsize) && stream.winsize&.size == 2
+    rescue Errno::ENOTTY
+      @ws = false
+    end
+
+    def wrapper = self
+    def prefix = nil
+    alias suffix prefix
+
+    private_class_method :new
+  end
+end

data/lib/natty-ui.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+require_relative 'natty-ui/wrapper'
+require_relative 'natty-ui/ansi_wrapper'
+
+#
+# Module to create beautiful, nice, nifty, fancy, neat, pretty, cool, lovely,
+# natty user interfaces for your CLI.
+#
+# It creates {Wrapper} instances which can optionally support ANSI. The UI
+# consists of {Wrapper::Element}s and {Wrapper::Section}s for different
+# {Features}.
+#
+module NattyUI
+  class << self
+    # @see .valid_in?
+    # @return [IO] IO stream used to read input
+    # @raise TypeError when a non-readable stream will be assigned
+    attr_reader :in_stream
+
+    # @param [IO] stream to read input
+    def in_stream=(stream)
+      unless valid_in?(stream)
+        raise(TypeError, "readable IO required  - #{stream.inspect}")
+      end
+      @in_stream = stream
+    end
+
+    # Create a wrapper for given `stream`.
+    #
+    # @see .valid_out?
+    #
+    # @param [IO] stream valid out stream
+    # @param [Boolean, :auto] ansi whether ANSI should be supported
+    #   or automatically selected
+    # @return [Wrapper] wrapper for the given `stream`
+    # @raise TypeError when `stream` is not a writable stream
+    def new(stream, ansi: :auto)
+      unless valid_out?(stream)
+        raise(TypeError, "writable IO required  - #{stream.inspect}")
+      end
+      wrapper_class(stream, ansi).__send__(:new, stream)
+    end
+
+    # Test if the given `stream` can be used for output
+    #
+    # @param [IO] stream IO instance to test
+    # @return [Boolean] whether if the given stream is usable
+    def valid_out?(stream)
+      (stream.is_a?(IO) && !stream.closed? && stream.stat.writable?) ||
+        (stream.is_a?(StringIO) && !stream.closed_write?)
+    rescue StandardError
+      false
+    end
+
+    # Test if the given `stream` can be used for input
+    #
+    # @param [IO] stream IO instance to test
+    # @return [Boolean] whether if the given stream is usable
+    def valid_in?(stream)
+      (stream.is_a?(IO) && !stream.closed? && stream.stat.readable?) ||
+        (stream.is_a?(StringIO) && !stream.closed_read?)
+    rescue StandardError
+      false
+    end
+
+    # Translate embedded attribute descriptions into ANSI control codes.
+    #
+    # @param [#to_s] str string to edit
+    # @return ]String] edited string
+    def embellish(str)
+      str = str.to_s
+      return '' if str.empty?
+      reset = false
+      ret =
+        str.gsub(/(\[\[((?~\]\]))\]\])/) do
+          match = Regexp.last_match[2]
+          unless match.delete_prefix!('/')
+            ansi = Ansi.try_convert(match)
+            next ansi ? reset = ansi : "[[#{match}]]"
+          end
+          match.empty? or next "[[#{match}]]"
+          reset = false
+          Ansi.reset
+        end
+      reset ? "#{ret}#{Ansi.reset}" : ret
+    end
+
+    # Remove embedded attribute descriptions from given string.
+    #
+    # @param [#to_s] str string to edit
+    # @return ]String] edited string
+    def plain(str)
+      str
+        .to_s
+        .gsub(/(\[\[((?~\]\]))\]\])/) do
+          match = Regexp.last_match[2]
+          unless match.delete_prefix!('/')
+            ansi = Ansi.try_convert(match)
+            next ansi ? nil : "[[#{match}]]"
+          end
+          match.empty? ? nil : "[[#{match}]]"
+        end
+    end
+
+    # Calculate monospace (display) width of given String.
+    # It respects Unicode character sizes inclusive emoji.
+    #
+    # @param [#to_s] str string to calculate
+    # @return [Integer] the display size
+    def display_width(str)
+      str = str.to_s
+      return 0 if str.empty?
+      ret = Unicode::DisplayWidth.of(str, 1)
+      ret -= emoji_extra_width_of(str) if defined?(Unicode::Emoji)
+      [ret, 0].max
+    end
+
+    private
+
+    def wrapper_class(stream, ansi)
+      return AnsiWrapper if ansi == true
+      return Wrapper if ansi == false || ENV.key?('NO_COLOR')
+      stream.tty? ? AnsiWrapper : Wrapper
+    end
+
+    def emoji_extra_width_of(string)
+      ret = 0
+      string.scan(Unicode::Emoji::REGEX) do |emoji|
+        ret += 2 * emoji.scan(EMOJI_MODIFIER_REGEX).size
+        emoji.scan(EMOKI_ZWJ_REGEX) do |zwj_succ|
+          ret += Unicode::DisplayWidth.of(zwj_succ, 1, {})
+        end
+      end
+      ret
+    end
+
+    def stderr_is_stdout?
+      STDOUT.tty? && STDERR.tty? && STDOUT.pos == STDERR.pos
+    rescue IOError, SystemCallError
+      false
+    end
+  end
+
+  if defined?(Unicode::Emoji)
+    EMOJI_MODIFIER_REGEX = /[#{Unicode::Emoji::EMOJI_MODIFIERS.pack('U*')}]/
+    EMOKI_ZWJ_REGEX = /(?<=#{[Unicode::Emoji::ZWJ].pack('U')})./
+    private_constant :EMOJI_MODIFIER_REGEX, :EMOKI_ZWJ_REGEX
+  end
+
+  # Instance for standard output.
+  StdOut = new(STDOUT)
+
+  # Instance for standard error output.
+  StdErr = stderr_is_stdout? ? StdOut : new(STDERR)
+
+  self.in_stream = STDIN
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: natty-ui
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Mike Blumtritt
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: unicode-display_width
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: |
+  This is the beautiful, nice, nifty, fancy, neat, pretty, cool, lovely,
+  natty user interface you like to have for your command line interfaces
+  (CLI).
+  Here you find elegant, simple and beautiful tools that enhance your
+  command line application functionally and aesthetically.
+email:
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- examples/basic.rb
+- examples/colors.rb
+- examples/illustration.svg
+- examples/progress.rb
+- examples/query.rb
+- lib/natty-ui.rb
+- lib/natty-ui/ansi.rb
+- lib/natty-ui/ansi_wrapper.rb
+- lib/natty-ui/version.rb
+- lib/natty-ui/wrapper.rb
+- lib/natty-ui/wrapper/ask.rb
+- lib/natty-ui/wrapper/element.rb
+- lib/natty-ui/wrapper/features.rb
+- lib/natty-ui/wrapper/framed.rb
+- lib/natty-ui/wrapper/heading.rb
+- lib/natty-ui/wrapper/message.rb
+- lib/natty-ui/wrapper/mixins.rb
+- lib/natty-ui/wrapper/progress.rb
+- lib/natty-ui/wrapper/query.rb
+- lib/natty-ui/wrapper/section.rb
+- lib/natty-ui/wrapper/task.rb
+homepage: https://github.com/mblumtritt/natty-ui
+licenses:
+- BSD-3-Clause
+metadata:
+  source_code_uri: https://github.com/mblumtritt/natty-ui
+  bug_tracker_uri: https://github.com/mblumtritt/natty-ui/issues
+  documentation_uri: https://rubydoc.info/gems/natty-ui
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.21
+signing_key:
+specification_version: 4
+summary: This is the beautiful, nice, nifty, fancy, neat, pretty, cool, lovely, natty
+  user interface you like to have for your CLI.
+test_files: []