colours 0.5.48

data/lib/colours/toplevel_methods/fancy_parse.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/fancy_parse.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/toplevel_methods/bold.rb'
+  require 'colours/toplevel_methods/italic.rb'
+  require 'colours/toplevel_methods/methods_related_to_html_colours.rb'
+  require 'colours/toplevel_methods/underline.rb'
+
+  # ========================================================================= #
+  # === Colours.fancy_parse
+  #
+  # This method can be used to parse a line containing special tags,
+  # such as <i> or <teal>, and replace them with the corresponding
+  # ASCII code for the commandline. The second example, e. g. <teal>,
+  # is known as a HTML colour tag (htmlcolour).
+  #
+  # The idea for this method is to simply use it to quickly colourize
+  # some arbitrary text.
+  #
+  # The method will only return the resulting, sanitizing String; if
+  # you wish to display this on the terminal/commandline then you
+  # will have to use puts or print on your own.
+  #
+  # Usage example:
+  #
+  #   Colours.fancy_parse '<i>hey</i> <teal>there</teal>'
+  #
+  # ========================================================================= #
+  def self.fancy_parse(i = '')
+    if i.is_a? Array
+      i = i.join
+    end
+    i = i.dup # Work on a copy.
+    # ======================================================================= #
+    # === Handle italic tags, aka <i>
+    # ======================================================================= #
+    if i.include?('<i>') and
+       i.include?('</i>')
+      use_this_regex = /<i>(.+)<\/i>/
+      i.gsub!(
+        use_this_regex,
+        return_italic('\1')
+      )
+    end
+    # ======================================================================= #
+    # === Handle bold tags, aka <b>
+    # ======================================================================= #
+    if i.include?('<b>') and
+       i.include?('</b>')
+      use_this_regex = /<b>(.+)<\/b>/
+      i.gsub!(
+        use_this_regex,
+        return_bold('\1')
+      )
+    end
+    # ======================================================================= #
+    # Finally, handle all HTML colours in the given line.
+    # ======================================================================= #    
+    i = replace_all_html_colours_in_this_line(i)
+    i
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  result = Colours.fancy_parse(ARGV)
+  puts result
+  # pp result # <- This line is just for simple debugging.
+end # fancy_parse "<lightgreen><i>hey</i></lightgreen> <teal>there</teal>"
+    # fancy_parse "<tomato>hey</tomato> <teal>there</teal>"
+    # fancy_parse "<tomato><i>hey</i></tomato> <teal>there</teal>"
+    # fancy_parse "<tomato><b><i>hey</i></b></tomato> <teal>there</teal>"
+    # fancy_parse "<tomato><b><i>hey</i></b></tomato> <teal>there</teal> <b>how do you do</b>"
+    # fancy_parse "<tomato><b>Hello world.</b></tomato>"

data/lib/colours/toplevel_methods/html_colourize.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/html_colourize.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/rgb/rgb.rb'
+  require 'colours/revert/revert.rb'
+
+  # ========================================================================= #
+  # === Colours.html_colourize
+  #
+  # This method will simply return the colour-code + text.
+  #
+  # The third argument, called `append_revert`, can be used to determine
+  # whether we will append the revert code to the generated output String
+  # or whether we will not. By default we will, but there are examples
+  # where we may wish to assemble our own colour string, and in these
+  # cases we do not yet know which text is to be shown - hence, this
+  # must become an optional argument.
+  #
+  # A block can be passed to this method. If the block has, as content,
+  # the Symbol :omit_end then the end-part of the ANSI code will not
+  # be used.
+  #
+  # Usage examples:
+  #
+  #   x = Colours.colourize('slateblue', 'Hello world!'); pp x
+  #   y = Colours.colourize('slateblue', 'Hello world!') { :omit_end }; pp y
+  #
+  # ========================================================================= #
+  def self.html_colourize(
+      colour_to_use = return_random_html_colour,
+      this_text     = nil,
+      append_revert = true,
+      &block
+    )
+    if block_given?
+      yielded = yield
+      case yielded
+      when :omit_end
+        append_revert = false
+      end
+    end
+    if this_text.nil?
+      this_text = colour_to_use.to_s.dup
+    end
+    if append_revert
+      "#{rgb_value_as_escape_code_string(colour_to_use)}#{this_text}#{revert}"
+    else
+      "#{rgb_value_as_escape_code_string(colour_to_use)}#{this_text}"
+    end
+  end; self.instance_eval { alias colourize       html_colourize } # === Colours.colourize
+       self.instance_eval { alias kde_colour      html_colourize } # === Colours.kde_colour
+       self.instance_eval { alias konsole_colours html_colourize } # === Colours.konsole_colours
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts Colours.html_colourize('slateblue', 'Hello world 1!')
+  puts Colours.html_colourize(:crimson, 'Hello world 2!')
+end

data/lib/colours/toplevel_methods/is_on_roebe.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/is_on_roebe.rb'
+# =========================================================================== #
+module Colours
+
+  # ========================================================================= #
+  # === Colours.is_on_roebe?
+  # ========================================================================= #
+  def self.is_on_roebe?
+    ENV['IS_ROEBE'].to_s == '1'
+  end
+
+end

data/lib/colours/toplevel_methods/italic.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/italic.rb'
+# =========================================================================== #
+require 'colours/revert/revert.rb'
+require 'colours/toplevel_methods/e.rb'
+require 'colours/rgb/rgb.rb'
+
+module Colours
+
+  # ========================================================================= #
+  # === ITALIC_CODE
+  #
+  # If you wish to test italic output quickly on the terminal, then you
+  # can use something like this:
+  #
+  #   echo -e "\e[3mone two three\e[23m"
+  #
+  # ========================================================================= #
+  ITALIC_CODE = '3'
+
+  # ========================================================================= #
+  # === Colours.return_italic
+  #
+  # To test this, try:
+  #   Colours.italic('Hello world!')
+  # ========================================================================= #
+  def self.return_italic(
+      show_this_text = 'This must be italic.', 
+      make_newline   = false
+    )
+    result = "\x1b".dup
+    result << '['
+    result << ITALIC_CODE
+    if block_given?
+      # ===================================================================== #
+      # Right now we assume that this must be a colour.
+      # ===================================================================== #
+      result << ";38;2;"
+      result << html_colour_to_stringified_rgb_values(yield)
+    end
+    result << 'm'
+    if make_newline
+      show_this_text = "#{show_this_text}\n"
+    end
+    result << show_this_text
+    result << REVERT
+    result
+  end; self.instance_eval { alias string_italic return_italic } # === Colours.string_italic
+
+  # ========================================================================= #
+  # === Colours.italic
+  #
+  # This method will "puts" the result of applying italic 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_italic or its
+  # alias called Colours.string_italic.
+  #
+  # To test this, try:
+  #   Colours.italic('Hello world!')
+  # ========================================================================= #
+  def self.italic(
+      i            = '', 
+      make_newline = false,
+      &block
+    )
+    e return_italic(i, make_newline, &block)
+  end
+
+  # ========================================================================= #
+  # === italic
+  # ========================================================================= #
+  def italic(
+      i            = '',
+      make_newline = false
+    )
+    ::Colours.italic(i, make_newline)
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  txt = 'Hello world!'
+  if ARGV.empty?
+    require 'colours/requires/require_all_colour_methods.rb'
+    COLOURS = Colours::AllColourMethods
+    system 'clear'
+    Colours.italic(txt)
+    e COLOURS.palegreen('italic in palegreen:')
+    print '  '; puts Colours.string_italic(txt) { :palegreen }
+    e COLOURS.slateblue('italic in slateblue:')
+    print '  '; puts Colours.string_italic(txt) { :slateblue }
+    e COLOURS.orange('italic in orange:')
+    print '  '; puts Colours.string_italic(txt) { :orange }
+    e COLOURS.crimson('italic in crimson:')
+    print '  '; puts Colours.string_italic(txt) { :crimson }
+  else
+    print '  '; puts Colours.string_italic(ARGV.join(' ').strip)
+    print '  '; puts Colours.string_italic(ARGV.join(' ').strip) { :crimson }
+  end
+end # italic

data/lib/colours/toplevel_methods/make_colour.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/make_colour.rb'
+# =========================================================================== #
+require 'colours/constants/colour_constants.rb'
+require 'colours/constants/misc.rb'
+require 'colours/toplevel_methods/e.rb'
+
+module Colours
+
+  # ========================================================================= #
+  # === Colours.make_colour
+  #
+  # This is used primarily for testing.
+  # ========================================================================= #
+  def self.make_colour(
+      what_colour_to_use
+    )
+    i = what_colour_to_use # Copy.
+    constant = i.to_s.upcase
+    name_of_colour = const_get(constant)
+    string = '%-34s' % ("#{name_of_colour} Test with #{constant}.")
+    string << IS_A_TEST+'('+name_of_colour.inspect.delete('"')+')'
+    e(string)
+  end
+
+end

data/lib/colours/toplevel_methods/methods_related_to_html_colours.rb

@@ -0,0 +1,325 @@
+#!/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
+      # ===================================================================== #
+      # 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'  => :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/lNUo2JvuN2GrYg
+            #
+            # =============================================================== #
+            /<#{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.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.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 }
+    result = result.dup
+    # ======================================================================= #
+    # 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.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 # html_colour_to_hex_value slateblue