colours 0.8.12 → 0.9.8

data/bin/colours

@@ -2,6 +2,6 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
-require 'colours'
+require 'colours/commandline/commandline.rb'
 
-Colours.menu(ARGV)
+Colours::Commandline.new(ARGV)

data/bin/show_basic_colour_palette

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'colours/toplevel_methods/toplevel_methods.rb'
+
+Colours.show_basic_colour_palette

data/colours.gemspec

@@ -22,8 +22,7 @@ display text on the terminal with colours.
 
 For more information about this project, have a look at the online
 documentation for this gem at the link called "documentation", at
-the bottom right side of the colours
-gem homepage:
+the bottom right side of the colours gem homepage:
 
   #{::Colours::URL_TO_THE_DOCUMENTATION}
 

data/doc/README.gen

@@ -6,52 +6,69 @@ Making colours great again! \o/
 
 ## 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
+The Colours project originated from a distinct requirement to have to support
+<b>colours</b> on the commandline, such as for commandline-oriented
+scripts.
+
+Colours can be immensely helpful for use in computer programs, so it appears
+to be a logical conclusion to make use of them on the commandline as well.
+The modern www also makes use of colours - just look at any random webpage;
+you may find lots of different colours in use there, for various reasons
+and purposes.
+
+If you do happen to take a look on different projects offered on <b>rubygems.org</b>
+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.
+was because I needed certain functionality made available 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).
 
-![alt text][screenshot1]
-[screenshot1]: https://i.imgur.com/F6kac8W.png
+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 <b>colours-related project</b> that could abstract this away for me.
+That way I can focus on other problems, and delegate the colour-specific issues
+to this gem here.
 
-The **main goal** of the **colours project** is to collect colour-related
+Let's next show how this may then look on the commandline:
+
+<img src="https://i.imgur.com/F6kac8W.png" style="margin: 1em">
+
+The <b>main goal</b> 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.
+can benefit from colour support via one project: the <b>colours gem</b>.
+
+The primary goal herein lies on **commandline applications**, but there
+are some <b>HTML components</b> as part of this project that could be used
+as well, such as for when you wish to make use of **HTML colours** (slateblue,
+royalblue, teal, tomato, steelblue and names such as these) in a webpage.
+
+Elements such as:
 
-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.)
+    <span class="dodgerblue">This is in dodgerblue.</span>
 
-Note that many **terminals** support the **display of HTML colours**, via
+The partial screenshot that was shown above indicates this situation, on a
+black <b>KDE konsole</b> background. (I tend to prefer dark backgrounds
+for my terminals.)
+
+Note that many **terminals** support the <b>display of HTML colours</b>, 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.
+these names directly, as method calls as well - names such as <b>slateblue</b>
+or <b>royalblue</b>). This is the reason why method calls such as 
+<b>Colours.royalblue()</b> or <b>Colours.darkgreen</b> will also work - see
+for a later subsection how to customize (and control) this behaviour.
+
+Historically the **Colours gem** was inspired by other, older projects, such
+as <b>AnsiColours</b>, ColourE, AliasE and several other smaller sub-projects
+that I have used over the years. These projects were eventually integrated
+into one namespace - <b>module Colours</b>. This gem is thus a <b>bundled
+project</b>. This is specifically mentioned in the event that you may wish
+to peek 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:
+To require the colours project, simply do:
 
     require 'colours'
 
@@ -62,13 +79,144 @@ You can also **autoinclude** this module into your project, at
 
 This will make the **Colours namespace** and the
 **Colours::HtmlColours namespace** available, via 
-**include Colours** ultimately.
+<b>include Colours</b> 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.
 
+The project was partially rewritten in November 2023. If you
+want to autoinclude the project still then I recommend you
+use this:
+
+    require 'colours/html_colours'
+
+After that methods such as <b>Colours.steelblue()</b> will
+work.
+
+## ASCII Escape Characters
+
+The code in the colours gem makes use of elements such as \033 or
+\x1b. These are basically the same ASCII escape characters, as the
+following table shows:
+
+|-------------|------------|
+| octal       | \033       |
+|-------------|------------|
+| hexadecimal | \x1b       |
+|-------------|------------|
+| Unicode     | \u1b, \U1b |
+|-------------|------------|
+| literal     | \e, \E     |
+|-------------|------------|
+
+The last variant can often be found in <b>Bash scripts</b>.
+
+The semicolon <b>;</b> serves as the delimiter if multiple instructions
+are given.
+
+The 8 actual colours defined by the ANSI standard are as follows:
+
+    0  black
+    1  red
+    2  green
+    3  yellow
+    4  blue
+    5  magenta
+    6  cyan
+    7  white
+
+## Linux terminals and colour support
+
+The general syntax rules for colours is in the form of <b>fg_bg</b> values,
+where a value of <b>38</b> stands for the foreground, and <b>48</b> stands
+for the background.
+
+For instance, 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 in Bash:
+
+    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 colour to the foreground
+or to the background, use an **fg_bg** value of <b>38</b> or <b>48</b>
+(respectively).
+
+Examples for this:
+
+    # printf "\e[<fg_bg>;2;<R>;<G>;<B>m" # General syntax example.
+    printf "\e[38;2;255;0;0m Foreground color: red\n"
+    printf "\e[48;2;0;0;0m Background color: black\n"
+    printf "\033[91m\033[107mThis is red text on a white background\033[0m" # As this example shows, \e is the same as \033.
+
+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'
+
 ## Introduction and Overview
 
 The toplevel module name is **Colours** and you can include
@@ -161,93 +309,17 @@ 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.
+Note that in November 2023 I rewrote parts of the gem. This also
+led to a re-evaluation of methods such as sdir() or sfancy().
 
-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'
+I use sfile(), sdir() and sfancy() a lot. I also use simp(),
+as abbreviation for simportant(), sometimes. However had, other
+methods, such as ssymlink(), I rarely use; and I never used
+sarguments(), yet the project still carried code that supported
+such a use case. During the partial rewrite in November 2023
+I decided to deprecate and remove sarguments() aka Colours.sarguments().
+I also deprecated snormal(), aka Colours.snormal(), as I also have
+not ever used that method actually.
 
 ## Obtain all available HTML colours
 
@@ -347,45 +419,6 @@ Use code similar to the following variant for this:
     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
@@ -601,11 +634,11 @@ then you can require the module, and include it into your class.
 
 Example for this:
 
-    require 'new_colours/autogenerated/support_for_256_colours.rb'
+    require 'colours/autogenerated/support_for_256_colours.rb'
 
     class Foobar
 
-      include NewColours::SupportFor256Colours
+      include Colours::SupportFor256Colours
 
       def initialize
         puts darkturquoise('HELLO ')+
@@ -1033,28 +1066,28 @@ Here is example code that shows this functionality:
 
 ## Colours.new
 
-Since as of November 2022 <b>Colours.new</b> can be used to
-build up a String that should be colourized.
+Since as of <b>November 2022</b>, <b>Colours.new</b> can be used
+to build up a String that should be colourized.
 
 This will internally delegate towards:
 
     ::Colours::Colours.new(i)
 
-This may need some modifications in the future; the code is
-also a bit confusing right now.
+This may need some modifications in the future; the code is also
+a bit confusing right now.
   
 ## Licence
 
 The colours project used to be under the **GPL-2.0 licence** (no later clause),
-until **August 2019** (**26.08.2019**, in dd.mm.yyyy notation).
+until **August 2019** (**26.08.2019**, in <b>dd.mm.yyyy notation</b>).
 
 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, GPL and
-MIT, are perfectly 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.
+MIT, are perfectly fine licences, but I feel that for the <b>basic building
+blocks</b>, 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:
@@ -1081,12 +1114,14 @@ on something IF the no-warranty clause would not be mentioned).
 https://ss64.com/nt/syntax-ansi.html
 
 https://www.lihaoyi.com/post/BuildyourownCommandLinewithANSIescapecodes.html
-^^^ This one shows how to build a progress-indicator in python. The equivalent
-ruby code is very similar.
+
+^^^ This webpage one shows how to build a progress-indicator in python. The
+equivalent ruby code is very similar.
 
 ## Commandline executables for individual colours
 
-In March 2023 I decided to add files such as bin/orange.
+In <b>March 2023</b> I decided to add files such as 
+<b>bin/orange</b>.
 
 The idea here is that you can chain this via a pipe, such as:
 
@@ -1097,9 +1132,90 @@ Or simply:
     orange Hello world!
     orange foobar.md # This variant should read the file, and read its content.
 
-My idea is to add this for each HTML colour. However had, I am not yet
-certain whether this should be done. So for now, I may add single 
-individual files. Perhaps in the future all HTML colours will have a
-corresponding bin/ executable file.
+The idea here is to add this for each HTML colour. However had, I am not yet
+certain whether this should be done, as it would lead to many more files
+added to the colours gem. So for now, I may add single individual files
+but probably not all HTML colours, as executables. Perhaps in the future
+all HTML colours will have a corresponding bin/ executable file or I may
+add the option to autogenerate these files - we'll see.
+
+## KDE Konsole support
+
+The **Colours gem** used to have a submodule called **Konsole**,
+in particular the <b>KDE Konsole</b>. In <b>May 2019</b> 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
+<b>mate-terminal</b>). gnome-terminal also supports true
+24 bit colours, which means that 16 millions colours are supported.
+
+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 though.
+
+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 <b>code like this</b>:
+
+    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
+<b>puts-related output</b> (display onto the commandline).
+In other words, <b>to print the text that comes afterwards</b>.
+
+To print something in bold, you can use **Colours.bold()**
+like in this way:
+
+    Colours.bold
+
+How to use this in raw KDE konsole, if ruby is not available?
+
+You need to make use of the corresponding R, G and B
+values.
+
+Example for this:
+
+    printf "\e[38;2;100;200;200mTesting this output\e[0m\n"
+
+## class Colours::ReplaceTokensWithColourCode
+
+class Colours::ReplaceTokensWithColourCode can be used to
+replace HTML-like tokens, such as <one>, in a given String.
+
+The use case for this is to be able to easily colourize
+words on the commandline, as well as sentences, in different
+colours. The studium-gem makes use of this, for instance,
+where exam-questions are colourized based on the more important
+parts of the question at hand.
+
+## Colours::HtmlColoursMethods
+
+class Colours::HtmlColoursMethods will hold code for making
+use of HTML-colours as method names, such as:
+
+    Colours.royalblue()
+    Colours.royalblue('Hello World!')
+
+To require this file do:
+
+    require 'colours/autogenerated/html_colours_methods.rb'
+
+Note that depending on how you require the colours gem,
+this may also be automatically pulled in if you do:
+
+    include Colours
+
+And then use methods such as Colours.sfancy().
 
 ADD_CONTACT_INFORMATION

data/doc/how_to_pick_your_own_colours/how_to_pick_your_own_colours.md

@@ -0,0 +1,33 @@
+This file describes how to pick your own colours - or how to use
+the Colours gem in general.
+
+The colours-centric Hash will contain entries such as the following:
+
+    sdir: :olivedrab
+
+Now, what does this mean?
+
+This is ultimately a hash entry, a key->value pair, with the key being
+called :sdir (a Symbol), and the value being :olivedrab (also a 
+Symbol).
+
+"sdir" in turn is an abbreviation for "string_dir", which is short for
+"string_directory". This means a String that keeps the colour stored
+for when we wish to colourize a directory, such as /tmp/. So, when
+such a directory is shown, the HTML colour "olivedrab" will be used.
+
+:olivedrab is thus a HTML colour (== "olivedrab"), which is a beige-green
+variant.
+
+What this thus does means, in english, is basically to "use the colour
+olivedrab, in order to display all directories in a coloured fashion".
+
+If you wish to use another colour, simply change the Symbol on the
+right hand side, aka :olivedrab, to another name, such as :steelblue
+or :orange. The names that should be chosen here are HTML Colour
+names.
+
+If you wish to get an overview over all available HTML colours, via
+ruby, you can do this via the Colours namespace like this:
+
+    Colours.show_html_colours

data/lib/colours/autoalias_e.rb

@@ -2,9 +2,12 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
-# This file is deliberately not included by default.
+# This file is deliberately not included by default. It simply aliases
+# e onto puts.
 # =========================================================================== #
 # Usage example:
+#
 #   require 'colours/autoalias_e'
+#
 # =========================================================================== #
 alias e puts