colours 0.8.12

data/lib/colours/toplevel_methods/methods_related_to_html_colours.rb

@@ -0,0 +1,336 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file will hold code that relates to the html-colours, such as
+# "steelblue" or "royalblue" and so forth.
+# =========================================================================== #
+# require 'colours/toplevel_methods/methods_related_to_html_colours.rb'
+# Colours.html_colour_to_hex_value(ARGV)
+# =========================================================================== #
+module Colours
+  
+  require 'colours/html_colours/html_colours.rb'
+  require 'colours/autogenerated/toplevel_basic_colour_methods.rb'
+
+  # ========================================================================= #
+  # === REGEX_FOR_HTML_COLOURS
+  #
+  # This regex supports the use case where we can match against HTML
+  # colours. (The name is a bit of a misnomer, though.)
+  #
+  # For the following regex, see this entry at rubular:
+  #
+  #   https://rubular.com/r/o5r4DneMTGOsbX
+  #
+  # ========================================================================= #
+  REGEX_FOR_HTML_COLOURS =
+    /<([()a-zA-Z0-9²→\n]+?)>/
+
+  # ========================================================================= #
+  # === USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR
+  #
+  # Here we specify the default colour to be used, in order to revert
+  # to the prior colour in use. This can be modified by the user,
+  # in order to conform to other colours if said user wishes to
+  # do so.
+  # ========================================================================= #
+  USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR = :grey
+
+  # ========================================================================= #
+  # === Colours.return_main_regex_to_use_for_obtaining_the_full_content
+  #
+  # The first regex that is commented out, in the body of this method,
+  # was in use until May 2023. It was then replaced with the new
+  # regex, which also has an associated test-case, in the test/
+  # subdirectory of the colours gem.
+  #
+  # For the current regex see here:
+  #
+  #   https://rubular.com/r/1dpSmYqQ9SVvMt
+  #
+  # I was also using a second regex that was slightly incompatible.
+  # For legacy reasons it can be seen here: https://rubular.com/r/sDNQd81MtciMJL
+  # ========================================================================= #
+  def self.return_main_regex_to_use_for_obtaining_the_full_content(this_colour)
+    # /<#{this_colour}>([\-\{\}\[\]\\\(\)\/a-zA-Z0-9’éúÄäÖöÜüÅαβß&%+−=≡πμ°₁₂₃₄₅₆₇₈₉⁰¹²³⁴⁵⁶⁷⁸⁹⁻!#\*~:;∨"',_\|\n\. ]+)<\/#{this_colour}>/
+    # /<#{this_numbered_word}>([-#~≥!\e=><;,→⁻⁺@^„“γαµ_₀₁₂₃₄₅₆₇₈₉²³⁴⁵⁶⁷⁸⁹äöüÄÖÜβß%&:≡°$A-Za-z0-9\n \?\\'\|\(\)\{\}\[\]\"\*\.\+]+)<\/#{this_numbered_word}>/
+    /<#{this_colour}>([\n₀₁₂₃₄₅₆₇₈₉⁰¹²³⁴⁵⁶⁷⁸⁹°→⁻⁺≥$@σπµμγ∨^αβßÅÄäéúÖöÜüa-zA-Z0-9’'"„“~#&%!,;:_+−=≡<>\*\\\/\.\{\}\(\)\|\[\]\?\- ]*?)<\/#{this_colour}>/
+  end
+
+  # ========================================================================= #
+  # === Colours.replace_number_words_with_the_corresponding_html_colour
+  #
+  # The input to this method should be the String that contains HTML
+  # numbers such as <one> or <two>.
+  #
+  # This method can be customized a bit. One way to customize it is
+  # to pass the default colour to this method, as second argument.
+  # The default colour is (currently, in Oct 2020) grey.
+  #
+  # The third argument is a Hash. This Hash can be used to denote the
+  # default colours for <one>, <two> and so forth. So if you want
+  # to change the colours, pass in your own Hash into this method.
+  #
+  # Usage examples:
+  #
+  #   x = Colours.replace_number_words_with_the_corresponding_html_colour("- <teal>Asbestbedingte Erkrankungen</teal> haben eine <two>Latenzzeit</two> von etwa n Jahren? Etwa <steelblue>30 Jahren</steelblue>.")
+  #   x = "<one>Methämoglobin</one> ist <two>ungeeignet</two> für <three>den</three> Sauerstofftransport; die <two>roten Blutkörperchen</two>. Welches Enzymsystem ist dies?"
+  #   y = Colours.replace_number_words_with_the_corresponding_html_colour(x)
+  #
+  # See also:
+  #
+  #   https://rubular.com/r/XUPQJFKlDs2OYP
+  #
+  # ========================================================================= #
+  def self.replace_number_words_with_the_corresponding_html_colour(
+      i,
+      use_this_as_replacement_hash = :default
+    )
+    # ======================================================================= #
+    # Specify our "replacement-hash", that is colours used for e. g.
+    # <one>, <two> or <three>.
+    # ======================================================================= #
+    case use_this_as_replacement_hash
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         :default_hash
+      # ===================================================================== #
+      # The following hash can be used as a default "replacement" Hash.
+      # ===================================================================== #
+      use_this_as_replacement_hash = {
+        one:            :teal,
+        two:            :lightseagreen,
+        three:          :mediumseagreen, # ← Used to be 'peru' up until 23.11.2019.
+        four:           :mediumorchid,   # ← Used to be 'olivedrab' up until 06.12.2022.
+        five:           :lightgreen,
+        default_colour: USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR # Defined on top.
+      }
+    end
+    # ======================================================================= #
+    # === :default_colour
+    # ======================================================================= #
+    if use_this_as_replacement_hash.has_key? :default_colour
+      use_this_colour_for_the_default_colour = use_this_as_replacement_hash[:default_colour]
+    end
+    # ======================================================================= #
+    # === Enable support for <one>, <two>, <three>, <four> and <five> next.
+    # ======================================================================= #
+    if i.include?('<one>')   or
+       i.include?('<two>')   or
+       i.include?('<three>') or
+       i.include?('<four>')  or
+       i.include?('<five>')
+      scanned_results = i.scan(
+        REGEX_FOR_HTML_COLOURS
+      ).flatten.uniq
+      scanned_results.each {|this_numbered_word|
+        # =================================================================== #
+        # Since as of December 2021 we only accept Symbols here.
+        # =================================================================== #
+        this_numbered_word = this_numbered_word.to_sym
+        if use_this_as_replacement_hash.has_key? this_numbered_word
+          i = i.dup if i.frozen?
+          replacement_colour = use_this_as_replacement_hash[this_numbered_word]
+          use_this_regex =
+            # =============================================================== #
+            # We will simply re-use the regex-generator near the top of this
+            # file here.
+            # =============================================================== #
+            ::Colours.return_main_regex_to_use_for_obtaining_the_full_content(this_numbered_word)
+          # ================================================================= #
+          # We must use .gsub!() because the colour-string may occur more
+          # than once.
+          # ================================================================= #
+          i.gsub!(
+            use_this_regex,
+            ::Colours::AllColourMethods.send(replacement_colour.to_sym, "\\1")       { :omit_end }+
+            ::Colours::AllColourMethods.send(use_this_colour_for_the_default_colour) { :omit_end }
+          )
+          # i << ::Colours.revert
+        end
+      }
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === Colours.replace_html_colours_in_this_string
+  #
+  # This method will replace all HTML colours in a given string, such as 
+  # "<slateblue>test</slateblue>", with the corresponding RGB colour 
+  # variant for the commandline.
+  #
+  # Typically this refers to a terminal such as the KDE Konsole, and a
+  # shell such as bash (although other shells are fine too, and many
+  # other terminals, such as the gnome-terminal, most likely will work
+  # fine as well - but it is optimized for the KDE Konsole). 
+  #
+  # This method should only be called after a prior check was done,
+  # to determine whether the given input String at hand does indeed
+  # include a valid HTML colour; otherwise it would be fairly pointless
+  # to invoke this method, if it is already known that the String at
+  # hand does not contain any HTML colour at all. In order to
+  # determine whether a String may include a valid HTML colour,
+  # the method called line_contains_a_valid_html_colour?() can be
+  # used.
+  #
+  # Usage example:
+  #
+  #   Colours.replace_html_colours_in_this_string
+  #   Colours.replace_html_colours_in_this_string('- The <one>UID</one> of <royalblue>the</royalblue> user called <two>root</two> is ... ? <one>0</one>.', :lightgreen)
+  #
+  # ========================================================================= #
+  def self.replace_html_colours_in_this_string(
+      i,
+      use_this_colour_for_the_default_colour = :default, # ← This specifies the default colour.
+      shall_we_revert_at_the_end_of_the_line = true
+    )
+    i = i.dup # We want to work on a copy.
+    result = ''.dup # Our result-string.
+    case use_this_colour_for_the_default_colour
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         :default_colour
+      use_this_colour_for_the_default_colour = USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR
+    end
+    case shall_we_revert_at_the_end_of_the_line
+    # ======================================================================= #
+    # === :revert
+    # ======================================================================= #
+    when :revert
+      shall_we_revert_at_the_end_of_the_line = true
+    end
+    result << ::Colours::AllColourMethods.send(use_this_colour_for_the_default_colour) { :omit_end }
+    # result = result.dup
+    # ======================================================================= #
+    # This method will make use of two different regexes.
+    # ======================================================================= #
+    scanned_results = i.scan(
+      REGEX_FOR_HTML_COLOURS
+    ).flatten.uniq
+    add_on_string = i.dup
+    # ======================================================================= #
+    # scanned_results may be an Array such as ['steelblue', 'tomato']
+    # ======================================================================= #
+    scanned_results.each {|this_colour|
+      if is_this_a_valid_html_colour?(this_colour)
+        # =================================================================== #
+        # We must use .gsub!() because the colour-string may occur more 
+        # than once. Unfortunately for longer Strings this becomes a bit
+        # fragile.
+        # =================================================================== #
+        part1 = ::Colours::AllColourMethods.send(this_colour.to_sym, "\\1") { :omit_end }
+        part2 = ::Colours::AllColourMethods.send(use_this_colour_for_the_default_colour) { :omit_end }
+        add_on_string.gsub!(
+          ::Colours.return_main_regex_to_use_for_obtaining_the_full_content(this_colour),
+          part1+part2
+        ).dup
+      end
+    }
+    result << add_on_string
+    if shall_we_revert_at_the_end_of_the_line
+      result << ::Colours.revert
+    end
+    return result
+  end; self.instance_eval { alias replace_html_colours                      replace_html_colours_in_this_string } # === Colours.replace_html_colours
+       self.instance_eval { alias replace_all_raw_html_colours_in_this_line replace_html_colours_in_this_string } # === Colours.replace_all_raw_html_colours_in_this_line
+       self.instance_eval { alias replace_all_html_colours_in_this_line     replace_html_colours_in_this_string } # === Colours.replace_all_html_colours_in_this_line
+       self.instance_eval { alias parse_html_colour                         replace_html_colours_in_this_string } # === Colours.parse_html_colour
+
+  # ========================================================================= #
+  # === Colours.does_this_string_include_a_html_colour?
+  # ========================================================================= #
+  def self.does_this_string_include_a_html_colour?(i)
+    result = (i =~ REGEX_FOR_HTML_COLOURS)
+    result = false if result.nil?
+    result
+  end
+
+  # ========================================================================= #
+  # === Colours.does_this_string_include_a_html_number?
+  #
+  # This method will return true if the string includes tags such as
+  # <one> or <two> and so forth.
+  # ========================================================================= #
+  def self.does_this_string_include_a_html_number?(i)
+    i.include?('<one>')   or
+    i.include?('<two>')   or
+    i.include?('<three>') or
+    i.include?('<four>')  or
+    i.include?('<five>')
+  end
+
+  # ========================================================================= #
+  # === Colours.eliminate_html
+  #
+  # This method simply combines two other methods, without any further
+  # checks inside of this method. The method will thus remove entries
+  # such as <one> or <steelblue>.
+  # ========================================================================= #
+  def self.eliminate_html(
+      i,
+      use_this_colour_for_the_default_colour = :default,
+      use_this_as_replacement_hash           = :default_hash
+    )
+    i = i.dup
+    i = Colours.replace_number_words_with_the_corresponding_html_colour(
+      i,
+      use_this_colour_for_the_default_colour,
+      use_this_as_replacement_hash
+    )
+    i = i.dup
+    i = Colours.replace_html_colours_in_this_string(
+      i,
+      use_this_colour_for_the_default_colour
+    )
+    return i.dup
+  end; self.instance_eval { alias away_with_html_colours_and_special_numbers eliminate_html } # === Colours.away_with_html_colours_and_special_numbers
+       self.instance_eval { alias remove_html_tags_and_special_words         eliminate_html } # === Colours.remove_html_tags_and_special_words
+       self.instance_eval { alias remove_crap                                eliminate_html } # === Colours.remove_crap
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  input = ARGV
+  if input.empty?
+    input << 'steelblue'
+  end
+  e 'Testing: Colours.html_colour_to_hex_value(ARGV) next'
+  e Colours.html_colour_to_hex_value(input)
+  e "Testing: Colours.does_this_string_include_a_html_number?('abc <one>def</one>') next"
+  puts Colours.does_this_string_include_a_html_number?('abc <one>def</one>')
+  # ========================================================================= #
+  # Test the behaviour of the method next:
+  # ========================================================================= #
+  this_line = "- <lightseagreen>hey</lightseagreen> yo <green>there</green>"
+  puts Colours.replace_html_colours(
+    this_line
+  )
+  puts Colours.does_this_string_include_a_html_colour?('<steelblue>')
+  e
+  e Colours.replace_number_words_with_the_corresponding_html_colour(
+    "- <teal>Asbestbedingte Erkrankungen</teal> haben eine <two>Latenzzeit</two> von etwa n Jahren? Etwa <steelblue>30 Jahren</steelblue>."
+  )
+  x = "<one>Methämoglobin</one> ist <two>ungeeignet</two> für <three>den</three> Sauerstofftransport; die <two>roten Blutkörperchen</two>. Welches Enzymsystem ist dies?"
+  e Colours.replace_number_words_with_the_corresponding_html_colour(x)
+  e Colours.replace_html_colours_in_this_string("<one>Methämoglobin</one> ist <steelblue>ungeeignet</steelblue>.")
+  e
+  string = "- <teal>Asbestbedingte Erkrankungen</teal> haben eine <two>Latenzzeit</two> von etwa n Jahren? Etwa <steelblue>30 Jahren</steelblue>."
+  e string
+  e Colours.replace_html_colours_in_this_string(
+    string
+  )
+  e
+  result = Colours.replace_all_html_colours_in_this_line(' |<steelblue>E</steelblue>]', :default, :revert)
+  e result
+  e
+  e 'And it looks like this via pp:'
+  e
+  pp result
+end # htmlcolourtohexvalue slateblue

data/lib/colours/toplevel_methods/misc.rb

@@ -0,0 +1,226 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/misc.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/html_colours/html_colours.rb'
+  require 'colours/toplevel_methods/esystem.rb'
+  require 'colours/toplevel_methods/open_this_file.rb'
+  require 'colours/toplevel_methods/remove_escape_sequence.rb'
+
+  # ========================================================================= #
+  # === Colours.colour_method_or_display_the_content_of_the_file_or_use_via_pipe
+  #
+  # This method has an awful name, but its core use case is simple.
+  #
+  # It will handle commandline instructions such as:
+  #
+  #   orange Hey there
+  #   slateblue how are you doing?
+  #
+  # Usage example from within ruby:
+  #
+  #   Colours.testing123('abc', :orange)
+  #
+  # ========================================================================= #
+  def self.colour_method_or_display_the_content_of_the_file_or_use_via_pipe(
+      i                  = ARGF,
+      name_of_the_colour = $PROGRAM_NAME
+    )
+    require 'colours/autogenerated/support_for_html_colours.rb'
+    # ======================================================================= #
+    # === :read
+    # ======================================================================= #
+    if i.respond_to? :read
+      i = i.read
+    elsif i and File.exist?(i)
+      i = File.read(i)
+    end
+    i = Colours.remove_trailing_end_from(i)
+    if i.is_a? Array
+      i = i.join(' ').strip
+    end
+    if name_of_the_colour
+      if name_of_the_colour.respond_to?(:include?) and
+         name_of_the_colour.include?('/')
+        name_of_the_colour = File.basename(name_of_the_colour)
+      end
+    end
+    name_of_the_colour = name_of_the_colour.to_sym
+    return ::Colours::SupportForHTMLColours.send(name_of_the_colour, i)
+  end
+
+  # ========================================================================= #
+  # === Colours.sanitize_line
+  #
+  # This method will replace one line with the proper R,G,B valid entries.
+  # ========================================================================= #
+  def self.sanitize_line(entry)
+    all_potential_matches = entry.scan(/<(\w+)>/).flatten
+    all_potential_matches.each {|substring|
+      entry.gsub!(/<\/>/, rev)
+      entry.gsub!(/<#{substring}>/, rgb_format(substring))
+    }
+    begin
+      require 'roebe/modules/remove_html.rb'
+    rescue LoadError; end
+    if Object.const_defined?(:Roebe) and
+       Roebe.respond_to?(:remove_html)
+      entry = Roebe.remove_html[entry]
+    end
+    return entry
+  end
+
+  # ========================================================================= #
+  # === Colours.read_and_display_this_file
+  #
+  # This method accepts a file path - in other words, the input should be
+  # the location of a specific file on your filesystem - and then simply
+  # reads in the content of said file via File.readlines().
+  #
+  # Content such as <slateblue> found in this file will be replaced
+  # with the respective R,G,B substring value.
+  #
+  # In the test/ subdirectory there is an example file for this - have
+  # a look there for more information.
+  # ========================================================================= #
+  def self.read_and_display_this_file(
+      i = TEST_FILE
+    )
+    i = i.to_s
+    if File.exist? i
+      new_array = []
+      data = File.readlines(i)
+      data.each {|entry|
+        # ======================================================================= #
+        # Check whether the entry has a <> tag:
+        # ======================================================================= #
+        if entry.include?('<') and entry.include?('>') and 
+           entry.include?('</>')
+          # ================================================================= #
+          # Ok, we may assume that something like <slateblue> is there.
+          # ================================================================= #
+          entry = sanitize_line(entry)
+        end
+        new_array << entry
+      }
+      e new_array # For now we will simply output that modified Array.
+    else
+      e "Notice: The file at `#{sfile(i)}` does not exist."
+    end
+  end; self.instance_eval { alias read_file read_and_display_this_file } # === Colours.read_file
+
+  # ========================================================================= #
+  # === Colours.does_this_line_include_a_html_colour?
+  #
+  # This method can be used to determine whether the given input-string
+  # contains a valid HTML colour or whether it does not.
+  #
+  # Returns: a boolean.
+  #
+  # Invocation examples:
+  #
+  #   Colours.does_this_line_include_a_html_colour? "<green>yo there</green> <orange>getline() function</orange>" # => true
+  #   Colours.does_this_line_include_a_html_colour? "foo bar" # => false
+  #
+  # ========================================================================= #
+  def self.does_this_line_include_a_html_colour?(
+      line
+    )
+    html_colours?.any? {|entry|
+      line.include? entry
+    }
+  end
+
+  # ========================================================================= #
+  # === Colours.convert_hex_to_rgb
+  #
+  # This method will convert e. g. #baf185 to [186, 241, 133]. Thus it
+  # will return an Array, denoting the R, G, B values.
+  #
+  # How to do this conversion on your own?
+  #
+  #   (1) Get the 2 left digits of the hex color code and convert
+  #       to decimal value to get the red color level.
+  #   (2) Get the 2 middle digits of the hex color code and
+  #       convert to decimal value to get the green color level.
+  #   (3) Get the 2 right digits of the hex color code and
+  #       convert to decimal value to get the blue color level.
+  #
+  # Usage example:
+  #
+  #   Colours.convert_hex_to_rgb('#baf185') # => [186, 241, 133]
+  #
+  # ========================================================================= #
+  def self.convert_hex_to_rgb(hex)
+    if hex.is_a? Array
+      hex = hex.first
+    end
+    hex = hex.to_s.dup
+    hex.delete!('#') if hex.include? '#'
+    array = [] # We will return this Array.
+    r = hex[0,2].to_i(16)
+    g = hex[2,2].to_i(16)
+    b = hex[4,2].to_i(16)
+    array << r << g << b
+    return array
+  end; self.instance_eval { alias hex_to_rgb convert_hex_to_rgb } # === Colours.hex_to_rgb
+
+  # ========================================================================= #
+  # === Colours.convert_hex_code_to_RGBA_array
+  #
+  # RGBA stands for "red, green, blue, alpha". Alpha indicates how
+  # opaque each pixel is.
+  #
+  # The usual values for the alpha parameter, aka the last parameter,
+  # is a number between 0.0 (which means "fully transparent") and
+  # the number 1.0 (which means "not transparent at all").
+  #
+  # Note that this method is similar to Colours.convert_hex_to_rgb(hex),
+  # but it has a fourth argument, aka A (for Alpha), on top of
+  # the RGB values.
+  #
+  # Usage example:
+  #
+  #   Colours.convert_hex_code_to_RGBA_array('#baf185') # => [186, 241, 133]
+  #
+  # ========================================================================= #
+  def self.convert_hex_code_to_RGBA_array(
+      i, default_alpha_value = 1.0
+    )
+    rgba_array = convert_hex_to_rgb(i)
+    rgba_array << default_alpha_value
+    return rgba_array
+  end
+
+  # ========================================================================= #
+  # === Colours.reset_the_line
+  #
+  # This method will reset the current line. This can then be used in a
+  # progress indicator application.
+  # ========================================================================= #
+  def self.reset_the_line
+    STDOUT.write("\u001b[1000D") # Move to the left by 1000 characters. Aka reset.
+    STDOUT.flush # This line will force the output to appear immediately, 
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # ========================================================================= #
+  # Example code demonstrating the method defined above:
+  # ========================================================================= #
+  index = 1
+  loop {
+    Colours.reset_the_line
+    print 'OK! '+
+           Random.rand(11).to_s 
+    index += 1
+    break if index == 50
+    sleep 0.3
+  }
+  puts
+end

data/lib/colours/toplevel_methods/open_this_file.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/open_this_file.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/toplevel_methods/esystem.rb'
+
+  # ========================================================================= #
+  # === Colours.open_this_file
+  # ========================================================================= #
+  def open_this_file(
+      shall_we_exit = false
+    )
+    case shall_we_exit
+    when :then_exit
+      shall_we_exit = true
+    end
+    _ = "bluefish #{__FILE__}"
+    esystem(_)
+    exit if shall_we_exit
+  end
+
+end

data/lib/colours/toplevel_methods/prefer_this_colour_schemata.rb

@@ -0,0 +1,88 @@
+#!/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
+    # === :html_colours
+    when :html_colours
+      @use_html_colours = true
+    # === :support_for_256_colours
+    when :support_for_256_colours
+      @use_256_colours = true
+    # === :basic_colours
+    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