colours 0.6.12

data/lib/colours/toplevel_methods/prefer_this_colour_schemata.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/prefer_this_colour_schemata.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/requires/require_yaml.rb'
+  require 'colours/html_colours/add_html_colours_onto_the_toplevel_namespace.rb'
+  require 'colours/autogenerated/support_for_html_colours.rb'
+
+  # ========================================================================= #
+  # === @prefer_this_colour_schemata
+  #
+  # The following Array ranks which colour schemata we will try to use.
+  # More important entries should come on top.
+  #
+  # Konsole will be the default, normally, followed by the 256 colours; and
+  # then the basic colours.
+  #
+  # Of course you can decide on your own via the .yml file, and other
+  # methods that allow us to change this setting, but when it comes
+  # to implementations such as for simp() or sfancy() then we will
+  # honour the setting in the yaml file (if we use any colours at all,
+  # that is). The yaml file is typically called
+  # "prefer_this_colour_schemata.yml".
+  # ========================================================================= #
+  if File.exist? FILE_PREFER_THIS_COLOUR_SCHEMATA
+    @prefer_this_colour_schemata = YAML.load_file(FILE_PREFER_THIS_COLOUR_SCHEMATA)
+  end
+
+  # ========================================================================= #
+  # === @use_html_colours
+  #
+  # If the following variable is set to true then the HTML colours will
+  # be used, if available. These are colours such as 'slateblue' or
+  # 'crimson'.
+  # ========================================================================= #
+  @use_html_colours = false
+
+  # ========================================================================= #
+  # === @use_256_colours
+  # ========================================================================= #
+  @use_256_colours = false
+
+  # ========================================================================= #
+  # === @use_basic_colours
+  # ========================================================================= #
+  @use_basic_colours = false
+
+  # ========================================================================= #
+  # Next, we will set some other toplevel instance variables based on
+  # the value of this yaml file.
+  # ========================================================================= #
+  if @prefer_this_colour_schemata
+    first_entry  = @prefer_this_colour_schemata[1]
+    _second_entry = @prefer_this_colour_schemata[2]
+    _third_entry  = @prefer_this_colour_schemata[3]
+
+    case first_entry
+    when :html_colours
+      @use_html_colours = true
+    when :support_for_256_colours
+      @use_256_colours = true
+    when :basic_colours
+      @use_basic_colours = true
+    end
+  end
+
+  # ========================================================================= #
+  # === Colours.prefer_which_colour_schemata?
+  # ========================================================================= #
+  def self.prefer_which_colour_schemata?
+    @prefer_this_colour_schemata[1].to_sym if @prefer_this_colour_schemata
+  end; self.instance_eval { alias prefer_which_colour_scheme? prefer_which_colour_schemata? } # === Colours.prefer_which_colour_scheme
+
+  # ========================================================================= #
+  # Designate @use_256_colours to true:
+  # ========================================================================= #
+  if prefer_which_colour_schemata? == :support_for_256_colours
+    @use_256_colours = true
+  end
+
+end

data/lib/colours/toplevel_methods/random_html_colour.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/random_html_colour.rb'
+# =========================================================================== #
+module Colours
+
+require 'colours/html_colours/misc.rb'
+
+# =========================================================================== #
+# === Colours.random_html_colour
+#
+# This method will simply return a (one) random HTML colour, in long
+# format, e. g. "teal" or "slateblue".
+#
+# If you wish to have it colourized properly, you need to use another
+# method.
+#
+# Usage examples:
+#
+#   Colours.random_colour? # => "teal"
+#   Colours.random_colour? # => "blueviolet"
+#
+# =========================================================================== # 
+def self.random_html_colour
+  ::Colours::HtmlColours.random_colour?
+end; self.instance_eval { alias random_colour?            random_html_colour } # === Colours.random_colour?
+     self.instance_eval { alias return_html_colour?       random_html_colour } # === Colours.return_html_colour?
+     self.instance_eval { alias random_html_colour?       random_html_colour } # === Colours.random_html_colour?
+     self.instance_eval { alias return_random_html_colour random_html_colour } # === Colours.return_random_html_colour
+
+# =========================================================================== #
+# === random_colour?
+# =========================================================================== #
+def random_colour?
+  ::Colours::HtmlColours.random_colour?
+end; alias random_colour             random_colour? # === random_colour
+     alias random                    random_colour? # === random
+     alias sample                    random_colour? # === sample
+     alias random_html_colour        random_colour? # === random_html_colour
+     alias return_random_html_colour random_colour? # === return_random_html_colour
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts Colours.random_colour? # => "teal" 
+end

data/lib/colours/toplevel_methods/random_value.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/random_value.rb'
+# =========================================================================== #
+module Colours
+
+  # ========================================================================= #
+  # === Colours.random_value?
+  #
+  # We will obtain a random value between 0 and 255, hence why we will
+  # use rand(256).
+  # ========================================================================= #
+  def self.random_value?
+    rand(256)
+  end; self.instance_eval { alias random_value random_value? } # === Colours.random_value
+       self.instance_eval { alias rvalue       random_value? } # === Colours.rvalue
+       self.instance_eval { alias r?           random_value? } # === Colours.r?
+       self.instance_eval { alias g?           random_value? } # === Colours.g?
+       self.instance_eval { alias b?           random_value? } # === Colours.b?
+
+  # ========================================================================= #
+  # === random_value
+  #
+  # We will obtain a random value between 0 and 255, hence why we will
+  # use rand(256). 
+  # ========================================================================= #
+  def random_value?
+    Colours.random_value?
+  end; alias rvalue       random_value? # === rvalue
+       alias random_value random_value? # === random_value
+       alias r?           random_value? # === r?
+       alias g?           random_value? # === g?
+       alias b?           random_value? # === b?
+
+end

data/lib/colours/toplevel_methods/remove_escape_sequence.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/remove_escape_sequence.rb'
+# Colours.remove_escape_sequence
+# =========================================================================== #
+module Colours
+
+  require 'colours/constants/colour_constants.rb'
+
+  # ========================================================================= #
+  # === Colours.remove_escape_sequence
+  #
+  # The method Colours.remove_escape_sequence() will remove all Ansi 
+  # Escape sequences from a given string.
+  # ========================================================================= #
+  def self.remove_escape_sequence(i = ARGV)
+    if i.is_a? Array
+      i = i.join("\n")
+    end
+    i = i.to_s.dup
+    # ======================================================================= #
+    # Iterate over the registered ansi-colours next.
+    # ======================================================================= #
+    ARRAY_REGISTERED_ANSI_COLOURS.each {|entry|
+      if i.include? entry
+        entry = Regexp.quote(entry)
+        i.sub!(/#{entry}/, '')
+      end
+      # ===================================================================== #
+      # Next, check for KDE konsole colours. We must use "" there, not ''.
+      # ===================================================================== #
+      if i.include?("\e[") and i =~ /\d+m/ # Such as: "\e[38;2;220;20;60m|"
+        # =================================================================== #
+        # The next regex will (hopefully) remove all escape-characters
+        # from the given String.
+        # =================================================================== #
+        regex_for_html_colours = # Detect entries such as: \e[38;2;106;90;205m
+          /(\e\[\d{2};\d{1};\d{3};\d{1,2};\d{3}m)/ # See: https://rubular.com/r/tG3XeOK5NPsfmI
+        i.gsub!(regex_for_html_colours, '')
+        # =================================================================== #
+        # See: https://rubular.com/r/SdS28fAGSxIELn
+        # =================================================================== #
+        # /(\\e\[\d{1,2};?\d{1,2};?\d{0,3};?\d{0,3};?\d{1,2}m|\\e\[\d{0,2}m|\\e\[K|\\e\[\d{0,2};\d{0,2}m|(\\e\[.+\dm)|\\e\[0;37m)/
+        [
+          /\e\[\d{1,2};?\d{1,2};?\d{0,3};?\d{0,3};?\d{1,2}m/,
+          /\\e\[\d{0,2}m|\\e\[K|\\e\[\d{0,2};\d{0,2}m/,
+          /\\e\[.+\dm/,
+          /\\e\[0;37m/
+        ].each {|regex_to_use|
+          i.gsub!(regex_to_use, '')
+        }
+      end
+    }
+    return i
+  end; self.instance_eval { alias remove                  remove_escape_sequence } # === Colours.remove
+       self.instance_eval { alias remove_escape_sequences remove_escape_sequence } # === Colours.remove_escape_sequences
+       self.instance_eval { alias remove_colours          remove_escape_sequence } # === Colours.remove_colours
+       self.instance_eval { alias escape                  remove_escape_sequence } # === Colours.escape
+
+  # ========================================================================= #
+  # === Colours.remove_trailing_end_from
+  #
+  # The second argument to this method can be the escape sequence that you
+  # wish to remove.
+  #
+  # Invocation example:
+  #
+  #   x = Colours.remove_trailing_end_from("\e[38;2;70;130;180m\e[0;37m") # => "\e[38;2;70;130;180m"
+  #
+  # ========================================================================= #
+  def self.remove_trailing_end_from(
+      i,
+      remove_this_escape_sequence = Colours.revert?
+    )
+    quoted = Regexp.quote(remove_this_escape_sequence)
+    # ======================================================================= #
+    # Anchor it at the end via $.
+    # ======================================================================= #
+    return i.sub(
+      /#{quoted}$/, ''
+    )
+  end; self.instance_eval { alias remove_trailing_escape_part       remove_trailing_end_from } # === Colours.remove_trailing_escape_part
+       self.instance_eval { alias remove_trailing_ansii_escape_code remove_trailing_end_from } # === Colours.remove_trailing_ansii_escape_code
+       self.instance_eval { alias remove_trailing_ANSII_escape_code remove_trailing_end_from } # === Colours.remove_trailing_ANSII_escape_code
+       self.instance_eval { alias remove_trailing_escape_code       remove_trailing_end_from } # === Colours.remove_trailing_escape_code
+       self.instance_eval { alias remove_trailing_code              remove_trailing_end_from } # === Colours.remove_trailing_code
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  begin
+    require 'colours/autoinclude'
+  rescue LoadError; e 'the colours gem is not available.'; end
+  include Colours
+  e
+  e 'Next testing an escape sequence (which will be shown via pp only):'
+  e
+  x = "\e[01m\e[Kcc1:\e[m\e[K \e[01;35m\e[Kwarning: \e[m\e[K-Wabi won't warn about anything [\e[01;35m\e[K-Wabi\e[m\e[K]
+
+A\e[38;2;220;20;60m|AGCTT"
+  pp x
+  e
+  x = Colours.remove_escape_sequence(x)
+  e
+  pp x
+  e x
+  pp Colours.remove_escape_sequences(Colours.slateblue('Hello world!')) # => "\e[38;2;106;90;205mHello world!"
+  p Colours.slateblue('Hello world!') # => "\e[38;2;106;90;205mHello world!\e[0;37m"
+end

data/lib/colours/toplevel_methods/set_last_colour_used.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/set_last_colour_used.rb'
+# =========================================================================== #
+module Colours
+
+  # ========================================================================= #
+  # === @last_colour_used
+  #
+  # This instance variable keeps track what the last colour used was.
+  # ========================================================================= #
+  @last_colour_used = nil
+
+  # ========================================================================= #
+  # === last_colour_used?
+  #
+  # Tell us which colour was used last.
+  # ========================================================================= #
+  def last_colour_used?
+    @last_colour_used.to_s # Always required a string.
+  end
+
+  # ========================================================================= #
+  # === Colours.set_last_colour_used
+  # ========================================================================= #
+  def self.set_last_colour_used(i)
+    @last_colour_used = i
+  end
+
+end

data/lib/colours/toplevel_methods/show_basic_colour_palette.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal =  true
+# =========================================================================== #
+# require 'colours/toplevel_methods/show_basic_colour_palette.rb'
+# =========================================================================== #
+require 'colours/constants/hash_simple_colours.rb'
+require 'colours/toplevel_methods/cliner.rb'
+require 'colours/toplevel_methods/e.rb'
+require 'colours/toplevel_methods/make_colour.rb'
+
+module Colours
+
+  # ========================================================================= #
+  # === Colours.show_basic_colour_palette
+  #
+  # This will show a colour palette on the commandline.
+  # ========================================================================= #
+  def self.show_basic_colour_palette
+    e
+    MAIN_COLOURS.reject {|e| e == :black }.each { |entry|
+      make_colour(entry) # make_colour() is defined in this file here.
+    }
+    cliner
+    SECONDARY_COLOURS.each { |entry|
+      make_colour(entry)
+    }
+    e
+  end; self.instance_eval { alias show_palette        show_basic_colour_palette } # === Colours.show_palette
+       self.instance_eval { alias show_colour_palette show_basic_colour_palette } # === Colours.show_colour_palette
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Colours.show_basic_colour_palette
+end # show_basic_colour_palette

data/lib/colours/toplevel_methods/underline.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file will handline underline-functionality in a terminal. It
+# supports basic colours and the HTML colours.
+# =========================================================================== #
+# require 'colours/toplevel_methods/underline.rb'
+# Colours.return_underline
+# =========================================================================== #
+module Colours
+
+  require 'colours/revert/revert.rb'
+  require 'colours/toplevel_methods/e.rb'
+  require 'colours/rgb/rgb.rb'
+
+  # ========================================================================= #
+  # === UNDERLINE_CODE
+  #
+  # To quickly test the underline-functionality, you can try:
+  #
+  #   echo -e "\e[4mone two three\e[23m" 
+  #
+  # ========================================================================= #
+  UNDERLINE_CODE = '4'
+
+  # ========================================================================= #
+  # === Colours.underline
+  #
+  # This method will "puts" the result of applying underline to a string,
+  # on the console/terminal. If you wish to do the output on your own
+  # then you have to use the method Colours.return_underline or its
+  # alias called Colours.string_underline.
+  #
+  # To test this, try:
+  #
+  #   Colours.underline('Hello world!')
+  #
+  # ========================================================================= #
+  def self.underline(
+      i            = '', 
+      make_newline = false,
+      &block
+    )
+    e return_underline(i, make_newline, &block)
+  end
+
+  # ========================================================================= #
+  # === underline
+  # ========================================================================= #
+  def underline(
+      i            = '',
+      make_newline = false
+    )
+    Colours.underline(i, make_newline)
+  end
+
+  # ========================================================================= #
+  # === Colours.return_underline
+  #
+  # The point of this method here is to make a given text (String) appear
+  # "underlined", via ANSI escape sequences. For underline the String
+  # that should be used is "\u001b[4m".
+  #
+  # This can be tested on the commandline such as via:
+  #
+  #   echoen "\u001b[4m Underline \u001b[0m"
+  #
+  # Usage examples:
+  #
+  #   puts ' ok | '+Colours.return_underline('Hello world!')+' | ok'
+  #   puts ' ok | '+Colours.return_underline('Hello world!') { :slateblue }+' | ok'
+  #
+  # In January 2022 the second variant was removed, though. Let's keep things
+  # simple for now - perhaps in the future this may be re-enabled.
+  # ========================================================================= #
+  def self.return_underline(
+      show_this_text          = 'This must be underline.',
+      make_newline            = false,
+      use_this_as_revert_code = REVERT
+    )
+    # ===================================================================== #
+    # Build up our main string that codes for underline.
+    # ===================================================================== #
+    result = "\u001b[4m".dup
+    # if block_given?
+    #   # ===================================================================== #
+    #   # Right now we assume that this must be a colour if it is supplied
+    #   # via a block. However had, in January 2022 I realised that this
+    #   # assumption is not always correct, so this was disabled for now.
+    #   # At a later moment in time we may reconsider this.
+    #   # ===================================================================== #
+    #   result << ";38;2;"
+    #   colour_replacement = colour_to_rgb_value(yield)
+    #   result << colour_replacement
+    # end
+    # result << 'm'
+    if make_newline # Append a newline in this case.
+      show_this_text = "#{show_this_text}\n"
+    end
+    result << show_this_text
+    result << use_this_as_revert_code
+    result
+  end; self.instance_eval { alias string_underline return_underline } # === Colours.string_underline
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.empty?
+    puts Colours.underline('Hello world!')
+    puts 'Hello world!'
+    # ======================================================================= #
+    # And then run some more tests:
+    # ======================================================================= #
+    require 'colours/toplevel_methods/use_colours.rb'
+    Colours.enable_html_colours
+    e Colours.palegreen('in palegreen:')
+    print '  '; print Colours.underline(txt) { :palegreen }
+    e Colours.slateblue('in slateblue:')
+    print '  '; print Colours.underline(txt) { :slateblue }
+    e Colours.orange('in orange:')
+    print '  '; print Colours.underline(txt) { :orange }
+    e Colours.crimson('in crimson:')
+    print '  '; print Colours.underline(txt) { :crimson }
+  else
+    puts Colours.underline(ARGV.join(' ').strip)
+    puts Colours.underline(ARGV.join(' ').strip) { :crimson }
+  end
+end # underline one TWO three