terminal_rb 0.20.0 → 1.0.4

data/lib/terminal.rb

@@ -4,105 +4,109 @@ require_relative 'terminal/output'
 require_relative 'terminal/input'
 require_relative 'terminal/ansi'
 
+# Terminal I/O with ANSI support, BBCode markup, Unicode display width,
+# keyboard/mouse events, and text formatting.
 #
-# Terminal access with support for ANSI control codes and
-# [BBCode-like](https://en.wikipedia.org/wiki/BBCode) embedded text attribute
-# syntax (see {Ansi.bbcode}).
-# It automagically detects whether your terminal supports ANSI features, like
-# coloring (see {colors}) or the
-# [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol) support
-# (see {read_key_event}, {on_key_event} and {input_mode}).
-# It calculates the display width for Unicode chars (see {Text.width}) and help
-# you to display text with word-wise line breaks (see {Text.each_line}).
+# The appropriate output and input modes are selected automatically at
+# load time based on terminal capabilities. Use the class-level methods
+# for all interaction.
+#
+# @example Formatted output with BBCode
+#   Terminal.puts '[bold green]Success![/]'
+#
+# @example Read a key event
+#   event = Terminal.read_key_event
+#   puts "You pressed: #{event.name}"
+#
+# @example Execute a shell command
+#   status, out, err = Terminal.sh('ls', '-la')
 #
 module Terminal
   class << self
+    #
     # @!group Attributes
+    #
 
-    # Terminal application identifier.
+    # Detect the terminal emulator application.
     #
-    # The detection supports a wide range of terminal emulators but may return
-    # `nil` if an unsupported terminal was found. These are the supported
-    # application IDs:
-    # `:alacritty`, `:amiga`, `:code_edit`, `:dg_unix`, `:docker`, `:fluent`,
-    # `:hpterm`, `:hyper`, `:iterm`, `:macos`, `:mintty`, `:ms_terminal`,
-    # `:ncr260`, `:nsterm`, `:terminator`, `:terminology`, `:termite`,
-    # `:vt100`, `:warp`, `:wezterm`, `:wyse`, `:xnuppc`
+    # Known applications:
+    # +:alacritty+,
+    # +:amiga+,
+    # +:code_edit+,
+    # +:dg_unix+,
+    # +:docker+,
+    # +:fluent+,
+    # +:hpterm+,
+    # +:hyper+,
+    # +:iterm+,
+    # +:kitty+,
+    # +:macos+,
+    # +:mintty+,
+    # +:ms_terminal+,
+    # +:ncr260+,
+    # +:nsterm+,
+    # +:terminator+,
+    # +:terminology+,
+    # +:termite+,
+    # +:vscode+,
+    # +:vt100+,
+    # +:warp+,
+    # +:wyse+,
+    # +:xnuppc+
+    #
+    # Any unrecognized +TERM_PROGRAM+ value is converted to a sanitized
+    # symbol. Returns +nil+ when no terminal can be identified.
+    #
+    # @example
+    #   Terminal.application # => :kitty
     #
     # @attribute [r] application
-    # @return [Symbol, nil] the application identifier
+    # @return [Symbol, nil] the detected application
     def application = (@application ||= Detect.application)
 
-    # @!endgroup
-
-    # @!group Tool methods
-
-    # Execute a command and report command output line by line
-    # or capture the output.
     #
-    # @example Execute a command wih arguments
-    #   ret, out, = Terminal.sh('curl', '--version')
-    #   raise('command not found - curl') unless ret
-    #   puts out
+    # @!endgroup
     #
-    # @example Execute shell commands and print error
-    #   ret, _, err = Terminal.sh("mkdir '/test' && cd '/test'")
-    #   raise('unable to execute') unless ret
-    #   puts("error #{ret.exitstatus}: #{err.join}") unless ret.success?
+    # @!group Tool methods
     #
-    # @example Copy a file content to clipboard
-    #   command = ENV.fetch('CLIP_COPY', 'pbcopy')
-    #   File.open(__FILE__) do |file|
-    #     ret, = Terminal.sh(*command, input: file)
-    #     raise("command not found - #{command}") unless ret
-    #   end
+
+    # Execute a shell command.
     #
     # @overload sh(*cmd, **options)
-    #   @return [[Process::Status, output, error]]
-    #     the status of the process successfully executed,
-    #     the captured output,
-    #     the captured error output,
-    #   @return [nil]
-    #     when the command was not executable
+    #   Run a command and capture output.
+    #   @param cmd [Array<String>] command and arguments
+    #   @param options [Hash] options passed to the shell runner
+    #   @return [Array<Process::Status, Array<String>, Array<String>>]
+    #     +[status, stdout_lines, stderr_lines]+
+    #   @example
+    #     status, output, error = Terminal.sh('echo', 'hello')
+    #     output # => ["hello\n"]
     #
-    # @overload sh(*cmd, **options)
-    #   @yieldparam line [String]
-    #     next received line from the process
-    #   @yieldparam type [:output, :error]
-    #     whether the received line is standard output or error
-    #   @return [Process::Status]
-    #     the status of the process successfully executed
-    #   @return [nil]
-    #     when the command was not executable
+    # @overload sh(*cmd, **options, &block)
+    #   Run a command and stream output to a block.
+    #   @param cmd [Array<String>] command and arguments
+    #   @param options [Hash] options passed to the shell runner
+    #   @yield [line, type] called for each output line
+    #   @yieldparam line [String] the output line
+    #   @yieldparam type [Symbol] +:output+ or +:error+
+    #   @return [Process::Status] the exit status
+    #   @example
+    #     Terminal.sh('make') do |line, type|
+    #       Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
+    #     end
     #
-    # @param cmd [Array<#to_s>]
-    #   command line or command with arguments
-    # @param options [Hash]
-    #   options how to execute the new process;
-    #   see `Process.spawn` for default execution options provided by Ruby
-    # @option options [Hash<String,String>] :env
-    #   key/value pairs added to the ENV of the process;
-    #   with option `:unsetenv_others` set to `true` it replaces the ENV
-    # @option options [true, false] :shell
-    #   whether to create a seperate shell or not
-    # @option options [#readpartial, #to_io, Array, #each, #to_a, #to_s] :input
-    #   piped to the command as input
-    # @raise [ArgumentError] when command is missing
-    def sh(*cmd, **options, &block)
+    # @raise [ArgumentError] if no command is given
+    def sh(*cmd, **, &)
       raise(ArgumentError, 'command expected') if cmd.empty?
-      return Shell.exec(cmd, **options, &block) if block_given?
+      return Shell.run(*cmd, **, &) if block_given?
       out = []
       err = []
-      [
-        Shell.exec(cmd, **options) do |line, type|
-          (type == :error ? err : out) << line
-        end,
-        out,
-        err
-      ]
+      [Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }, out, err]
     end
 
+    #
     # @!endgroup
+    #
   end
 
   dir = "#{__dir__}/terminal"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 1.0.4
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -29,10 +29,12 @@ files:
 - examples/bbcode.rb
 - examples/info.rb
 - examples/key-codes.rb
+- examples/screen_viewer.rb
 - examples/text.rb
 - lib/terminal.rb
 - lib/terminal/ansi.rb
 - lib/terminal/ansi/named_colors.rb
+- lib/terminal/ansi/screen_viewer.rb
 - lib/terminal/detect.rb
 - lib/terminal/input.rb
 - lib/terminal/input/ansi.rb
@@ -45,19 +47,19 @@ files:
 - lib/terminal/shell.rb
 - lib/terminal/text.rb
 - lib/terminal/text/char_width.rb
+- lib/terminal/text/formatter.rb
 - lib/terminal/version.rb
 - lib/terminal_rb.rb
-- terminal_rb.gemspec
 homepage: https://codeberg.org/mblumtritt/Terminal.rb
 licenses:
 - MIT
 - Ruby
 metadata:
-  source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
-  bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
-  documentation_uri: https://rubydoc.info/gems/terminal_rb/0.20.0
   rubygems_mfa_required: 'true'
   yard.run: yard
+  source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
+  bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.4
 rdoc_options: []
 require_paths:
 - lib
@@ -65,14 +67,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: 4.0.5
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise line
   break support and much more.

data/terminal_rb.gemspec

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/terminal/version'
-
-Gem::Specification.new do |spec|
-  spec.name = 'terminal_rb'
-  spec.version = Terminal::VERSION
-  spec.summary = <<~SUMMARY.tr("\n", ' ')
-    Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise
-    line break support and much more.
-  SUMMARY
-  spec.description = <<~DESCRIPTION.tr("\n", ' ')
-    Terminal.rb supports you with input and output on your terminal.
-    Simple BBCode-like markup for attributes and coloring, word-wise line
-    breaks, correct special key recognition and mouse event reporting enable
-    you to implement your CLI app quickly and easily.
-  DESCRIPTION
-
-  spec.author = 'Mike Blumtritt'
-  spec.licenses = %w[MIT Ruby]
-  spec.homepage = 'https://codeberg.org/mblumtritt/Terminal.rb'
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
-  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/terminal_rb/#{
-    Terminal::VERSION
-  }"
-  spec.metadata['rubygems_mfa_required'] = 'true'
-  spec.metadata['yard.run'] = 'yard'
-
-  spec.required_ruby_version = '> 3.0'
-
-  spec.files = Dir['lib/**/*.rb'] + Dir['examples/*.rb']
-  spec.files << 'terminal_rb.gemspec' << '.yardopts'
-  spec.executables = %w[bbcode]
-  spec.extra_rdoc_files = %w[README.md]
-end