colours 0.8.12

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/misc.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 = 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/revert.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal =  true
+# =========================================================================== #
+# require 'colours/toplevel_methods/revert.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/constants/escape.rb'
+
+  # ========================================================================= #
+  # === Colours::COLOUR_NC
+  #
+  # Note that this will actually reset all attributes.
+  #
+  # The "\e[0m" sequence removes all attributes, including formatting
+  # and colours. It may be useful to add it to the end of each colour
+  # text - and this is what the Colours project is essentially doing.
+  #
+  # An alternative may be to assign REVERT to WHITE, but this seems
+  # to be incorrect according to the specification.
+  # ========================================================================= #
+  COLOUR_NC        = "#{ESC}0m" # No Colour.
+    REVERT         = COLOUR_NC    # === REVERT
+    REV            = COLOUR_NC    # === REV
+    CLOSING_TAG    = COLOUR_NC    # === CLOSING_TAG (also represented as "#{ESC}0m")
+    RESET          = COLOUR_NC    # === RESET
+    RESET_TERMINAL = COLOUR_NC    # === RESET_TERMINAL
+    CLEAR          = COLOUR_NC    # === CLEAR
+    COLOUR_RESET   = COLOUR_NC    # === COLOUR_RESET
+    DEFAULT_COLOUR = COLOUR_RESET # === DEFAULT_COLOUR
+
+  # ========================================================================= #
+  # === RESET_ALL_ATTRIBUTES
+  #
+  # This is essentially the same as COLOUR_NC / RESET.
+  # ========================================================================= #
+  RESET_ALL_ATTRIBUTES = "\x1b[0m"
+
+  # ========================================================================= #
+  # === @revert
+  #
+  # We need a variable here in order to be able to change this.
+  # ========================================================================= #
+  @revert = "\e[0;37m"
+
+  # ========================================================================= #
+  # === Colours.set_revert
+  # ========================================================================= #
+  def self.set_revert(i = :default)
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      i = REVERT
+    end
+    @revert = i
+  end
+
+  # ========================================================================= #
+  # === Colours.rev
+  #
+  # We use this method to revert to the old default, that is, the prior
+  # state for ANSI colours. It should be equivalent to: "\x1b[0m" e. g.
+  # REVERT = "\x1b[0m" # "\x1b[39;49m" <--- This here seems to fail for Konsole.underline, though.
+  #
+  # An alternative could be DEFAULT_COLOUR.
+  # ========================================================================= #
+  def self.rev
+    # REVERT # <- This used to be: "\e[0;37m"
+    @revert # This is light white. I prefer this colour actually.
+  end; self.instance_eval { alias revert   rev } # === Colours.revert
+       self.instance_eval { alias revert?  rev } # === Colours.revert?
+       self.instance_eval { alias restore? rev } # === Colours.restore?
+
+  # ========================================================================= #
+  # === rev
+  #
+  # Use this method to "revert" to the old default colour again, by
+  # delegating towards the Colours.rev() method defined above.
+  #
+  # From this point on, we use methods that can be toggled.
+  # ========================================================================= #
+  def rev(i = '')
+    ::Colours.rev # This will refer to the Colours.rev() module method.
+  end; alias revert rev # === revert
+       # alias default_colour rev
+
+  # ========================================================================= #
+  # === restore?
+  #
+  # This will restore to the default again.
+  # ========================================================================= #
+  def restore?
+    Colours.restore?
+  end; alias revert restore? # === revert
+       alias rev?   restore? # === rev?
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  pp Colours.rev
+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/shell_file_containing_the_html_colours.sh

@@ -0,0 +1,148 @@
+# This is a shell file that contains the HTML colours
+export ALICEBLUE="\e[38;2;240;248;255m"
+export ANTIQUEWHITE="\e[38;2;250;235;215m"
+export AQUA="\e[38;2;0;255;255m"
+export AQUAMARINE="\e[38;2;127;255;212m"
+export AZURE="\e[38;2;240;255;255m"
+export BEIGE="\e[38;2;245;245;220m"
+export BISQUE="\e[38;2;255;228;196m"
+export BLACK="\e[38;2;0;0;0m"
+export BLANCHEDALMOND="\e[38;2;255;235;205m"
+export BLUE="\e[38;2;0;0;255m"
+export BLUEVIOLET="\e[38;2;138;43;226m"
+export BROWN="\e[38;2;165;42;42m"
+export BURLYWOOD="\e[38;2;222;184;135m"
+export CADETBLUE="\e[38;2;95;158;160m"
+export CHARTREUSE="\e[38;2;127;255;0m"
+export CHOCOLATE="\e[38;2;210;105;30m"
+export CORAL="\e[38;2;255;127;80m"
+export CORNFLOWERBLUE="\e[38;2;100;149;237m"
+export CORNSILK="\e[38;2;255;248;220m"
+export CRIMSON="\e[38;2;220;20;60m"
+export CYAN="\e[38;2;0;255;255m"
+export DARKBLUE="\e[38;2;0;0;139m"
+export DARKCYAN="\e[38;2;0;139;139m"
+export DARKGOLDENROD="\e[38;2;184;134;11m"
+export DARKGRAY="\e[38;2;169;169;169m"
+export DARKGREEN="\e[38;2;0;100;0m"
+export DARKGREY="\e[38;2;169;169;169m"
+export DARKKHAKI="\e[38;2;189;183;107m"
+export DARKMAGENTA="\e[38;2;139;0;139m"
+export DARKOLIVEGREEN="\e[38;2;85;107;47m"
+export DARKORANGE="\e[38;2;255;140;0m"
+export DARKORCHID="\e[38;2;153;50;204m"
+export DARKRED="\e[38;2;139;0;0m"
+export DARKSALMON="\e[38;2;233;150;122m"
+export DARKSEAGREEN="\e[38;2;143;188;143m"
+export DARKSLATEBLUE="\e[38;2;72;61;139m"
+export DARKSLATEGRAY="\e[38;2;47;79;79m"
+export DARKSLATEGREY="\e[38;2;47;79;79m"
+export DARKTURQUOISE="\e[38;2;0;206;209m"
+export DARKVIOLET="\e[38;2;148;0;211m"
+export DEEPPINK="\e[38;2;255;20;147m"
+export DEEPSKYBLUE="\e[38;2;0;191;255m"
+export DIMGRAY="\e[38;2;105;105;105m"
+export DIMGREY="\e[38;2;105;105;105m"
+export DODGERBLUE="\e[38;2;30;144;255m"
+export FIREBRICK="\e[38;2;178;34;34m"
+export FLORALWHITE="\e[38;2;255;250;240m"
+export FORESTGREEN="\e[38;2;34;139;34m"
+export FUCHSIA="\e[38;2;255;0;255m"
+export GAINSBORO="\e[38;2;220;220;220m"
+export GHOSTWHITE="\e[38;2;248;248;255m"
+export GOLD="\e[38;2;255;215;0m"
+export GOLDENROD="\e[38;2;218;165;32m"
+export GRAY="\e[38;2;128;128;128m"
+export GREY="\e[38;2;128;128;128m"
+export GREEN="\e[38;2;0;128;0m"
+export GREENYELLOW="\e[38;2;173;255;47m"
+export HONEYDEW="\e[38;2;240;255;240m"
+export HOTPINK="\e[38;2;255;105;180m"
+export INDIANRED="\e[38;2;205;92;92m"
+export INDIGO="\e[38;2;75;0;130m"
+export IVORY="\e[38;2;255;255;240m"
+export KHAKI="\e[38;2;240;230;140m"
+export LAVENDER="\e[38;2;230;230;250m"
+export LAVENDERBLUSH="\e[38;2;255;240;245m"
+export LAWNGREEN="\e[38;2;124;252;0m"
+export LEMONCHIFFON="\e[38;2;255;250;205m"
+export LIGHTBLUE="\e[38;2;173;216;230m"
+export LIGHTCORAL="\e[38;2;240;128;128m"
+export LIGHTCYAN="\e[38;2;224;255;255m"
+export LIGHTGOLDENRODYELLOW="\e[38;2;250;250;210m"
+export LIGHTGRAY="\e[38;2;211;211;211m"
+export LIGHTGREY="\e[38;2;211;211;211m"
+export LIGHTGREEN="\e[38;2;144;238;144m"
+export LIGHTPINK="\e[38;2;255;182;193m"
+export LIGHTSALMON="\e[38;2;255;160;122m"
+export LIGHTSEAGREEN="\e[38;2;32;178;170m"
+export LIGHTSKYBLUE="\e[38;2;135;206;250m"
+export LIGHTSLATEGRAY="\e[38;2;119;136;153m"
+export LIGHTSLATEGREY="\e[38;2;119;136;153m"
+export LIGHTSTEELBLUE="\e[38;2;176;196;222m"
+export LIGHTYELLOW="\e[38;2;255;255;224m"
+export LIME="\e[38;2;0;255;0m"
+export LIMEGREEN="\e[38;2;50;205;50m"
+export LINEN="\e[38;2;250;240;230m"
+export MAGENTA="\e[38;2;255;0;255m"
+export MAROON="\e[38;2;128;0;0m"
+export MEDIUMAQUAMARINE="\e[38;2;102;205;170m"
+export MEDIUMBLUE="\e[38;2;0;0;205m"
+export MEDIUMORCHID="\e[38;2;186;85;211m"
+export MEDIUMPURPLE="\e[38;2;147;112;219m"
+export MEDIUMSEAGREEN="\e[38;2;60;179;113m"
+export MEDIUMSLATEBLUE="\e[38;2;123;104;238m"
+export MEDIUMSPRINGGREEN="\e[38;2;0;250;154m"
+export MEDIUMTURQUOISE="\e[38;2;72;209;204m"
+export MEDIUMVIOLETRED="\e[38;2;199;21;133m"
+export MIDNIGHTBLUE="\e[38;2;25;25;112m"
+export MINTCREAM="\e[38;2;245;255;250m"
+export MISTYROSE="\e[38;2;255;228;225m"
+export MOCCASIN="\e[38;2;255;228;181m"
+export NAVAJOWHITE="\e[38;2;255;222;173m"
+export NAVY="\e[38;2;0;0;128m"
+export OLDLACE="\e[38;2;253;245;230m"
+export OLIVE="\e[38;2;128;128;0m"
+export OLIVEDRAB="\e[38;2;107;142;35m"
+export ORANGE="\e[38;2;255;165;0m"
+export ORANGERED="\e[38;2;255;69;0m"
+export ORCHID="\e[38;2;218;112;214m"
+export PALEGOLDENROD="\e[38;2;238;232;170m"
+export PALEGREEN="\e[38;2;152;251;152m"
+export PALETURQUOISE="\e[38;2;175;238;238m"
+export PALEVIOLETRED="\e[38;2;219;112;147m"
+export PAPAYAWHIP="\e[38;2;255;239;213m"
+export PEACHPUFF="\e[38;2;255;218;185m"
+export PERU="\e[38;2;205;133;63m"
+export PINK="\e[38;2;255;192;203m"
+export PLUM="\e[38;2;221;160;221m"
+export POWDERBLUE="\e[38;2;176;224;230m"
+export PURPLE="\e[38;2;128;0;128m"
+export RED="\e[38;2;255;0;0m"
+export ROSYBROWN="\e[38;2;188;143;143m"
+export ROYALBLUE="\e[38;2;65;105;225m"
+export SADDLEBROWN="\e[38;2;139;69;19m"
+export SALMON="\e[38;2;250;128;114m"
+export SANDYBROWN="\e[38;2;244;164;96m"
+export SEAGREEN="\e[38;2;46;139;87m"
+export SEASHELL="\e[38;2;255;245;238m"
+export SIENNA="\e[38;2;160;82;45m"
+export SILVER="\e[38;2;192;192;192m"
+export SKYBLUE="\e[38;2;135;206;235m"
+export SLATEBLUE="\e[38;2;106;90;205m"
+export SLATEGRAY="\e[38;2;112;128;144m"
+export SLATEGREY="\e[38;2;112;128;144m"
+export SNOW="\e[38;2;255;250;250m"
+export SPRINGGREEN="\e[38;2;0;255;127m"
+export STEELBLUE="\e[38;2;70;130;180m"
+export TAN="\e[38;2;210;180;140m"
+export TEAL="\e[38;2;0;128;128m"
+export THISTLE="\e[38;2;216;191;216m"
+export TOMATO="\e[38;2;255;99;71m"
+export TURQUOISE="\e[38;2;64;224;208m"
+export VIOLET="\e[38;2;238;130;238m"
+export WHEAT="\e[38;2;245;222;179m"
+export WHITE="\e[38;2;255;255;255m"
+export WHITESMOKE="\e[38;2;245;245;245m"
+export YELLOW="\e[38;2;255;255;0m"
+export YELLOWGREEN="\e[38;2;154;205;50m"

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'
+# =========================================================================== #
+module Colours
+
+  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'
+
+  # ========================================================================= #
+  # === 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 # showbasiccolourpalette

data/lib/colours/toplevel_methods/underline.rb

@@ -0,0 +1,130 @@
+#!/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/toplevel_methods/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[#{UNDERLINE_CODE}m".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
+    return result
+  end; self.instance_eval { alias string_underline return_underline } # === Colours.string_underline
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  if ARGV.empty?
+    e Colours.underline('Hello world!')
+    e '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