natty-ui 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c61c16b1c5d1611a98f1505bb9eb86b71a0289021a9332f41e2095f7810b144
-  data.tar.gz: e8acc6fdf67bd259fd671defd80533f5de0fa9aa7b005cef9f092b7ebf097606
+  metadata.gz: f193a0c86adab949f0d0c40d522e879d47f0a75a6a52ae9cf4f9ff39a7582e0e
+  data.tar.gz: 2841fcf9135c48ef2df17ffcea4f5ff7619fe51dc62a489e58a9b7fc21f2bc1d
 SHA512:
-  metadata.gz: a38c19bc286fff4f5776fde2bb1a1de897ea3cdc8498c774691c449de6c2614b229f50a84d6eaf3a89c90af8a99500f6fc8e9237fea9dea7c8234370d4629399
-  data.tar.gz: 9d74ccf3a7202619718e8dd67e19cf53534996738c2e04522e3ba6b67aac51323167e7989577c9ace0c793e729130e984eeffb2eae9d98b8458e5f401249b7cc
+  metadata.gz: 8d956fcf0d7cf2809bda3db9e82e84a02fe260e7646c54f1ba195dc04e3e8842677d6bb2c6e3dc95712c2da59580d6753e5218cccd2779408d10c1174cf96d12
+  data.tar.gz: 99c7fa8acd5d4f6c12db79b95e02da4a269ade5439a8d6918ca8b47a07ac2dce24cb2f91a146f23fe3b9d4554588b2e6f9b02be476cf725d9e058985f7ed763a

data/.yardopts

@@ -9,4 +9,3 @@
 lib/**/*.rb
 -
 README.md
-LICENSE

data/README.md

@@ -4,7 +4,7 @@ This is the beautiful, nice, nifty, fancy, neat, pretty, cool, rich, lovely, nat
 
 - Gem: [rubygems.org](https://rubygems.org/gems/natty-ui)
 - Source: [codeberg.org](https://codeberg.org/mblumtritt/natty-ui)
-- Help: [rubydoc.info](https://rubydoc.info/gems/natty-ui/index)
+- Help: [rubydoc.info](https://rubydoc.info/gems/natty-ui/NattyUI)
 
 ## Features
 

data/examples/8bit-colors.rb

@@ -10,12 +10,14 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]8bit Color Support[/]' do
     [#ff]#{0.upto(7).map(&color).join}
     [#00]#{8.upto(15).map(&color).join}
   COLORS
+  ui.end
 
   ui.space
   ui.message 'Grayscale', <<~GRAYSCALE.chomp
     [#ff]#{0xe8.upto(0xf3).map(&color).join}
     [#ff]#{0xf4.upto(0xff).map(&color).join}
   GRAYSCALE
+  ui.end
 
   ui.space
   ui.message '6x6x6 Color Cube' do

data/examples/sections.rb

@@ -10,17 +10,25 @@ ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Sections[/]' do
       means they may contain text, other sections, titles, horizontal rules,
       lists, progress bars and much more!
     TEXT
-  end
 
-  ui.space
-  ui.warning "Warning\nThis is a warning message example."
-
-  ui.space
-  ui.error 'Error Message' do
     ui.space
     ui.cols do |cc|
       cc.add "()-()\n \\\"/\n  `", width: 6, style: :yellow
       cc.add 'You can add all other elements to a section.', vertical: :middle
     end
+
+    ui.framed(<<~TEXT, align: :centered, eol: false).end
+      Sections and messages can be called with code blocks and will be
+      automatically closed when the block ends. Without a code block the
+      section or message needs to be closed.
+    TEXT
   end
+
+  ui.warning "Warning\nThis is a warning message example."
+  ui.end
+
+  ui.error('Error Message', <<~MSG, align: :right, prefix: '[b red]>[/] ').end
+    Error message text with
+    print options.
+  MSG
 end

data/lib/natty-ui/element.rb

@@ -8,6 +8,11 @@ module NattyUI
   class Element
     include Features
 
+    # Close the element.
+    #
+    # @return [Features] current element
+    def end = NattyUI.__send__(:_end, self)
+
     # @private
     def columns = @parent.columns - @prefix_width - @suffix_width
 
@@ -71,13 +76,13 @@ module NattyUI
     # Close the element.
     #
     # @param [#to_s] text optional message
-    # @return [Element] itself
+    # @return [Features] current element
     def ok(*text)
       return self if @state
       text = [@title] if text.empty? && @title
       _done(text)
       @state = :ok
-      self
+      self.end
     end
     alias done ok
 
@@ -86,14 +91,17 @@ module NattyUI
     # @param text [#to_s] optional message
     # @yield optionally, when block is given
     # @yieldparam failed [Section] see {Features.failed}
-    # @return [Element] itself
+    # @return [Features] current element
     def failed(*text, &block)
       return self if @state
-      _failed
+      if text.empty?
+        super(@title, &block).ok if @title
+      else
+        super.ok
+      end
       @state = :failed
-      text = [@title] if text.empty? && @title
-      @parent.failed(*text, &block)
-      self
+      _failed
+      self.end
     end
   end
 end

data/lib/natty-ui/features.rb

@@ -2,7 +2,8 @@
 
 module NattyUI
   # These are all supported features by {NattyUI} or any other sub- element
-  # like {section}, {message}, {task}, ...
+  # like {#section}, {#message}, {#information}, {#warning}, {#error},
+  # {#failed}, {#framed}, {#task}, ...
   #
   # Any printed text can contain *BBCode*-like embedded ANSI attributes which
   # will be used when the output terminal supports attributes and colors.
@@ -26,8 +27,8 @@ module NattyUI
     #
     # @see #pin
     #
-    # @param text [#to_s]
-    #   one or more convertible objects to print line by line
+    # @param text [*#to_s]
+    #   one or more objects to print line by line
     # @param options [{Symbol => Object}]
     # @option options [:left, :right, :centered] :align (:left)
     #   text alignment
@@ -570,13 +571,14 @@ module NattyUI
     #   @return [Object]
     #     the result of the given block
     def progress(title, max: nil, pin: false, &block)
-      progress =
+      __with(
         if Terminal.ansi?
           Progress.new(self, title, max, pin)
         else
           DumbProgress.new(self, title, max)
-        end
-      block ? __with(progress, &block) : progress
+        end,
+        &block
+      )
     end
 
     # Execute a program.
@@ -649,101 +651,163 @@ module NattyUI
     #
 
     # Create a visually separated section for the output of text elements.
+    # Besides this simple sections there exist sections of different kinds:
+    # {#message}, {#information}, {#warning}, {#error}, {#failed}, {#framed}
+    #
     # Like any other {Element} sections support all {Features}.
     #
-    # @example
-    #   ui.section do |section|
+    # @overload section#
+    #   @example
+    #     ui.section do |section|
+    #       section.h1 'About Sections'
+    #       section.space
+    #       section.puts 'Sections are areas of text elements.'
+    #       section.puts 'You can use any other feature inside such an area.'
+    #     end
+    #     # => ╭────╶╶╶
+    #     # => │ ╴╶╴╶─═══ About Sections ═══─╴╶╴╶
+    #     # => │
+    #     # => │ Sections are areas of text elements.
+    #     # => │ You can use any other feature inside such an area.
+    #     # => ╰──── ─╶╶╶
+    #
+    #   @yieldparam section [Section]
+    #     itself
+    #   @return [Object]
+    #     the result of the given block
+    #
+    # @overload section(*text, **options)
+    #
+    #   @example
+    #     section = ui.section
     #     section.h1 'About Sections'
     #     section.space
     #     section.puts 'Sections are areas of text elements.'
-    #     section.puts 'You can use any other feature inside such an area.'
-    #   end
-    #   # => ╭────╶╶╶
-    #   # => │ ╴╶╴╶─═══ About Sections ═══─╴╶╴╶
-    #   # => │
-    #   # => │ Sections are areas of text elements.
-    #   # => │ You can use any other feature inside such an area.
-    #   # => ╰──── ─╶╶╶
-    #
-    # @param text [#to_s]
-    #   convertible objects to print line by line
-    #
-    # @yieldparam section [Section]
-    #   itself
+    #     section.end # close the section
     #
-    # @return [Object]
-    #   the result of the given block
-    def section(*text, &block) = __sec(:default, nil, text, &block)
-
-    # @!macro like_msg
-    #   @see section
-    #   @param title [#to_s]
-    #     title to print as section head
-    #   @param text (see section)
-    #   @yieldparam (see section)
-    #   @return (see section)
-
-    # Create a visually separated section with a title for the output of text
+    #   @param text [*#to_s]
+    #     optional objects to print line by line
+    #   @param options [{Symbol => Object}]
+    #     print options – see {puts}
+    #   @return [Section]
+    #     itself
+    def section(*text, **options, &block)
+      __sec(:default, false, nil, text, options, &block)
+    end
+    alias begin section
+
+    # @!macro msg_like
+    #
+    #   Like any other {Element} sections support all {Features}.
+    #
+    #   @overload $0(title)
+    #     @param title [#to_s]
+    #       section title
+    #     @yieldparam message [Section]
+    #       itself
+    #     @return [Object]
+    #       the result of the given block
+    #   @overload $0(title, *text, **options)
+    #     @param title [#to_s]
+    #       section title
+    #     @param text [*#to_s]
+    #       optional objects to print line by line
+    #     @param options [{Symbol => Object}]
+    #       print options – see {puts}
+    #     @return [Section]
+    #       itself
+
+    # Create a visually separated section with title for the output of text
     # elements.
-    #
-    # @macro like_msg
-    def message(title, *text, &block) = __sec(:message, title, text, &block)
+    # @macro msg_like
+    def message(title, *text, **options, &block)
+      __sec(:message, false, title, text, options, &block)
+    end
     alias msg message
 
-    # Create a visually separated section marked as informational with a title
-    # for the output of text elements.
+    # Create a visually separated section marked as informational with title for
+    # the output of text elements.
     #
-    # @macro like_msg
-    def information(title, *text, &block)
-      __tsec(:information, title, text, &block)
+    # @macro msg_like
+    def information(title, *text, **options, &block)
+      __sec(:information, true, title, text, options, &block)
     end
     alias info information
 
-    # Create a visually separated section marked as a warning with a title for
+    # Create a visually separated section marked as warning with title for
     # the output of text elements.
     #
-    # @macro like_msg
-    def warning(title, *text, &block) = __tsec(:warning, title, text, &block)
+    # @macro msg_like
+    def warning(title, *text, **options, &block)
+      __sec(:warning, true, title, text, options, &block)
+    end
     alias warn warning
 
-    # Create a visually separated section marked as an error with a title for
+    # Create a visually separated section marked as error with title for
     # the output of text elements.
     #
-    # @macro like_msg
-    def error(title, *text, &block) = __tsec(:error, title, text, &block)
+    # @macro msg_like
+    def error(title, *text, **options, &block)
+      __sec(:error, true, title, text, options, &block)
+    end
     alias err error
 
-    # Create a visually separated section marked as a failure with a title for
+    # Create a visually separated section marked as failure with title for
     # the output of text elements.
     #
-    # @macro like_msg
-    def failed(title, *text, &block) = __tsec(:failed, title, text, &block)
+    # @macro msg_like
+    def failed(title, *text, **options, &block)
+      __sec(:failed, true, title, text, options, &block)
+    end
 
     # Create a framed section.
+    # Like any other {Element} sections support all {Features}.
     #
-    # @param text (see section)
-    # @param align [:left, :right, :centered]
-    #   text alignment,
-    #   see {Attributes::Align}
-    # @param border [Symbol]
-    #   kind of border,
-    #   see {Attributes::Border}
-    # @param border_style [Enumerable<Symbol>]
-    #   style of border,
-    #   see {Attributes::BorderStyle}
-    #
-    # @yieldparam frame [Framed] itself
-    #
-    # @return (see section)
-    def framed(*text, align: :left, border: :default, border_style: nil, &block)
+    # @overload framed(align: :left, border: :default, border_style: nil)
+    #   @param align [:left, :right, :centered]
+    #     text alignment,
+    #     see {Attributes::Align}
+    #   @param border [Symbol]
+    #     kind of border,
+    #     see {Attributes::Border}
+    #   @param border_style [Enumerable<Symbol>]
+    #    style of border,
+    #    see {Attributes::BorderStyle}
+    #   @yieldparam framed [Element]
+    #     itself
+    #   @return [Object] the result of the given block
+    # @overload framed(*text, align: :left, border: :default, border_style: nil, **options)
+    #   @param text [*#to_s]
+    #     optional objects to print line by line
+    #   @param align [:left, :right, :centered]
+    #     text alignment,
+    #     see {Attributes::Align}
+    #   @param border [Symbol]
+    #     kind of border,
+    #     see {Attributes::Border}
+    #   @param border_style [Enumerable<Symbol>]
+    #     style of border,
+    #     see {Attributes::BorderStyle}
+    #   @param options [{Symbol => Object}]
+    #     print options – see {puts}
+    #   @return [Element] itself
+    def framed(
+      *text,
+      align: :left,
+      border: :default,
+      border_style: nil,
+      **options,
+      &block
+    )
       __with(
         Framed.new(
           self,
           Utils.align(align),
           Theme.current.border(border),
-          Utils.style(border_style),
-          text
+          Utils.style(border_style)
         ),
+        *text,
+        **options,
         &block
       )
     end
@@ -752,14 +816,17 @@ module NattyUI
     #
     # @param title [#to_s]
     #   task title text
-    # @param text (see section)
+    # @param text [*#to_s]
+    #   optional objects to print line by line
     # @param pin [true, false] whether to keep text "pinned"
+    # @param options [{Symbol => Object}]
+    #   print options – see {puts}
     #
     # @yieldparam task [Task] itself
     #
-    # @return (see section)
-    def task(title, *text, pin: false, &block)
-      __with(Task.new(self, title, text, pin), &block)
+    # @return [Task] itself
+    def task(title, *text, pin: false, **options, &block)
+      __with(Task.new(self, title, pin), *text, **options, &block)
     end
 
     #
@@ -972,9 +1039,18 @@ module NattyUI
     # Display some temporary content.
     # The content displayed in the block will be erased after the block ends.
     #
-    # @example Show tempoary information
+    # @example
+    #   ui.temporary(<<~MSG) { ui.await }
+    #     This is a [i]temporary[/i] displayed text.
+    #     It will disappear when you press [b]ENTER[/b].
+    #   MSG
+    #
+    # @example
     #   ui.temporary do
-    #     ui.info 'Information', 'This text will disappear when you pressed ENTER.'
+    #     ui.information 'Hint' do
+    #       ui.puts 'This is a [i]temporary[/i] displayed text.'
+    #       ui.puts 'It will disappear when you press [b]ENTER[/b].'
+    #     end
     #     ui.await
     #   end
     #
@@ -982,7 +1058,9 @@ module NattyUI
     #   itself
     #
     # @return (see section)
-    def temporary(&block) = __with(Temporary.new(self), &block)
+    def temporary(*text, **options, &block)
+      __with(Temporary.new(self), *text, **options, &block)
+    end
 
     #
     # @!endgroup
@@ -990,14 +1068,15 @@ module NattyUI
 
     private
 
-    def __with(element, &block) = NattyUI.__send__(:with, element, &block)
+    def __with(...) = NattyUI.__send__(:_with, ...)
 
-    def __sec(color, title, text, &block)
-      __with(Section.new(self, title, text, color), &block)
-    end
-
-    def __tsec(color, title, text, &block)
-      __sec(color, "#{Theme.current.mark(color)}#{title}", text, &block)
+    def __sec(color, mark, title, text, options, &block)
+      if title && !title.empty?
+        title, *rest =
+          Text.each_line(title, limit: columns - 9, ansi: Terminal.ansi?).to_a
+        text.unshift(rest.join("\n")) unless rest.empty?
+      end
+      __with(Section.new(self, color, mark, title), *text, **options, &block)
     end
 
     def __await(yes, no)
@@ -1014,7 +1093,7 @@ module NattyUI
     end
   end
 
-  dir = __dir__ # call the function once
+  dir = __dir__
 
   autoload :Framed, "#{dir}/framed.rb"
   autoload :Section, "#{dir}/section.rb"

data/lib/natty-ui/framed.rb

@@ -29,7 +29,7 @@ module NattyUI
 
     private
 
-    def initialize(parent, align, chars, style, msg)
+    def initialize(parent, align, chars, style)
       super(parent)
       @align = align
       if style
@@ -45,7 +45,6 @@ module NattyUI
       line = chars[10] * (parent.columns - 2)
       parent.puts("#{style}#{chars[0]}#{line}#{chars[2]}")
       @bottom = "#{style}#{chars[6]}#{line}#{chars[8]}"
-      puts(*msg) unless msg.empty?
     end
   end
 end

data/lib/natty-ui/progress.rb

@@ -55,6 +55,9 @@ module NattyUI
       self
     end
 
+    # @private
+    def end = NattyUI.__send__(:_end, self)
+
     alias _to_s to_s
     private :_to_s
 

data/lib/natty-ui/section.rb

@@ -3,7 +3,7 @@
 require_relative 'element'
 
 module NattyUI
-  # Display section used by
+  # Display section instance used by
   #
   # - {Features.section}
   # - {Features.message}
@@ -11,6 +11,7 @@ module NattyUI
   # - {Features.warning}
   # - {Features.error}
   # - {Features.failed}
+  # - {Features.framed}
   #
   class Section < Element
     include WithStatus
@@ -42,25 +43,13 @@ module NattyUI
       )
     end
 
-    def initialize(parent, title, msg, kind)
+    def initialize(parent, kind, mark, title)
       super(parent)
-      title, rest = split(title) if title && !title.empty?
       @border = Theme.current.section_border(kind)
-      show_title(title)
+      mark &&= Theme.current.mark(kind)
+      show_title(mark ? "#{mark}#{title}" : title)
       @prefix = @border.prefix
       @prefix_width = @prefix.width
-      puts(*rest) if rest && !rest.empty?
-      puts(*msg) unless msg.empty?
-    end
-
-    def split(title)
-      rest =
-        Text.each_line(
-          title,
-          limit: @parent.columns - 9,
-          ansi: Terminal.ansi?
-        ).to_a
-      [rest.shift, rest]
     end
   end
 end

data/lib/natty-ui/task.rb

@@ -3,7 +3,7 @@
 require_relative 'element'
 
 module NattyUI
-  # Task display section used by {Features.task}.
+  # Task section used by {Features.task}.
   #
   class Task < Temporary
     include WithStatus
@@ -27,7 +27,7 @@ module NattyUI
       @start_line = nil
     end
 
-    def initialize(parent, title, msg, pin)
+    def initialize(parent, title, pin)
       super(parent)
       @title = title
       @pin = pin
@@ -42,7 +42,6 @@ module NattyUI
         prefix: "#{@prefix}#{style}",
         prefix_width: cm.width
       )
-      puts(*msg) unless msg.empty?
     end
   end
 end

data/lib/natty-ui/version.rb

@@ -2,5 +2,5 @@
 
 module NattyUI
   # The version number of the gem.
-  VERSION = '0.34.0'
+  VERSION = '0.35.0'
 end

data/lib/natty-ui.rb

@@ -87,17 +87,33 @@ module NattyUI
 
     private
 
-    def with(element)
+    def _begin(element)
       Terminal.hide_cursor if @element == self
-      current, @element = @element, element
-      yield(element) if block_given?
-    ensure
-      element.done if element.respond_to?(:done)
-      Terminal.show_cursor if (@element = current) == self
+      @stack << element
+      @element = element
+    end
+
+    def _end(element)
+      idx = @stack.index(element) or return @element
+      @stack.drop(idx).each { _1.done if _1.respond_to?(:done) }
+      @stack = @stack.take(idx)
+      Terminal.show_cursor if (@element = @stack[-1]) == self
+      @element
+    end
+
+    def _with(element, *text, **options, &block)
+      _begin(element)
+      element.puts(*text, **options) unless text.empty?
+      return element unless block
+      begin
+        yield(element)
+      ensure
+        _end(element)
+      end
     end
   end
 
-  @element = self
+  @stack = [@element = self]
   @lines_written = 0
   @title_stack = []
 

data/natty-ui.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.metadata['yard.run'] = 'yard'
 
   spec.required_ruby_version = '>= 3.0'
-  spec.add_dependency 'terminal_rb', '>= 0.17.0'
+  spec.add_dependency 'terminal_rb', '>= 0.17.2'
 
   spec.files = Dir['lib/**/*.rb'] + Dir['examples/*.rb']
   spec.files << 'natty-ui.gemspec' << '.yardopts'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: natty-ui
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.35.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 0.17.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 0.17.2
 description: 'This is the beautiful, nice, nifty, fancy, neat, pretty, cool, rich,
   lovely, natty user interface tool you like to have for your command line applications.
   It contains elegant, simple and beautiful features that enhance your command line
@@ -103,7 +103,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.1
 specification_version: 4
 summary: This is the beautiful, nice, nifty, fancy, neat, pretty, cool, rich, lovely,
   natty user interface you like to have for your CLI.