colours 0.6.12

data/README.md

@@ -0,0 +1,970 @@
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/colours.svg)](https://badge.fury.io/rb/colours)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">15.09.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">18:08:12</span> o'clock.
+
+# The Colours project
+
+## Goals, Scope and the History of the colours project
+
+The Colours project originated from a requirement to have to support **colours**
+on the commandline. Colours can be immensely helpful, so it makes sense
+to make use of them on the commandline. The modern www also makes use of
+colours - just look at any random webpage; you may find lots of
+different colours in use there.
+
+If you do happen to take a look on the projects offered on rubygems.org then
+you may be able to find **lots** of different colour-related projects, written
+in ruby. The primary reason as to why I created a new colour-centric project
+was because I needed certain functionality that was not provided by any of
+the other projects; at the least not in a way as I thought it should be
+available (and used in downstream projects). For example, some terminals
+support **RGB values** and other terminals do not. I did not want to have
+to spend time thinking about this much at all, so I wanted to have a
+colours-related project that could abstract this away for me.
+
+![alt text][screenshot1]
+[screenshot1]: https://i.imgur.com/F6kac8W.png
+
+The **main goal** of the **colours project** is to collect colour-related
+code and make this code available to other projects, so that these projects
+can benefit from colour support.
+
+The primary goal herein is for **commandline applications**, but there
+are some HTML components as part of this project that could be used,
+such as for when you wish to make use of **HTML colours** (slateblue,
+royalblue, teal, tomato, steelblue and names such as these). The
+partial screenshot above indicates this, on a black **KDE konsole**
+background. (I tend to prefer dark backgrounds for my terminals.)
+
+Note that many **terminals** support the **display of HTML colours**, via
+their **corresponding RGB values**. Since I wanted to use good terminals,
+such as the **KDE konsole**, the colours project also had to support
+these names (such as **slateblue** or **royalblue**) directly. This is
+why method calls such as **Colours.royalblue()** will also work - see
+for a later subsection how to customize (and control) this.
+
+The **Colours gem** has other, older projects, such as AnsiColours,
+ColourE, AliasE and several other smaller sub-projects that I have
+used over the years, integrated. It is thus a **bundled project**. This
+is specifically mentioned in the event that you may wish to look at
+the code, and wonder a little why it is structured the way it is.
+
+## Requiring the colours project
+
+To require the colours project, do:
+
+    require 'colours'
+
+You can also **autoinclude** this module into your project, at
+<b>require-time</b>, via:
+
+    require 'colours/autoinclude'
+
+This will make the **Colours namespace** and the
+**Colours::HtmlColours namespace** available, via 
+**include Colours** ultimately.
+
+If you need more control over the include-action then you should
+just use the first variant, require 'colours', and then do the
+include action specifically onto whatever class/module you need
+that functionality.
+
+## Introduction and Overview
+
+The toplevel module name is **Colours** and you can include
+this module in any of your classes, via:
+
+    require 'colours'
+
+    include Colours
+
+If you include Colours into main (toplevel), then you can simply
+use the colour-constants directly:
+
+    puts RED+'This is a red text.'
+    puts BLUE+'This will be in blue.'
+
+Keep in mind when you use something like the above, with the
+leading escape-code for RED or BLUE, then this is missing the
+proper escape-code for **end** (**revert**). This value is
+usually **\e[0;37m**, or simpler, use **Colours.rev()** such
+as in:
+
+    puts RED+'This is a red text.'+Colours.rev
+    puts BLUE+'This will be in blue.'+Colours.rev
+
+The corresponding colour-methods can also be used:
+
+    red 'This is a red text.'
+    blue 'This is a blue text.'
+
+This has the advantage that you do not have to use
+Colours.rev anymore. So in some ways the colour-named
+methods are better. (Of course it is a bit complicated
+if you want to use RGB colours, so always make sure to
+specifically **include** what you really need.)
+
+Colour-related constants are simply **hardcoded**, such as
+in this way:
+
+    GREEN = "\e[0;32m"
+
+To test all colours, after requiring the project such as
+described above, do:
+
+    Colours.test
+
+Several methods exist as well, such as **sfancy()**, **swarn()**,
+**simp()**, **sdir()** and **sfile()**, among others.
+
+These methods can be used to colourize certain Strings,
+such as:
+
+    a file      → use sfile()
+    a directory → use sdir()
+    a warning   → use swarn()
+
+The methods **sfancy()** and **simp()** are there to denote 
+more important output, usually in the middle of a String.
+Think of this as a way to **emphasize** what you wish to 
+display to the user at hand. (The important parts of
+the sentence should be colourized and emphasized. This is
+the whole point for simp() to exist; simp() is a shortcut
+for **string_important**, by the way.)
+
+To make use of the **html-colours component**, such as converting
+a "HTML Colour" to its RGB values, you can do this:
+
+    puts Colours::HtmlColours.colour_to_rgb(:sienna) # ← This variant no longer works.
+    puts Colours.html_colours.colour_to_rgb(:sienna) # ← This variant no longer works.
+    pp Colours.colour_to_rgb(:sienna)                # ← This variant actually works, and will return an Array such as: [160, 82, 45]
+
+If you want to return a random HTML colour, you can use this method 
+call:
+
+    Colours::HtmlColours.random
+
+or
+
+    Colours.html_colours.sample # => "darksalmon"
+    Colours.html_colours.sample # => "turquoise"
+    Colours.html_colours.sample # => "lightblue"
+
+Or just:
+
+    Colours.sample # => "khaki"
+    Colours.random_html_colour # => "slateblue"
+
+Use whichever variant you prefer. The shorter names are more elegant in
+my opinion.
+
+In general, the html component can be used to convert the trivial
+<b>html colours</b> into <b>corresponding R,G,B values</b>.
+
+## Linux terminals and colour support
+
+The general syntax rules for colours is in the form of **fg_bg** values,
+where a value of 38 stands for the foreground, and 48 stands for
+the background.
+
+The ANSI colour for red is 196 and the ANSI colour for black is
+0.
+
+To use the colour red, you could issue this command:
+
+    printf "\e[38;5;196m Hello world in red\n"
+
+To use the colour black as background, you could issue this command:
+
+    printf "\e[48;5;0m Hello world in black\n"
+
+Do note that the same can be accomplished via RGB values rather than
+ANSI color codes, as long as the terminal supports this (KDE Konsole
+does).
+
+Depending on whether you want to apply the color to the foreground or
+to the background, use an **fg_bg** value of 38 or 48 (respectively).
+
+Example:
+
+    printf "\e[<fg_bg>;2;<R>;<G>;<B>m"
+    printf "\e[38;2;255;0;0m Foreground color: red\n"
+    printf "\e[48;2;0;0;0m Background color: black\n"
+
+This may be the better variant altogether, as it is quite easy to convert
+into (and from) **RGB values**, but your mileage may vary.
+
+Of course you can use this in plain ruby just as well - let's show this
+via puts:
+
+    puts "\e[38;2;#{222};#{131};#{141}m Hello world!"
+    puts "\e[38;2;#{122};#{56};#{141}m Hello world!"
+    puts "\e[38;2;122;156;141m Hello world!"
+    puts "\x1b[3mHello world!\x1b[0m"
+    puts "\e[38;3mHello world!\x1b[0m"
+
+In bash the ESC code can be either of the following:
+
+    \e
+    \033 (octal)
+    \x1B (hexadecimal)
+
+The "\e[0m" sequence removes all attributes, including formatting and colors.
+It may be useful to add it to the end of each colour text - and this is
+what the **Colours** project is essentially doing.
+
+To see which colours are supported/supportable, for each terminal,
+have a look at the following **link**:
+
+https://misc.flogisoft.com/bash/tip_colors_and_formatting#terminals_compatibility
+
+To set both the foreground and background colours at once, you can use:
+
+    printf "\e[S;FG;BGm"
+    echo -e "\e[S;FG;BGm"
+
+For example, bold white foreground on a red background:
+
+    printf "\e[1;97;41mHello world!"
+    printf "\e[1;97;41mHello world!\n"
+
+Thus, if you would like to use red colour on black background,
+you could do this:
+
+    printf '\e[38;5;196m;\e[48;5;0m Hello world!\n'
+
+Specifically, the background colours are:
+
+    40  black
+    41  red
+    42  green
+    43  yellow
+    44  blue
+    45  magenta
+    46  cyan
+    47  white
+
+The following command will use red background:
+
+    echo -e '\e[0;41m'
+    echo -e '\e[0;41m hello world\n\n ok\e[0;m'
+
+## Obtain all available HTML colours
+
+To obtain all available html-colours, do this:
+  
+    Colours::HtmlColours.all_colours?
+
+Or in a simpler way, without the ::HtmlColours part:
+
+    Colours.return_all_html_colours
+
+There are presently 142 registered HTML colours available:
+
+    Colours.return_all_html_colours.size # => 142
+
+If you need to find out whether a given String (a **word**)
+is registered as part of the HTML-Colours within **module
+Colours**, then you could use the following toplevel-method:
+
+    Colours.is_this_html_colour_included?
+    Colours.is_this_html_colour_included? :slateblue  # => true 
+    Colours.is_this_html_colour_included? 'royalblue' # => true
+
+## eparse()
+
+The eparse() method is a convenience method to apply on
+Strings such as 'Foo: bar'. Note the ':' character
+there. That input will be split, and then displayed
+via two different colours.
+
+## Underline / Underlining
+
+You can **underline** text, and print it onto the terminal,
+by issuing a command such as the following:
+
+    txt = 'Hello world!'
+
+    Colours.underline(txt)
+
+You can also add colours to this, via {}:
+
+    Colours.underline(txt)
+    Colours.underline(txt) { :palegreen }
+    Colours.underline(txt) { :slateblue }
+    Colours.underline(txt) { :orange }
+    Colours.underline(txt) { :crimson }
+
+Within the {} block you can use HTML colours, as symbol, such as
+:slateblue or :orange and so forth. If you would rather not like
+to use these colours then simply do not pass them into the
+method, as the first variant shows. :)
+
+If you only want to get the colour code for that string, without
+displaying it on the terminal it, then you can use .string_underline()
+or .return_underline() method:
+
+    Colours.string_underline(txt) { :palegreen }
+    Colours.string_underline(txt) { :slateblue }
+    Colours.string_underline(txt) { :orange }
+    Colours.string_underline(txt) { :crimson }
+    Colours.return_underline(txt) { :royalblue }
+
+## include Colours::Methods
+
+Since as of February 2019 there is a module called **Methods**
+part of the colours gem. This module allows us to include
+the konsole-related colour methods into a subclass.
+
+Example:
+
+    class Foo
+      include Colours::Methods
+    end
+
+    e Foo.new.royalblue('hey there')
+
+As you can see, this class will have the HTML colours available,
+such as .royalblue() or .slateblue() and so forth.
+
+I needed this in some of my other code, so it was added. I like
+full colour support on terminals such as **KDE konsole**.
+
+Note that this has to be specifically included, as I am not sure
+everyone wants to have that the moment **include Colours** is
+done. The toplevel Colours module will stay a bit simpler by
+default; for customization, you will have to go the extra
+line through **include Colours::Methods**, which appears to be
+an acceptable trade-off.
+
+Note that you can also subclass from a "dummy" class with colour
+support, such as royalblue() or slateblue.
+
+Use code similar to the following variant for this:
+
+    require 'colours/base/base.rb'
+
+    class Foobar < Colours::Base # Or whatever the name of your class is
+    end
+
+## KDE Konsole support
+
+The **Colours gem** used to have a submodule called **Konsole**,
+in particular the <b>KDE Konsole</b>. In May 2019 this submodule
+was removed; the functionality is now available in the form of
+an autogenerated .rb file instead.
+
+You can **use RGB colours** in the KDE konsole (but also in
+other terminal-types such as vte-based ones, like
+**mate-terminal**).
+
+For an example, have a look at the file **bin/colours**
+that is distributed with this gem here (the colours gem). That file
+will output all the HTML colour variants (via their RGB values).
+Best shown on a black background in your terminal.
+
+To **view all RGB colours** based on their HTML names, such
+as <b>palegreen</b> or <b>slateblue</b>, do this:
+
+    colours
+
+Also note that since as of **May 2018**, you can invoke the
+HTML colours on the Konsole namespace directly, including
+text-output, via code like this:
+
+    Colours.edarkgreen 'yo there'
+    Colours.eslateblue 'yo there'
+    Colours.eroyalblue 'yo there'
+    Colours.edarkgreen 'Hello world!'
+
+The leading 'e' of these methods stands for "echo", aka
+puts-related output. In other words, to print the text
+that comes afterwards.
+
+To print something in bold, you can use **Colours.bold()**
+like in this way:
+
+    Colours.bold
+
+## Showing the colour palette on the commandline
+
+You can show the "classical" ASCII colours on the commandline by
+invoking this method:
+
+    Colours.show_palette
+
+This also works, or should work, from the commandline, like so:
+
+    colours --show-palette
+    colours --palette
+
+## The KDE colour palette
+
+The **KDE project** makes use of a special, **named colour palette**.
+
+This palette includes the following **20 different colours**, via
+a trivial name:
+
+    Abyss Blue
+    Alternate Grey
+    Beware Orange
+    Burnt Charcoal
+    Cardboard Grey
+    Charcoal Grey
+    Coastal Fog
+    Deco Blue
+    Hover Blue
+    Hyper Blue
+    Icon Blue
+    Icon Green
+    Icon Grey
+    Icon Red
+    Icon Yellow
+    Lazy Grey
+    Noble Fir
+    Paper White
+    Pimpinella
+    Plasma Blue
+
+You can find these entries, including their hex-values and their 
+RGB values, on websites such as this one here:
+
+https://community.kde.org/KDE_Visual_Design_Group/HIG/Color
+
+Note that these are also called the "Breeze" colours, which I 
+assume is the name of the theme.
+
+Since as of July 2018, the colours project also includes these
+colours, via the file <b>colours/constants/kde_colour_palette.rb</b>.
+
+The entries are stored in a **.yml file**, so if anyone wants to re-use
+these from a yaml file, feel free to just copy/paste it from there.
+That file is at <b>colours/yaml/kde_colour_palette.yml</b>.
+
+Internally, the values are made available via the constant:
+
+    Colours::KDE_COLOUR_PALETTE
+
+Which is a hash. There are also a few methods that may be useful to
+use. For example, if you want to use a random colour, and output
+<b>Hello world!</b>, then you could use the following method:
+
+    Colours.write_this_via_kde_colour_palette 'Hello world!', :random
+
+While random colours may be nice, perhaps you may want to use a
+definite colour from the above list. Say that you may want to
+write via <b>Plasma Blue</b>. In this case, you could use:
+
+    Colours.write_this_via_kde_colour_palette 'Hello world!', :plasma_blue
+
+So using a symbol works too.
+
+If you tend to use this regularly, then an even simpler way may exist,
+by simply calling a method that already has that as part of its name.
+
+Examples with **Hello World!**:
+
+    Colours.kde_colour_palette_abyss_blue 'Hello world!'
+    Colours.kde_colour_palette_alternate_grey 'Hello world!'
+    Colours.kde_colour_palette_beware_orange 'Hello world!'
+    Colours.kde_colour_palette_burnt_charcoal 'Hello world!'
+    Colours.kde_colour_palette_cardboard_grey 'Hello world!'
+    Colours.kde_colour_palette_charcoal_grey 'Hello world!'
+    Colours.kde_colour_palette_coastal_fog 'Hello world!'
+    Colours.kde_colour_palette_deco_blue 'Hello world!'
+    Colours.kde_colour_palette_hover_blue 'Hello world!'
+    Colours.kde_colour_palette_hyper_blue 'Hello world!'
+    Colours.kde_colour_palette_icon_blue 'Hello world!'
+    Colours.kde_colour_palette_icon_green 'Hello world!'
+    Colours.kde_colour_palette_icon_grey 'Hello world!'
+    Colours.kde_colour_palette_icon_red 'Hello world!'
+    Colours.kde_colour_palette_icon_yellow 'Hello world!'
+    Colours.kde_colour_palette_lazy_grey 'Hello world!'
+    Colours.kde_colour_palette_noble_fir 'Hello world!'
+    Colours.kde_colour_palette_paper_white 'Hello world!'
+    Colours.kde_colour_palette_pimpinella 'Hello world!'
+    Colours.kde_colour_palette_plasma_blue 'Hello world!'
+
+The reason as to why this is so long is so that we can avoid any name clashes -
+but in principle, we could also enable a **shorter name**, such as:
+
+    Colours.pimpinella # much shorter than Colours.kde_colour_palette_pimpinella
+
+You can also use the "e" method, **e** which stands for **echo**, such as in:
+
+    Colours.epimpinella 'Hello cats!'
+    Colours.eplasma_blue 'Hello cats!'
+
+This functionality is available for the Colours project since as of July 2018 -
+but be careful, since this may change one day, in the event that a conflict
+may exist with an already defined name (such as the names in the HTML colour
+charts, e. g. "slateblue", "royalblue" and so forth).
+
+Do note that the behaviour may change, too; e. g. **Colours.pimpinella()** may in
+the future only return a String, and a new method called **Colours.epimpinella()**
+would be tasked with outputting the text - but for the time being, things stay
+as described above (in July 2018).
+
+## Generating a shell file with all HTML colours
+
+You can generate a shell file that can be sourced, in **bash**, **fish**
+and possibly **zsh**, in order to make use of the HTML colours on the
+commandline.
+
+The method that does so is:
+
+    Colours.generate_shell_file_containing_the_html_colours()
+
+This will store in the current working directory; or to another
+directory if you pass an argument to it.
+
+The file will have entries such as:
+
+    export CHARTREUSE="\e[38;2;127;255;0m"
+
+This is the RGB variant for the colour at hand. The closing tag
+is missing there, so you may have to use it if you wish to
+output text that is coloured.
+
+You can source this .sh file and re-use it in your own scripts.
+
+You can also generate this **shell file** from the commandline,
+through **bin/colours**.
+
+Issue a command like any of the following variants:
+
+    colours --generate-shell-file-containing-the-html-colours
+    colours --generate_shell_file_containing_the_html_colours
+    colours --generateshellfilecontainingthehtmlcolours
+    colours --create-shell-file
+
+== Using the Konsole submodule
+
+In the past there was a Konsole submodule, but in May 2019 during
+a large rewrite, this submodule has been removed.
+
+The functionality has been integrated into an autogenerated .rb
+file though. That module can be found in the file called
+**toplevel_basic_colour_methods.rb**.
+
+Old invocation examples such as:
+
+    Colours[:slateblue]
+
+Should be possible still.
+
+You can also include this new module:
+
+    include Colours::AllColourMethods
+
+Then you can simply call the respective colour output:
+
+    slateblue('Hello World!')
+  
+    eslateblue()
+    eslateblue('Hello World!')
+
+eslateblue() works like slateblue() but outputs the
+result.
+  
+    konsole_colour_slateblue('Hello World!')
+    ekonsole_colour_slateblue('Hello world!')
+
+The above two variants are probably too long, but they
+also exist if you wish to be more specific.
+
+Automatic inclusion can be done like so:
+
+    require 'colours/konsole/autoinclude'
+
+    Konsole['slateblue']+'Hello World'
+    konsole :green, 'hello world'
+
+Of course you can also manually include it by yourself:
+
+    require 'colours'
+
+Note that when you include that module, you will have access
+to methods such as e. g. slateblue() or sandybrown().
+
+    konsole_colours :slateblue, 'hello world!'
+
+## 256 colour support
+
+Some terminals allow **support for 256 colours**.
+
+The colours gem allows you to test this, via this toplevel-method:
+
+    Colours.show_all_256_colours
+
+If you need to specifically use one of these colours, have a look
+at the following two methods:
+
+    Colours.return_this_256_colour()
+    Colours.display_this_256_colour()
+
+The first input argument should be the number, from 0-255, and
+the second argument is the text that is to be displayed (append
+a newline to this if you need one).
+
+The first input argument is called <b>id</b>, for the purpose of
+this document here.
+
+Let's provide specific examples how to use the latter method.
+
+For example, to ouput, in **red**, the sentence "<b>Ruby is awesome!</b>",
+you could use either of the following methods:
+
+    Colours.display_this_256_colour(88, "Ruby is awesome!\n")
+    Colours.display_this_in_256_colour(88, "Ruby is awesome!\n")
+
+Note that you can also use several colours, based on the id input,
+via a pseudo-range. A **pseudo-range** is input that is a String and
+includes one '-' character. For example, **33-44** is a pseudo-range
+and so is **0-255**.
+
+In ruby code, this could work like so - give it a try:
+
+    require 'colours'
+
+    Colours.display_this_256_colour('0-255',"Hello world, in a batch!\n")
+
+If you wish to make use of these colour-methods in one of your classes,
+then you can require the module, and include it into your class.
+
+Example for this:
+
+    require 'new_colours/autogenerated/support_for_256_colours.rb'
+
+    class Foobar
+
+      include NewColours::SupportFor256Colours
+
+      def initialize
+        puts darkturquoise('HELLO ')+
+             maroon('WORLD ')+
+             'This is ok again'
+      end
+
+    end
+
+    Foobar.new
+
+## revert
+
+The toplevel instance variable called **@revert** designates which
+escape code is used for reverting the colours again.
+
+By default, this is **\e0m**. However had, for some strange reason
+this does not appear to work very well on the default terminal
+style that I use (KDE konsole, white font on black background).
+It seems to default to white bold text, but I would rather want
+light white text, aka **\e[0;37m**. This is why revert defaults
+to **\e[0;37m**.
+
+If you wish to use \e0m instead, then you can do so via:
+
+    Colours.set_revert('\e0m')
+
+Or, via symbol, to the same value:
+
+    Colours.set_revert(:default)
+
+## Legacy versions of the Colours gem
+
+In May 2019, the old **Konsole** submodule has been removed; the 
+functionality itself has been retained, though. Still, as the API
+changed this means that not everyone may be able to use the new
+colours gem release.
+
+This is the reason why the old version at **0.3.40** will continue
+to be available here. This one still has the old **Colours::Konsole**
+submodule defined, so if you need it in a project, feel free to
+use that older version.
+
+Otherwise I recommend to **upgrade** to the latest version of the
+colours gem - the code is, in my opinion, better too.
+
+In 2021 the old gem was released; only version 0.5.55 is
+still available. Consider changing to the new code base if
+possible - it should have a higher quality as well. 
+
+## Available colour methods
+
+If you wish to find out which colour methods will be available by
+default, onto the main Colours namespace, you can use the following
+method to find out:
+
+    Colours.all_available_colour_methods?
+
+This will return an Array containing the names of all these
+toplevel methods. In May 2019 we can find 307 available 
+colour methods e. g. such as **Colours.slateblue** or
+**Colours.lightblue** and so forth.
+
+## Remove escaping sequences
+
+If you wish to remove all escaping sequences from a given String,
+you can use the following API for this:
+
+    Colours.remove_escape_sequences()
+    Colours.remove_escape_sequences "\e[38;2;41;128;18mHello world!\e[0;37m" # => "Hello world!"
+    pp Colours.remove_escape_sequences(Colours.slateblue('Hello world!')) # => "Hello world!"
+
+The latter example shows that the escape-sequences are properly removed.
+
+If you still find an example where the escape sequences are not
+working properly, e. g. because they are retained, then consider
+this to be a bug; once reported, a test case can be added to allow
+for removing this escape sequence as well.
+
+**Sometimes** you may **only wish to remove the trailing escape
+sequence**, aka "\e[0;37m". In this case the following method may
+be useful:
+
+    Colours.remove_trailing_end_from()
+    Colours.remove_trailing_ansii_escape_code()
+
+Usage example:
+
+    x = Colours.remove_trailing_end_from("\e[38;2;70;130;180m\e[0;37m") # => "\e[38;2;70;130;180m"
+
+## Colours.does_this_line_include_a_html_colour?
+
+If you need to determine whether a line (a string) includes a valid
+HTML colour, such as slateblue>, then you can use the following method:
+
+    Colours.does_this_line_include_a_html_colour?
+    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
+
+## Colours.replace_all_html_colours_in_this_line
+
+If you wish to replace all HTML colours in a given line/string,
+then the following **toplevel method** can be used:
+
+    Colours.replace_all_html_colours_in_this_line
+    puts Colours.replace_all_html_colours_in_this_line '<one>hey</one>' # ← This variant works as well.
+
+This has been specifically added for commandline-use. It allows us
+to replace HTML colour "tags" with the corresponding RGB value,
+so that a terminal emulator such as the KDE konsole can display
+this.
+
+## Rainbow colours
+
+You must install the paint gem first:
+
+    gem install paint
+
+Then you can do the following:
+
+    Colours::RainbowColours.print_rainbow_line("Hello world \n" * 40)
+
+To print a line directly you can also use printl_plain():
+
+    Colours::RainbowColours.println_plain "one two three four five six seven eight nine ten\n\n\n"
+
+## Colours.fancy_parse
+
+The toplevel method **Colours.fancy_parse()** can be used to
+parse a more complicated text/string.
+
+For example, say that you have a HTML string with embedded i
+tag and HTML colours.
+
+You can display this on the commandline.
+
+Example:
+
+    puts Colours.fancy_parse "<lightgreen><i>hey</i></lightgreen> <teal>there</teal>"
+    puts Colours.fancy_parse "<tomato>hey</tomato> <teal>there</teal>"
+    puts Colours.fancy_parse "<tomato><i>hey</i></tomato> <teal>there</teal>"
+    puts Colours.fancy_parse "<tomato><b>Hello world.</b></tomato>"
+    puts Colours.fancy_parse "<tomato>Hello world.</tomato>"
+
+I recommend the KDE Konsole for this, but it should work on gnome-terminal as
+well. Currently (September 2019) only HTML colours, such as tomato, steelblue,
+and so forth, are supported, as well as i (italic). This may be extended at
+a later time including bold.
+
+Note that this is not working perfectly correctly for longer strings with
+lots of tags. At a later point this will have to be improved, but for now,
+it simply has to suffice. Patches are welcome, though. :)
+
+## Support for italic text
+
+In KDE konsole, the escape sequences **\e[3m** and **\e[23m** can be used
+to turn **italics** on and off, respectively. See this commit:
+
+https://invent.kde.org/utilities/konsole/commit/68a98ed77063e622985d422b625d7dc5895f10c3
+
+Let's have a look at an example for this in ruby (and KDE konsole,
+but it may work in other terminals as well, such as the mate-terminal,
+which in turn is based on **VTE**):
+
+    puts "\e[3mHello world!\e[23m" 
+
+I tested this in **July 2020** and it works fine.
+
+You can use regular text afterwards and that works as well.
+
+Example:
+
+    puts "\e[3mHello world!\e[23m abc"
+
+See the following partial image:
+
+<img src="https://i.imgur.com/gZ183qA.png" style="margin: 1em; margin-left: 3em">
+
+Of course it can also work on the commandline, e. g. via bash/zsh or 
+a similar shell, as the following example shows:
+
+    echo -e "\e[3mHello World\e[0m"
+
+Notice the **3** there - this is the code for <i>italic</i>.
+
+If you use the colours gem and you need a String in italic,
+consider using the following API:
+
+    puts Colours.string_italic("Hello World!")+' OK' # => Hello World! OK
+
+## Removing html-colours and other "tags" from a String
+
+If you have entries such as <one> or <steelblue> (aka one, and steelblue),
+and wish to replace them with the RGB values, for commandline use,
+you could try to use this method:
+
+    Colours.eliminate_html(your_string_here)
+    Colours.away_with_html_colours_and_special_numbers(your_string_here)
+    Colours.away_with_html_colours_and_special_numbers "<royalblue>+</royalblue>" # => "\e[38;2;128;128;128m\e[38;2;65;105;225m+\e[38;2;128;128;128m"
+
+This was needed so that other projects can **turn strings into colourized
+strings** - on the commandline. This explains the result, as the \e is
+typically used to specify an escape sequence.
+
+## Converting hex-value to R,G,B value
+
+If you need the R,G,B value from a hexadecimal value then you can
+use the following method:
+
+    Colours.convert_hex_to_rgb('#baf185') # => [186, 241, 133]
+    Colours.hex_to_rgb('#baf185') # => [186, 241, 133]
+
+Note that this will return an Array, with R,G,B values. If you need
+a string, use **.join()** on that result.
+
+## class Colours::Colours
+
+This oddly named class (<b>Colours::Colours</b>) has been
+<b>inspired by another gem</b>, called **rainbow**.
+
+That gem allows you to do the following:
+
+    require 'rainbow'
+    x = Rainbow("hola!").blue.bright.underline
+    puts x
+
+I found this neat, in particular the <b>Rainbow(STRING_GOES_HERE)</b>
+part. Then I realised that the **colours** gem does not allow for a
+toplevel-method call such as **Colours()**. So, in <b>December 2021</b>,
+I decided to change this, and added the file **colours/class/class.rb**.
+
+This file defines **Colours()**, as method. In the long run I
+intend to make this fully compatible with what **Rainbow()**
+offers, but for now this is a semi-minimal implementation.
+
+Have a look at that .rb file to see what it is currently capable
+of doing.
+
+## Converting html-colours to their HEX value
+
+If you want to convert a html-colour into the corresponding RGB value
+then try **bin/html_colour_to_hex_value** like in this way:
+
+    html_colour_to_hex_value slateblue # Output would be '#6A5ACD', without '' quotes.
+
+(You may have to add the bin/ path of that gem to your $PATH.)
+
+Internally the code that allows this is the following:
+
+    require 'colours/toplevel_methods/methods_related_to_html_colours.rb'
+    puts Colours.html_colour_to_hex_value(ARGV)
+
+If you need the alpha value then you could use this method:
+
+    Colours.convert_hex_code_to_RGBA_array('#baf185') # => [186, 241, 133, 1.0]
+
+This defaults to alpha being 1.0. In a future release of the
+colours gem this may be made more sophisticated, but for
+now this has to suffice.
+
+## Licence
+
+The project used to be under the **GPL-2.0 licence** (no later clause),
+until **August 2019** (**26.08.2019**, in dd.mm.yyyy notation).
+
+However had, I have changed my mind for various reasons (including the
+situation that different projects, with different licenses, may make
+use of the **colours gem**) and thus re-published the colours
+project under the less stringent **MIT licence**. Both licences are
+fine licences, but I feel that for the basic building blocks, such
+as the colours gem, a less stringent licence makes a lot more
+sense.
+
+See the file **LICENCE.md** for this licence, or just have look at
+the following URL here:
+
+https://opensource.org/licenses/MIT
+
+Replace the effective year simply with whatever was the last release
+on the rubygems.org homepage of this gem here.
+
+The most important requirement for the MIT licence is the no-warranty
+clause. The rest is, IMO, not so relevant (I don't even care about
+author citation either, but mentioning a no-warranty clause makes
+sense, in my opinion).
+
+
+## Contact information and mandatory 2FA coming up in 2022
+
+If your creative mind has ideas and specific suggestions to make this gem
+more useful in general, feel free to drop me an email at any time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail for various reasons. In order to limit this
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore, for various reasons.
+
+Do keep in mind that responding to emails may take some time, depending on
+the amount of work I may have at that moment.
+
+In 2022 rubygems.org decided to make 2FA mandatory for every gem owner:
+see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+As I can not use 2FA, for reasons I will skip explaining here (see
+various github issue discussions in the past), this effectively means that
+Betty Li and others who run the show at rubygems.org will perma-ban me
+from using rubygems as a developer.
+
+As I disagree with that decision completely, this will mean that all my
+gems will be removed from rubygems.org prior to that sunset date, e. g.
+before they permanently lock me out from the code that I used
+to maintain. It is pointless to want to discuss this with them anymore -
+they have made up their minds and decided that you can only use
+the code if 2FA is in place, even though the code itself works just
+fine. If you don't use 2FA you are effectively locked out from your
+own code; I consider this a malicious attack. See also how they limited
+discussions to people with mandatory 2FA on the ruby-bugtracker, thus
+banning everyone permanently without 2FA:  
+
+https://bugs.ruby-lang.org/issues/18800
+
+Guess it may indeed be time to finally abandon ruby - not because
+ruby is a bad language, but there are people now in charge who
+really should not be part of ruby in the first place.
+