colours 0.5.41

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
+
+  # ========================================================================= #
+  # === Colours::VERSION
+  # ========================================================================= #
+  VERSION = '0.5.41'
+
+  # ========================================================================= #
+  # === Colours::LAST_UPDATE
+  # ========================================================================= #
+  LAST_UPDATE = '23.10.2020'
+
+  # ========================================================================= #
+  # === URL_TO_THE_DOCUMENTATION
+  # ========================================================================= #
+  URL_TO_THE_DOCUMENTATION =
+    "http://www.rubydoc.info/gems/#{self.to_s.downcase}/#{VERSION}"
+
+end

data/lib/colours/yaml/256_colours.yml

@@ -0,0 +1,277 @@
+# =========================================================================== #
+# This file will map the colour-names to the xterm-colour codes.
+#
+# For example, Gold1 will correspond to the number 220.
+#
+# The following list has been taken from:
+#
+#   https://jonasjacek.github.io/colors/
+#
+# However had - that entry has duplicates, such as DeepSkyBlue3: 31
+# and DeepSkyBlue3: 32. Other sites list this as well, though,
+# such as http://0xff.jp/256color.html - so I have simply named it.
+#
+# A similar problem exists for Purple4, which has the numbers 54
+# and 55. This means that, if we are going to use names for these
+# colours then we will not be able to use all 256 colours. If you
+# need all colours, thus, you should use the numbers instead.
+# =========================================================================== #
+# x = YAML.load_file(FILE_256_COLOURS)
+# =========================================================================== #
+
+Black:                0
+Maroon:               1
+Green:                2
+Olive:                3
+Navy:                 4
+Purple:               5
+Teal:                 6
+Silver:               7
+Grey:                 8
+Red:                  9
+Lime:                10
+Yellow:              11
+Blue:                12
+Fuchsia:             13
+Aqua:                14
+White:               15
+Grey0:               16
+NavyBlue:            17
+DarkBlue:            18
+Blue3:               19
+Blue3:               20
+Blue1:               21
+DarkGreen:           22
+DeepSkyBlue4:        23
+DeepSkyBlue4:        24
+DeepSkyBlue4:        25
+DodgerBlue3:         26
+DodgerBlue2:         27
+Green4:              28
+SpringGreen4:        29
+Turquoise4:          30
+DeepSkyBlue3:        31
+DeepSkyBlue3:        32
+DodgerBlue1:         33
+Green3:              34
+SpringGreen3:        35
+DarkCyan:            36
+LightSeaGreen:       37
+DeepSkyBlue2:        38
+DeepSkyBlue1:        39
+Green3:              40
+SpringGreen3:        41
+SpringGreen2:        42
+Cyan3:               43
+DarkTurquoise:       44
+Turquoise2:          45
+Green1:              46
+SpringGreen2:        47
+SpringGreen1:        48
+MediumSpringGreen:   49
+Cyan2:               50
+Cyan1:               51
+DarkRed:             52
+DeepPink4:           53
+Purple4:             54
+Purple4:             55
+Purple3:             56
+BlueViolet:          57
+Orange4:             58
+Grey37:              59
+MediumPurple4:       60
+SlateBlue3:          61
+SlateBlue3:          62
+RoyalBlue1:          63
+Chartreuse4:         64
+DarkSeaGreen4:       65
+PaleTurquoise4:      66
+SteelBlue:           67
+SteelBlue3:          68
+CornflowerBlue:      69
+Chartreuse3:         70
+DarkSeaGreen4:       71
+CadetBlue:           72
+CadetBlue:           73
+SkyBlue3:            74
+SteelBlue1:          75
+Chartreuse3:         76
+PaleGreen3:          77
+SeaGreen3:           78
+Aquamarine3:         79
+MediumTurquoise:     80
+SteelBlue1:          81
+Chartreuse2:         82
+SeaGreen2:           83
+SeaGreen1:           84
+SeaGreen1:           85
+Aquamarine1:         86
+DarkSlateGray2:      87
+DarkRed:             88
+DeepPink4:           89
+DarkMagenta:         90
+DarkMagenta:         91
+DarkViolet:          92
+Purple:              93
+Orange4:             94
+LightPink4:          95
+Plum4:               96
+MediumPurple3:       97
+MediumPurple3:       98
+SlateBlue1:          99
+Yellow4:            100
+Wheat4:             101
+Grey53:             102
+LightSlateGrey:     103
+MediumPurple:       104
+LightSlateBlue:     105
+Yellow4:            106
+DarkOliveGreen3:    107
+DarkSeaGreen:       108
+LightSkyBlue3:      109
+LightSkyBlue3:      110
+SkyBlue2:           111
+Chartreuse2:        112
+DarkOliveGreen3:    113
+PaleGreen3:         114
+DarkSeaGreen3:      115
+DarkSlateGray3:     116
+SkyBlue1:           117
+Chartreuse1:        118
+LightGreen:         119
+LightGreen:         120
+PaleGreen1:         121
+Aquamarine1:        122
+DarkSlateGray1:     123
+Red3:               124
+DeepPink4:          125
+MediumVioletRed:    126
+Magenta3:           127
+DarkViolet:         128
+Purple:             129
+DarkOrange3:        130
+IndianRed:          131
+HotPink3:           132
+MediumOrchid3:      133
+MediumOrchid:       134
+MediumPurple2:      135
+DarkGoldenrod:      136
+LightSalmon3:       137
+RosyBrown:          138
+Grey63:             139
+MediumPurple2:      140
+MediumPurple1:      141
+Gold3:              142
+DarkKhaki:          143
+NavajoWhite3:       144
+Grey69:             145
+LightSteelBlue3:    146
+LightSteelBlue:     147
+Yellow3:            148
+DarkOliveGreen3:    149
+DarkSeaGreen3:      150
+DarkSeaGreen2:      151
+LightCyan3:         152
+LightSkyBlue1:      153
+GreenYellow:        154
+DarkOliveGreen2:    155
+PaleGreen1:         156
+DarkSeaGreen2:      157
+DarkSeaGreen1:      158
+PaleTurquoise1:     159
+Red3:               160
+DeepPink3:          161
+DeepPink3:          162
+Magenta3:           163
+Magenta3:           164
+Magenta2:           165
+DarkOrange3:        166
+IndianRed:          167
+HotPink3:           168
+HotPink2:           169
+Orchid:             170
+MediumOrchid1:      171
+Orange3:            172
+LightSalmon3:       173
+LightPink3:         174
+Pink3:              175
+Plum3:              176
+Violet:             177
+Gold3:              178
+LightGoldenrod3:    179
+Tan:                180
+MistyRose3:         181
+Thistle3:           182
+Plum2:              183
+Yellow3:            184
+Khaki3:             185
+LightGoldenrod2:    186
+LightYellow3:       187
+Grey84:             188
+LightSteelBlue1:    189
+Yellow2:            190
+DarkOliveGreen1:    191
+DarkOliveGreen1:    192
+DarkSeaGreen1:      193
+Honeydew2:          194
+LightCyan1:         195
+Red1:               196
+DeepPink2:          197
+DeepPink1:          198
+DeepPink1:          199
+Magenta2:           200
+Magenta1:           201
+OrangeRed1:         202
+IndianRed1:         203
+IndianRed1:         204
+HotPink:            205
+HotPink:            206
+MediumOrchid1:      207
+DarkOrange:         208
+Salmon1:            209
+LightCoral:         210
+PaleVioletRed1:     211
+Orchid2:            212
+Orchid1:            213
+Orange1:            214
+SandyBrown:         215
+LightSalmon1:       216
+LightPink1:         217
+Pink1:              218
+Plum1:              219
+Gold1:              220
+LightGoldenrod2:    221
+LightGoldenrod2:    222
+NavajoWhite1:       223
+MistyRose1:         224
+Thistle1:           225
+Yellow1:            226
+LightGoldenrod1:    227
+Khaki1:             228
+Wheat1:             229
+Cornsilk1:          230
+Grey100:            231
+Grey3:              232
+Grey7:              233
+Grey11:             234
+Grey15:             235
+Grey19:             236
+Grey23:             237
+Grey27:             238
+Grey30:             239
+Grey35:             240
+Grey39:             241
+Grey42:             242
+Grey46:             243
+Grey50:             244
+Grey54:             245
+Grey58:             246
+Grey62:             247
+Grey66:             248
+Grey70:             249
+Grey74:             250
+Grey78:             251
+Grey82:             252
+Grey85:             253
+Grey89:             254
+Grey93:             255

data/lib/colours/yaml/basic_colours.yml

@@ -0,0 +1,23 @@
+# =========================================================================== #
+# This is essentially an Array keeping track as to which methods are
+# available via ANSI escape codes. Aliases will NOT be stored here -
+# the Array may only list one name for each escape code.
+# =========================================================================== #
+
+- black         # 0;30
+- red           # 0;31
+- green         # 0;32
+- yellow        # 0;33
+- blue          # 0;34
+- magenta       # 0;35
+- cyan          # 0;36
+- light gray    # 0;37
+
+- dark gray     # 1;30
+- light red     # 1;31
+- light green   # 1;32
+- brown         # 1;33
+- light blue    # 1;34
+- light magenta # 1;35
+- light cyan    # 1;36
+- white         # 1;37