colsole 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a430d377ca6b98614b6d3127bf1f35f2dc259b2bb4378bdc61570519d5126130
-  data.tar.gz: c2e890a8104283b070323f9916db75bc9ec692d81e49630159b2127b0b8d83f9
+  metadata.gz: 2fd26345db2525e6804965d0686301be91d7c27d9fe3894550a781e73e1c2f72
+  data.tar.gz: f44de99c02442edeae3723d405be87fe29d845c130460ee16a23bf0aab254901
 SHA512:
-  metadata.gz: 4bc5fc5638d1cb43b0a88d487686fd7afc918626446220b2874a419443bf2d4ac2dd24ac3711fe9f13a62fea07d80d0e1cea4a15d2da398b7f18ceba819fb401
-  data.tar.gz: 3232586c10d02fdc7fd4ca3adc517cae833c62440eeec552bf2e50bc23d1d5192718212cbc7bd6dcda7647c404c55b11ac7427b7972911a8062c9e722a2a21c5
+  metadata.gz: ff6fb2074275bf9479ab0ba400bec991aa1d5972488c0c21c143ab012851733452aca15549278d770f8427c05ff5bcfad077f53c2649860ceb063934ebe0cba0
+  data.tar.gz: 8bd0e29dc5216b94ade0bec78636122bf015bbe502061655312cf52aaecd4c3462bac97310bf4e5f35d7ad0a51ad9fe5f4093d806b36968b4597f9df3789574a

data/README.md

@@ -1,5 +1,4 @@
-Colsole
-==================================================
+# Colsole
 
 [![Gem Version](https://badge.fury.io/rb/colsole.svg)](https://badge.fury.io/rb/colsole)
 [![Build Status](https://github.com/DannyBen/colsole/workflows/Test/badge.svg)](https://github.com/DannyBen/colsole/actions?query=workflow%3ATest)
@@ -9,32 +8,30 @@ Colsole
 
 Utility functions for colorful console applications.
 
----
+> **Upgrade Note**
+>
+> This README is for the latest version of colsole (0.8.x), which is compatible
+> with older versions. Version 1.x will NOT be compatible.
+>
+> See [Uprading](#upgrading) below.
 
+## Install
 
-Install
---------------------------------------------------
+Add to your Gemfile:
 
 ```
-$ gem install colsole
+$ gem 'colsole', '>= 0.6.0', '< 2.0'
 ```
 
-Features
---------------------------------------------------
-
-- Print colored messages 
-- Color parts of a message
-- Print neatly aligned status messages
-- Word wrap with indentation consideration
+## Examples
 
-See the [Examples file][1] for more.
+See the [Examples file](https://github.com/DannyBen/colsole/blob/master/example.rb).
 
-Primary Functions
---------------------------------------------------
+## Primary Functions
 
 ### `say "anything"`
 
-An alternative to puts.
+An alternative to puts with line wrapping, colors and more.
 
 ```ruby
 say "Hello"
@@ -47,30 +44,27 @@ say "appears in "
 say "one line"
 ```
 
-Embed color markers in the string:
+Embed [color markers](#colors) in the string:
 
 ```ruby
-say "!txtred!I am RED !txtgrn!I am GREEN"
+say "This is r`red`, and this gu`entire phrase is green underlined`"
 ```
 
-### `say_status :status, "message" [, :color]`
-
-Print a message with a colored status
+Provide the `replace: true` option after a space terminated "said" string to
+rewrite the line:
 
 ```ruby
-say_status :create, "perpetual energy"
+# space terminated string to say it without a newline
+say "downloading data... "
+# long process here...
+say "download complete.", replace: true
 ```
 
-You can provide a color in the regulat 6 letter code:
-
-```ruby
-say_status :error, "does not compute", :txtred
-```
 
 ### `word_wrap "   string" [, length]`
 
-Wrap long lines while keeping words intact, and keeping 
-indentation based on the leading spaces in your string:
+Wrap long lines while keeping words intact, and keeping indentation based on the
+leading spaces in your string:
 
 ```ruby
 say word_wrap("    one two three four five", 15)
@@ -84,37 +78,21 @@ say word_wrap("    one two three four five", 15)
 If `length` is not provided, `word_wrap` will attempt to determine it
 automatically based on the width of the terminal.
 
-
-### `resay "anything"`
-
-Use resay after a space terminated "said" string to rewrite the line
-
-```ruby
-say "downloading... "
-# long process here...
-resay "downloaded."
-```
-
-
 ### `say! "anything to stderr"`
 
 Use say! to output to stderr with color markers:
 
 ```ruby
-say! "!txtred!Error!txtrst!: This just did not work"
+# red inverted ERROR
+say! "ri` ERROR ` This just did not work"
 ```
 
-Utility / Support Functions
---------------------------------------------------
+## Utility / Support Functions
 
-### `colorize "!txtred!Hello"`
+### `colorize "string"`
 
 Parses and returns a color-flagged string.
 
-Respects pipe and auto terminates colored strings.
-	
-Call without text to see a list/demo of all available colors.
-
 ### `terminal?`
 
 Returns true if we are running in an interactive terminal
@@ -123,21 +101,76 @@ Returns true if we are running in an interactive terminal
 
 Checks if the provided string is a command in the path.
 
-### `detect_terminal_size fallback_value`
+### `terminal_size [fallback_cols, fallback_rows]`
 
 Returns an array `[width, height]` of the terminal, or the supplied 
-`fallback_value` if it is unable to detect.
+fallback if it is unable to detect.
+
+### `terminal_width` / `terminal_height`
+
+Returns only the terminal width or height. This is a shortcut to 
+`terminal_size[0]` / terminal_size[1].
 
-### `terminal_width`
 
-Returns only the terminal width. This is a shortcut to 
-`detect_terminal_size[0]`.
+## Colors
 
+Strings that are surrounded by backticks, and preceded by a color code and
+optional styling markers will be converted to the respective ANSI color.
+
+```ruby
+say "this is b`blue` and ru`this is red underlined`"
+```
 
-Color Codes
---------------------------------------------------
+The one letter color code is required, followed by up to 3 style code.
 
-[![Color Codes](https://raw.githubusercontent.com/DannyBen/colsole/master/color-codes.png)](https://raw.githubusercontent.com/DannyBen/colsole/master/color-codes.png)
+| Color Code | Color
+|------------|-------
+| `n`        | no color
+| `k`        | black
+| `r`        | red
+| `g`        | green
+| `y`        | yellow
+| `b`        | blue
+| `m`        | magenta
+| `c`        | cyan
+| `w`        | white
 
+| Style Code | Style
+|------------|-------
+| `b`        | bold
+| `u`        | underlined
+| `i`        | inverted
+| `z`        | terminate
 
-[1]: https://github.com/DannyBen/colsole/blob/master/example.rb
+## Upgrading
+
+Version 0.8.x changes several things, including the syntax of the color
+markers. For easy transition, it is compatible with older versions.
+
+Follow these steps to upgrade:
+
+```ruby
+
+# => Require a more flexible version
+# change this
+gem 'colsole'
+# to this (to avoid conflicts with other gems that require 0.x)
+gem 'colsole', '>= 0.6.0', '< 2.0'
+
+# => Remove 'say_status'
+# It will no longer be supported in 1.0.0
+say_status "text"
+
+# => Replace 'resay'
+# 'resay' is replaced with 'say replace: true'
+# change this
+resay "text"
+# to this
+say "text", replace: true
+
+# => Change color markers syntax
+# replace this
+say "the !txtblu!blue"
+# with this
+say "the b`blue`"
+```

data/lib/colsole/compat.rb

@@ -0,0 +1,55 @@
+# This file contains methods that are called by the main Colsole module
+# for compatibility with older versions of colsole.
+# Do not use these methods directly.
+module Colsole
+  def old_colorize(text)
+    reset = colors['txtrst']
+    reset_called_last = true
+
+    out = text.gsub(/!([a-z]{6})!/) do
+      reset_called_last = $1 == 'txtrst'
+      colors[$1]
+    end
+
+    reset_called_last or out = "#{out}#{reset}"
+    out
+  end
+
+  def old_strip_colors(text)
+    text.gsub(/!([a-z]{6})!/, '')
+  end
+
+  def resay(text)
+    say text, replace: true
+  end
+
+  def say_status(status, message = nil, color = nil)
+    color ||= (message ? :txtgrn : :txtblu)
+    say "!#{color}!#{status.to_s.rjust 12} !txtrst! #{message}".strip
+  end
+
+  def colors
+    @colors ||= begin
+      esc = 27.chr
+      pattern = "#{esc}[%{decor};%{fg}m"
+
+      decors = { txt: 0, bld: 1, und: 4, rev: 7 }
+      color_codes = { blk: 0, red: 1, grn: 2, ylw: 3, blu: 4, pur: 5, cyn: 6, wht: 7 }
+      colors = {}
+
+      decors.each do |dk, dv|
+        color_codes.each do |ck, cv|
+          key = "#{dk}#{ck}"
+          val = pattern % { decor: dv, fg: "3#{cv}" }
+          colors[key] = val
+        end
+      end
+
+      colors['txtbld'] = "#{esc}[1m"
+      colors['txtund'] = "#{esc}[4m"
+      colors['txtrev'] = "#{esc}[7m"
+      colors['txtrst'] = "#{esc}[0m"
+      colors
+    end
+  end
+end

data/lib/colsole/version.rb

@@ -1,3 +1,3 @@
 module Colsole
-  VERSION = "0.7.2"
-end
+  VERSION = '0.8.0'
+end

data/lib/colsole.rb

@@ -1,103 +1,91 @@
-require "colsole/version"
-
-# Colsole - Colorful Console Applications
-#
-# This class provides several utility functions for console application 
-# developers.
-#
-# - #colorize string - return a colorized strings
-# - #say string - print a string with colors  
-# - #say! string - print a string with colors to stderr
-# - #resay string - same as say, but overwrite current line  
-# - #say_status symbol, string [, color] - print a message with status
-# - #word_wrap string - wrap a string and maintain indentation
-# - #detect_terminal_size
-# - #terminal_width
-#
-# Credits:
-# terminal width detection by Gabrial Horner https://github.com/cldwalker
+require 'io/console'
+require 'colsole/compat'
 
+# Utility functions for colorful console applications.
 module Colsole
-  # Prints a color-flagged string.
-  # Use color flags (like !txtred!) to change color in the string.
-  # Space terminated strings will leave the cursor at the same line.
-  def say(text, force_color = false)
-    last = text[-1, 1]
-    if terminal? and (last == ' ' or last == '\t')
-      print colorize(text, force_color)
+  ANSI_COLORS = {
+    'n' => '',       # no color
+    'k' => "\e[30m", # black
+    'r' => "\e[31m", # red
+    'g' => "\e[32m", # green
+    'y' => "\e[33m", # yellow
+    'b' => "\e[34m", # blue
+    'm' => "\e[35m", # magenta
+    'c' => "\e[36m", # cyan
+    'w' => "\e[37m", # white
+  }
+
+  ANSI_STYLES = {
+    'b' => "\e[1m", # bold
+    'u' => "\e[4m", # underlined
+    'i' => "\e[7m", # inverted
+    'z' => "\e[0m", # terminate
+  }
+
+  # Output a string with optional color markers to stdout.
+  # If text is ended with a white space, you can call again with replace: true
+  # to replace that line
+  def say(text, replace: false)
+    internal_say text, $stdout, replace: replace
+  end
+
+  # Output a string with optional color markers to stderr.
+  # Behaves similarly to `#say`.
+  def say!(text, replace: false)
+    internal_say text, $stderr, replace: replace
+  end
+
+  # Returns true if stdout/stderr are a terminal
+  def terminal?(stream = $stdout)
+    case ENV['TTY']
+    when 'on'  then true
+    when 'off' then false
     else
-      print colorize("#{text}\n", force_color)
+      stream.tty?
     end
   end
 
-  # Prints a color-flagged string to STDERR
-  # Use color flags (like !txtred!) to change color in the string.
-  def say!(text, force_color = false)
-    $stderr.puts colorize(text, force_color, :stderr)
-  end
-
-  # Erase the current output line, and say a new string.
-  # This should be used after a space terminated say().
-  def resay(text, force_color = false)
-    text = "\033[2K\r#{text}" if terminal?
-    say text, force_color
-  end
-
-  # Prints a line with a colored status and message.
-  # Status can be a symbol or a string. Color is optional, defaults to
-  # green (:txtgrn) when there is a message, and to blue (:txtblu) when
-  # there is only a status
-  def say_status(status, message = nil, color = nil)
-    color ||= (message ? :txtgrn : :txtblu)
-    say "!#{color}!#{status.to_s.rjust 12} !txtrst! #{message}".strip
-  end
-
-  # Returns true if stdout/stderr is interactive terminal
-  def terminal?(stream = :stdout)
-    stream == :stdout ? out_terminal? : err_terminal?
-  end
-
-  # Returns true if stdout is interactive terminal
-  def out_terminal?
-    ENV['TTY'] == 'on' ? true : ENV['TTY'] == 'off' ? false : $stdout.tty?
-  end
-
-  # Returns true if stderr is interactive terminal
-  def err_terminal?
-    ENV['TTY'] == 'on' ? true : ENV['TTY'] == 'off' ? false : $stderr.tty?
-  end
-
-  # Determines if a shell command exists.
+  # Returns true if the command exists in the path
   def command_exist?(command)
     ENV['PATH'].split(File::PATH_SEPARATOR).any? do |dir|
       File.exist?(File.join dir, command) or File.exist?(File.join dir, "#{command}.exe")
     end
   end
 
-  # Returns [width, height] of terminal when detected, or a default
-  # value otherwise.
-  def detect_terminal_size(default = [80,30])
-    if (ENV['COLUMNS'] =~ /^\d+$/) && (ENV['LINES'] =~ /^\d+$/)
-      result = [ENV['COLUMNS'].to_i, ENV['LINES'].to_i]
-    elsif (RUBY_PLATFORM =~ /java/ || (!STDIN.tty? && ENV['TERM'])) && command_exist?('tput')
-      result = [`tput cols 2>&1`.to_i, `tput lines 2>&1`.to_i]
-    elsif STDIN.tty? && command_exist?('stty')
-      result = `stty size 2>&1`.scan(/\d+/).map { |s| s.to_i }.reverse
+  # Returns true if we can and should use colors in this stream
+  def use_colors?(stream = $stdout)
+    ENV['FORCE_COLOR'] || (!ENV['NO_COLOR'] && terminal?(stream))
+  end
+
+  # Returns the terminal size as [columns, rows].
+  # Environment variables can be used to cheat.
+  def terminal_size(default = [80, 30])
+    result = if (ENV['COLUMNS'] =~ /^\d+$/) && (ENV['LINES'] =~ /^\d+$/)
+      [ENV['COLUMNS'].to_i, ENV['LINES'].to_i]
     else
+      safe_get_tty_size default
+    end
+
+    unless result[0].is_a?(Integer) && result[1].is_a?(Integer) && result[0].positive? && result[1].positive?
       result = default
     end
-    result = default unless result[0].is_a? Integer and result[1].is_a? Integer and result[0] > 0 and result[1] > 0
+
     result
   end
 
-  # Returns terminal width
+  # Returns the columns part of the `#terminal_size`
   def terminal_width
-    detect_terminal_size[0]
+    terminal_size[0]
+  end
+
+  # Returns the rows part of the `#terminal_size`
+  def terminal_height
+    terminal_size[1]
   end
 
   # Converts a long string to be wrapped keeping words in tact.
-  # If the string starts with one or more spaces, they will be 
-  # preserved in all subsequent lines (i.e., remain indented).
+  # If the string starts with one or more spaces, they will be preserved in
+  # all subsequent lines (i.e., remain indented).
   def word_wrap(text, length = nil)
     length ||= terminal_width
     lead = text[/^\s*/]
@@ -105,7 +93,7 @@ module Colsole
     length -= lead.length
     text.split("\n").collect! do |line|
       if line.length > length
-        line.gsub!(/([^\s]{#{length}})([^\s$])/, "\\1 \\2")
+        line.gsub!(/([^\s]{#{length}})([^\s$])/, '\\1 \\2')
         line.gsub(/(.{1,#{length}})(\s+|$)/, "#{lead}\\1\n").rstrip
       else
         "#{lead}#{line}"
@@ -113,68 +101,50 @@ module Colsole
     end * "\n"
   end
 
-  # Parses and returns a color-flagged string.
-  # Respects pipe and auto terminates colored strings.
-  # Call without text to see a list/demo of all available colors.
-  def colorize(text = nil, force_color = false, stream = :stdout)
-    return show_color_demo if text.nil?
-    return strip_color_markers(text) unless terminal?(stream) || force_color
-    colorize! text
+  # Convert color markers to ansi colors.
+  def colorize(string)
+    # compatibility later
+    compat_string = old_colorize string
+
+    process_color_markers compat_string do |color, styles, text|
+      "#{styles}#{color}#{text}#{ANSI_STYLES['z']}"
+    end
   end
 
-private
+  # Remove color markers.
+  def strip_colors(string)
+    # compatibility layer
+    compat_string = old_strip_colors string
 
-  def colors
-    @colors ||= prepare_colors
+    process_color_markers(compat_string) { |_color, _styles, text| text }
   end
 
-  def colorize!(text)
-    reset = colors['txtrst']
-    reset_called_last = true
+private
 
-    out = text.gsub(/\!([a-z]{6})\!/) do |m|
-      reset_called_last = $1 == "txtrst"
-      colors[$1]
+  def process_color_markers(string)
+    string.gsub(/([rgybmcn])([ubi]{0,3})`([^`]*)`/) do
+      color = ANSI_COLORS[$1]
+      styles = $2.chars.map { |a| ANSI_STYLES[a] }.join
+      text = $3
+      yield color, styles, text
     end
-    
-    reset_called_last or out = "#{out}#{reset}"
-    out
   end
 
-  # Create a colors array with keys such as :txtgrn and :bldgrn
-  # and values which are the escape codes for the colors.
-  def prepare_colors
-    esc = 27.chr
-    pattern = "#{esc}[%{decor};%{fg}m"
-
-    decors = { txt: 0, bld: 1, und: 4, rev: 7 }
-    color_codes = { blk: 0, red: 1, grn: 2, ylw: 3, blu: 4, pur: 5, cyn: 6, wht: 7 }
-    colors = {}
-
-    decors.each do |dk, dv|
-      color_codes.each do |ck, cv|
-        key = "#{dk}#{ck}"
-        val = pattern % { decor: dv, fg: "3#{cv}" }
-        colors[key] = val
-      end
-    end
-    colors['txtbld'] = "#{esc}[1m"
-    colors['txtund'] = "#{esc}[4m"
-    colors['txtrev'] = "#{esc}[7m"
-    colors['txtrst'] = "#{esc}[0m"
-    colors
-  end
+  def internal_say(text, stream, replace: false)
+    text = "\033[2K\r#{text}" if replace && terminal?
+    last = text[-1, 1]
+    handler = use_colors?(stream) ? :colorize : :strip_colors
 
-  def show_color_demo
-    i = colors.count
-    colors.keys.each do |k| 
-      puts colorize "#{k} = !#{k}! #{i} bottles of beer on the wall !txtrst!"
-      i -= 1
+    if terminal? && ((last == ' ') || (last == '\t'))
+      stream.print send(handler, text)
+    else
+      stream.print send(handler, "#{text}\n")
     end
   end
 
-  def strip_color_markers(text)
-    text.gsub(/\!([a-z]{6})\!/, '')
+  def safe_get_tty_size(default = [80, 30])
+    $stdout.winsize.reverse
+  rescue Errno::ENOTTY
+    default
   end
-
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: colsole
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-31 00:00:00.000000000 Z
+date: 2023-01-20 00:00:00.000000000 Z
 dependencies: []
 description: Utility functions for making colorful console applications
 email: db@dannyben.com
@@ -18,11 +18,13 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/colsole.rb
+- lib/colsole/compat.rb
 - lib/colsole/version.rb
 homepage: https://github.com/DannyBen/colsole
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -31,14 +33,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.4.3
 signing_key: 
 specification_version: 4
 summary: Colorful Console Applications