natty-ui 0.5.0

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'features'
+
+module NattyUI
+  class Wrapper
+    #
+    # Basic visual element implementing all {Features}.
+    #
+    class Element
+      include Features
+
+      # @return [Section] when embedded in a section
+      # @return [Wrapper] when not embedded in a section
+      attr_reader :parent
+
+      # @return [Symbol] close status when closed
+      # @return [nil] when not closed
+      attr_reader :status
+
+      # @attribute [r] closed?
+      # @return [Boolean] whether its closed or not
+      def closed? = (@status != nil)
+
+      # Close the element.
+      #
+      # @return [Element] itself when used without a code block
+      # @return [nil] when used with a code block
+      def close = _close(:closed)
+
+      alias _to_s to_s
+      private :_to_s
+
+      # @!visibility private
+      def inspect
+        "#{_to_s[..-2]} status=#{@status}}}>"
+      end
+
+      protected
+
+      def prefix = "#{@parent.__send__(:prefix)}#{@prefix}"
+      def suffix = "#{@parent.__send__(:suffix)}#{@suffix}"
+      def finish = nil
+
+      def wrapper
+        return @wrapper if @wrapper
+        @wrapper = self
+        @wrapper = @wrapper.parent until @wrapper.is_a?(Wrapper)
+        @wrapper
+      end
+
+      def initialize(parent)
+        @parent = parent
+      end
+
+      def _close(state)
+        return self if @status
+        @status = state
+        finish
+        @raise ? raise(BREAK) : self
+      end
+
+      def _call
+        @raise = true
+        yield(self)
+        close unless closed?
+      rescue BREAK
+        nil
+      end
+
+      BREAK = Class.new(StandardError)
+      private_constant :BREAK
+
+      private_class_method :new
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module NattyUI
+  #
+  # Mix-in for output functionality.
+  #
+  module Features
+    protected
+
+    def _element(type, *args)
+      wrapper.class.const_get(type).__send__(:new, self).__send__(:_call, *args)
+    end
+
+    def _section(type, args, **opts, &block)
+      __section(self, type, args, **opts, &block)
+    end
+
+    def __section(owner, type, args, **opts, &block)
+      sec = wrapper.class.const_get(type).__send__(:new, owner, **opts)
+      sec.puts(*args) if args && !args.empty?
+      block ? sec.__send__(:_call, &block) : sec
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative 'section'
+
+module NattyUI
+  module Features
+    # Creates frame-enclosed section with a highlighted `title` and
+    # prints given additional arguments as lines into the section.
+    #
+    # When no block is given, the section must be closed, see {Section#close}.
+    #
+    # @param [#to_s] title object to print as section title
+    # @param [Array<#to_s>] args more objects to print
+    # @param [Symbol] type frame type;
+    #   valid types are `:rounded`, `:simple`, `:heavy`, `:semi`, `:double`
+    # @yieldparam [Wrapper::Framed] section the created section
+    # @return [Object] the result of the code block
+    # @return [Wrapper::Framed] itself, when no code block is given
+    def framed(title, *args, type: :rounded, &block)
+      _section(:Framed, args, title: title, type: type, &block)
+    end
+  end
+
+  class Wrapper
+    #
+    # A frame-enclosed {Section} with a highlighted title.
+    #
+    # @see Features#framed
+    class Framed < Section
+      protected
+
+      def initialize(parent, title:, type:, **opts)
+        top_start, top_suffix, left, bottom = components(type)
+        parent.puts(" #{title} ", prefix: top_start, suffix: top_suffix)
+        @bottom = bottom
+        super(parent, prefix: "#{left} ", **opts)
+      end
+
+      def finish = parent.puts(@bottom)
+
+      def components(type)
+        COMPONENTS[type] || raise(ArgumentError, "invalid frame type - #{type}")
+      end
+
+      COMPONENTS = {
+        rounded: %w[╭── ───── │ ╰──────────],
+        simple: %w[┌── ───── │ └──────────],
+        heavy: %w[┏━━ ━━━━━ ┃ ┗━━━━━━━━━━],
+        semi: %w[┍━━ ━━━━━ │ ┕━━━━━━━━━━],
+        double: %w[╔══ ═════ ║ ╚══════════]
+      }.compare_by_identity.freeze
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative 'section'
+
+module NattyUI
+  module Features
+    # Creates section with a H1 title.
+    #
+    # @param (see #information)
+    # @yieldparam [Wrapper::Heading] section the created section
+    # @return [Object] the result of the code block
+    # @return [Wrapper::Heading] itself, when no code block is given
+    def h1(title, *args, &block)
+      _section(:Heading, args, title: title, weight: 1, &block)
+    end
+
+    # Creates section with a H2 title.
+    #
+    # @param (see #information)
+    # @yieldparam (see #h1)
+    # @return (see #h1)
+    def h2(title, *args, &block)
+      _section(:Heading, args, title: title, weight: 2, &block)
+    end
+
+    # Creates section with a H3 title.
+    #
+    # @param (see #information)
+    # @yieldparam (see #h1)
+    # @return (see #h1)
+    def h3(title, *args, &block)
+      _section(:Heading, args, title: title, weight: 3, &block)
+    end
+
+    # Creates section with a H4 title.
+    #
+    # @param (see #information)
+    # @yieldparam (see #h1)
+    # @return (see #h1)
+    def h4(title, *args, &block)
+      _section(:Heading, args, title: title, weight: 4, &block)
+    end
+
+    # Creates section with a H5 title.
+    #
+    # @param (see #information)
+    # @yieldparam (see #h1)
+    # @return (see #h1)
+    def h5(title, *args, &block)
+      _section(:Heading, args, title: title, weight: 5, &block)
+    end
+  end
+
+  class Wrapper
+    #
+    # A {Section} with a highlighted title.
+    #
+    # @see Features#h1
+    # @see Features#h2
+    # @see Features#h3
+    # @see Features#h4
+    # @see Features#h5
+    class Heading < Section
+      protected
+
+      def initialize(parent, title:, weight:, **opts)
+        prefix, suffix = enclose(weight)
+        parent.puts(title, prefix: prefix, suffix: suffix)
+        super(parent, **opts)
+      end
+
+      def enclose(weight)
+        enclose = ENCLOSE[weight]
+        return "#{enclose} ", " #{enclose}" if enclose
+        raise(ArgumentError, "invalid heading weight - #{weight}")
+      end
+
+      ENCLOSE = {
+        1 => '═══════',
+        2 => '━━━━━',
+        3 => '━━━',
+        4 => '───',
+        5 => '──'
+      }.compare_by_identity.freeze
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative 'section'
+
+module NattyUI
+  module Features
+    # Creates a simple message section with a highlighted `title`  and
+    # prints given additional arguments as lines into the section.
+    #
+    # @param [#to_s] title object to print as section title
+    # @param [Array<#to_s>] args more objects to print
+    # @param [#to_s] symbol symbol/prefix used for the title
+    # @yieldparam [Wrapper::Message] section the created section
+    # @return [Object] the result of the code block
+    # @return [Wrapper::Message] itself, when no code block is given
+    def message(title, *args, symbol: :default, &block)
+      _section(:Message, args, title: title, symbol: symbol, &block)
+    end
+    alias msg message
+
+    # Creates a informational message section with a highlighted `title`  and
+    # prints given additional arguments as lines into the section.
+    #
+    # @param [#to_s] title object to print as section title
+    # @param [Array<#to_s>] args more objects to print
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def information(title, *args, &block)
+      _section(:Message, args, title: title, symbol: :information, &block)
+    end
+    alias info information
+
+    # Creates a warning message section with a highlighted `title`  and
+    # prints given additional arguments as lines into the section.
+    #
+    # @param (see #information)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def warning(title, *args, &block)
+      _section(:Message, args, title: title, symbol: :warning, &block)
+    end
+    alias warn warning
+
+    # Creates a error message section with a highlighted `title`  and
+    # prints given additional arguments as lines into the section.
+    #
+    # @param (see #information)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def error(title, *args, &block)
+      _section(:Message, args, title: title, symbol: :error, &block)
+    end
+    alias err error
+
+    # Creates a completion message section with a highlighted `title`  and
+    # prints given additional arguments as lines into the section.
+    #
+    # When used for a {#task} section it closes this section with status `:ok`.
+    #
+    # @param (see #information)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def completed(title, *args, &block)
+      _section(:Message, args, title: title, symbol: :completed, &block)
+    end
+    alias done completed
+    alias ok completed
+
+    # Creates a failure message section with a highlighted `title` and
+    # prints given additional arguments as lines into the section.
+    #
+    # When used for a {#task} section it closes this section with status
+    # `:failed`.
+    #
+    # @param (see #information)
+    # @yieldparam (see #message)
+    # @return (see #message)
+    def failed(title, *args, &block)
+      _section(:Message, args, title: title, symbol: :failed, &block)
+    end
+  end
+
+  class Wrapper
+    #
+    # A {Section} with a highlighted title.
+    #
+    # @see Features#message
+    # @see Features#information
+    # @see Features#warning
+    # @see Features#error
+    # @see Features#completed
+    # @see Features#failed
+    class Message < Section
+      protected
+
+      def initialize(parent, title:, symbol:, **opts)
+        parent.puts(title, **title_attr(str = as_symbol_str(symbol), symbol))
+        super(parent, prefix: ' ' * (NattyUI.display_width(str) + 1), **opts)
+      end
+
+      def title_attr(str, _symbol) = { prefix: "#{str} " }
+      def as_symbol_str(symbol) = (SYMBOL[symbol] || symbol)
+
+      SYMBOL = {
+        default: '•',
+        information: 'i',
+        warning: '!',
+        error: 'X',
+        completed: '✓',
+        failed: 'F',
+        query: '▶︎',
+        task: '➔'
+      }.compare_by_identity.freeze
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module NattyUI
+  #
+  # Additional attributes for progression elements.
+  #
+  # Progression elements have additional states ({#completed?}, {#failed?}) and
+  # can be closed with calling {Features#completed} or {Features#failed}.
+  #
+  # @see Wrapper::Progress
+  # @see Wrapper::Task
+  #
+  module ProgressAttributes
+    # @attribute [r] completed?
+    # @return [Boolean] whether the task completed sucessfully
+    def completed? = (@status == :completed)
+
+    # @attribute [r] failed?
+    # @return [Boolean] whether the task failed
+    def failed? = (@status == :failed)
+
+    # @!visibility private
+    def completed(*args)
+      @final_text = args unless args.empty?
+      _close(:completed)
+    end
+    alias done completed
+    alias ok completed
+
+    # @!visibility private
+    def failed(*args)
+      @final_text = args unless args.empty?
+      _close(:failed)
+    end
+  end
+
+  #
+  # Additional attributes for progression elements.
+  #
+  # @see Wrapper::Progress
+  #
+  module ValueAttributes
+    # @return [Float] current value
+    attr_reader :value
+
+    def value=(val)
+      @value = [0, val.to_f].max
+      @max_value = @value if @max_value&.< 0
+      redraw
+    end
+
+    # Maximal value.
+    #
+    # @return [Float] maximal value
+    # @return [nil] when no max_value was configured
+    attr_reader :max_value
+
+    # Increase the value by given amount.
+    #
+    # @param increment [#to_f] value increment
+    # @return [Wrapper::Element] itself
+    def step(increment = 1)
+      self.value = @value + increment.to_f
+      self
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'element'
+require_relative 'mixins'
+
+module NattyUI
+  module Features
+    # Creates progress element implementing additional {ProgressAttributes}.
+    #
+    # A progress element has additional states and can be closed with {#completed}
+    # or {#failed}.
+    #
+    # @param [#to_s] title object to print as progress title
+    # @param [##to_f] max_value maximum value of the progress
+    # @return [Wrapper::Progress] the created progress element
+    def progress(title, max_value: nil)
+      _section(:Progress, nil, title: title, max_value: max_value)
+    end
+  end
+
+  class Wrapper
+    #
+    # An {Element} displaying a progression.
+    #
+    # @see Features#progress
+    class Progress < Element
+      include ProgressAttributes
+      include ValueAttributes
+
+      protected
+
+      def initialize(parent, title:, max_value:, **_)
+        super(parent)
+        @final_text = [title]
+        @max_value = [0, max_value.to_f].max if max_value
+        @value = 0
+        @progress = 0
+        draw_title(title)
+      end
+
+      def draw_title(title) = (wrapper.stream << prefix << "➔ #{title} ").flush
+      def draw_final = (wrapper.stream << "\n")
+
+      def redraw
+        return (wrapper.stream << '.').flush unless @max_value
+        cn = (20 * @value / @max_value).to_i
+        return if @progress == cn
+        (wrapper.stream << ('.' * (cn - @progress))).flush
+        @progress = cn
+      end
+
+      def finish
+        draw_final
+        return @parent.failed(*@final_text) if failed?
+        @status = :ok if @status == :closed
+        @parent.completed(*@final_text)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative 'element'
+
+module NattyUI
+  module Features
+    # Request a choice from user.
+    #
+    # @example Select by Index
+    #   choice = sec.query(
+    #     'Which fruits do you prefer?',
+    #     'Apples',
+    #     'Bananas',
+    #     'Cherries'
+    #   )
+    #   # => '1' or '2' or '3' or nil if user aborted
+    #
+    # @example Select by given char
+    #   choice = sec.query(
+    #     'Which fruits do you prefer?',
+    #     a: 'Apples',
+    #     b: 'Bananas',
+    #     c: 'Cherries'
+    #   )
+    #   # => 'a' or 'b' or 'c' or nil if user aborted
+    #
+    # @param question [#to_s] Question to display
+    # @param choices [#to_s] choices selectable via index (0..9)
+    # @param result  [Symbol] defines how the result ist returned
+    # @param kw_choices [{Char => #to_s}] choices selectable with given char
+    # @return [Char] when `result` is configured as `:char`
+    # @return [#to_s] when `result` is configured as `:choice`
+    # @return [[Char, #to_s]] when `result` is configured as `:both`
+    # @return [nil] when input was aborted with `ESC`, `^C` or `^D`
+    def query(question, *choices, result: :char, **kw_choices)
+      _element(:Query, question, choices, kw_choices, result)
+    end
+  end
+
+  class Wrapper
+    #
+    # An {Element} to request a user choice.
+    #
+    # @see Features#query
+    class Query < Element
+      protected
+
+      def _call(question, choices, kw_choices, result_typye)
+        choices = grab(choices, kw_choices)
+        return if choices.empty?
+        wrapper.temporary do
+          __section(
+            @parent,
+            :Message,
+            choices.map { |k, v| "#{k} #{v}" },
+            title: question,
+            symbol: :query
+          )
+          read(choices, result_typye)
+        end
+      end
+
+      def read(choices, result_typye)
+        while true
+          char = NattyUI.in_stream.getch
+          return if "\3\4\e".include?(char)
+          next unless choices.key?(char)
+          return char if result_typye == :char
+          return choices[char] if result_typye == :choice
+          return char, choices[char]
+        end
+      end
+
+      def grab(choices, kw_choices)
+        Array
+          .new(choices.size) { |i| i + 1 }
+          .zip(choices)
+          .to_h
+          .merge!(kw_choices)
+          .transform_keys! { |k| [k.to_s[0], ' '].max }
+          .transform_values! { |v| v.to_s.tr("\r\n", ' ') }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'element'
+
+module NattyUI
+  module Features
+    # Creates a default section and prints given arguments as lines
+    # into the section.
+    #
+    # @param [Array<#to_s>] args objects to print
+    # @yieldparam [Wrapper::Section] section the created section
+    # @return [Object] the result of the code block
+    # @return [Wrapper::Section] itself, when no code block is given
+    def section(*args, &block)
+      _section(:Section, args, prefix: '  ', suffix: '  ', &block)
+    end
+    alias sec section
+
+    # Creates a quotation section and prints given arguments as lines
+    # into the section.
+    #
+    # @param (see #section)
+    # @yieldparam (see #section)
+    # @return (see #section)
+    def quote(*args, &block)
+      _section(:Section, args, prefix: '▍ ', prefix_attr: 39, &block)
+    end
+  end
+
+  class Wrapper
+    #
+    # Visual element to keep text lines together.
+    #
+    # A section can contain other elements and sections.
+    #
+    # @see Features#section
+    # @see Features#quote
+    class Section < Element
+      # Close the section.
+      #
+      # @return [Section] itself when used without a code block
+      # @return [nil] when used with a code block
+      def close = _close(:closed)
+
+      # Print given arguments as lines into the section.
+      #
+      # @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 [Section] itself
+      def puts(*args, prefix: nil, suffix: nil)
+        return self if @status
+        @parent.puts(
+          *args,
+          prefix: prefix ? "#{@prefix}#{prefix}" : @prefix,
+          suffix: suffix ? "#{@suffix}#{suffix}" : @suffix
+        )
+        self
+      end
+      alias add puts
+
+      # Add at least one empty line
+      #
+      # @param [#to_i] lines count of lines
+      # @return [Section] itself
+      def space(lines = 1)
+        @parent.puts(
+          *Array.new([lines.to_i, 1].max),
+          prefix: @prefix,
+          suffix: @suffix
+        )
+        self
+      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
+      #   section.temporary do |temp|
+      #     temp.info('This message will disappear in 5 seconds!')
+      #     sleep 5
+      #   end
+      #
+      # @yield [Section] itself
+      # @return [Object] block result
+      def temporary
+        block_given? ? yield(self) : self
+      end
+
+      protected
+
+      def initialize(parent, prefix: nil, suffix: nil, **_)
+        super(parent)
+        @prefix = prefix
+        @suffix = suffix
+      end
+    end
+  end
+end