natty-ui 0.35.0 → 1.0.2

data/examples/tables.rb

@@ -2,57 +2,39 @@
 
 require_relative '../lib/natty-ui'
 
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Tables[/]' do
+ui.section '[b]ᓚᕠᗢ NattyUI[/b] [i green]Print Tables' do
   ui.space
-  ui.table(border: :rounded, border_around: true) do |table|
-    table.add(
-      'Header Col 0',
-      'Header Col 1',
-      'Header Col 2',
-      align: :centered,
-      style: %i[bold red]
+  ui.table border_frame: :double do |table|
+    table.add_row(
+      '[bold red]Header Col 0',
+      '[bold red]Header Col 1',
+      '[bold red]Header Col 2',
+      align: :center
     )
 
-    table.add do |row|
+    table.add_row padding: [0, 2] do |row|
       row.add '[blue]Row 1 Col 0', align: :left, vertical: :middle
       row.add '[blue]Row 1 Col 1', "Line 2\nLine 3", align: :right
-      row.add '[blue]Row 1 Col 2', align: :centered, vertical: :bottom
-      row.padding = [0, 2]
+      row.add '[blue]Row 1 Col 2', align: :center, vertical: :bottom
     end
 
     filler_text = <<~FILLER
       This is some filler text to demonstrate word-wise line breaks inside
       a table cell. Please, just ignore this nonsense-text gently.
     FILLER
-    table.add do |row|
-      row.add '[blue]Row 2 Col 0', filler_text, eol: false, align: :right
-      row.add '[blue]Row 2 Col 1', filler_text, eol: false, align: :centered
-      row.add '[blue]Row 2 Col 2', filler_text, eol: false, align: :left
-      row.padding = [1, 2]
-    end
-  end
 
-  ui.space
-  ui.table(border_style: :bright_blue, border: :default) do |table|
-    table.add(*('A'..'Z').each_slice(2).map(&:join))
-    table.add(*('😀'..'😌'))
-    table.add(*(3..15).map { _1.to_s(3) })
-    table.each { |row| row.assign(align: :centered, style: :bright_yellow) }
+    table.add_row padding: [1, 2], eol: false do |row|
+      row.add '[blue]Row 2 Col 0', filler_text, align: :right, max_width: 0.25
+      row.add '[blue]Row 2 Col 1', filler_text, align: :center
+      row.add '[blue]Row 2 Col 2', filler_text, align: :left, max_width: 0.25
+    end
   end
 
   ui.space
-  ui.table do |table|
-    table.add do |row|
-      row.add 'green', style: :on_green, max_width: 0.1
-      row.add 'blue', style: :on_blue, max_width: 0.25
-      row.add 'red', style: :on_red, max_width: 0.1
-      row.align = :centered
-    end
-    table.add do |row|
-      row.add 'yellow', style: :on_yellow
-      row.add 'magenta', style: :on_magenta
-      row.add 'cyan', style: :on_cyan
-      row.align = :centered
-    end
+  ui.table border_style: :bright_blue, width: :max do |table|
+    table.add_row(*('A'..'Z').each_slice(2).map(&:join))
+    table.add_row(*('😀'..'😌'))
+    table.add_row(*(3..15).map { it.to_s(3) })
+    table.each_row { it.attributes.align = :center }
   end
 end

data/examples/tasks.rb

@@ -2,51 +2,61 @@
 
 require_relative '../lib/natty-ui'
 
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Tasks[/]' do
+ui.begin '[b]ᓚᕠᗢ NattyUI[/b] [i green]Tasks' do
   ui.space
   ui.puts <<~TEXT, eol: false
-    Tasks are sections that are closed either successfully or with an error
-    message. If successful, their content is only displayed temporarily and can
-    consist of all other features, in particular further (sub)tasks. As an
-    exception to this, some elements can be “pinned” as permanent content.
+    [i]Tasks[/i] are sections that are either completed successfully or result
+    in an error message. Upon successful completion, their content is displayed
+    only temporarily and may consist of any other elements, including additional
+    (sub)tasks. As an exception to this, some elements can be “pinned” as
+    permanent content.
   TEXT
 
   # to simulate some work:
-  def do_something = sleep(0.25)
-  def do_something_heavy = sleep(0.75)
+  simulate =
+    Module.new do
+      if ENV.key?('NO_SLEEP')
+        def self.work = nil
+        def self.heavy_work = nil
+      else
+        def self.work = sleep(0.2)
+        def self.heavy_work = sleep(1)
+      end
+    end
 
   ui.space
-  ui.task 'Actualize Reading List' do
-    ui.puts 'This is a simple which actualizes the book reading list.'
+  ui.task 'Update Reading List' do
+    ui.puts 'This is an example which actualizes the book reading list.'
 
     ui.task 'Connect to Library' do
-      do_something
+      simulate.work
       ui.mark 'Server Found', mark: :checkmark
-      ui.task('Login...') { do_something_heavy }
+      ui.task('Login...') { simulate.heavy_work }
     end
 
-    ui.task('Request New Books') { do_something_heavy }
+    ui.task('Request New Books') { simulate.heavy_work }
 
-    bar = ui.progress('Loading Books...', pin: true)
-    11.times do
-      do_something
-      bar.step
+    ui.progress('Loading Books...') do |progress|
+      while progress.value < 17
+        simulate.work
+        progress.step
+      end
     end
-    bar.ok 'Books Loaded'
+    ui.ok '17 Books Loaded'
 
-    ui.task('Disconnect from Library') { do_something_heavy }
+    ui.task('Disconnect from Library') { simulate.heavy_work }
 
-    ui.progress 'Read Cover Images', max: 11 do |progress|
+    ui.progress 'Read Cover Images', max: 13 do |progress|
       while progress.value < progress.max
-        do_something
+        simulate.work
         progress.step
       end
     end
 
     ui.pin 'New Books Marked', mark: :checkmark
 
-    ui.task('Optimize Database') { do_something_heavy }
+    ui.task('Optimize Database') { simulate.heavy_work }
 
-    ui.task('Remove Dust') { do_something_heavy }
+    ui.task('Remove Dust') { simulate.heavy_work }
   end
 end

data/examples/vbars.rb

@@ -2,7 +2,7 @@
 
 require_relative '../lib/natty-ui'
 
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Vertical Bars[/]' do
+ui.begin '[b]ᓚᕠᗢ NattyUI[/b] [i green]Print Vertical Bars' do
   values = [
     11.97,
     14.35,
@@ -27,13 +27,15 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Vertical Bars[/]' do
   ].freeze
 
   ui.space
-  ui.vbars values, style: :blue
+  ui.vbars values, style: :blue, bar_width: :auto
   ui.puts 'NattyUI can quick dump values as vertical bars.'
 
   ui.space
-  ui.vbars values, style: :green, normalize: true, bar_width: 2
+  ui.vbars values, style: :green, normalize: true
   ui.puts <<~INFO, eol: false
     These are the same values but [i]normalized[/i]
     and printed with a fixed bar width.
   INFO
+
+  ui.space
 end

data/lib/natty-ui/dumb_progress.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative 'element'
+
+module NattyUI
+  # @private
+  class DumbProgress < Element
+    # @return [Numeric]
+    attr_reader :max
+
+    # @return [Numeric]
+    attr_reader :value
+
+    # @attribute [w] value
+    def value=(val)
+      return if @done != 0
+      return if @value == (val = @max ? val.clamp(0, @max) : [0, val].max)
+      @value = val
+      draw_bar if @max
+    end
+
+    def update(*title, value: nil, **)
+      return if @done != 0
+      draw_title(*title, **) unless title.empty?
+      if value
+        self.value = value
+      elsif @max
+        draw_bar
+      end
+      self
+    end
+
+    def step(*, count: 1, **) = update(*, value: value + count, **)
+
+    # @private
+    def puts(...) = @done == 0 ? super : self
+
+    private
+
+    def done
+      @done += 1
+    end
+
+    def draw_bar
+      diff = @value / @max.to_f
+      return if (fill = '█' * (20 * diff)).empty? || @last == fill
+      percent = diff == 1 ? '100.0%' : format('%.2f%%', 100 * diff)
+      percent = "0#{percent}" if percent.size < 6
+      @parent.puts(
+        "#{percent}▕#{@last = fill}#{'░' * (20 - fill.size)}▏",
+        prefix: @prefix
+      )
+    end
+
+    def draw_title(*, **options)
+      options[:cprefix] = Utils.mark[:active]
+      options[:prefix] = @prefix = Utils.mark[:none]
+      @parent.puts(*, **options)
+    end
+
+    def initialize(parent, max, *title, **)
+      super(parent)
+      @value = 0
+      @max = [0, max].max if max
+      draw_title(*title, **) unless title.empty?
+    end
+  end
+end

data/lib/natty-ui/element.rb

@@ -3,37 +3,80 @@
 require_relative 'features'
 
 module NattyUI
-  # Base element class supporting all {Features}.
+  # Base class for all UI container elements.
   #
+  # Instances are never created directly; they are returned (or yielded) by the
+  # section-opening methods on {Features}: {#section}, {#frame},
+  # {#task}, {#progress}, {#margin}, {#temporary}, and their typed variants.
+  #
+  # Every `Element` includes {Features}, so all output and section methods are
+  # available on the element itself.
+  #
+  # @example Using an element returned without a block
+  #   frm = ui.frame 'Progress'
+  #   frm.puts 'Loading…'
+  #   frm.end   # closes the frame
+  #
+  # @example The element is also yielded inside a block
+  #   ui.section 'Summary' do |sec|
+  #     sec.ok 'Done'
+  #   end
   class Element
     include Features
 
-    # Close the element.
     #
-    # @return [Features] current element
+    # @!group Section elements
+    #
+
+    # Closes this element and returns the parent element.
+    #
+    # Calling `end` on an already-closed element is a no-op.  All output
+    # methods on this element become no-ops after `end` is called.
+    #
+    # @example
+    #   frm = ui.frame 'Results'
+    #   ui.puts 'Content'
+    #   frm.end   # closes the frame, returns NattyUI (or the parent element)
+    #
+    # @return [Features] the parent element (or {NattyUI} if this was the
+    #   outermost element)
     def end = NattyUI.__send__(:_end, self)
 
+    #
+    # @!endgroup
+    #
+
     # @private
-    def columns = @parent.columns - @prefix_width - @suffix_width
+    def columns
+      ret = @parent.columns
+      ret -= @prefix.width if @prefix
+      @suffix ? ret - @suffix.width : ret
+    end
 
     # @private
-    def puts(*objects, **options)
+    def puts(*, **options)
       if @prefix
-        options[:prefix] = "#{@prefix}#{options[:prefix]}"
-        options[:prefix_width] = options[:prefix_width].to_i + @prefix_width
-        if (first_line = options[:first_line_prefix])
-          options[:first_line_prefix] = "#{@prefix}#{first_line}"
-          if (flw = options[:first_line_prefix_width])
-            options[:first_line_prefix_width] = flw + @prefix_width
-          end
+        pref = options[:prefix]
+        if (cpref = options[:cprefix]).nil? || cpref == true
+          options[:prefix] = pref ? @prefix + pref : @prefix
+        else
+          cpref = StrConst[cpref] unless StrConst === cpref
+          options[:cprefix] = @prefix + cpref
+          options[:prefix] = @prefix + (pref || StrConst.spacer(cpref.width))
         end
       end
       if @suffix
-        options[:suffix] = "#{options[:suffix]}#{@suffix}"
-        options[:suffix_width] = options[:suffix_width].to_i + @suffix_width
+        suff = options[:suffix]
+        if (csuff = options[:csuffix]).nil? || csuff == true
+          options[:suffix] = suff ? suff + @suffix : @suffix
+        else
+          csuff = StrConst[csuff] unless StrConst === csuff
+          options[:csuffix] = csuff + @suffix
+          options[:suffix] = (suff || StrConst.spacer(csuff.width)) + @suffix
+        end
       end
       # options[:max_width] = @max_width if @max_width
-      @parent.puts(*objects, **options)
+      @parent.puts(*, **options)
       self
     end
 
@@ -45,63 +88,11 @@ module NattyUI
 
     private
 
+    def done = raise(NotImplementedError)
+
     def initialize(parent)
       @parent = parent
-      @prefix_width = @suffix_width = 0
-    end
-  end
-
-  # Methods for elements with status like {ProgressHelper}, {Section}, {Task}.
-  #
-  module WithStatus
-    # @return [Symbol, nil] element's current status
-    attr_reader :status
-
-    # @attribute [r] active?
-    # @return [true, false] whether the element is still active
-    def active? = @status.nil?
-
-    # @attribute [r] closed?
-    # @return [true, false] whether the element is closed
-    def closed? = !active?
-
-    # @attribute [r] closed?
-    # @return [true, false] whether the element is completed
-    def ok? = @state == :ok
-
-    # @attribute [r] failed?
-    # @return [true, false] whether the element is completed with failure
-    def failed? = @state == :failed
-
-    # Close the element.
-    #
-    # @param [#to_s] text optional message
-    # @return [Features] current element
-    def ok(*text)
-      return self if @state
-      text = [@title] if text.empty? && @title
-      _done(text)
-      @state = :ok
-      self.end
-    end
-    alias done ok
-
-    # Close the element with a failure.
-    #
-    # @param text [#to_s] optional message
-    # @yield optionally, when block is given
-    # @yieldparam failed [Section] see {Features.failed}
-    # @return [Features] current element
-    def failed(*text, &block)
-      return self if @state
-      if text.empty?
-        super(@title, &block).ok if @title
-      else
-        super.ok
-      end
-      @state = :failed
-      _failed
-      self.end
+      @done = 0
     end
   end
 end