directory_paradise 1.4.5

data/lib/directory_paradise/report/report.rb

@@ -0,0 +1,1874 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === DirectoryParadise::Report
+#
+# The purpose of this class is to show the content of a directory, either
+# in a plain variant without any colours, or in a fancified variant, with
+# colours.
+#
+# The initial reason for creating this class was that I needed a general
+# adaptor for when I would be using ruby on windows, or on another
+# operating system, whenever I would try to use larger projects such
+# as the Roebe::Shell component, which is part of the gem called
+# "roebe".
+#
+# In the past, this was the sole use case that class ShowDirectoryContent
+# had to fulfil, but lateron I thought that I could factor this code out
+# into a standalone class, and make it available for other projects as
+# well - as true standalone project. Thus, the directory_content gem
+# was born. \o/
+#
+# This class here has, at least, the following main features that it
+# has to support:
+#
+#    - The ability to show the modification time.
+#    - The ability to truncate long file names.
+#    - The ability to list hidden files.
+#    - The ability to sort by size, by passing the argument "size" to it.
+#    - The ability to set and define your own colours.
+#    - The ability to show a simplified, shorter result.
+#    - The ability to make the colour output optional.
+#    - The ability to filter on the content, e. g. via '*'.
+#
+# A good general overview for available options for the GNU "ls" command
+# can be found here:
+#
+#   https://ss64.com/bash/ls.html
+#
+# =========================================================================== #
+# require 'directory_paradise/report/report.rb'
+# DirectoryParadise::Report.new(ARGV)
+# =========================================================================== #
+require 'directory_paradise/base/base.rb'
+
+module DirectoryParadise
+
+class Report < Base # === DirectoryParadise::Report
+
+  require 'colours'
+  require 'directory_paradise/project/project.rb'
+  require 'directory_paradise/content/content.rb'
+  require 'directory_paradise/report/menu.rb'
+
+  # ========================================================================= #
+  # === COLOURIZE_KB_AND_MB
+  #
+  # If true then we colourize KB and MB. This also includes B.
+  # ========================================================================= #
+  COLOURIZE_KB_AND_MB = true
+
+  # ========================================================================= #
+  # === FILE_SIZE_THRESHOLD
+  #
+  # When an inode entry has more than this amount of chars, we will
+  # truncate.
+  # ========================================================================= #
+  FILE_SIZE_THRESHOLD = 50
+
+  # ========================================================================= #
+  # === FILE_COLOURS_FOR_BYTES_VALUES
+  # ========================================================================= #
+  FILE_COLOURS_FOR_BYTES_VALUES = ::DirectoryParadise.project_base_directory?+
+                                  'yaml/colours_for_bytes_values.yml'
+
+  # ========================================================================= #
+  # === HASH_COLOURS_FOR_BYTES_VALUE
+  # ========================================================================= #
+  if File.exist? FILE_COLOURS_FOR_BYTES_VALUES
+    HASH_COLOURS_FOR_BYTES_VALUE = 
+      YAML.load_file(
+        FILE_COLOURS_FOR_BYTES_VALUES
+      )
+  end
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument is the target directory that should be displayed.
+  # ========================================================================= #
+  def initialize(
+      work_on_this_directory = return_pwd,
+      run_already            = true
+    )
+    register_sigint
+    reset
+    # ======================================================================= #
+    # === Handle the run_already variable next
+    # ======================================================================= #
+    case run_already
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet,
+         :dont_run_yet,
+         :dont_run_as_of_yet,
+         :dontrunyet
+      run_already = false
+    # ======================================================================= #
+    # === :display
+    # ======================================================================= #
+    when :display,
+         :do_show,
+         :do_show_it
+      do_show_the_content
+      run_already = true
+    # ======================================================================= #
+    # === :run
+    # ======================================================================= #
+    when :run
+      run_already = true
+    end
+    # ======================================================================= #
+    # Assign to an instance variable next. This must come after
+    # reset().
+    # ======================================================================= #
+    @internal_hash[:run_already] = run_already
+    set_commandline_arguments(
+      work_on_this_directory
+    )
+    set_work_on_this_directory( # This method call can alter @run_already.
+      work_on_this_directory
+    )
+    run if @internal_hash[:run_already]
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    infer_the_namespace
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :work_on_this_directory
+    # ======================================================================= #
+    @internal_hash[:work_on_this_directory] = return_pwd
+    # ======================================================================= #
+    # === :collapse
+    #
+    # Whether to collapse or not.
+    # ======================================================================= #
+    @internal_hash[:collapse] = false
+    # ======================================================================= #
+    # === :total_filesize
+    # ======================================================================= #
+    @internal_hash[:total_filesize] = 0 # Keep the total file size.
+    # ======================================================================= #
+    # === :report_filesize
+    #
+    # Tell the user the total filesize of the listing.
+    # ======================================================================= #
+    @internal_hash[:report_filesize] = true
+    # ======================================================================= #
+    # === :default_colour
+    # ======================================================================= #
+    @internal_hash[:default_colour] = :steelblue
+    # ======================================================================= #
+    # === :colourize_kb_and_mb
+    # ======================================================================= #
+    @internal_hash[:colourize_kb_and_mb] = COLOURIZE_KB_AND_MB
+    # ======================================================================= #
+    # === :threshold_for_file_size
+    #
+    # Only honoured if @truncate_long_file_names is true.
+    # ======================================================================= #
+    @internal_hash[:threshold_for_file_size] = FILE_SIZE_THRESHOLD
+    # ======================================================================= #
+    # === :show_group_information
+    # ======================================================================= #
+    @internal_hash[:show_group_information] = true
+    # ======================================================================= #
+    # === :show_modification_time
+    #
+    # if true then we show the modification time of the inode in question.
+    # ======================================================================= #
+    @internal_hash[:show_modification_time] = true
+    # ======================================================================= #
+    # === :use_colours
+    # ======================================================================= #
+    @internal_hash[:use_colours] = true
+    # ======================================================================= #
+    # === :show_leading_slash
+    #
+    # Show the leading slash in / directory.
+    # ======================================================================= #
+    @internal_hash[:show_leading_slash] = false
+    # ======================================================================= #
+    # === :sort_by
+    #
+    # This value must be nil initially, so that we will not do any
+    # sorting at all whatsoever.
+    # ======================================================================= #
+    @internal_hash[:sort_by] = nil
+    # ======================================================================= #
+    # === :show_only_symlinks
+    # ======================================================================= #
+    @internal_hash[:show_only_symlinks] = false
+    # ======================================================================= #
+    # === truncate_long_file_names
+    #
+    # If true, we truncate too-long file names.
+    # ======================================================================= #
+    @internal_hash[:truncate_long_file_names] = false
+    # ======================================================================= #
+    # === :colour_for_symlinks
+    # ======================================================================= #
+    @internal_hash[:colour_for_symlinks] = Colours.colour_for_symlinks
+    # ======================================================================= #
+    # === :show_size
+    #
+    # Whether to show the size of the entry at hand.
+    # ======================================================================= #
+    @internal_hash[:show_size] = true
+    # ======================================================================= #
+    # === :show_header
+    # ======================================================================= #
+    @internal_hash[:show_header] = true
+    # ======================================================================= #
+    # === :show_index
+    #
+    # Whether to show a leading index or not. I like this, so it is on
+    # by default.
+    # ======================================================================= #
+    @internal_hash[:show_index] = true
+    # ======================================================================= #
+    # === :colourize_path
+    #
+    # If the next variable is set to true then the path, such as
+    # /foo/bar.md will be colourized when .report() is called.
+    # ======================================================================= #
+    @internal_hash[:colourize_path] = true
+    # ======================================================================= #
+    # === :show_permission_bits
+    #
+    # If the following variable is set to true then the entry at hand
+    # will show inclusive "drwxr-xr-x".
+    # ======================================================================= #
+    @internal_hash[:show_permission_bits] = true
+    # ======================================================================= #
+    # === :show_dots_only_entries
+    #
+    # This setting filters away '.' and '..' from the result.
+    # ======================================================================= #
+    @internal_hash[:show_dots_only_entries] = false
+    # ======================================================================= #
+    # === :show_statistics
+    # ======================================================================= #
+    @internal_hash[:show_statistics] = true
+    # ======================================================================= #
+    # === :directory_content
+    #
+    # This variable will keep a reference to class
+    # DirectoryParadise::Content.
+    # ======================================================================= #
+    @internal_hash[:directory_content] = DirectoryParadise::Content.new
+    # ======================================================================= #
+    # === :hash_colours_for_bytes_value
+    #
+    # We need to capture this here because we may try to want to sanitize
+    # the given values, such as when the user types an incorrect colour,
+    # like "mediumpurples" rather than "mediumpurple".
+    # ======================================================================= #
+    @internal_hash[:hash_colours_for_bytes_value] = HASH_COLOURS_FOR_BYTES_VALUE
+    # ======================================================================= #
+    # === :show_simplified
+    #
+    # The following variable tells this class to keep a simplified directory
+    # layout.
+    #
+    # If it is true, then we only display a short variant of the file
+    # content.
+    # ======================================================================= #
+    @internal_hash[:show_simplified] = true
+    # ======================================================================= #
+    # === :result
+    # ======================================================================= #
+    @internal_hash[:result] = ''.dup
+    do_not_show_hidden_files # Do not show hidden files by default.
+    do_show_header
+    do_show_index
+    do_show_modification_time
+    do_show_the_content
+    do_not_stop_on_missing_symlink
+  end
+
+  # ========================================================================= #
+  # === try_to_report_the_total_filesize
+  #
+  # Use this method to report the total filesize from a given directory.
+  # ========================================================================= #
+  def try_to_report_the_total_filesize
+    total_file_size = total_file_size?
+    if total_file_size > 0
+      ee "\nTotal file size in the directory "
+      if use_colours?
+        e colourize_directory(which_dir?)
+      else
+        e which_dir?
+      end
+      append("\nTotal file size in the directory #{which_dir?}")
+      n_KB = (total_file_size / 1024.0)
+      n_MB = (n_KB / 1024.0)
+      append(
+        "  #{total_file_size} bytes (#{n_KB.round(2)} KB) "\
+        "(#{n_MB.round(2)} MB)"
+      )
+      e steelblue(
+          "  #{total_file_size} bytes (#{n_KB.round(2)} KB) "\
+          "(#{n_MB.round(2)} MB)"
+        )
+    end
+  end
+
+  # ========================================================================= #
+  # === return_file_permission_of
+  # ========================================================================= #
+  def return_file_permission_of(i)
+    if condensed? and i.size == 10 # Then we assume we have the long format.
+      Roebe::PermissionAsciiFormat[i, :convert_into_decimal_format]
+    else # else we must convert it back.
+      i # Simply return as-is here.
+    end
+  end
+
+  # ========================================================================= #
+  # === set_sort_by
+  # ========================================================================= #
+  def set_sort_by(i)
+    @internal_hash[:sort_by] = i
+  end; alias sort_by= set_sort_by # === sort_by=
+       alias sort_by  set_sort_by # === sort_by
+
+  # ========================================================================= #
+  # === sort_how                                     (sort tag, sort how tag)
+  #
+  # Here we determine how to sort.
+  #
+  # The sort possibilities are:
+  #
+  #   - by datesort_how
+  #   - by size
+  #   - in a reversed manner
+  #
+  # ========================================================================= #
+  def sort_how(
+      how = :size
+    )
+    how = how.to_s.downcase.to_sym # We want a downcased Symbol here.
+    case how # case tag
+    # ======================================================================= #
+    # === :reversed
+    # ======================================================================= #
+    when :reversed,
+         :reverse,
+         :by_reverse,
+         :by_reversed
+      set_sort_by(:reversed)
+    # ======================================================================= #
+    # === :date
+    # ======================================================================= #
+    when :date,
+         :by_date
+      set_sort_by(:date)
+    # ======================================================================= #
+    # === :size
+    # ======================================================================= #
+    when :size,
+         :sized,
+         :by_size # Sort by size.
+      set_sort_by(:size)
+    # ======================================================================= #
+    # === :modification_time
+    # ======================================================================= #
+    when :modification_time,
+         :by_modification_time
+      set_sort_by(:modification_time)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_help_options                                          (help tag)
+  #
+  # To invoke this method, try:
+  #
+  #   sdc --help
+  #
+  # ========================================================================= #
+  def show_help_options # Help tag.
+    e "#{rev}The currently available help options for "\
+      "#{simp('DirectoryContent::Report')} are:"
+    e
+    show_this_help_line :collapse, :short
+    show_this_help_line :toggle
+    show_this_help_line :nocolours
+    show_this_help_line :only_dirs
+    show_this_help_line :show_hidden_files
+    show_this_help_line :sized
+    show_this_help_line :date
+    show_this_help_line :lead
+    show_this_help_line :disable_show_modification_time
+    show_this_help_line :condensed
+    e
+    e 'Additionally, the following options are a bit more '\
+      'extensively documented here:'
+    e
+    Colours.eparse '  --show-only-symlinks # '\
+                   'This will show only symlinks in the target directory'
+    e
+    exit
+  end
+
+  # ========================================================================= #
+  # === show_dots_only_entries?
+  # ========================================================================= #
+  def show_dots_only_entries?
+    @internal_hash[:show_dots_only_entries]
+  end
+
+  # ========================================================================= #
+  # === show_only_symlinks?
+  # ========================================================================= #
+  def show_only_symlinks?
+    @internal_hash[:show_only_symlinks]
+  end
+
+  # ========================================================================= #
+  # === ignore_backups?
+  # ========================================================================= #
+  def ignore_backups?
+    @internal_hash[:ignore_backups]
+  end
+
+  # ========================================================================= #
+  # === collapse?
+  #
+  # The revers of whether we will show the full path or not.
+  # ========================================================================= #
+  def collapse?
+    !show_full_path?
+  end
+
+  # ========================================================================= #
+  # === content?
+  # ========================================================================= #
+  def content?
+    @internal_hash[:directory_content].content?
+  end; alias content content? # === content?
+
+  # ========================================================================= #
+  # === show_inode?
+  # ========================================================================= #
+  def show_inode?
+    @internal_hash[:show_inode]
+  end
+
+  # ========================================================================= #
+  # === show_full_path?
+  # ========================================================================= #
+  def show_full_path?
+    @internal_hash[:show_full_path]
+  end; alias show_full_path show_full_path? # === show_full_path
+
+  # ========================================================================= #
+  # === show_group_information?
+  # ========================================================================= #
+  def show_group_information?
+    @internal_hash[:show_group_information]
+  end
+
+  # ========================================================================= #
+  # === show_size?
+  # ========================================================================= #
+  def show_size?
+    @internal_hash[:show_size]
+  end
+
+  # ========================================================================= #
+  # === colourize_path?
+  # ========================================================================= #
+  def colourize_path?
+    @internal_hash[:colourize_path]
+  end
+
+  # ========================================================================= #
+  # === show_permissionsbits?
+  # ========================================================================= #
+  def show_permission_bits?
+    @internal_hash[:show_permission_bits]
+  end; alias show_permissions? show_permission_bits? # === show_permissions?
+
+  # ========================================================================= #
+  # === directory_content?
+  # ========================================================================= #
+  def directory_content?
+    @internal_hash[:directory_content]
+  end
+
+  # ========================================================================= #
+  # === obtain_from_directory_content
+  # ========================================================================= #
+  def obtain_from_directory_content(i)
+    @internal_hash[:directory_content].obtain_from(i)
+  end
+
+  # ========================================================================= #
+  # === display_only_directories?
+  # ========================================================================= #
+  def display_only_directories?
+    @internal_hash[:display_only_directories]
+  end
+
+  # ========================================================================= #
+  # === show_hidden_files?
+  # ========================================================================= #
+  def show_hidden_files?
+    @internal_hash[:show_hidden_files]
+  end
+
+  # ========================================================================= #
+  # === show_index?
+  # ========================================================================= #
+  def show_index?
+    @internal_hash[:show_index]
+  end; alias use_index? show_index? # === use_index?
+
+  # ========================================================================= #
+  # === entries?
+  # ========================================================================= #
+  def entries?
+    @internal_hash[:directory_content].entries
+  end; alias _ entries? # === _
+
+  # ========================================================================= #
+  # === sort_by?
+  # ========================================================================= #
+  def sort_by?
+    @internal_hash[:sort_by]
+  end
+
+  # ========================================================================= #
+  # === symlinks?
+  # ========================================================================= #
+  def symlinks?
+    @internal_hash[:directory_content].symlinks?
+  end
+
+  # ========================================================================= #
+  # === n_symlinks?
+  # ========================================================================= #
+  def n_symlinks?
+    symlinks?.size
+  end
+
+  # ========================================================================= #
+  # === directories?
+  # ========================================================================= #
+  def directories? # Feedback all available directories here.
+    @internal_hash[:directory_content].directories?
+  end
+
+  # ========================================================================= #
+  # === files?
+  #
+  # Query for all available files, by delegating towards class
+  # DirectoryContent.
+  # ========================================================================= #
+  def files?
+    @internal_hash[:directory_content].files?
+  end
+
+  # ========================================================================= #
+  # === n_files?
+  # ========================================================================= #
+  def n_files?
+    files?.size
+  end
+
+  # ========================================================================= #
+  # === show_statistics?
+  # ========================================================================= #
+  def show_statistics?
+    @internal_hash[:show_statistics]
+  end
+
+  # ========================================================================= #
+  # === return_directory_content
+  # ========================================================================= #
+  def return_directory_content(
+      i = @internal_hash[:work_on_this_directory]
+    )
+    obtain_from_directory_content(i)
+    consider_sorting
+    _ = @internal_hash[:directory_content].entries?
+    return _
+  end; alias gather_content           return_directory_content # === gather_content
+       alias gather                   return_directory_content # === gather
+       alias run_main_loop            return_directory_content # === run_main_loop
+       alias obtain_directory_listing return_directory_content # === obtain_directory_listing
+       alias obtain_entries           return_directory_content # === obtain_entries
+
+  # ========================================================================= #
+  # === display_content?
+  # ========================================================================= #
+  def display_content?
+    @internal_hash[:display_content]
+  end
+
+  # ========================================================================= #
+  # === do_not_show_simplified
+  # ========================================================================= #
+  def do_not_show_simplified
+    @internal_hash[:show_simplified] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_simplified
+  # ========================================================================= #
+  def do_show_simplified
+    @internal_hash[:show_simplified] = true
+  end; alias show_simplified do_show_simplified # === show_simplified
+
+  # ========================================================================= #
+  # === n_directories?
+  #
+  # This will exclude directories with a trailing '.'
+  # ========================================================================= #
+  def n_directories?
+    directories = directories?.reject {|entry| entry.end_with? '/.' }
+    return directories.size
+  end
+
+  # ========================================================================= #
+  # === hash_colours_for_bytes_value?
+  # ========================================================================= #
+  def hash_colours_for_bytes_value?
+    @internal_hash[:hash_colours_for_bytes_value]
+  end
+
+  # ========================================================================= #
+  # === report_filesize?
+  # ========================================================================= #
+  def report_filesize?
+    @internal_hash[:report_filesize]
+  end; alias report_the_total_filesize? report_filesize? # === report_the_total_filesize?
+
+  # ========================================================================= #
+  # === total_filesize?
+  # ========================================================================= #
+  def total_filesize?
+    @internal_hash[:total_filesize]
+  end; alias total_file_size? total_filesize? # === total_file_size?
+
+  # ========================================================================= #
+  # === work_on_which_directory?
+  # ========================================================================= #
+  def work_on_which_directory?
+    @internal_hash[:work_on_this_directory]
+  end; alias from_which_directory? work_on_which_directory? # === from_which_directory?
+       alias base_directory?       work_on_which_directory? # === base_directory?
+       alias input?                work_on_which_directory? # === input?
+       alias which_directory?      work_on_which_directory? # === which_directory?
+       alias which_dir?            work_on_which_directory? # === which_dir?
+       alias base_dir?             work_on_which_directory? # === base_dir?
+       alias dir?                  work_on_which_directory? # === dir?
+
+  # ========================================================================= #
+  # === dont_show_header
+  # ========================================================================= #
+  def dont_show_header
+    @internal_hash[:show_header] = false
+  end; alias do_not_show_the_header dont_show_header # === do_not_show_the_header
+
+  # ========================================================================= #
+  # === do_show_hidden_files
+  # ========================================================================= # 
+  def do_show_hidden_files
+    @internal_hash[:show_hidden_files] = true
+  end
+
+  # ========================================================================= #
+  # == dont_show_index
+  # ========================================================================= #
+  def dont_show_index
+    @internal_hash[:show_index] = false
+  end; alias do_not_show_the_index dont_show_index # === do_not_show_the_index
+       alias do_not_show_index     dont_show_index # === do_not_show_index
+
+  # ========================================================================= #
+  # === toggle_colourize
+  # ========================================================================= #
+  def toggle_colourize
+    if @internal_hash[:colourize_kb_and_mb] == false
+      @internal_hash[:colourize_kb_and_mb] = true
+    else
+      @internal_hash[:colourize_kb_and_mb] = false
+    end
+  end; alias toggle toggle_colourize # === toggle
+
+  # ========================================================================= #
+  # === do_not_ignore_backups
+  # ========================================================================= #
+  def do_not_ignore_backups
+    @internal_hash[:ignore_backups] = false
+  end
+
+  # ========================================================================= #
+  # === do_colourize_kb_and_mb
+  # ========================================================================= #
+  def do_colourize_kb_and_mb
+    @internal_hash[:colourize_kb_and_mb] = true
+  end
+
+  # ========================================================================= #
+  # === collapse=
+  # ========================================================================= #
+  def collapse=(i)
+    @internal_hash[:collapse] = i
+  end
+
+  # ========================================================================= #
+  # === stop_on_missing_symlink=
+  # ========================================================================= #
+  def stop_on_missing_symlink=(i)
+    @internal_hash[:stop_on_missing_symlink] = i
+  end
+
+  # ========================================================================= #
+  # === do_show_full_path
+  # ========================================================================= #
+  def do_show_full_path
+    @internal_hash[:show_full_path] = true
+  end
+
+  # ========================================================================= #
+  # === dont_show_full_path
+  #
+  # I assume that this option is interconnected with another option,
+  # namely the ability to show, or rather not show, a leading slash.
+  #
+  # Thus, as of May 2015, we will also disable showing the leading
+  # slash whenever we invoke this method here.
+  # ========================================================================= #
+  def dont_show_full_path
+    set_show_full_path(false)
+    do_not_show_leading_slash
+  end; alias do_not_show_full_path     dont_show_full_path # === do_not_show_full_path
+       alias enable_collapse           dont_show_full_path # === enable_collapse
+       alias do_not_show_the_full_path dont_show_full_path # === do_not_show_the_full_path
+       alias do_show_only_filename     dont_show_full_path # === do_show_only_filename
+
+  # ========================================================================= #
+  # === check_whether_we_use_colours
+  #
+  # We will enable the colours if necessary.
+  # ========================================================================= #
+  def check_whether_we_use_colours
+    if use_colours?
+      enable_colours
+      check_whether_the_colours_defined_in_the_yaml_file_are_valid
+      define_colours
+    end
+  end
+
+  # ========================================================================= #
+  # === do_not_stop_on_missing_symlink
+  # ========================================================================= #
+  def do_not_stop_on_missing_symlink
+    @internal_hash[:stop_on_missing_symlink] = false # if true we will stop on missing symlink.
+  end
+
+  # ========================================================================= #
+  # === do_show_condensed_permissions
+  # ========================================================================= #
+  def do_show_condensed_permissions
+    @internal_hash[:show_condensed_permissions] = true
+  end
+
+  # ========================================================================= #
+  # === ignore_backups
+  # ========================================================================= #
+  def ignore_backups
+    @internal_hash[:ignore_backups] = true
+  end
+
+  # ========================================================================= #
+  # === do_not_report_filesize
+  # ========================================================================= #
+  def do_not_report_filesize
+    @internal_hash[:report_filesize] = false
+  end; alias dont_report_total_filesize do_not_report_filesize # === dont_report_total_filesize
+
+  # ========================================================================= #
+  # === do_show_index
+  # ========================================================================= #
+  def do_show_index
+    @internal_hash[:show_index] = true # if true then we will show the index.
+  end
+
+  # ========================================================================= #
+  # === do_report_filesize
+  # ========================================================================= #
+  def do_report_filesize
+    @internal_hash[:report_filesize] = true
+  end
+
+  # ========================================================================= #
+  # === do_not_show_size
+  # ========================================================================= #
+  def do_not_show_size
+    @internal_hash[:show_size] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_almost_nothing
+  # ========================================================================= #
+  def do_show_almost_nothing
+    do_not_show_size
+    do_not_show_index
+    do_not_show_permissions
+    do_not_show_modtime
+  end
+
+  # ========================================================================= #
+  # === do_truncate_long_file_names
+  # ========================================================================= #
+  def do_truncate_long_file_names
+    @internal_hash[:truncate_long_file_names] = true
+  end; alias truncate do_truncate_long_file_names # === truncate
+
+  # ========================================================================= #
+  # === disable_show_modification_time
+  # ========================================================================= #
+  def disable_show_modification_time
+    @internal_hash[:show_modification_time] = false
+  end; alias dont_show_modification_time   disable_show_modification_time
+       alias do_not_show_modification_time disable_show_modification_time
+       alias do_not_show_modtime           disable_show_modification_time
+
+  # ========================================================================= #
+  # === do_shorten_display
+  # ========================================================================= #
+  def do_shorten_display
+    enable_collapse
+    disable_show_modification_time # Added Aug 2012.
+  end
+
+  # ========================================================================= #
+  # === do_not_debug
+  # ========================================================================= #
+  def do_not_debug
+    @internal_hash[:debug] = false # Whether we debug this class or not.
+  end
+
+  # ========================================================================= #
+  # === do_not_truncate_long_file_names
+  # ========================================================================= #
+  def do_not_truncate_long_file_names
+    @internal_hash[:truncate_long_file_names] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_leading_slash
+  # ========================================================================= #
+  def do_show_leading_slash
+    @internal_hash[:show_leading_slash] = true
+  end
+
+  # ========================================================================= #
+  # === do_show_modification_time
+  # ========================================================================= #
+  def do_show_modification_time
+    @internal_hash[:show_modification_time] = true
+  end
+
+  # ========================================================================= #
+  # === do_not_show_inode
+  # ========================================================================= #
+  def do_not_show_inode
+    @internal_hash[:show_inode] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_inode
+  # ========================================================================= #
+  def do_show_inode # Show the inode number if true.
+    @internal_hash[:show_inode] = true
+  end
+
+  # ========================================================================= #
+  # === do_hide_files
+  # ========================================================================= #
+  def do_hide_files
+    @internal_hash[:show_hidden_files] = false
+  end; alias do_not_show_hidden_files do_hide_files # === do_not_show_hidden_files
+
+  # ========================================================================= #
+  # === do_show_uncondensed_permissions
+  # ========================================================================= #
+  def do_show_uncondensed_permissions
+    @internal_hash[:show_condensed_permissions] = false
+  end; alias dont_show_condensed_permissions do_show_uncondensed_permissions
+
+  # ========================================================================= #
+  # === show_this_help_line
+  # ========================================================================= #
+  def show_this_help_line(
+      i = :toggle, optional_additional_argument = nil
+    )
+    if optional_additional_argument
+      e "  - #{sfancy(i)} / #{sfancy(optional_additional_argument)}"
+    else
+      e "  - #{sfancy(i)}"
+    end
+  end
+
+  # ========================================================================= #
+  # === set_show_full_path
+  # ========================================================================= #
+  def set_show_full_path(i = true)
+    @internal_hash[:show_full_path] = i
+  end
+
+  # ========================================================================= #
+  # === run_already?
+  # ========================================================================= #
+  def run_already?
+    @internal_hash[:run_already]
+  end
+
+  # ========================================================================= #
+  # === set_work_on_this_directory
+  #
+  # This method will determine on which target directory (the base
+  # directory) this class will work on.
+  #
+  # It must be ensured that this variable will have a trailing '/'
+  # character, to properly indicate that we are dealing with a
+  # directory here.
+  # ========================================================================= #
+  def set_work_on_this_directory(
+      i = return_pwd
+    )
+    # ======================================================================= #
+    # === Handle Hashes first
+    # ======================================================================= #
+    if i.is_a? Hash
+      if i.has_key? :from
+        i = i.delete(:from)
+      end
+    end
+    if i.is_a? Array
+      _ = return_non_hyphen_entries_from(i)
+      if _.empty?
+        i = return_pwd
+      else
+        i = _
+      end
+      i = i.join(' ').strip if i.is_a? Array
+    end
+    case i
+    # ======================================================================= #
+    # === :dont_run_yet
+    # ======================================================================= #
+    when :dont_run_yet
+      i = nil
+      @internal_hash[:run_already] = false
+    # ======================================================================= #
+    # === :show_content
+    # ======================================================================= #
+    when :show_content
+      do_show_the_content
+      i = return_pwd
+    end
+    begin
+      # ===================================================================== #
+      # Default values come next here in this clause.
+      # ===================================================================== #
+      i = return_pwd if i.nil?
+      i = i.dup if i.frozen?
+      # ===================================================================== #
+      # We need to default to the current directory if there exists a
+      # directory with that name.
+      # ===================================================================== #
+      i = return_pwd unless Dir.exist?(i)
+      if i.is_a? String and i.empty?
+        i = return_pwd
+      end
+    rescue Errno::ENOENT # Rescue non-existing directories.
+      e 'An error occurred. The directory may have been removed or the local'
+      e "filesystem is unavailable. Thus, we will display \"/\" instead.#{N}"
+      i = '/'
+    end
+    i = i.dup if i.frozen?
+    i << '/' unless i.end_with? '/'
+    i.squeeze!('/')
+    @internal_hash[:work_on_this_directory] = i
+  end; alias set_from_which_directory set_work_on_this_directory # === set_from_which_directory
+       alias set_dir                  set_work_on_this_directory # === set_dir
+       alias set_main_directory       set_work_on_this_directory # === set_main_directory
+       alias set_base_directory       set_work_on_this_directory # === set_base_directory
+
+  # ========================================================================= #
+  # === yaml_file?
+  # ========================================================================= #
+  def yaml_file? 
+    FILE_COLOURS_FOR_BYTES_VALUES
+  end
+
+  # ========================================================================= #
+  # === check_whether_the_colours_defined_in_the_yaml_file_are_valid
+  # ========================================================================= #
+  def check_whether_the_colours_defined_in_the_yaml_file_are_valid
+    _ = @internal_hash[:hash_colours_for_bytes_value]
+    _.each_pair {|key, value| # The entries will be 'KB' and :lightgreen, for instance.
+      if Object.const_defined?(:Colours) and
+         ::Colours.respond_to?(value)
+      else
+        e 'Attention please: the Colours namespace does not have a'
+        e 'colour named `'+value.to_s+'` defined.'
+        e
+        e 'One key (the one named '+key.to_s+') currently has this'
+        e 'value defined, though.'
+        e
+        e 'Please change this by modifying the following file:'
+        e
+        e sfile("  #{yaml_file?}")
+        e
+        e 'To get a listing of all defined colour-names, do this:'
+        e
+        e "  require 'colours'"
+        e '  pp Colours.html_colours?'
+        e
+        exit
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === apply_filter
+  #
+  # Use this method here to apply a filter on the main entries.
+  # ========================================================================= #
+  def apply_filter(i)
+    i = i.dup if i.frozen?
+    i.delete!('*') if i.include? '*'
+    i.delete!('/') if i.include? '/' # This may be incorrect.
+    obtain_entries unless entries?
+    entries?.select! {|entry|
+      entry.include?(i)
+    }
+    entries?
+  end
+
+  # ========================================================================= #
+  # === consider_colourizing_filename
+  # ========================================================================= # 
+  def consider_colourizing_filename(filename)
+    result = ''.dup
+    if File.exist? filename
+      filetype = File.ftype(filename)
+      unless show_leading_slash?
+        filename[0,1] = '' if filename.start_with? '/'
+      end
+      # ===================================================================== #
+      # Next, honour the variable @show_full_path if it was set to true.
+      # ===================================================================== #
+      unless show_full_path?
+        filename = File.basename(filename)
+      end
+      case filetype
+      # ===================================================================== #
+      # === link
+      # ===================================================================== #
+      when 'link' # Handle Symlinks here.
+        result = colourize_symlink(filename)
+      # ===================================================================== #
+      # === directory
+      # ===================================================================== #
+      when 'directory'
+        result = colourize_directory(filename) # This is actually sdir().
+      # ===================================================================== #
+      # === file
+      # ===================================================================== #
+      when 'file'
+        result = sfile(filename)
+      end
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === do_ignore_backups
+  # ========================================================================= #
+  def do_ignore_backups
+    # ======================================================================= #
+    # Do not list implied entries ending with '~' in the following option.
+    # ======================================================================= #
+    if ignore_backups?
+      directory_content?.ignore_backups
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_sorting_by
+  #
+  # This is the specific sorting-action. The method will delegate onto
+  # class DirectoryContent::ShowDirectoryContent.
+  # ========================================================================= #
+  def consider_sorting_by(
+      i = sort_by?
+    )
+    directory_content?.consider_sorting_by(i)
+  end
+
+  # ========================================================================= #
+  # === shorten_file_elegantly
+  #
+  # We need to take into account that our file could be a directory too.
+  # ========================================================================= #
+  def shorten_file_elegantly(
+      i, threshold = FILE_SIZE_THRESHOLD
+    )
+    i = i.to_s.dup
+    middle_pos = (i.size / 2) - 10
+    oversize = i.size - threshold # The oversize value
+    if oversize > 0
+      start_pos = middle_pos - (oversize / 2)
+      end_pos   = start_pos + oversize
+      i[start_pos .. end_pos] = '[… Truncated …]' # This is the padding to use.
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === do_not_display_content
+  # ========================================================================= #
+  def do_not_display_content
+    @internal_hash[:display_content] = false # if true, we display() the result.
+  end
+
+  # ========================================================================= #
+  # === do_show_the_content
+  # ========================================================================= #  
+  def do_show_the_content
+    @internal_hash[:display_content] = true
+  end; alias do_display_content do_show_the_content # === do_display_content
+
+  # ========================================================================= #
+  # === colourize_symlink
+  #
+  # Use this method to colourize a symlink.
+  # ========================================================================= #
+  def colourize_symlink(i)
+    result = return_name_of_this_symlink(i)
+    # ======================================================================= #
+    # Check whether we will use colours or whether we will not.
+    # ======================================================================= #
+    if File.symlink?(i)
+      if use_colours?
+        if stop_on_missing_symlink? and !File.readlink?(i)
+          opn; e "The symlink for #{i} does not exist."
+          opn; e 'Exiting now, as set per a configuration option.'
+          exit
+        end
+        result = " → #{skyblue(File.readlink(i))}" # Need to readlink on the original variant.
+      else
+        result = " → #{File.readlink(i)}"
+      end
+    end
+    return result
+  end
+
+  # ========================================================================= #
+  # === return_name_of_this_symlink
+  #
+  # File.basename() kills off leading '/', hence we need this method.
+  # ========================================================================= #
+  def return_name_of_this_symlink(i)
+    i = File.basename(i)
+    if return_pwd == '/' and show_leading_slash?
+      i.prepend '/'
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === do_show_only_symlinks
+  # ========================================================================= #
+  def do_show_only_symlinks
+    @internal_hash[:show_only_symlinks] = true
+  end
+
+  # ========================================================================= #
+  # === toggle_permission
+  # ========================================================================= #
+  def toggle_permission
+    _ = @internal_hash[:show_condensed_permissions]
+    @internal_hash[:show_condensed_permissions] = !_ # Toggle it here.
+  end
+
+  # ========================================================================= #
+  # === do_not_display_only_directories
+  # ========================================================================= #
+  def do_not_display_only_directories
+    @internal_hash[:display_only_directories] = false # Whether to display only directories or not.
+  end
+
+  # ========================================================================= #
+  # === do_not_show_permissions
+  # ========================================================================= #
+  def do_not_show_permissions
+    @internal_hash[:show_permission_bits] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_header
+  # ========================================================================= #
+  def do_show_header
+    @internal_hash[:show_header] = true
+  end
+
+  # ========================================================================= #
+  # === do_sort_reversed
+  # ========================================================================= #
+  def do_sort_reversed
+    sort_how :reverse
+  end
+
+  # ========================================================================= #
+  # === do_not_show_group_information
+  # ========================================================================= #
+  def do_not_show_group_information
+    @internal_hash[:show_group_information] = false
+  end; alias no_groups do_not_show_group_information # === no_groups
+
+  # ========================================================================= #
+  # === do_not_show_the_owner
+  # ========================================================================= #
+  def do_not_show_the_owner
+    @internal_hash[:show_owner] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_group_information
+  # ========================================================================= #
+  def do_show_group_information
+    @internal_hash[:show_group_information] = true
+  end
+
+  # ========================================================================= #
+  # === do_show_owner
+  # ========================================================================= #
+  def do_show_owner
+    @internal_hash[:show_owner] = true
+  end
+
+  # ========================================================================= #
+  # === do_not_show_leading_slash
+  # ========================================================================= #
+  def do_not_show_leading_slash
+    @internal_hash[:show_leading_slash] = false
+  end
+
+  # ========================================================================= #
+  # === do_show_permissions
+  # ========================================================================= #
+  def do_show_permissions
+    @internal_hash[:show_permission_bits] = true
+  end
+
+  # ========================================================================= #
+  # === only_directories
+  #
+  # Only get directories, with this method.
+  # ========================================================================= #
+  def only_directories
+    @internal_hash[:display_only_directories] = true
+  end
+
+  # ========================================================================= #
+  # === run_then_display
+  # ========================================================================= #
+  def run_then_display
+    run
+    display
+  end; alias gather_then_display_content run_then_display # === gather_then_display_content
+
+  # ========================================================================= #
+  # === show_header?
+  #
+  # Whether we will show the header or whether we will not. That header
+  # is not typical for the normal GNU "ls" command, hence why we need
+  # to have such an option.
+  # ========================================================================= #
+  def show_header?
+    @internal_hash[:show_header]
+  end
+
+  # ========================================================================= #
+  # === colourize_kb_and_mb?
+  # ========================================================================= #
+  def colourize_kb_and_mb?
+    @internal_hash[:colourize_kb_and_mb]
+  end
+
+  # ========================================================================= #
+  # === stop_on_missing_symlink?
+  # ========================================================================= #
+  def stop_on_missing_symlink?
+    @internal_hash[:stop_on_missing_symlink]
+  end
+
+  # ========================================================================= #
+  # === show_condensed_permissions?
+  # ========================================================================= #
+  def show_condensed_permissions?
+    @internal_hash[:show_condensed_permissions]
+  end; alias condensed? show_condensed_permissions? # === condensed?
+
+  # ========================================================================= #
+  # === owner?
+  # ========================================================================= #
+  def owner?(i)
+    @internal_hash[:directory_content].owner?(i)
+  end
+
+  # ========================================================================= #
+  # === truncate_long_file_names?
+  # ========================================================================= #
+  def truncate_long_file_names?
+    @internal_hash[:truncate_long_file_names]
+  end
+
+  # ========================================================================= #
+  # === show_modification_time?
+  # ========================================================================= #
+  def show_modification_time?
+    @internal_hash[:show_modification_time]
+  end
+
+  # ========================================================================= #
+  # === show_leading_slash?
+  # ========================================================================= #
+  def show_leading_slash?
+    @internal_hash[:show_leading_slash]
+  end
+
+  # ========================================================================= #
+  # === colour_for_files?
+  # ========================================================================= #
+  def colour_for_files?
+    @internal_hash[:colour_for_files]
+  end
+
+  # ========================================================================= #
+  # === colour_for_symlinks?
+  # ========================================================================= #
+  def colour_for_symlinks?
+    @internal_hash[:colour_for_symlinks]
+  end
+
+  # ========================================================================= #
+  # === colour_for_directories?
+  # ========================================================================= #
+  def colour_for_directories?
+    @internal_hash[:colour_for_directories]
+  end
+
+  # ========================================================================= #
+  # === show_simplified?
+  # ========================================================================= #
+  def show_simplified?
+    @internal_hash[:show_simplified]
+  end
+
+  # ========================================================================= #
+  # === do_sort_by_size
+  # ========================================================================= #
+  def do_sort_by_size
+    sort_how :by_size
+  end
+
+  # ========================================================================= #
+  # === consider_sorting
+  # ========================================================================= #
+  def consider_sorting
+    if sort_by?
+      @internal_hash[:directory_content].do_sort(sort_by?)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_content_for
+  # ========================================================================= #
+  def show_content_for(
+      this_path = '/'
+    )
+    @directory_content.obtain_entries(this_path)
+    report
+  end
+
+  # ========================================================================= #
+  # === report                               (report tag, display tag, d tag)
+  # 
+  # This method will always report the main dataset, as determined by
+  # class DirectoryParadise::Content.
+  # ========================================================================= #
+  def report(
+      _ = return_directory_content # This will return a Hash.
+    )
+    result?.clear # Clear the old results.
+    @internal_hash[:total_filesize] = 0 # Reset it always here.
+    show_condensed_permissions = show_condensed_permissions?
+    show_the_index             = show_index?
+    show_hidden_files          = show_hidden_files?
+    show_permission_bits       = show_permission_bits?
+    colourize_path             = colourize_path?
+    display_only_directories   = display_only_directories?
+    show_only_symlinks         = show_only_symlinks?
+    show_modification_time     = show_modification_time?
+    if display_only_directories
+      _.select! {|path, inner_hash| inner_hash[:type] == 'directory' }
+    end
+    if show_only_symlinks
+      _.select! {|path, inner_hash| inner_hash[:type] == 'link' }
+    end
+    # ======================================================================= #
+    # === Build up the header                                    (header tag)
+    #
+    # Build up the header first, then display it, but only if the user
+    # allows this to happen:
+    # ======================================================================= #
+    if show_header?
+      if show_statistics?
+        n_files       = n_files?
+        n_directories = n_directories?
+        n_symlinks    = n_symlinks?
+        file_string = ''
+        file_string = 's' if (n_files >= 0) # plural or not.
+        # =================================================================== #
+        # Pluralize the directory-string.
+        # =================================================================== #
+        directory_string = 'y'
+        symlink_string = 's'
+        symlink_string = '' if n_symlinks == 1
+        # =================================================================== #
+        # Last but not least notify the user of the findings.
+        # =================================================================== #
+        cmd = "#{rev}The directory #{sdir(work_on_which_directory?)}"
+        append(
+          "The directory #{work_on_which_directory?}"
+        )
+        e cmd
+        cmd = "#{rev}contains "+
+          sfile(
+            n_files.to_s+' file'+file_string
+          )+', '+
+          sdir(
+            n_directories.to_s+' director'+directory_string
+          )+' and '+
+          ssymlink(
+            n_symlinks.to_s+' symlink'+symlink_string
+          )+'.'
+        append("contains "+
+          n_files.to_s+' file'+file_string+
+          ', '+
+          n_directories.to_s+' director'+directory_string+
+          ' and '+
+          n_symlinks.to_s+' symlink'+symlink_string+
+          '.'
+        )
+        e cmd
+      end
+      header = ''.dup
+      header << "#{rev}" if use_colours?
+      append(:liner)
+      # ===================================================================== #
+      # Add the index next onto the header.
+      # ===================================================================== #
+      if show_the_index
+        padded = 'Index'.ljust(6)
+        header << sfancy(padded)
+        raw_append(padded)
+      end
+      # ===================================================================== #
+      # Show permission bits
+      # ===================================================================== #
+      if show_permission_bits
+        permissions = 'Permissions'.ljust(16)
+        header << springgreen(permissions)
+        raw_append(permissions)
+      end
+      # ===================================================================== #
+      # Next, determine whether we will display the modification-time
+      # or whether we will not:
+      # ===================================================================== #
+      if show_modification_time
+        modtime = 'ModTime'.ljust(8)
+        raw_append(modtime)
+        header << modtime
+      end
+      header << 'FileSize'.ljust(9)
+      raw_append('FileSize'.ljust(9))
+      header << 'Name'.ljust(5)
+      append('Name'.ljust(5))
+      eliner
+      append(:liner)
+      e header
+    end
+    # ======================================================================= #
+    # This may look like so:
+    #
+    #   "/Depot/j/yodel.rb"=>
+    #     {:size=>129,ei leader is lined up against a w
+    #      :type=>"file",
+    #      :is_executable=>false,
+    #      :path=>"/Depot/j/yodel.rb",
+    #      :ascii_representation=>"",
+    #      :last_modified=>2021-05-31 20:55:53.826658499 +0000,
+    #      :gid=>0,
+    #      :inode_number=>93858692,
+    #      :uid=>0,
+    #      :access_mode=>"644"}}}>
+    #
+    # ======================================================================= #
+    index = 0
+    _.each_pair {|path, inner_hash| # each tag
+      if path.end_with?('.') and !show_dots_only_entries? and
+         ( (path.end_with? '.') or (path.end_with? '..') )
+        next
+      end
+      if File.basename(path).start_with?('.') and !show_hidden_files
+        # =================================================================== #
+        # Ignore hidden files if the user specified so.
+        # =================================================================== #
+        next
+      end
+      index += 1
+      # ===================================================================== #
+      # Obtain the file size next, then add it onto the :total_filesize
+      # entry in the Hash.
+      # ===================================================================== #
+      file_size = inner_hash[:size]
+      name_of_owner = inner_hash[:name_of_owner]
+      name_of_owner = '%-10s' % owner?(name_of_owner) # Beautify this.
+      name_of_owner.strip!
+      @internal_hash[:total_filesize] += file_size.to_i # .to_i to avoid pesky nil values.
+      # ===================================================================== #
+      # Make the filesize human readable.
+      # ===================================================================== #
+      file_size = to_human_readable(file_size)
+      last_modified = inner_hash[:last_modified] # Example: 2021-01-11 05:53:35.844402868 +0000,
+      # ===================================================================== #
+      # All the output will be stored onto the variable called "line".
+      # ===================================================================== #
+      line = ''.dup
+      # ===================================================================== #
+      # === Index                                                 (index tag)
+      #
+      # Show the index next, if the user has enabled this.
+      # ===================================================================== #
+      if show_the_index
+        use_this_value_for_ljusting = 6
+        if _.size.to_s.size > 3
+          use_this_value_for_ljusting += (_.size.to_s.size - 3)
+        end
+        index_to_display = ("(#{index})") # Add () here as well.
+        index_to_display = index_to_display.ljust(use_this_value_for_ljusting)
+        raw_append(index_to_display)
+        if use_colours?
+          index_to_display.gsub!(/\((.+)\)/, '('+sfancy("\\1")+')')
+        end
+        line << index_to_display
+      end
+      # ===================================================================== #
+      # Add the permissions next - either in good old classical number
+      # format, such as 755, or as its ascii_representation.
+      # ===================================================================== #
+      if show_permission_bits
+        # =================================================================== #
+        # We update the inode-entry next to the hash.
+        # =================================================================== #
+        if show_inode?
+          inode = ' Inode: '
+          raw_append(inode)
+          inode = simp(inode) if use_colours?
+          line << inode+File.stat(path).ino.to_s # Add the Inode here.
+          append(File.stat(path).ino.to_s)
+        end
+        # =================================================================== #
+        # Next show the permission bits, if requested to do so.
+        # =================================================================== #
+        raw_append("#{return_chmod_value_of_this_file(path).ljust(5)}")
+        line << springgreen("#{return_chmod_value_of_this_file(path).ljust(5)}")
+        unless show_condensed_permissions
+          raw_append(
+            return_file_permission_of(
+              inner_hash[:ascii_representation]
+            ).ljust(11)
+          )
+          line << return_file_permission_of(
+            inner_hash[:ascii_representation]
+          ).ljust(11)
+        end
+      end
+      # ===================================================================== #
+      # === Show the modification time
+      #
+      # Add the last-modified part next.
+      #
+      # This could be last_modified.strftime(' %d.%m.%Y %H:%M') instead.
+      # ===================================================================== #
+      if show_modification_time?
+        raw_append("#{return_assumed_modification_time(last_modified)} ")
+        line << "#{return_assumed_modification_time(last_modified)} "
+      end
+      original_file_size_as_string = file_size.rjust(8)
+      file_size = original_file_size_as_string.dup
+      # ===================================================================== #
+      # Insert proper units next.
+      # ===================================================================== #
+      if colourize_kb_and_mb? && use_colours? # use .gsub directly
+        hash = hash_colours_for_bytes_value?
+        if file_size.include?    ' KB'
+          file_size.sub!(/KB/, send(hash['KB'].to_sym, 'KB'))
+        elsif file_size.include? ' MB'
+          file_size.sub!(/MB/, send(hash['MB'].to_sym, 'MB'))
+        elsif file_size.include? 'GB'
+          file_size.sub!(/GB/, send(hash['GB'].to_sym, 'GB'))
+        elsif file_size.include? ' B'
+          file_size.sub!(/ B/, send(hash['B'].to_sym, ' B'))
+        end
+      end
+      # ===================================================================== #
+      # === Show the Owner
+      #
+      # Add the owner. Must be padded, like the group name, in order to
+      # prevent mis-alignments.
+      # ===================================================================== #
+      unless show_simplified?
+        raw_append(" #{name_of_owner.ljust(6)}")
+        line << " #{name_of_owner.ljust(6)}"
+      end
+      # ===================================================================== #
+      # === Show the Group Information
+      #
+      # Add the group, if we allow that.
+      # ===================================================================== #
+      if show_group_information?
+        if inner_hash and inner_hash[:name_of_group]
+          raw_append(" #{inner_hash[:name_of_group].ljust(7)}")
+          line << " #{inner_hash[:name_of_group].ljust(7)}"
+        end
+      end
+      # ===================================================================== #
+      # Add the file size next:
+      # ===================================================================== #
+      raw_append(" #{original_file_size_as_string}")
+      line << " #{file_size}"
+      # ===================================================================== #
+      # === Truncate long file names
+      #
+      # We have to check whether the filename is too long. If it is then
+      # we will modify a call to .shorten_file_elegantly() but only if
+      # the user has requested this option.
+      #
+      # Directories will be handled in a special manner.
+      # ===================================================================== #
+      if (path.size > FILE_SIZE_THRESHOLD) and truncate_long_file_names?
+        # dirname = File.dirname(path)
+        # basename = File.basename(path)[0 .. FILE_SIZE_THRESHOLD]
+        # path = dirname+'/'+basename
+        path = shorten_file_elegantly(path)
+      end
+      unless show_full_path?
+        path = File.basename(path)
+      end
+      if File.directory?(path) and !path.end_with?('/')
+        path << '/'
+      end
+      raw_append(" #{path}")
+      line << " #{steelblue(path)}" # ← Add the filename here.
+      if colourize_path and path.include?('/')
+        splitted = path.split('/')
+        # =================================================================== #
+        # The last part can be a directory, symlink or file, typically.
+        # =================================================================== #
+        last = splitted.last
+        if File.directory? last
+          last << '/' unless last.end_with?('/')
+        end
+        raw_append(splitted[0..-2].join('/')+'/'+last)
+        last = lightblue(last)
+        path = splitted[0..-2].join('/')+'/'+last
+      end
+      if File.symlink?(path)
+        if stop_on_missing_symlink? # add functionality to stop on a missing symlink.
+          if !File.exist?(File.readlink(path))
+            add ' ← FILE DOES NOT EXIST!!! STOPPING NOW!'
+            exit
+          else # ok symlink exists.
+            # e ' IS A SYMLINK '
+          end
+        else
+          line << colourize_symlink(path)
+        end
+      end
+      append_newline
+      # ===================================================================== #
+      # Finally display the line to the user.
+      # ===================================================================== #
+      e line
+    }
+    append(:liner)
+    eliner
+    # ======================================================================= #
+    # Only add the filesize if we will report it.
+    # ======================================================================= #
+    try_to_report_the_total_filesize if report_the_total_filesize?
+  end; alias show                report # === show
+       alias display             report # === display
+       alias display_result      report # === display_result
+       alias display_content     report # === display_content
+       alias display_listing     report # === display_listing
+       alias do_report           report # === do_report
+       alias display_main_string report # === display_main_string
+
+  # ========================================================================= #
+  # === result?
+  #
+  # This will show the string that can be displayed.
+  # ========================================================================= #
+  def result?
+    @internal_hash[:result]
+  end
+
+  # ========================================================================= #
+  # === string?
+  # ========================================================================= #
+  def string?
+    result?.to_s
+  end; alias text? string? # === text?
+
+  # ========================================================================= #
+  # === append_to_the_result
+  #
+  # This currently always appends with a newline as well.
+  # ========================================================================= #
+  def append_to_the_result(i)
+    case i
+    # ======================================================================= #
+    # === :liner
+    # ======================================================================= #
+    when :liner,
+         :cliner
+      i = '―' * 80
+    end
+    @internal_hash[:result] << "#{i}\n"
+  end; alias append append_to_the_result # === append
+
+  # ========================================================================= #
+  # === append_newline
+  # ========================================================================= #
+  def append_newline
+    @internal_hash[:result] << "\n"
+  end
+
+  # ========================================================================= #
+  # === raw_append
+  # ========================================================================= #
+  def raw_append(i)
+    @internal_hash[:result] << i
+  end
+
+  # ========================================================================= #
+  # === rev
+  #
+  # The rev value can be re-defined by the user of this class.
+  # ========================================================================= #
+  def rev
+    @internal_hash[:default_colour]
+  end
+
+  # ========================================================================= #
+  # === define_colours
+  #
+  # define_colours() is called from reset()
+  # ========================================================================= #
+  def define_colours(
+      optional_hash_use_these_colours = nil
+    ) # Colours tag, colors tag.
+    _ = optional_hash_use_these_colours
+    if use_colours?
+      if _ # If the Hash is defined, enter here.
+pp 111
+        @internal_hash[:default_colour]           = Colours.beautiful _['colour_for_normal']
+        @internal_hash[:colour_for_files]         = Colours.beautiful _['colour_for_files']
+        @internal_hash[:colour_for_symlinks]      = Colours.beautiful _['colour_for_symlinks']
+        @internal_hash[:colour_for_directories]   = Colours.beautiful _['colour_for_directories']
+      else # Try to use Konsole after this point.
+        if Object.const_defined? :Colours
+pp 222
+          @internal_hash[:default_colour]         = Colours.restore? # Restore the default again.
+          @internal_hash[:colour_for_files]       = Colours.springgreen
+          @internal_hash[:colour_for_symlinks]    = Colours.slateblue
+          @internal_hash[:colour_for_directories] = Colours.paleturquoise
+        else # Else, use the default colours. They are defined in the module Colours.
+pp 333
+          @internal_hash[:default_colour]         = Colours::WHITE
+          @internal_hash[:colour_for_files]       = Colours::GREEN
+          @internal_hash[:colour_for_symlinks]    = Colours::BLUE
+          @internal_hash[:colour_for_directories] = Colours::CYAN # Which colour to use for directories.
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    check_whether_we_use_colours
+    menu
+    report if display_content?
+    do_display_content # Re-toggle it again after run() is used.
+  end
+
+end
+
+# =========================================================================== #
+# === DirectoryParadise.show
+# =========================================================================== #
+def self.show(i = ARGV)
+  DirectoryParadise::Report.new(i)
+end; self.instance_eval { alias []      show } # === DirectoryParadise[]
+     self.instance_eval { alias run     show } # === DirectoryParadise.run
+     self.instance_eval { alias do_show show } # === DirectoryParadise.do_show
+     self.instance_eval { alias report  show } # === DirectoryParadise.report
+
+# =========================================================================== #
+# === DirectoryParadise.new
+# =========================================================================== #
+def self.new(
+    work_on_this_directory = return_pwd,
+    run_already            = true
+  )
+  DirectoryParadise.new(work_on_this_directory, run_already)  
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  alias e puts
+  _ = DirectoryParadise.report(ARGV)
+#pp _
+  # _.print_the_namespace
+  e
+  e 'The raw string is:'
+  e
+  e _.result?
+end # rcontent