colours 0.5.41

data/lib/colours/toplevel_methods/methods_related_to_html_colours.rb

@@ -0,0 +1,314 @@
+#!/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 'yaml'
+  require 'colours/constants/file_constants.rb'
+  require 'colours/html_colours/is_this_html_colour_included.rb'
+  require 'colours/autogenerated/toplevel_basic_colour_methods.rb'
+
+  # ========================================================================= #
+  # === USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR
+  # ========================================================================= #
+  USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR = :grey
+
+  # ========================================================================= #
+  # === 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]+?)>/
+
+  # ========================================================================= #
+  # === 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_colour_for_the_default_colour = :default,
+      use_this_as_replacement_hash           = :default
+    )
+    case use_this_colour_for_the_default_colour
+    when :default
+      use_this_colour_for_the_default_colour = USE_THIS_COLOUR_FOR_THE_DEFAULT_COLOUR
+    end
+    # ======================================================================= #
+    # Specify our "replacement-hash", that is colours used for e. g.
+    # <one>, <two> or <three>.
+    # ======================================================================= #
+    case use_this_as_replacement_hash
+    when :default,
+         :default_hash
+      use_this_as_replacement_hash = {
+        'one'   => :teal,
+        'two'   => :lightseagreen,
+        'three' => :mediumseagreen, # ← Used to be 'peru' up until 23.11.2019.
+        'four'  => :olivedrab,
+        'five'  => :lightgreen
+      }
+    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|
+        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 =
+            # =============================================================== #
+            # See:
+            #
+            #   https://rubular.com/r/A7cJMTVSqbghej
+            #
+            # =============================================================== #
+            /<#{this_numbered_word}>([-#~≥!\e=><;,→⁻⁺@^„“γα_₂₃₄₅²äöüÄÖÜβß%&:≡°$A-Za-z0-9\n \?\\'\|\(\)\{\}\[\]\"\*\.\+]+)<\/#{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
+    i
+  end
+
+  # ========================================================================= #
+  # === 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.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 a bit pointless
+  # to invoke the 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
+  #
+  # ========================================================================= #
+  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 = false
+    )
+    i = i.dup # We want to work on a copy.
+    result = ''.dup # Our result-string.
+    case use_this_colour_for_the_default_colour
+    when :default
+      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
+    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 }
+    # ======================================================================= #
+    # This method will make use of two different regexes.
+    # ======================================================================= #
+    scanned_results = i.scan(
+      REGEX_FOR_HTML_COLOURS
+    ).flatten
+    add_on_string = i.dup
+    scanned_results.uniq.each {|this_colour|
+      if is_this_a_valid_html_colour?(this_colour)
+        # =================================================================== #
+        # === Defining the Regex in use
+        #
+        # Regex see:
+        #
+        #   https://rubular.com/r/5oYax0SCz7R7I6
+        #
+        # =================================================================== #
+        use_this_regex =
+          /<#{this_colour}>([\[\]\\{}\(\)\/!\-#*~:;≡=+a-zA-Z0-9₁₂₃₄₅₆äöüÄÖÜαβß&%°"',_\|\n\. ]+)<\/#{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!(use_this_regex, 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
+
+  # ========================================================================= #
+  # === Colours.html_colour_to_hex_value
+  # ========================================================================= #
+  def self.html_colour_to_hex_value(
+      this_html_colour,
+      return_with_hash_key = true
+    )
+    if this_html_colour.is_a? Array
+      this_html_colour = this_html_colour.first
+    end
+    _ = file_html_colours_to_rgb?
+    if File.exist? _
+      dataset = YAML.load_file(_)
+      if dataset.has_key? this_html_colour
+        _ = dataset[this_html_colour].last
+        if return_with_hash_key
+          _ = _.dup if _.frozen?
+          _ = _.to_s unless _.is_a? String
+          _[0,0] = '#' if _.respond_to? :[]=
+        end
+        return _
+      end
+    end
+    return this_html_colour
+  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 = Colours.replace_number_words_with_the_corresponding_html_colour(
+      i, use_this_colour_for_the_default_colour, use_this_as_replacement_hash
+    )
+    i = Colours.replace_html_colours_in_this_string(
+      i, use_this_colour_for_the_default_colour
+    )
+    return i
+  end; self.instance_eval { alias away_with_html_colours_and_special_numbers eliminate_html } # === Colours.away_with_html_colours_and_special_numbers
+
+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 # html_colour_to_hex_value slateblue

data/lib/colours/toplevel_methods/misc.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/misc.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/toplevel_methods/esystem.rb'
+  require 'colours/toplevel_methods/open_this_file.rb'
+  require 'colours/html_colours/misc.rb'
+
+  # ========================================================================= #
+  # === 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
+    )
+    Colours.html_colours?.any? {|entry|
+      line.include? entry
+    }
+  end
+
+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'
+# =========================================================================== #
+require 'colours/toplevel_methods/esystem.rb'
+
+module Colours
+
+  # ========================================================================= #
+  # === self.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,80 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/prefer_this_colour_schemata.rb'
+# =========================================================================== #
+require 'colours/html_colours/add_html_colours_onto_the_toplevel_namespace.rb'
+require 'colours/autogenerated/support_for_html_colours.rb'
+
+module Colours
+
+  # ========================================================================= #
+  # === @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".
+  # ========================================================================= #
+  @prefer_this_colour_schemata = YAML.load_file(FILE_PREFER_THIS_COLOUR_SCHEMATA)
+
+  # ========================================================================= #
+  # === @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.
+  # ========================================================================= #
+  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
+
+  # ========================================================================= #
+  # === Colours.prefer_which_colour_schemata?
+  # ========================================================================= #
+  def self.prefer_which_colour_schemata?
+    @prefer_this_colour_schemata[1]
+  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,44 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/random_html_colour.rb'
+# =========================================================================== #
+require 'colours/html_colours/misc.rb'
+
+module Colours
+
+# =========================================================================== #
+# === 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_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