term_color 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d7de87ceb0f3dfa90c19e011c9e2cddc1bf767a92ec88868e13574336601ba92
+  data.tar.gz: 20101cdbcf43876dfa89cab889443850a8f59d742db7dbd3a5d66336d34994da
+SHA512:
+  metadata.gz: 36863a07e2d674605356d73295d0a903413fd713041abb977868b37cf4661e2ad07e5b3e0f4c461605c2b6fed05bf97eec5756a9ceae3a2f208ab6fe744f1266
+  data.tar.gz: 31333b2890a8497edd93781f62a4239692f4981d2bd719c2e45ee641b7406c9fa99d2d8da1ffd0940716e25968f17131512d149996393afb65027d1fc591ba30

data/README.md

@@ -0,0 +1,110 @@
+# TermColor
+
+Rule-based text coloring/styling library for terminal text
+
+## Overview
+
+### Justifying Features
+
+- Define named text style rules once, combining fg/bg color and styling that can be reused through out application
+    - Able to manually specify what gets reset after style use is finished in a line, which parts to reset, etc.
+- Streamline including multiple styles within a single string, including allowing nested rules
+
+### Requirements
+
+- Tested/developed for Ruby 2.6.1
+
+## Concepts/Syntax
+
+Rules are grouped into `RuleSets`, which are represented by instances of {TermColor::RuleSet}.
+
+### Rule Set
+
+A set is constructed from a Hash of rule, where they keys are rule names and the values are the rule definition hashes.
+
+```ruby
+rules = {
+    # Rule named :title
+    title: { fg: :yellow, enable: :underline }
+}
+# Create instance of RuleSet
+rule_set = TermColor.create_rule_set(rules)
+# or
+rule_set = TermColor::RuleSet.new(rules)
+```
+
+#### Applying to Text
+
+Once you've got a `RuleSet` instance, calling its `apply` or `print`/`printf` methods with a string parameter will give back a copy of that string with styles applied
+
+__Methods__
+
+- `apply` - {TermColor::RuleSet#apply}
+- `print` - {TermColor::RuleSet#print}
+- `printf` - {TermColor::RuleSet#printf}
+
+__Use__
+
+- To apply a style to a section of the input string, surround it with `%rule_name` and `%%`
+    - E.g.: `"%titleTitle Text%%"`
+    - `%%` indicates the end of rule application, after which any `after` rules will get applied
+    - Including `%%` when no rule is active will apply the `default` rule's `:after` options, which can either be overridden in your rule set, or make use of the built-in version which simply resets all colors and text styling to system default
+- Rule application can be nested (`"%titleTitle of %otherBook%%%%"`)
+
+### Rule Definitions
+
+_For more details on rule definitions, see {file:docs/rule_dsl.md Rule DSL} ([View on GitHub](https://github.com/vdtdev/term_color/blob/master/docs/rule_dsl.md))_
+
+Rule definitions are just hashes that include rule options. The included options can be divided into `:inside` (applied to text rule is applied to) and `:after` (applied to text following text rule is applied to). If neither of these sub hashes are included, all options are treated as being for `:inside`, and an `:after` set is auto-generated to unapply style changes made inside rule for following text. To prevent an `:after` section from being automatically generated, either include your own `:after` section or include `after: {}`. 
+
+```ruby
+# No groups, after will be generated
+rule = { fg: :red }
+# Same as above but with groups. after will be generated
+rule = { inside: { fg: :red } }
+# No groups, skip after generation by setting it to 
+# empty hash of options
+rule = { fg: :red, after: {} }
+# Both groups, same as others but with explicitly set after options,
+# no auto-generation
+rule = { inside: { fg: :red }, after: { reset: :fg } }
+```
+
+For more details on rule definitions, see {file:docs/rule_dsl.md Rule DSL} ([View on GitHub]{https://github.com/vdtdev/term_color/blob/master/docs/rule_dsl.md})
+
+## Examples
+
+[If example images are missing, view readme on github](https://github.com/vdtdev/term_color/blob/master/README.md)
+
+### Basic
+
+```ruby
+rule_set = TermColor.create_rule_set({
+    opt: { fg: :cyan },
+    err: { fg: :red }
+})
+
+rule_set.printf "%errInvalid%% option: %opt%s%%\n", "fruit"
+```
+
+![](./file/docs/example_1.png)
+![](./docs/example_1.png)
+
+### Nested /w XTerm RGB
+
+```ruby
+rule_set = TermColor.create_rule_set({
+    title: { fg: :yellow, enable: :underline },
+    emph: { fg: [0xa0,0xa0,0xff], enable: :italic },
+    author: { fg: :green, bg: :blue, enable: :bold }
+})
+
+rule_set.print "book: %%titleHarry Potter (%emph%%)%% by %authorJ. K. Rowling%%\n"
+```
+
+![](./file/docs/example_2.png)
+![](./docs/example_2.png)
+
+## License
+
+(c) 2020, Wade H. (vdtdev.prod@gmail.com). All Rights Reserved. Released under MIT license.

data/lib/term_color/rule.rb

@@ -0,0 +1,316 @@
+module TermColor
+    ##
+    # Rule processor
+    # @example Basic Rule
+    #   # Foreground color set to blue
+    #   # Underline style turned on
+    #   # Not broken into `a:` and `z:`, so rules will
+    #   # be treated as `a:`, `z:` will be auto-generated
+    #   # to reset forground color and disable underline
+    #   rule = { fg: :blue, enable: :underline }
+    # @example Full after reset
+    #   # Insize: (`a:`) Foreground yellow, bg red, dark style on
+    #   # After: Resets all color and style options to default,
+    #   # including those set by other rules
+    #   rule = { 
+    #       a: {
+    #           fg: :yellow, bg: :red, enable: :dark 
+    #       },
+    #       z: {
+    #           reset: :all
+    #       }
+    #  }
+    # @example Italic red, only clearing color at end
+    #   # Inside: red fg, italic style
+    #   # After: color will reset to default, italic will remain on
+    #   rule = { a: { fg: :red, enable: :italic }, z: { reset: :fg }}
+    # @author Wade H. <vdtdev.prod@gmail.com>
+    module Rule
+        extend self
+
+        ##
+        # Named Standard ANSI Color constants
+        # (Basic named values for `fg` and `bg` rule option attributes)
+        Colors = {
+            black: 0,
+            red: 1,
+            green: 2,
+            yellow: 3,
+            blue: 4,
+            magenta: 5,
+            cyan: 6,
+            white: 7
+        }.freeze
+
+                ##
+        # Numerical modifiers used with Color Values
+        # to target foreground or background.
+        # 
+        # - For {Colors Named Standard Colors}, value is added to given
+        #   color's numerical value
+        # - For XTerm 256/16m color codes, value is added to mode base
+        # 
+        # @example Named Standard Color Background
+        #   { bg: :red } #=> 40 + 1 = 41
+        # @example XTerm 256 Foreground
+        #   { fg: [208] } #=> 8 + 30 = 38
+        ColorTargets = { 
+            fg: 30, # Foreground target
+            bg: 40  # Background target
+        }.freeze
+
+        ##
+        # Style option constants
+        # (Values that can be included in style `enable` and `disable` 
+        # rule option attributes)
+        Styles = {
+            bold: 1,
+            ##
+            # Alias for bold
+            intense: 1,
+            dim: 2,
+            ##
+            # Alias for dim
+            dark: 2,
+            italic: 3,
+            underline: 4,
+            inverse: 7,
+            strikethrough: 9
+        }.freeze
+
+        ##
+        # Style action codes
+        # (Numerical modifiers applied to {Styles Style Codes} to
+        # enable/disable them based on which option attribute action
+        # was used)
+        # @example Disable italic
+        #   (:disable) + (:italic) #=> 20 + 3 = 23
+        StyleActions = { 
+            # Enable style(s) action
+            enable: 0,
+            # Disable style(s) action
+            disable: 20 
+        }
+
+        ##
+        # Reset option constants
+        # (Values for `reset` rule option attribute)
+        Resets = {
+            # Reset everything
+            all: 0,
+            # Reset foreground color only
+            fg: 39,
+            # Reset background color only
+            bg: 49
+        }.freeze
+
+        ##
+        # Descriptive aliases for part names
+        Parts = {
+            # Style applied on rule open
+            inside: :inside,
+            # Style appled when rule close is given
+            after: :after
+        }
+
+        ##
+        # Valid rule operations mapped to accepted const values
+        # (colors [fg, bg] can also accept integers)
+        Ops = {
+            # Foreground color option
+            fg: Colors.keys,
+            # Background color option
+            bg: Colors.keys,
+            # Enable style(s) action
+            enable: Styles.keys,
+            # Disable style(s) action
+            disable: Styles.keys,
+            # Reset action
+            reset: [
+                :fg,    # Reset fg color 
+                :bg,    # Reset bg color
+                :style, # Reset all styles
+                :all    # Reset colors and styles
+            ]
+        }
+
+        ##
+        # Value added to ColorTarget when using XTerm colors
+        XTERM_COLOR_TARGET = 8
+        ##
+        # Mode constant for XTerm 256 Colors
+        XTERM_COLOR_256 = 5
+        ##
+        # Mode constant for XTerm 16m Colors
+        XTERM_COLOR_16M = 2
+
+        ##
+        # Structure used to hold compiled rule
+        # @!attribute [r] original
+        #   Original rule hash
+        #   @return [Hash]
+        # @!attribute [r] evaluated
+        #   Evaluated copy of rule, including generated :after.
+        #   Consists of code arrays
+        #   @return [Hash]
+        # @!attribute [r] rule
+        #   Hash of inside and after ANSI code strings
+        #   @return [Hash]
+        Compiled = Struct.new(:original, :evaluated, :rule) do
+            ##
+            # Get codes for part of compiled rule
+            def codes(part)
+                rule[part]
+            end
+        end
+
+        ##
+        # Compile rule into frozen instance of `Compiled` struct
+        # @param [Hash] rule Rule hash
+        # @return [Compiled] Frozen instance of `Compiled` struct
+        #   containing compiled rule
+        def compile(rule)
+            evaluated = evaluate(rule)
+            return Compiled.new(
+                rule,
+                evaluated,
+                codes(evaluated)
+            ).freeze
+        end
+
+        private
+
+        def evaluate_ops(ops)
+            codes = []
+            v_ops = ops.filter{|k,v| Ops.keys.include?(k.to_sym)}
+            color_keys = ColorTargets.keys
+            style_keys = StyleActions.keys
+            reset_keys = Resets.keys
+            v_ops.each_pair do |k,v|
+                k=k.to_sym
+                if color_keys.include?(k)
+                    codes << resolve_color(v, k)
+                elsif style_keys.include?(k)
+                    [v].flatten.each do |val|
+                        codes << resolve_style(val, k)
+                    end
+                elsif k == :reset
+                    [v].flatten.each do |val|
+                        codes << resolve_reset(val)
+                    end
+                end
+            end
+            codes = codes.flatten.compact.uniq
+        end                
+
+        def resolve_color(color, target = :fg)
+            if color.is_a?(Array)
+                color = color[0..2]
+                return xterm_color(color, target)
+            end
+                
+            if !color.is_a?(Integer)
+                
+                if color.is_a?(Hash) && ColorsAdvanced.keys.include?(color.keys[0])
+                    return self.method(ColorsAdvanced[color.keys[0]]).call(color.values[0])
+                end
+                color = Colors[color.to_sym].to_i
+            end
+            (color + ColorTargets[target.to_sym].to_i)
+        end
+
+        def resolve_style(style, state = :enable)
+            if !style.is_a?(Integer)
+                style = Styles[style.to_sym].to_i
+            end
+            (style + StyleActions[state.to_sym].to_i)
+        end
+
+        def resolve_reset(target)
+            if Resets.keys.include?(target.to_sym)
+                return Resets[target.to_sym]
+            elsif Styles.keys.include?(target.to_sym)
+                return resolve_style(target, :disable)
+            else
+                return nil
+            end
+        end
+
+        def xterm_color(val,target)
+            r,g,b = [val].flatten
+            if g.nil? && b.nil?
+                [
+                    ColorTargets[target] + XTERM_COLOR_TARGET,
+                    XTERM_COLOR_256,
+                    r
+                ].join(';')
+            else
+                [
+                    ColorTargets[target] + XTERM_COLOR_TARGET,
+                    XTERM_COLOR_16M,
+                    r,g,b
+                ].join(';')
+            end
+        end
+
+        ##
+        # Evaluate rule, returning new hash containing list of numerical
+        # codes to use for inside (`:inside`) and after (`:after`)
+        # @param [Hash] rule Rule hash to evaluate
+        # @return [Hash] evaluated version of rule, containing code numbers
+        def evaluate(rule)
+            # error if not hash
+            return nil if !rule.is_a?(Hash)
+
+            inside_part_key = Parts[:inside]
+            after_part_key = Parts[:after]
+            rule_keys = rule.keys.map{|k|k.to_sym}
+            
+            # Find 'inside' rule options
+            if rule_keys.include?(inside_part_key)
+                # 'inside' key explicitly defined, so pull from that
+                inside_part = rule[:inside]
+            else
+                # no 'inside' key, so pull from entire hash excluding
+                # 'after' key, if present
+                inside_part = rule.filter { |k,v| k != after_part_key }
+            end
+
+            # Find 'after' rule options, using nil if not present
+            # This means that if it is defined but as an empty hash,
+            # no 'after' rule options will be auto-generated
+            after_part = rule.fetch(after_part_key, nil)
+
+            # Auto-generate 'after' rule options if not explicitly defined
+            if after_part.nil?
+                resets = inside_part.keys.filter { |k| ColorTargets.keys.include?(k) }
+                disables = inside_part.fetch(:enable, [])
+                after_part = {}
+                after_part[:reset] = resets if resets.length > 0
+                after_part[:disable] = disables if disables.length > 0
+            end
+
+            parts = {}
+
+            parts[inside_part_key] = evaluate_ops(inside_part)
+            parts[after_part_key] = evaluate_ops(after_part)
+
+            return parts.merge({evaluated: true})
+
+        end
+        
+        ##
+        # Return ANSI color codes from evaluated rule
+        # @param [Hash] rule Full rule
+        # @return [Hash] Hash with code strings for `:inside` and `:after`
+        def codes(rule)
+            code = Proc.new {|c| "\e[#{c}m" }
+            inside = Parts[:inside]
+            after = Parts[:after]
+            {
+                (inside) => rule[inside].map{|c| code.call(c) }.join(''),
+                (after) => rule[after].map{|c| code.call(c) }.join('')
+            }
+        end
+    end
+end

data/lib/term_color/rule_set.rb

@@ -0,0 +1,214 @@
+module TermColor
+    ##
+    # TermColor style rule setc class
+    # @author Wade H. <vdtdev.prod@gmail.com>
+    # @license MIT
+    class RuleSet
+
+        ##
+        # Symbol used as prefix for rule name to denote rule start
+        RULE_SYMBOL='%'
+        ##
+        # String used to denote rule close / reset
+        RESET_SYMBOL='%%'
+
+        DEFAULT_RESET_RULE = {z: {reset: :all} }
+
+        attr_reader :rules, :regexs
+
+        ##
+        # Construct new rule set
+        # @param [Hash] rules Hash of rule names mapping to rule hashes,
+        #   which can define before rules (`a:`), after rules (`z:`) or both.
+        #   - If neither are given, content is treated as though it was inside a `a:` key.
+        #   - If `a:` only is given, {TermColor::Rule#evaluate Rule evaluate method} attempts to
+        #       auto guess `z:`, resetting any used color or style rules from `a:`
+        # @see TermColor::Rule
+        # @example
+        #   rules = RuleSet.new({
+        #       # Green underlined text; will auto reset fg and disable underline
+        #       # for close, since no z: is provided
+        #       name: {fg: :green, enable: :underline},
+        #       # Italic text; will auto generate z: that disables italic
+        #       quote: { enable: :italic },
+        #       # A weird rule that will make fg red inside rule,
+        #       # and change fg to blue after rule block ends
+        #       weird: { a: { fg: :red }, z: { fg: :blue }}
+        #   })
+        #
+        #   print rules.colorize("%nameJohn%%: '%%quoteRoses are %%weirdRed%% (blue)%%.\n")
+        #   # Result will be:
+        #   #   fg green+underline "John"
+        #   #   regular ":  "
+        #   #   italic "Roses are "
+        #   #   fg red (still italic) "Red"
+        #   #   (fg blue)(still italic) "(blue)"
+        #   #   (regular) "."
+        def initialize(rules)
+            @base_rules = rules
+            @base_rules[:default] = @base_rules.fetch(:default, DEFAULT_RESET_RULE)
+            evaluate_rules
+            build_regexs
+        end
+
+        ##
+        # Apply styling to string using rule set
+        # @param [String] text Text to parse for stylization
+        # @return [String] Text with ANSI style codes injected
+        def apply(text)
+            raw = process_text(text)
+            last_rule = nil
+            str = ''
+            raw.each do |r|
+                if r.is_a?(Symbol)
+                    # if (r == :close_rule && !last_rule.nil?)
+                    #     str.concat(Rule.codes(@rules[last_rule][:z]))
+                    #     last_rule = nil
+                    # elsif  r == :default
+                    #     str.concat(Rule.codes(@rules[r][:z]))
+                    #     last_rule = nil
+                    # else
+                    #     last_rule = r
+                    #     str.concat(Rule.codes(@rules[r][:a]))
+                    # end
+                    if (r == :default) && !last_rule.nil?
+                        str.concat(@rules[last_rule].codes(Rule::Parts[:after]))
+                        last_rule = nil
+                    elsif  r == :default
+                        str.concat(@rules[r].codes(Rule::Parts[:after]))
+                        last_rule = nil
+                    else
+                        last_rule = r
+                        str.concat(@rules[r].codes(Rule::Parts[:inside]))
+                    end
+                else
+                    str.concat(r)
+                end
+            end
+            str
+        end
+
+        ##
+        # Wraps STDOUT print method, passing output of `apply` to `print`
+        # @param [Array] args Print arguments, including TermColor style tags
+        # @param [Hash] opts Optional params
+        # @option opts [IO] :out Optional override for IO class to call `print`
+        #   on (default `$stdout`)
+        def print(*args,**opts)
+            stdout = opts.fetch(:out, $stdout)
+            t = args.map{|a|apply(a)}
+            stdout.print *t
+        end
+
+        ##
+        # Wraps STDOUT printf method, passing output of `apply` to `print`
+        # Doesn't actually use `printf`, instead passes result of
+        # `format_string % args` to `print`.
+        # @param [String] format_string printf format string, 
+        #   including TermColor style tags
+        # @param [Array] args printf values to use with format string
+        # @param [Hash] opts Optional params
+        # @option opts [IO] :out Optional override for IO class to call `print`
+        #   on (default `$stdout`)
+        def printf(format_string,*args,**opts)
+            stdout = opts.fetch(:out, $stdout)
+
+            # Sanitize rule symbols
+            sanitized = format_string.dup
+            @rules.keys.each { |k| sanitized.gsub!("#{RULE_SYMBOL}#{k.to_s}","#{255.chr}#{k.to_s}") }
+            sanitized.gsub!(RESET_SYMBOL, 255.chr*2)
+            
+            t = sanitized % args
+            # Reinstate rule symbols
+            @rules.keys.each { |k| t.gsub!("#{255.chr}#{k.to_s}","#{RULE_SYMBOL}#{k.to_s}") }
+            t.gsub!(255.chr*2,RESET_SYMBOL)
+            
+            stdout.print apply(t)
+        end
+            
+        private
+
+        def evaluate_rules
+            @rules = {}
+            @base_rules.each_pair do |k,v|
+                @rules[k] = Rule.compile(v)
+            end
+        end
+
+        def build_regexs
+            @regexs = {}
+            src = @rules
+            src.each_pair do |k,v|
+                @regexs[k] = Regexp.compile(
+                    "(?<#{k.to_s}>(#{RULE_SYMBOL}#{k.to_s}))"
+                )
+            end
+            @regexs[:default] = Regexp.compile(
+                "(?<default>(#{RESET_SYMBOL}))"
+            )
+        end
+
+        def locate_rules_in_string(text)
+            tracking = {}
+            @regexs.keys.each do |k|
+                tracking[k] = {index: 0, done: false}
+            end
+            tracking_done = Proc.new {
+                tracking.values.select{|t|!t[:done]}.length == 0
+            }
+            is_done = false
+
+            locations = []
+            # binding.pry
+            until is_done do
+                @regexs.each_pair do |k,v|
+                    t = tracking[k]
+                    # print "Tracking #{k} (#{t})\n"
+                    unless t[:done]
+                        m = v.match(text,t[:index])
+                        if m.nil?
+                            # print "No matches found\n"
+                            tracking[k][:done] = true
+                        else
+                            tracking[k][:index] = m.end(0)
+                            a=m.begin(0);b=m.end(0)
+                            locations << {
+                                symbol: k,
+                                begin: a,
+                                sym_end: b - 1,
+                                continue_pos: b
+                            }
+                            # print "\tMatch found (#{a}..#{b}): #{text[a..b]}\n"
+                        end
+                    end
+                end
+                is_done = tracking_done.call()
+            end
+            locations.sort{|a,b|a[:continue_pos]<=>b[:continue_pos]}
+        end
+
+        def process_text(text)
+            locations = locate_rules_in_string(text)
+
+            working = []
+            return [text] if locations.length == 0
+
+            if locations[0][:begin] > 0
+                working << text[0..locations[0][:begin]-1]
+            end
+
+            locations.each_with_index do |l,i|
+                is_last = locations.length - 1 - i == 0
+                end_pos = -1
+                if !is_last
+                    end_pos = locations[i+1][:begin] - 1
+                end
+    
+                working << l[:symbol]
+                working << text[l[:continue_pos]..end_pos]
+            end
+            working
+        end
+
+    end
+end

data/lib/term_color.rb

@@ -0,0 +1,16 @@
+require_relative './term_color/rule.rb'
+require_relative './term_color/rule_set.rb'
+##
+# Main TermColor module
+# @author Wade H. <vdtdev.prod@gmail.com>
+module TermColor
+    extend self
+
+    ##
+    # Alias for constructing a new RuleSet
+    # @see TermColor::RuleSet
+    def create_rule_set(rules={})
+        TermColor::RuleSet.new(rules)
+    end
+
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: term_color
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Wade H.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+description: "        Rule-based tool for easily applying color and styling to terminal
+  text output.\n"
+email: vdtdev.prod@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/term_color.rb
+- lib/term_color/rule.rb
+- lib/term_color/rule_set.rb
+homepage: https://github.com/vdtdev/term_color
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/vdtdev/term_color
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Terminal Colors
+test_files: []