colours 0.8.12

data/doc/todo/todo.md

@@ -0,0 +1,25 @@
+-------------------------------------------------------------------------------
+(1) → integrate rainbow into the
+      Colours gem, at the least the core functionality from:
+        http://www.rubydoc.info/gems/rainbow/2.1.0
+
+require 'rainbow'; x = Rainbow("hola!").blue.bright.underline; pp x; ''
+"\e[34m\e[1m\e[4mhola!\e[0m"
+# ^^^
+
+    e Rainbow("hola!").blue.bright.underline
+    e Colours("hola!").blue.bright.underline
+
+Colours('hi').red
+^^^ as a first step enable this.
+and then document it as well.
+
+This works fairly well now, since as of November 2022. 
+
+We may have to still check whether we implement all of it
+or not.
+-------------------------------------------------------------------------------
+(2) → in colours. fix the italic part. The problem is that the default
+      colour is not restored correctly so. We may need to simplify
+      this eventually.
+-------------------------------------------------------------------------------

data/lib/colours/256_colours/support_for_256_colours.rb

@@ -0,0 +1,196 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'colours/256_colours/support_for_256_colours.rb'
+# =========================================================================== #
+module Colours
+
+  require 'yaml'
+  require 'colours/constants/misc.rb'
+  require 'colours/constants/newline.rb'
+  require 'colours/constants/file_constants.rb'
+  require 'colours/toplevel_methods/revert.rb'
+
+  # ========================================================================= #
+  # === @dataset_for_the_256_colours
+  #
+  # We will keep the keys in a downcased variant, as this will make it
+  # easier to use them as method-names.
+  # ========================================================================= #
+  if File.exist?(FILE_256_COLOURS) # Must safeguard.
+    @dataset_for_the_256_colours = YAML.load_file(FILE_256_COLOURS).
+                                   transform_keys(&:downcase)
+  else
+    @dataset_for_the_256_colours = nil
+  end
+
+  # ========================================================================= #
+  # === Colours.return_this_256_colour
+  #
+  # The first argument to this method should be a number from 0 to 255.
+  #
+  # For example, 255 is also known as "Grey93" - a variant of grey.
+  #
+  # It appears to work better if you use print() rather than puts() for
+  # whatever is returned here - perhaps due to the leading \u001b part.
+  #
+  # You can also input the colour variant, such as 'Grey93'. 
+  #
+  # Invocation example:
+  #
+  #   Colours.return_this_256_colour(255, "Hello world in grey!\n")
+  #   print Colours.return_this_256_colour(255, (Roebe.block_character*5)+"  Hello world in grey!  "+(Roebe.block_character*5)+" \n")
+  #   print Colours.return_this_256_colour('DarkTurquoise', (Roebe.block_character*5)+"  Hello world in DarkTurquoise!  "+(Roebe.block_character*5)+" \n")
+  #
+  # ========================================================================= #
+  def self.return_this_256_colour(
+      id            = 9,
+      use_this_text = "Hello world!"
+    )
+    id = id.to_s.downcase
+    if (id !~ /^\d+/) and @dataset_for_the_256_colours and
+      @dataset_for_the_256_colours.has_key?(id)
+      id = @dataset_for_the_256_colours[id]
+    end
+    "\u001b[38;5;#{id}m#{use_this_text}#{REVERT}"
+  end
+
+  # ========================================================================= #
+  # === Colours.write_this_in_256_colours
+  #
+  # Similar to the other write method, but has the arguments reversed. 
+  # ========================================================================= #
+  def self.write_this_in_256_colours(
+      this_text = "Hello world!\n",
+      id        = rand(256),
+      &block
+    )
+    display_this_256_colour(id, this_text, &block)
+  end; self.instance_eval { alias write_in_256_colour write_this_in_256_colours } # === Colours.write_in_256_colour
+
+  # ========================================================================= #
+  # === write_in_256_colour
+  #
+  # Include-able method to the above module-level instance.
+  # ========================================================================= #
+  def write_in_256_colour(
+      i  = 'hi there',
+      id = 33
+    )
+    write_this_in_256_colours(i, id)
+  end
+
+  # ========================================================================= #
+  # === Colours.display_this_256_colour
+  #
+  # The first argument should be a number from 0 to 255.
+  #
+  # You can also batch-output all colours, by using something like:
+  #
+  #   Colours.display_this_256_colour('0-255',"Hello world, in a batch!\n")
+  #
+  # Generic usage example:
+  #
+  #   Colours.display_this_256_colour(33, 'yo there') { :newline }
+  #
+  # ========================================================================= #
+  def self.display_this_256_colour(
+      id            = 9,
+      use_this_text = "Hello world!\n",
+      &block
+    )
+    if block_given?
+      yielded = yield
+      case yielded
+      when :newline
+        use_this_text = use_this_text.dup if use_this_text.frozen?
+        use_this_text << "\n"
+      end
+    end
+    if id.is_a?(String) and id.include?('-')
+      # ===================================================================== #
+      # Assume pseudo-range input.
+      # ===================================================================== #
+      splitted = id.split('-')
+      range = (splitted.first.to_i .. splitted.last.to_i).to_a
+      range.each {|this_range_id|
+        display_this_256_colour(this_range_id, use_this_text, &block)
+      }
+    else
+      print return_this_256_colour(id, use_this_text)
+    end
+  end; self.instance_eval { alias display_this_in_256_colour display_this_256_colour } # === Colours.display_this_in_256_colour
+
+  # ========================================================================= #
+  # === Colours.show_all_256_colours
+  # ========================================================================= #
+  def self.show_all_256_colours
+    yielded = nil
+    if block_given?
+      yielded = yield
+    end
+    0.upto(255).each {|this_number|
+      result = this_number.to_s.rjust(4)+' '+
+               return_this_256_colour(this_number).to_s.dup
+      if yielded and yielded == :newline
+        result << "\n"
+      end
+      print result
+    }
+  end
+
+  # ========================================================================= #
+  # === Colours.show_256_colour_cube
+  #
+  # This will show the 256-colours cube. Colours 16-231 are a
+  # 6x6x6 color cube.
+  # ========================================================================= #
+  def self.show_256_colour_cube
+    puts 'Color cube, 6x6x6 blocks:'
+    0.upto(5) {|green|
+      0.upto(5) {|red|
+        0.upto(5) {|blue|
+          colour = 16 + (red * 36) + (green * 6) + blue
+          print "\x1b[48;5;#{colour}m  "
+        }
+        print "\x1b[0m "
+      }
+      puts
+    }
+  end
+
+  # ========================================================================= #
+  # === Colours.is_this_a_256_colour?
+  #
+  # Invocation example:
+  #
+  #   Colours.is_this_a_256_colour? 'LightSteelBlue3'
+  #
+  # ========================================================================= #
+  def self.is_this_a_256_colour?(i)
+    if @dataset_for_the_256_colours
+      @dataset_for_the_256_colours.keys.map(&:downcase).include?(i.to_s.downcase)
+    else
+      false
+    end
+  end
+
+  # ========================================================================= #
+  # === is_this_a_256_colour?
+  # ========================================================================= #
+  def is_this_a_256_colour?(i)
+    ::Colours.is_this_a_256_colour?(i)
+  end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  Colours.show_256_colour_cube
+  # The next line can be found in: colours/test/testing_256_colours_support.rb
+  # Colours.test_256_colours_support
+  e
+  Colours.display_this_256_colour('0-255',"Hello world, in a batch!\n")
+  e
+end # supportfor256colours

data/lib/colours/autoalias_e.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file is deliberately not included by default.
+# =========================================================================== #
+# Usage example:
+#   require 'colours/autoalias_e'
+# =========================================================================== #
+alias e puts

data/lib/colours/autogenerated/README.md

@@ -0,0 +1,2 @@
+This directory will contain autogenerated code - that is, code that
+has been autogenerated from the Colours gem itself.