colours 0.6.12

data/lib/colours/toplevel_methods/use_colours.rb

@@ -0,0 +1,290 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/toplevel_methods/use_colours.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/toplevel_methods/set_last_colour_used.rb'
+
+  # ========================================================================= #
+  # === @use_colours
+  #
+  # Whether we will use colours or whether we will not. This can be
+  # used to globally disable colours in every project using the
+  # Colours gem.
+  # ========================================================================= #
+  @use_colours = true
+
+  # ========================================================================= #
+  # === @use_html_colours
+  #
+  # This is a separate variable so that we can selectively disable or
+  # enable the colours for the Konsole submodule. Some terminals do
+  # not respond nicely to the R,G,B values that the Konsole submodule
+  # may require.
+  # ========================================================================= #
+  @use_html_colours = true
+
+  # ========================================================================= #
+  # === Colours.use_colours?
+  #
+  # Use this method to find out whether we wish to use colours or
+  # whether we do not.
+  # ========================================================================= #
+  def self.use_colours?
+    @use_colours
+  end
+
+  # ========================================================================= #
+  # === Colours.enable_html_colours
+  #
+  # Use this method to specifically enable konsole-colours.
+  # ========================================================================= #
+  def self.enable_html_colours
+    @use_html_colours = true
+  end; self.instance_eval { alias enable_konsole_colours enable_html_colours } # === Colours.enable_konsole_colours
+
+  # ========================================================================= #
+  # === Colours.disable_konsole_colours
+  #
+  # Disable the KDE-Konsole colours.
+  # ========================================================================= #
+  def self.disable_konsole_colours
+    @use_html_colours = false
+  end
+
+  # ========================================================================= #
+  # === Colours.use_html_colours?
+  #
+  # Query whether we will use the HTML colours or whether we will not.
+  # ========================================================================= #
+  def self.use_html_colours?
+    @use_html_colours
+  end; self.instance_eval { alias use_konsole?         use_html_colours? } # === Colours.use_konsole?
+       self.instance_eval { alias use_konsole_colours? use_html_colours? } # === Colours.use_konsole_colours??
+
+  # ========================================================================= #
+  # === Colours.disable_colours
+  #
+  # This method can be used to disable the colours on the Colours
+  # namespace.
+  # ========================================================================= #
+  def self.disable_colours(
+      be_verbose = false
+    )
+    puts 'Disabling colours next.' if be_verbose
+    @use_colours = false
+  end; self.instance_eval { alias disable disable_colours } # === Colours.disable
+
+  # ========================================================================= #
+  # === Colours.enable_colours
+  #
+  # Use this method to enable colours for the whole Colours namespace.
+  # ========================================================================= #
+  def self.enable_colours(
+      be_verbose = false
+    )
+    puts 'Enabling colours next.' if be_verbose
+    @use_colours = true # Defined below.
+  end; self.instance_eval { alias enable enable_colours } # === Colours.enable
+
+  # ========================================================================= #
+  # === Colours.use_colours=
+  #
+  # Determine whether we will use colours or whether we will not.
+  #
+  # The first input argument to this method should be a Bool, such
+  # as true or false.
+  # ========================================================================= #
+  def self.use_colours=(
+      new_value = true
+    )
+    @use_colours = new_value
+  end; self.instance_eval { alias set_use_colours use_colours= } # === Colours.set_use_colours
+
+  # ========================================================================= #
+  # === use_colours?
+  #
+  # Delegate towards the class-method here. Unsure whether this method
+  # is really needed, but let's keep it for now. After all we can
+  # use "include Colours" to add that method.
+  # ========================================================================= #
+  def use_colours?
+    Colours.use_colours?
+  end
+
+  # ========================================================================= #
+  # === Colours.report_whether_colours_will_be_used
+  # ========================================================================= #
+  def self.report_whether_colours_will_be_used
+    if @use_colours
+      puts 'Yes, colours will be used.'
+    else
+      puts 'Colours are currently disabled.'
+    end
+  end
+
+# =========================================================================== #
+# This file includes a standalone Colour class, as part of the
+# Colours namespace.
+# =========================================================================== #
+class Colour # === Colours::Colour
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      optional_input = nil
+    )
+    reset
+    set_input(optional_input) if optional_input
+  end
+
+  # ========================================================================= #
+  # === set_r
+  # ========================================================================= #
+  def set_r(i = nil)
+    @r = i
+  end
+
+  # ========================================================================= #
+  # === set_g
+  # ========================================================================= #
+  def set_g(i = nil)
+    @g = i
+  end
+
+  # ========================================================================= #
+  # === set_b
+  # ========================================================================= #
+  def set_b(i = nil)
+    @b = i
+  end
+
+  # ========================================================================= #
+  # === random_colour?
+  # ========================================================================= #
+  def random_colour?(
+      optional_text = nil
+    )
+    if optional_text
+      write_this_in_random_colour(optional_text)
+    else
+      ::Colours.random_colour?
+    end
+  end
+
+  # ========================================================================= #
+  # === set_rgb
+  # ========================================================================= #
+  def set_rgb(r,g,b)
+    set_r(r)
+    set_g(g)
+    set_b(b)
+  end
+
+  # ========================================================================= #
+  # === set_input
+  # ========================================================================= #
+  def set_input(i = nil)
+    @input = i
+  end
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+    set_r
+    set_g
+    set_b
+  end
+
+  # ========================================================================= #
+  # === r?
+  # ========================================================================= #
+  def r?
+    @r
+  end
+
+  # ========================================================================= #
+  # === g?
+  # ========================================================================= #
+  def g?
+    @g
+  end
+
+  # ========================================================================= #
+  # === b?
+  # ========================================================================= #
+  def b?
+    @b
+  end
+
+  # ========================================================================= #
+  # === output_this_string
+  # ========================================================================= #
+  def output_this_string(
+      i = DEFAULT_TEXT+N,
+      r = r?,
+      g = g?,
+      b = b?
+    )
+    result = return_this_string(i,r,g,b)
+    e result
+  end; alias output_this                 output_this_string # === output_this
+       alias output                      output_this_string # === output
+       alias write_this_in_random_colour output_this_string # === write_this_in_random_colour
+
+  # ========================================================================= #
+  # === return_this_string
+  # ========================================================================= #
+  def return_this_string(
+      i = DEFAULT_TEXT+N,
+      r = r?,
+      g = g?,
+      b = b?
+    )
+    i = DEFAULT_TEXT if i == :default
+    i = i.join(' ') if i.is_a? Array
+    i = i.to_s.dup
+    i = build_this_rgb_string(r, g, b)+i
+    return i
+  end
+
+  # ========================================================================= #
+  # === build_this_rgb_string
+  # ========================================================================= #
+  def build_this_rgb_string(r, g, b)
+    Colours.build_this_rgb_string(r,g,b)
+  end
+
+  # ========================================================================= #
+  # === random_colour
+  #
+  # Return a random colour here.
+  # ========================================================================= #
+  def random_colour(this_string_to_display = 'test')
+    return_this_string(
+      this_string_to_display, random_value, random_value, random_value
+    )
+  end; alias return_random_colour random_colour # === return_random_colour
+
+  # ========================================================================= #
+  # === seed_rgb_values
+  #
+  # Use this method to randomly obtain R,G,B values.
+  # ========================================================================= #
+  def seed_rgb_values
+    set_rgb(random_value, random_value, random_value)
+  end
+
+  # ========================================================================= #
+  # === random_value
+  # ========================================================================= #
+  def random_value
+    rand(255)
+  end
+
+end; end

data/lib/colours/utility_scripts/README.md

@@ -0,0 +1,2 @@
+This directory will contain code that is mostly "supportive" of the
+Colours project, but normally won't be needed for most users.

data/lib/colours/utility_scripts/autogenerate.rb

@@ -0,0 +1,291 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file contains code that can be used to autogenerate ruby code,
+# and store this into a .rb file. That functionality is mostly useful
+# on my home system, though.
+# =========================================================================== #
+# require 'colours/utility_scripts/autogenerate.rb'
+# =========================================================================== #
+module Colours
+
+  require 'colours/constants/file_constants.rb'
+  require 'colours/constants/newline.rb'
+  require 'colours/256_colours/support_for_256_colours.rb'
+  require 'colours/toplevel_methods/is_on_roebe.rb'
+  require 'colours/toplevel_methods/html_colourize.rb'
+  require 'colours/html_colours/misc.rb'
+
+  # ========================================================================= #
+  # === GENERIC_RUBY_HEADER
+  # ========================================================================= #
+  GENERIC_RUBY_HEADER = "#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #"
+
+  # ========================================================================= #
+  # === Colours.return_a_unique_array_containing_all_available_colours
+  # ========================================================================= #
+  def self.return_a_unique_array_containing_all_available_colours
+    array = []
+    array << YAML.load_file(FILE_HTML_COLOURS).keys                # (1) First the HTML colours
+    array << YAML.load_file(FILE_256_COLOURS).keys.map(&:downcase) # (2) Then the basic colours
+    array << YAML.load_file(FILE_BASIC_COLOURS)                    # (3) And finally the basic colours
+    array.flatten!
+    array.uniq!
+    array.map!(&:strip)
+    array.sort
+  end; self.instance_eval { alias all_available_colour_methods? return_a_unique_array_containing_all_available_colours } # === Colours.all_available_colour_methods?
+
+  # ========================================================================= #
+  # === Colours.generate_shell_file_containing_the_html_colours
+  #
+  # This method will generate a shell file into the current directory
+  # by default.
+  #
+  # The code in that file will generate a shell script that holds all
+  # the HTML-colours, via UPCASED names.
+  #
+  # These entries will then look like this:
+  #
+  #   SADDLEBROWN:  "\e[38;2;139;69;19m"
+  #   PERU:         "\e[38;2;205;133;63m"
+  #   CHOCOLATE:    "\e[38;2;210;105;30m"
+  #
+  # ========================================================================= #
+  def self.generate_shell_file_containing_the_html_colours(
+      generate_the_shell_file_into_this_directory = Dir.pwd
+    )
+    require 'save_file/module'
+    unless generate_the_shell_file_into_this_directory.end_with? '/'
+      if generate_the_shell_file_into_this_directory.frozen?
+        generate_the_shell_file_into_this_directory = generate_the_shell_file_into_this_directory.dup
+      end
+      generate_the_shell_file_into_this_directory << '/'
+    end
+    result = ''.dup
+    result << "# This is a shell file that contains the HTML colours\n"
+    ::Colours.html_colours?.each {|this_colour|
+      colour_code_to_use = ::Colours.html_colourize(this_colour.to_sym,'',false).inspect
+      result << "export #{this_colour.upcase}=#{colour_code_to_use}\n"
+    }
+    generate_the_shell_file_into_this_directory << 'shell_file_containing_the_html_colours.sh'
+    into = generate_the_shell_file_into_this_directory
+    e "Now creating a shell file at `#{into}`."
+    SaveFile.write_what_into(result, into)
+    # ======================================================================= #
+    # Generate files on my home system as well:
+    # ======================================================================= #
+    if is_on_roebe?
+      into = '/home/x/DATA/PROGRAMMING_LANGUAGES/RUBY/src/'\
+             'roebe/lib/roebe/shell_scripts/'+
+             File.basename(generate_the_shell_file_into_this_directory)
+      puts "And also saving into `#{into}`."
+      SaveFile.write_what_into(result, into)
+    end
+  end; self.instance_eval { alias autogenerate_shell_file_containing_the_html_colours generate_shell_file_containing_the_html_colours } # === Colours.autogenerate_shell_file_containing_the_html_colours
+
+  # ========================================================================= #
+  # === Colours.autogenerate_the_module_for_the_256_colours
+  #
+  # This method will autogenerate the module that will support
+  # the 256 colours.
+  # ========================================================================= #
+  def self.autogenerate_the_module_for_the_256_colours
+    _ = ''.dup
+    _ << GENERIC_RUBY_HEADER+"
+# require 'colours/autogenerated/support_for_256_colours.rb'
+# =========================================================================== #
+"
+    _ << "require 'colours/256_colours/support_for_256_colours.rb'\n\n"
+    _ << "module Colours\n\n"
+    _ << "module SupportFor256Colours # include Colours::SupportFor256Colours\n\n".dup
+    comment_line = '  # '+('='*73)+' #'+N
+    @dataset_for_the_256_colours.each {|name_of_the_colour, id|
+      use_this_name = name_of_the_colour.downcase
+      _ << comment_line
+      _ << '  # === Colours::SupportFor256Colours.'+use_this_name+N
+      _ << comment_line
+      _ << "  def self.#{use_this_name}(i = '')#{N}"
+      _ << "    if Colours.use_colours?\n"
+      _ << "      Colours.return_this_256_colour(__method__, i)\n"
+      _ << "    else\n"
+      _ << "      i\n"
+      _ << "    end\n"
+      _ << "  end; def #{use_this_name}(i = ''); SupportFor256Colours.#{use_this_name}(i); end#{N}#{N}"
+    }
+    _ << 'end; end'
+    what = _
+    # ======================================================================= #
+    # This is only useful on my home system really:
+    # ======================================================================= #
+    into = HOME_DIRECTORY_OF_USER_X+'DATA/PROGRAMMING_LANGUAGES/RUBY/src/'\
+           'colours/lib/colours/autogenerated/support_for_256_colours.rb'
+    puts 'Storing into:'
+    puts
+    puts '  '+into
+    puts
+    require 'save_file'
+    SaveFile.write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === Colours.autogenerate_the_module_for_the_html_colours
+  #
+  # This method will autogenerate the module that will support
+  # the html colours.
+  # ========================================================================= #
+  def self.autogenerate_the_module_for_the_html_colours(
+      into = HOME_DIRECTORY_OF_USER_X+'DATA/PROGRAMMING_LANGUAGES/RUBY/src/'\
+             'colours/lib/colours/autogenerated/support_for_html_colours.rb'
+    )
+    _ = ''.dup
+    _ << GENERIC_RUBY_HEADER+"
+# require 'colours/autogenerated/support_for_html_colours.rb'
+# =========================================================================== #
+"
+    _ << "require 'colours/toplevel_methods/html_colourize.rb'\n"
+    _ << "require 'colours/toplevel_methods/use_colours.rb'\n\n"
+    _ << "module Colours\n\n"
+    _ << "module SupportForHTMLColours # include Colours::SupportForHTMLColours\n\n".dup
+    comment_line = '  # '+('='*73)+' #'+N
+    available_html_colours?.each {|name_of_the_html_colour|
+      _ << comment_line
+      _ << '  # === Colours::SupportForHTMLColours.'+name_of_the_html_colour+N
+      _ << comment_line
+      _ << "  def self.#{name_of_the_html_colour}(i = '', &block)\n"
+      _ << "    if Colours.use_html_colours?\n"
+      _ << "      Colours.html_colourize(__method__, i, &block)\n"
+      _ << "    else\n"
+      _ << "      i\n"
+      _ << "    end\n"
+      _ << "  end; def #{name_of_the_html_colour}(i = '', &block); SupportForHTMLColours.#{name_of_the_html_colour}(i, &block); end#{N}"
+      # ===================================================================== #
+      # Next, due to several reasons, we add a prepended "konsole_colour_"
+      # as name to this method.
+      # ===================================================================== #
+      _ << "       def konsole_colour_#{name_of_the_html_colour}(i = '', &block); SupportForHTMLColours.#{name_of_the_html_colour}(i, &block); end#{N}#{N}"
+    }
+    _ << 'end; end'
+    what = _
+    # ======================================================================= #
+    # This is only useful on my home system really:
+    # ======================================================================= #
+    puts 'Storing into:'
+    puts
+    puts '  '+into
+    puts
+    require 'save_file'
+    SaveFile.write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === Colours.autogenerate_toplevel_basic_colour_methods
+  #
+  # The code in this method will autogenerate the toplevel colour
+  # methods, such as Colours.yellow().
+  #
+  # The code needs to respect several settings. For example, whether colours
+  # are used or not. Additionally, for methods such as Colours.yellow(),
+  # we need to find out whether we use the basic colours, the 256-colours or
+  # the HTML colours, and call the corresponding method in these cases.
+  # ========================================================================= # 
+  def self.autogenerate_toplevel_basic_colour_methods(
+      into = HOME_DIRECTORY_OF_USER_X+'DATA/PROGRAMMING_LANGUAGES/RUBY/src/'\
+             'colours/lib/colours/autogenerated/toplevel_basic_colour_methods.rb'
+    )
+    comment_line = "  # ======================================================================== \n"
+    store_this_string = ''.dup
+    header = <<-EOF
+#{GENERIC_RUBY_HEADER}
+# This file contains the code that will call the corresponding colour method
+# depending on which colour-mode the user prefers.
+# =========================================================================== #
+# require 'colours/autogenerated/toplevel_basic_colour_methods.rb'
+# =========================================================================== #
+require 'colours/toplevel_methods/use_colours.rb'
+require 'colours/basic_colours/basic_colours.rb'
+require 'colours/256_colours/support_for_256_colours.rb'
+require 'colours/autogenerated/support_for_html_colours.rb'
+
+module Colours
+
+module AllColourMethods # include Colours::AllColourMethods
+
+EOF
+
+    store_this_string << header
+    # ======================================================================= #
+    # First define the methods for the basic colours:
+    # ======================================================================= #
+    array = return_a_unique_array_containing_all_available_colours
+    array.each {|this_basic_colour| # <- e. g. "yellow".
+      this_basic_colour = this_basic_colour.dup
+      if this_basic_colour.include?(' ') and
+         array.include?(this_basic_colour.delete(' '))
+        # =================================================================== #
+        # === This must be an alias
+        #
+        # In this case we will also add an alias containing the '_' part.
+        # We will only add this as an alias for include-actions, though.
+        # (This may change at a later point in the future - not sure yet.)
+        # =================================================================== #
+        store_this_string << "       def #{this_basic_colour.tr(' ','_')}(i = ''); AllColourMethods.#{this_basic_colour.delete(' ')}(i); end\n"
+      else
+        name_of_the_method = this_basic_colour.downcase.delete(' ').dup
+        store_this_string << comment_line
+        store_this_string << "  # === Colours::AllColourMethods.#{name_of_the_method}\n"
+        store_this_string << comment_line
+        store_this_string << "  def self.#{name_of_the_method}(i = '', &block)\n"
+        store_this_string << "    if Colours.use_colours?\n"
+        # =================================================================== #
+        # Ok, so we determine what to do with this colour-method:
+        # =================================================================== #
+        store_this_string << "      if Colours.is_this_a_html_colour?(__method__)\n"
+        store_this_string << "        Colours::SupportForHTMLColours.#{name_of_the_method}(i, &block)\n"
+        store_this_string << "      elsif Colours.is_this_a_256_colour?(__method__)\n"
+        store_this_string << "        Colours::SupportFor256Colours.#{name_of_the_method}(i, &block)\n"
+        store_this_string << "      else\n"
+        store_this_string << "        Colours::BasicColours.#{name_of_the_method}(i, &block)\n"
+        store_this_string << "      end\n"
+        store_this_string << "    else\n"
+        store_this_string << "      i\n"
+        store_this_string << "    end\n"
+        store_this_string << "  end; def #{name_of_the_method}(i = '', &block); AllColourMethods.#{name_of_the_method}(i, &block); end\n"
+        # =================================================================== #
+        # Next, due to several reasons, we add a prepended "konsole_colour_"
+        # as name to this method.
+        # =================================================================== #
+        store_this_string << "       def konsole_colour_#{name_of_the_method}(i = ''); AllColourMethods.#{name_of_the_method}(i); end\n"
+        store_this_string << "       def konsole_#{name_of_the_method}(i = ''); AllColourMethods.#{name_of_the_method}(i); end\n"
+        store_this_string << "       self.instance_eval { alias konsole_colour_#{name_of_the_method} #{name_of_the_method} } # === Colours::AllColourMethods.konsole_colour_#{name_of_the_method}\n"
+        store_this_string << "       def Colours.e#{name_of_the_method}(i = ''); puts AllColourMethods.#{name_of_the_method}(i); end\n"
+        store_this_string << "       def e#{name_of_the_method}(i = ''); puts AllColourMethods.#{name_of_the_method}(i); end\n"
+        store_this_string << "       alias ekonsole_colour_#{name_of_the_method} e#{name_of_the_method}\n"
+        store_this_string << "\n"
+      end
+    }
+    store_this_string << "end; end\n"
+    what = store_this_string .dup
+    # ======================================================================= #
+    # This is only useful on my home system really:
+    # ======================================================================= #
+    puts 'Storing into the file:'
+    puts
+    puts "  #{into}"
+    puts
+    require 'save_file'
+    File.delete(into) if File.exist? into # Get rid of the old file.
+    SaveFile.write_what_into(what, into)
+  end; self.instance_eval { alias define_colour_methods autogenerate_toplevel_basic_colour_methods } # === Colours.define_colour_methods
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Colours.autogenerate_shell_file_containing_the_html_colours
+  Colours.autogenerate_the_module_for_the_256_colours
+  Colours.autogenerate_the_module_for_the_html_colours
+  Colours.autogenerate_toplevel_basic_colour_methods
+end # autogenerate_colours

data/lib/colours/version/version.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/version/version.rb'
+# =========================================================================== #
+module Colours
+
+  # ========================================================================= #
+  # === VERSION
+  # ========================================================================= #
+  VERSION = '0.6.12'
+
+  # ========================================================================= #
+  # === LAST_UPDATE
+  # ========================================================================= #
+  LAST_UPDATE = '15.09.2022'
+
+  # ========================================================================= #
+  # === URL_TO_THE_DOCUMENTATION
+  # ========================================================================= #
+  URL_TO_THE_DOCUMENTATION =
+    "https://www.rubydoc.info/gems/#{self.to_s.downcase}/#{VERSION}"
+
+end