natty-ui 0.34.0 → 1.0.2

data/lib/natty-ui.rb

@@ -6,34 +6,46 @@ require_relative 'natty-ui/features'
 # This is the beautiful, nice, nifty, fancy, neat, pretty, cool, rich, lovely,
 # natty user interface you like to have for your command line applications.
 #
-# The {NattyUI} ​ᓚᕠᗢ main module implements all {Features}.
+# {NattyUI} ᓚᕠᗢ is the top-level module and default UI element of the gem. It
+# extends {Features}, so every output, section, and interaction method is
+# available directly on the module or through the {Kernel#ui} helper.
+#
+# @example Require and use via the Kernel helper
+#   require 'natty-ui'
+#   ui.puts 'Hello, [b]world[/b]!'
+#
+# @example Direct module access
+#   require 'natty-ui'
+#   NattyUI.puts 'Hello, [b]world[/b]!'
 #
 module NattyUI
-  # Uses the ANSI tools of the Terminal.rb gem
-  Ansi = Terminal::Ansi
-
-  # Uses the Text tools of the Terminal.rb gem
-  Text = Terminal::Text
-
   extend Features
 
   class << self
-    # Current used {Element} (or {NattyUI} as top element) supporting all
-    # {Features}.
+    # Active {Element} (or {NattyUI} as top element) supporting all {Features}.
+    #
+    # Returns the innermost currently open element.  When no element is active
+    # this returns {NattyUI} itself, which also implements all {Features}.
+    #
+    # @example
+    #   ui.section do
+    #     NattyUI.element   # => the Section instance
+    #   end
+    #   NattyUI.element     # => NattyUI (no element open)
     #
     # @return [Features]
-    #   current element or itself
+    #   current active {Element}, or {NattyUI} itself when no element is open
     attr_reader :element
 
-    # Supported input mode.
+    # Supported input mode of the current terminal.
     #
     # @attribute [r] input_mode
     # @return [:default]
-    #   when terminal uses ANSI
+    #   when the terminal supports ANSI and interactive keyboard input
     # @return [:dumb]
-    #   when terminal does not support ANSI or interactive input
+    #   when the terminal does not support ANSI or interactive input
     # @return [nil]
-    #   when terminal input is not supported
+    #   when standard input is not available
     def input_mode
       case Terminal.input_mode
       when :csi_u, :legacy
@@ -43,16 +55,34 @@ module NattyUI
       end
     end
 
-    # Terminal title.
+    # Current terminal title.
+    #
+    # Returns the title most recently set via `title=`, or `nil` when no
+    # title has been set yet.  Titles are kept in an internal stack; assigning
+    # `nil` to `title=` pops the current entry and restores the previous one.
+    #
+    # @example
+    #   NattyUI.title = 'My App'
+    #   NattyUI.title = 'My App — Processing…'
+    #   do_work
+    #   NattyUI.title = nil   # => restore last title
+    #   NattyUI.title         # => "My App"
     #
     # @attribute [r] title
-    # @return [String]
-    #   configured title
-    # @return [nil]
-    #   when no title was set
+    # @return [String] currently active title
+    # @return [nil] when no title has been set
     def title = @title_stack[-1]
 
+    # Sets or clears the terminal title.
+    #
+    # Pushes the given title onto an internal stack and writes an ANSI title
+    # escape to the terminal (when ANSI is supported).  Passing `nil` pops the
+    # current title and restores the previous one.
+    #
+    #
     # @attribute [w] title
+    # @param value [#to_s, nil]
+    #   new title string, or `nil` to remove the current title
     def title=(value)
       if value
         title = Ansi.plain(value).gsub(/\s+/, ' ')
@@ -85,19 +115,33 @@ module NattyUI
       @lines_written = number
     end
 
+    # @private
+    def end = self
+
     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 { it.__send__(:done) }
+      @stack = @stack.take(idx)
+      Terminal.show_cursor if (@element = @stack[-1]) == self
+      @element
     end
   end
 
-  @element = self
+  # @private
+  Ansi = Terminal::Ansi
+
+  Text = Terminal::Text
+  private_constant(:Text)
+
+  @stack = [@element = self]
   @lines_written = 0
   @title_stack = []
 
@@ -105,12 +149,25 @@ module NattyUI
 end
 
 unless defined?(Kernel.ui)
+  # Extensions to the standard `Kernel` module added by NattyUI.
   module Kernel
-    # @attribute [r] ui
-    # @return [NattyUI::Features] current used UI element
-    # @see NattyUI.element
+    # Returns the currently active {NattyUI} element.
+    #
+    # Convenience shorthand for {NattyUI.element}.  All {NattyUI::Features}
+    # methods are available on the returned value.
+    #
+    # @example
+    #   ui.puts 'Hello!'
+    #
+    # @example Inside a section block
+    #   ui.section 'Results' do
+    #     ui.ok 'All tests passed'
+    #   end
+    #
+    # @return [NattyUI::Features]
+    #   active UI element ({NattyUI::Element} or {NattyUI} itself)
     def ui = NattyUI.element
 
-    # alias ​ᓚᕠᗢ ui
+    # alias ᓚᕠᗢ ui
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: natty-ui
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.17.0
+        version: 1.0.5
 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
@@ -38,57 +38,60 @@ files:
 - examples/3bit-colors.rb
 - examples/8bit-colors.rb
 - examples/attributes.rb
-- examples/cols.rb
 - examples/elements.rb
 - examples/examples.rb
+- examples/frames.rb
 - examples/hbars.rb
-- examples/illustration.rb
 - examples/info.rb
 - examples/key-codes.rb
 - examples/ls.rb
 - examples/named-colors.rb
-- examples/options.rb
 - examples/sections.rb
+- examples/select.rb
 - examples/sh.rb
 - examples/tables.rb
 - examples/tasks.rb
-- examples/themes.rb
 - examples/vbars.rb
 - lib/natty-ui.rb
-- lib/natty-ui/attributes.rb
-- lib/natty-ui/choice.rb
-- lib/natty-ui/dumb_choice.rb
-- lib/natty-ui/dumb_options.rb
+- lib/natty-ui/dumb_progress.rb
 - lib/natty-ui/element.rb
 - lib/natty-ui/features.rb
-- lib/natty-ui/framed.rb
-- lib/natty-ui/hbars_renderer.rb
-- lib/natty-ui/ls_renderer.rb
-- lib/natty-ui/options.rb
+- lib/natty-ui/frame.rb
+- lib/natty-ui/helper/table.rb
+- lib/natty-ui/margin.rb
 - lib/natty-ui/progress.rb
+- lib/natty-ui/renderer/bars.rb
+- lib/natty-ui/renderer/choice.rb
+- lib/natty-ui/renderer/dumb_choice.rb
+- lib/natty-ui/renderer/dumb_select.rb
+- lib/natty-ui/renderer/dumb_shell_runner.rb
+- lib/natty-ui/renderer/heading.rb
+- lib/natty-ui/renderer/horizontal_rule.rb
+- lib/natty-ui/renderer/ls.rb
+- lib/natty-ui/renderer/mark.rb
+- lib/natty-ui/renderer/quote.rb
+- lib/natty-ui/renderer/select.rb
+- lib/natty-ui/renderer/shell.rb
+- lib/natty-ui/renderer/shell_runner.rb
+- lib/natty-ui/renderer/table_renderer.rb
 - lib/natty-ui/section.rb
-- lib/natty-ui/shell_renderer.rb
-- lib/natty-ui/table.rb
-- lib/natty-ui/table_renderer.rb
 - lib/natty-ui/task.rb
 - lib/natty-ui/temporary.rb
-- lib/natty-ui/theme.rb
-- lib/natty-ui/utils.rb
-- lib/natty-ui/vbars_renderer.rb
+- lib/natty-ui/utils/border.rb
+- lib/natty-ui/utils/str_const.rb
+- lib/natty-ui/utils/utils.rb
 - lib/natty-ui/version.rb
-- lib/natty-ui/width_finder.rb
 - lib/natty_ui.rb
-- natty-ui.gemspec
 homepage: https://codeberg.org/mblumtritt/natty-ui
 licenses:
 - MIT
 - Ruby
 metadata:
-  source_code_uri: https://codeberg.org/mblumtritt/natty-ui
-  bug_tracker_uri: https://codeberg.org/mblumtritt/natty-ui/issues
-  documentation_uri: https://rubydoc.info/gems/natty-ui
   rubygems_mfa_required: 'true'
   yard.run: yard
+  source_code_uri: https://codeberg.org/mblumtritt/natty-ui
+  bug_tracker_uri: https://codeberg.org/mblumtritt/natty-ui/issues
+  documentation_uri: https://rubydoc.info/gems/natty-ui1.0.2
 rdoc_options: []
 require_paths:
 - lib
@@ -96,14 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.13
 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.

data/examples/cols.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/natty-ui'
-
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Print Columns[/]' do
-  ui.space
-  ui.cols(
-    'Here we',
-    'have some',
-    'columns',
-    'which are',
-    'arranged',
-    'and centered',
-    align: :centered,
-    border: :default
-  )
-
-  ui.space
-  ui.cols do |cc|
-    cc.add(<<~TEXT, style: 'bright_white on_blue', align: :left)
-      This is a left aligned blue column with some text but also with
-      a forced line break.
-    TEXT
-    cc.add(
-      'This is the middle red column.',
-      style: 'bright_white on_red',
-      align: :centered,
-      vertical: :middle
-    )
-    cc.add(
-      'This is a right aligned blue column vertically bottom aligned.',
-      style: 'bright_white on_blue',
-      align: :right,
-      vertical: :bottom
-    )
-    cc.padding = [1, 2]
-  end
-end

data/examples/illustration.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/natty-ui'
-
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b]' do
-  ui.space
-  ui.table(border: :defaulth, border_style: 'bright_blue') do |table|
-    table.add do |row|
-      row.add 'Styles'
-      row.add <<~TEXT, eol: false
-        Support of all ANSI styles like
-        [b]bold[/b],
-        [i]italic[/i],
-        [u]underline[/u],
-        [inv]invert[/inv],
-        [s]strike[/s],
-        [faint]faint[/faint],
-        [double_underline]double underline[/double_underline],
-        [curly_underline]curly underline[/curly_underline],
-        [dotted_underline]dotted underline[/dotted_underline],
-        [dashed_underline]dashed underline[/dashed_underline]
-        and even rarely supported like [fraktur]fraktur[/fraktur].
-      TEXT
-    end
-
-    table.add do |row|
-      row.add 'Colors'
-      row.add <<~TEXT
-        ✓ [palegreen]3/4-bit color[/fg]  ✓ #{NattyUI::Ansi.rainbow('Truecolor')}       ✓ [tan1]NO_COLOR convention[/fg]
-        ✓ [skyblue]8-bit color[/fg]    ✓ [gold]Dumb terminals[/fg]
-      TEXT
-    end
-
-    table.add do |row|
-      row.add 'Markup'
-      row.add '[0c]You can style your text using a [i]BBCode[/i]-like syntax.'
-    end
-
-    table.add do |row|
-      row.add 'Layout'
-      row.add <<~TEXT
-        🎩 heading elements     📝 messages    📊 bar graphs
-        📏 horizontal rulers    [blue]┼┼[/] tables
-        📋 lists                [b green]✓✓[/] tasks
-      TEXT
-    end
-
-    table.add do |row|
-      row.add 'Asian', 'language', 'support'
-      row.add <<~TEXT
-        [bright_green]🇨🇳 该库支持中文，日文和韩文文本！
-        [bright_green]🇯🇵 ライブラリは中国語、日本語、韓国語のテキストをサポートしています
-        [bright_green]🇰🇷 이 라이브러리는 중국어, 일본어 및 한국어 텍스트를 지원합니다
-      TEXT
-    end
-
-    table.columns[0].assign(style: 'bold red', width: 8)
-    table.columns[1].padding_right = 2
-  end
-end

data/examples/options.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/natty-ui'
-
-ui.message '[b]​ᓚᕠᗢ NattyUI[/b] [i green]Options and Selections[/]' do
-  ui.space
-  ui.puts <<~INFO, eol: false
-    [i]Options[/i] and [i]selections[/i] allow the user to select from several
-    options interactively.
-    If ANSI is available the user can use [b][Up][/b] and [b][Down][/b] keys to
-    navigate, switch the state of selected item with [b][Space][/b] and complete
-    the selection with [b][Enter][/b].
-  INFO
-
-  ui.space
-  options =
-    ui.select %w[Kitty iTerm2 Ghostty Tabby Rio] do
-      ui.puts '[i]Which terminal applications did you already tested?[/i]'
-    end
-  case options.size
-  when 0
-    ui.puts 'You selected nothing – test more in future!'
-  when 1
-    ui.puts "#{options.first} is indeed a nice terminal."
-  else
-    ui.puts "#{options.join(', ')} are worth to test!"
-  end
-end

data/examples/themes.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../lib/natty-ui'
-
-NAMES = NattyUI::Theme.names.freeze
-DESCR = NAMES.map { NattyUI::Theme.description(_1) }.freeze
-ORG = NattyUI::Theme.current_name
-
-def show(name)
-  NattyUI::Theme.use(name)
-  theme = NattyUI::Theme.current
-  ui.message(
-    "[b]​ᓚᕠᗢ NattyUI [/b] [i green]Theme #{NattyUI::Theme.description(name)}[/]"
-  ) do
-    ui.ls(
-      (1..6).map do |i|
-        left, right = theme.heading(i)
-        "#{left} H#{i} #{right}"
-      end
-    )
-    ui.space
-    ui.ls(theme.defined_marks.map { "#{theme.mark(_1)} #{_1}" })
-    ui.space
-    ui.ls(
-      %i[
-        task_style
-        choice_style
-        choice_current_style
-        sh_out_style
-        sh_err_style
-      ].map { "#{theme.send(_1)}█ #{_1} [/]" }
-    )
-    ui.space
-    %i[section message information warning error].each do |name|
-      ui.send(name, name.capitalize)
-    end
-  end
-end
-
-while true
-  selected =
-    ui.choice(*DESCR, abortable: true, selected: selected) do
-      ui.puts '[bright_green b]Select a theme:[/] [faint](Abort with [\\ESC])'
-    end
-  break unless selected
-  ui.temporary do
-    show(NAMES[selected])
-    ui.await { ui.puts '[faint][\\Press ENTER to continue...]' }
-  end
-  NattyUI::Theme.use(ORG)
-end