roebe 0.5.123

data/lib/roebe/shell/shell/core/show_display_feedback_and_report.rb

@@ -0,0 +1,2347 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# This file will store show-related, display-related, and report-related
+# methods. In other words, these methods are tasked to inform the user
+# about what is going on. It is, sort of, a report-interface towards the
+# end user who is working with a Roebe::Shell instance.
+#
+# Specifically methods that include the substring "show", "report",
+# and "display" should be stored in this file here, unless there is
+# a particular reason not to do so.
+# =========================================================================== #
+# require 'roebe/shell/shell/core/show_display_feedback_and_report.rb'
+# =========================================================================== #
+require 'roebe/base/base.rb'
+
+module Roebe
+
+class Shell < Base # === Roebe::Shell
+
+  require 'roebe/version/version.rb'
+  require 'roebe/toplevel_methods/display_array.rb'
+  # require 'roebe/shell/shell/constants.rb'
+  require 'roebe/shell/shell/core/documentation.rb'
+  require 'roebe/shell/shell/core/read_file.rb'
+  require 'roebe/shell/shell/core/yaml.rb'
+  require 'roebe/shell/colours/colour_codes.rb'
+
+  begin
+    require 'roebe/classes/on_screen_display.rb'
+  rescue LoadError => error
+    if ::Roebe.is_on_roebe?
+      p error
+      puts 'Roebe::OnScreenDisplay.rb does not seem to '\
+           'exist or is otherwise unavailable.'
+    end
+  end
+
+  # ========================================================================= #
+  # === show_configuration                                       (config tag)
+  #
+  # Use this method whenever you wish to show the configuration
+  # of the DiamondShell.
+  # ========================================================================= #
+  def show_configuration(
+      be_verbose = true
+    )
+    unicode_clinere
+    if be_verbose
+      e 'Showing the Configuration for the '+
+        steelblue('Roebe::Shell')+
+        ' component.'
+    end
+    config?.show_configuration if config?
+    padding = 52
+    # Next, we report the various config-entries.
+    begin
+      unicode_clinere
+      ee '  '; report_shell_version                 pad_to: padding # Which version is in use.
+      ee '  '; report_video_player_in_use           pad_to: padding
+      ee '  '; report_operating_system_in_use       pad_to: padding
+      ee '  '; report_which_editor_is_in_use        pad_to: padding
+      ee '  '; report_pdf_viewer_in_use             pad_to: padding
+      ee '  '; report_browser_in_use                pad_to: padding
+      ee '  '; feedback_will_we_use_colours?        pad_to: padding
+      ee '  '; do_we_use_readline?                  pad_to: padding
+      ee '  '; do_we_log_history?                   pad_to: padding # === History support
+      ee '  '; do_we_show_hidden_files?             pad_to: padding
+      ee '  '; will_we_show_the_absolute_path?      pad_to: padding
+      ee '  '; feedback_will_we_upload_screenshots? pad_to: padding
+    rescue Exception => error
+      e 'Error on line 72'
+      pp error
+    end if config?
+    unless config?
+      e 'We do not use a special configuration object so we '\
+        'will use'
+      e 'default values instead.'
+    end
+    unicode_clinere
+  end
+
+  # ========================================================================= #
+  # === feedback_will_we_upload_screenshots?
+  #
+  # This method will notify the user whether screenshots will be
+  # (automatically) uploaded. This is only really useful for
+  # my home system, but perhaps one day we may want to make
+  # this more generic, so that other users can also make use
+  # of thta configuration setting.
+  # ========================================================================= #
+  def feedback_will_we_upload_screenshots?(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash
+    e pad_this_string('Will we upload screenshots: ', counter)+
+      sfancy(
+        vt(upload_screenshots?
+      ).ljust(4))
+  end
+
+  # ========================================================================= #
+  # === show_default_applications
+  # ========================================================================= #
+  def show_default_applications(
+      i = FILE_DEFAULT_APPS
+    )
+    cat "#{i}"
+  end
+
+  # ========================================================================= #
+  # === do_we_log_history?
+  # ========================================================================= #
+  def do_we_log_history?(
+      optional_hash = {}
+    )
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash 
+    e pad_this_string('Do we log the history: ',counter)+
+      sfancy(
+        verbose_truth(shall_we_log_the_user_input_history?)
+      )
+  end
+
+  # ========================================================================= #
+  # === report_video_player_in_use
+  #
+  # Use this method to show which video player is in use.
+  # ========================================================================= #
+  def report_video_player_in_use(
+      optional_hash = {}
+    )
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash
+    e pad_this_string('Video Player designated in use: ', counter)+
+      sfancy(config?.video_player)
+  end; alias show_video_player report_video_player_in_use # === show_video_player
+
+  # ========================================================================= #
+  # === report_shell_version
+  # ========================================================================= #
+  def report_shell_version(
+      optional_hash = {}
+    )
+    version(:default, optional_hash) # ← This is defined in this file here.
+  end
+
+  # ========================================================================= #
+  # === show_full_configuration
+  # ========================================================================= #
+  def show_full_configuration
+    show_configuration # bl $DIA/base/show.rb
+    show_config_directory(:dont_pad) # Try this since June 2014.
+  end
+
+  # ========================================================================= #
+  # === display_this_file_or_run_the_command_called_file_on_it
+  # ========================================================================= #
+  def display_this_file_or_run_the_command_called_file_on_it(
+      i = this_file?
+    )
+    if i.nil? and this_file?
+      i = this_file?
+    end
+    i = i.to_s
+    if File.exist? i
+      set_file(i) # Since as of August 2022 we will keep track of the file.
+      esystem "file #{i}"
+    else
+      e col(i)
+    end
+  end
+
+  # ========================================================================= #
+  # === report_return_date
+  # ========================================================================= #
+  def report_return_date
+    _ = return_date
+    e simp(_)
+    set_result(_)
+    return _
+  end
+
+  begin
+    require 'directory_paradise'
+  rescue LoadError; end
+  # ========================================================================= #
+  # === show_directory_content
+  #
+  # Use this wrapper to show the content of a directory to the user.
+  #
+  #   The (1) first argument denotes which directory we will use to
+  #   display.
+  #
+  #   The (2) argument tells us whether we shall display hidden files
+  #   or not. By default we will not display hidden files. If you
+  #   need a specific method to show hidden files, input: "hidden"
+  #
+  # If the (1) first argument contains a '*' character, then we
+  # will use a filter. 
+  # ========================================================================= #
+  def show_directory_content(
+      from_where             = return_pwd,
+      also_show_hidden_files = show_hidden_files?,
+      show_only_directories  = false,
+      show_simplified        = config?.simplified
+    )
+    case show_simplified
+    # ======================================================================= #
+    # === :show_simplified
+    # ======================================================================= #
+    when :show_simplified
+      show_simplified = true
+    end
+    if from_where.is_a? Hash
+      if from_where.has_key? :show_hidden_files
+        also_show_hidden_files = from_where[:show_hidden_files]
+        from_where = return_pwd
+      end
+    elsif from_where.nil?
+      from_where = return_pwd # Default value in this case.
+    end
+    # ======================================================================= #
+    # We initialize an instance from class
+    # DirectoryContent::ShowDirectoryContent next.
+    #
+    # This object has to be customized, according to
+    # our configuration settings.
+    # ======================================================================= #
+    _ = ::DirectoryParadise::Report.new(
+          from_where,
+          :dont_run_yet
+        ) # bl $RSRC/directory_content/*/*/show_directory_content.rb
+    _.do_show_hidden_files if also_show_hidden_files
+    _.only_directories     if show_only_directories
+    if config?
+      _.show_simplified    if show_simplified
+      _.stop_on_missing_symlink = config?.stop_on_missing_symlink
+      _.truncate_long_file_names if config?.truncate_long_file_names
+      # ===================================================================== #
+      # Whether we will show the index or whether we will not.
+      # ===================================================================== #
+      _.do_not_show_the_index unless config?.display_index
+      # ===================================================================== #
+      # Whether we display the full path or whether we don't.
+      # ===================================================================== #
+      if config?.shorten_directory_names
+        _.do_not_show_the_full_path
+      else
+        _.do_show_full_path
+      end
+    end
+    # ======================================================================= #
+    # Whether we will show the modification time, or not, when doing a
+    # file-listing action (through "ls" or "ll" usually).
+    # ======================================================================= #
+    if config?.do_show_modification_time # ←- This since Aug 2012.
+      _.do_show_modification_time
+    else
+      _.do_not_show_modification_time
+    end if config?
+    # ======================================================================= #
+    # Whether we show the long variant of the permissions or the short
+    # variant.
+    # ======================================================================= #
+    if config?.show_condensed_permissions
+      _.do_show_condensed_permissions
+    else
+      _.do_show_uncondensed_permissions
+    end if config?
+    _.collapse = config?.collapse if config?
+    # ======================================================================= #
+    # Whether we show colours or whether we don't.
+    # ======================================================================= #
+    if use_colours?
+      _.enable_colours
+    else
+      _.disable_colours
+    end
+    # ======================================================================= #
+    # Next, we see whether we will use colours or not:
+    # ======================================================================= #
+    if config?
+      _.enable_colours(config?.colours) if use_colours?
+    end
+    if config?
+      _.menu('--shorten') if config?.shorten_directory_names
+    end
+    _.obtain_entries(from_where)
+    if from_where.include? '*' # Assume a filter.
+      _.apply_filter(from_where)
+      _.display # Display it here finally.
+    else
+      _.run
+      # _.display # This is no longer necessary as of May 2022.
+    end
+    set_result(_.result?) if _.result?
+  end; alias display_directory_content show_directory_content # === display_directory_content
+
+  # ========================================================================= #
+  # === verbose_report_whether_numbers_will_be_autoconverted
+  # ========================================================================= #
+  def verbose_report_whether_numbers_will_be_autoconverted
+    will_we_autoconvert_numbers = config?.autoconvert_numbers
+    _ = ''; _ = 'not ' unless will_we_autoconvert_numbers
+    e vt(will_we_autoconvert_numbers).delete('.')+
+      ', we will '+_+'autoconvert numbers.'
+  end
+
+  require 'roebe/toplevel_methods/display_array.rb'
+  # ========================================================================= #
+  # === show_completable_commands
+  #
+  # For this method to work, the Array @array_completion_proc must exist.
+  # ========================================================================= #
+  def show_completable_commands
+    e 'This is the listing of completable commands:'
+    e
+    _ = array_completion_proc?
+    ::Roebe::DisplayArray.display(_)
+  end
+
+  # ========================================================================= #
+  # === directory_content
+  #
+  # This method is run when the user issues "ls".
+  # ========================================================================= #
+  def directory_content(
+      from = return_pwd
+    )
+    unless Object.const_defined? :DirectoryParadise
+      begin
+        require 'directory_paradise'
+      rescue LoadError; end
+    end
+    ::DirectoryParadise.show(from)
+  end
+
+  # ========================================================================= #
+  # === show_the_status                                          (status tag)
+  # ========================================================================= #
+  def show_the_status(
+      we_use_these_components = load_which_components?
+    )
+    e
+    e rev+'The following '+steelblue(we_use_these_components.size.to_s)+
+      rev+' components were lazy-loaded so far:'
+    e
+    we_use_these_components.each {|entry|
+      e royalblue(entry)
+    }
+    e
+  end
+
+  # ========================================================================= #
+  # === display_banner
+  #
+  # This will display a simple ASCII-banner, with some optional text.
+  #
+  # Example:
+  #
+  #   display_banner This shell is a cool shell.
+  #
+  # ========================================================================= #
+  def display_banner(
+      text_to_display = :default
+    )
+    if text_to_display.is_a? Array
+      text_to_display = text_to_display.join(' ').strip
+    end
+    case text_to_display
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         nil
+      text_to_display = 'The Roebe::Shell'
+    end
+    text_to_display = text_to_display.dup if text_to_display.frozen? 
+    text_to_display.word_wrap! if text_to_display.size > 76
+    cliner '*'
+    text_to_display.split(N).each { |line|
+      result = '* '+( '%-76s' % line )+' *'
+      e result
+    }
+    cliner '*'
+  end
+
+  begin
+    require 'multimedia_paradise/requires/require_file_duration.rb'
+  rescue LoadError; end
+  # ========================================================================= #
+  # === show_duration_of
+  #
+  # When we wish to show the duration of an audio file, we can use
+  # this method here.
+  # ========================================================================= #
+  def show_duration_of(i)
+    i.each {|entry|
+      MultimediaParadise::FileDuration.new(entry, :be_verbose)
+      assign_file(entry)
+    }
+  end
+
+  # ========================================================================= #
+  # === report_size_of
+  #
+  # This will either call report_dirsize() or report_filesize().
+  #
+  # Usage example:
+  #
+  #   report_size_of /tmp/
+  #
+  # ========================================================================= #
+  def report_size_of(target)
+    if target.is_a? Array
+      target.each {|entry| report_size_of(entry) }
+    else
+      target = return_pwd if target.nil?
+      ftype = File.ftype(target)
+      case ftype # case tag
+      # ===================================================================== #
+      # === directory
+      # ===================================================================== #
+      when 'directory'
+        report_dirsize(target)
+      # ===================================================================== #
+      # === file
+      # ===================================================================== #
+      when 'file'
+        report_filesize(target)
+      else
+        ewarn "Unknown file type `#{sfancy(ftype)}` for #{col(target)}"
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_jumpers
+  #
+  # Use this method if you want to display the available jumpers.
+  # ========================================================================= #
+  def show_jumpers
+    cliner
+    e 'The available jumpers as defined in'
+    e "  #{sfile(yaml_configuration?+'jumper_directories.yml')}"
+    e 'are:'
+    cliner
+    n_entries = config?.jumper_directories.size
+    config?.jumper_directories.each_with_index {|entry,i|
+      formatting_to_use = '%2s'
+      formatting_to_use = '%1s' if n_entries < 10
+      index = (formatting_to_use % (i+1).to_s)
+      e '  ('+index+') '+sfancy(entry)
+    }
+  end; alias display_available_jumpers show_jumpers # === display_available_jumpers
+       alias show_setpoints            show_jumpers # === show_setpoints
+       alias setpoints?                show_jumpers # === setpoints?
+
+  # ========================================================================= #
+  # === show_modules
+  #
+  # Show modules on Linux.
+  #
+  # Invocation example:
+  #
+  #   lsmod
+  #
+  # ========================================================================= #
+  def show_modules
+    cliner
+    esystem :lsmod
+    cliner
+    e
+    _ = File.read(PROC_MODULES)
+    _ = _.split(N) unless _.is_a? Array
+    _.each_with_index { |line, index|
+      index = '%3s' % index 
+      e index.to_s+'  '+line.split(' ').first
+    }; e # Only show first line.
+  end
+
+  # ========================================================================= #
+  # === show_variables
+  #
+  # This method will show local variables - for now, only local variables.
+  # Local variables are by definition local variables defined in a
+  # running Roebe::Shell session.
+  # ========================================================================= #
+  def show_variables
+    cliner
+    efancy 'All known local variables are:'
+    print '  '
+    pp @local_variables
+    cliner
+  end
+
+  # ========================================================================= #
+  # === show_tasks                                                (tasks tag)
+  #
+  # Show the available tasks. This is probably no longer relevant as of
+  # August 2020 - but it will be kept for now.
+  # ========================================================================= #
+  def show_tasks(
+      file = shell_env?['MY_TODO'].to_s+'/yaml/tasks.yml'
+    )
+    if File.exist? file
+      keys = load_yaml(file).keys
+      e "Loaded from `|file|#{file}|_|`."
+      e
+      e 'The available tasks are:'
+      e
+      result = keys.map.with_index {|entry, index|
+        index += 1
+        if use_colours? # We make use of colours in this case.
+          '('+simp(index.to_s.rjust(2))+') '+entry+N
+        else
+          '('+index.to_s.rjust(2)+') '+entry+N
+        end
+      }.join('  ')
+      e "  #{result}"
+      e
+      show_array_threads
+    else
+      e "No file at #{sfile(file)} could be found."
+    end
+  end
+
+  # ========================================================================= #
+  # === show_padding                                   (pad tag, padding tag)
+  #
+  # This method shows the left padding.
+  # ========================================================================= #
+  def show_padding
+    e "We use #{sfancy(config?.padding.to_s)} spaces "\
+      "for padding content."
+  end
+
+  # ========================================================================= #
+  # === show_directories
+  #
+  # Simply show all available directories in the current directory.
+  # ========================================================================= #
+  def show_directories
+    get_directories.each {|dir|
+      e "  #{sdir(dir)}"
+    }
+  end; alias show_directory_listing show_directories # === show_directory_listing
+       alias show_only_directories  show_directories # === show_only_directories
+
+  # ========================================================================= #
+  # === display_contacts
+  #
+  # Displays my contacts.
+  # ========================================================================= #
+  def display_contacts(
+      from         = FILE_CONTACTS_YAML,
+      left_padding = left_padding?
+    )
+    if contacts?.nil? and is_on_roebe? and File.file?(from)
+      @internal_hash[:contacts] = YAML.load_file(from)
+    end
+    if contacts? and File.file?(from)
+      e N+'Reading from '+sfile(from)
+      e
+      lpad =  8
+      rpad = 30
+      bar  = '=' * 50
+      contacts?.each_with_index { |contact, index|
+        index += 1
+        name   = contact[0].to_s.strip
+        mobile = contact[1].to_s.strip
+        email  = contact[2].to_s.strip
+        born   = contact[3].to_s.strip
+        index = orchid(index) if use_colours?
+        e "#{index}) #{bar}"
+        e left_padding.to_s+simp(
+            'Name:'.ljust(lpad))+sfancy(name.rjust(rpad))
+        unless contact[1].nil?
+          e left_padding.to_s+simp(
+            'Mobile:'.ljust(lpad))+sfancy(mobile.rjust(rpad))
+        end
+        unless contact[2].nil?
+          email = email.rjust(rpad)
+          email = darkslateblue(email)
+          e left_padding.to_s+simp('Email:'.ljust(lpad))+email
+        end
+        unless contact[3].nil?
+          e left_padding.to_s+simp(
+            'Born:'.ljust(lpad))+cyan(born.rjust(rpad))
+        end
+        e
+      }
+    else
+      e 'Contact information is not available. No file '\
+        'was found at '+sfile(from)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_config_directory
+  #
+  # This method will show the configuration directory. That way a
+  # user can quickly find out where on his system the .yml files
+  # are stored.
+  # ========================================================================= #
+  def show_config_directory(
+      optional_padding = N
+    )
+    case optional_padding
+    when :dont_pad
+      optional_padding = ''.dup
+    end
+    config_dir = config_directory?
+    if config?
+      e optional_padding+'The various yaml configuration files for '\
+        'the '+steelblue('Roebe::Shell')+' can be found here:'
+      e
+      e "  #{sdir(config_dir)}#{N}"
+      e 'This directory listed above has a total of '+
+        simp(Dir[config_dir+'*'].size)+' yaml entries.'+
+        optional_padding+optional_padding
+    end
+  end
+
+  # ========================================================================= #
+  # === report_whether_we_will_show_hidden_files
+  # ========================================================================= #
+  def report_whether_we_will_show_hidden_files
+    e 'Will we show hidden files? '+
+       sfancy(vt(config?.show_hidden_files))
+    e
+    e steelblue('Hint:')+' you can toggle this via "'+simp('toggle hide')+'".'
+    e
+  end
+
+  # ========================================================================= #
+  # === show_fstab
+  # ========================================================================= #
+  def show_fstab
+    _ = read_file(:fstab)
+    _ = _.join if _.is_a? Array
+    e _
+  end
+
+  # ========================================================================= #
+  # === show_the_available_display_options
+  # ========================================================================= #
+  def show_the_available_display_options
+    e
+    ARRAY_AVAILABLE_DISPLAY_OPTIONS.each_with_index {|entry, index|
+      index += 1
+      e "  #{steelblue(index.to_s)}) #{lightgreen(entry)}"
+    }
+    e
+  end
+
+  # ========================================================================= #
+  # === show                                                       (show tag)
+  #
+  # To test this method, do:
+  #
+  #   show files
+  #   show help
+  #
+  # ========================================================================= #
+  def show(i)
+    if i.is_a? Array
+      i.each {|entry| show(entry) }
+    else
+      i = i.to_s # We don't want a symbol here, hence we convert to String.
+      if File.directory?(i)
+        show_file_listing(i)
+      elsif is_multimedia_file?(i)
+        case File.extname(i)[1..-1] # case tag
+        when 'ogg'
+          esystem "ogginfo #{i}"
+        else
+          e 'No idea what to do with this multimedia file.'
+        end
+      else
+        case i
+        # =================================================================== #
+        # === fstab
+        # =================================================================== #
+        when 'fstab','f'
+          show_fstab
+        # =================================================================== #
+        # === help
+        # =================================================================== #
+        when /^-?-?help$/i
+          show_the_available_display_options
+        # =================================================================== #
+        # === favourite_audio
+        # =================================================================== #
+        when 'favourite audio',
+             'favourite_audio',
+             'favaud'
+          show_favourite_audiofiles
+        # =================================================================== #
+        # === task
+        # =================================================================== #
+        when 'task','tasks'
+          show_tasks
+        # =================================================================== #
+        # === time
+        # =================================================================== #
+        when 'time'
+          show_time
+        # =================================================================== #
+        # === version
+        # =================================================================== #
+        when 'version'
+          show_version
+        # =================================================================== #
+        # === padding
+        # =================================================================== #
+        when 'padding'
+          show_padding
+        # =================================================================== #
+        # === files
+        # =================================================================== #
+        when 'files','listing','file_listing'
+          show_file_listing
+        # =================================================================== #
+        # === processes
+        # =================================================================== #
+        when 'processes','proc','processes?'
+          show_processes
+        # =================================================================== #
+        # === html
+        # =================================================================== #
+        when 'html','html_colours'
+          show_html_colours # in $DIA/diamond_colo*rb
+        # =================================================================== #
+        # === hidden
+        # =================================================================== #
+        when 'hidden'
+          show_hidden
+        # =================================================================== #
+        # === history
+        # =================================================================== #
+        when 'history',
+             'show_history'
+          show_history
+        # =================================================================== #
+        # === applications
+        # =================================================================== #
+        when 'applications',
+             'default'
+          show_default_applications
+        # =================================================================== #
+        # === configuration
+        # =================================================================== #
+        when 'configuration'
+          show_configuration
+        # =================================================================== #
+        # === news
+        # =================================================================== #
+        when 'news','show_news'
+          show_news
+        # =================================================================== #
+        # === hdd
+        # =================================================================== #
+        when 'hdd',
+             /^-?-?hdd(_|-)?info$/i
+          show_hdd_info
+        # =================================================================== #
+        # === environment
+        # =================================================================== #
+        when 'environment'
+          show_environment
+        # =================================================================== #
+        # === show_todo
+        # =================================================================== #
+        when 'show_todo',
+             'todo'
+          show_todo
+        # =================================================================== #
+        # === variables
+        # =================================================================== #
+        when 'variables','variable','vars','var'
+          show_variables
+        # =================================================================== #
+        # === ram
+        # =================================================================== #
+        when 'ram','mem','display_ram'
+          display_ram
+        # =================================================================== #
+        # === users
+        # =================================================================== #
+        when 'users','available_users'
+          display_available_users
+        else # else treat them as special shortcuts for 
+             # pretty url.
+          target_url = pretty_url(i)
+          if target_url
+            target_url = target_url.join('') if target_url.is_a? Array
+            e read_file(target_url)
+          end
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_last_user_input
+  #
+  # This shows the last user input.
+  # ========================================================================= #
+  def show_last_user_input
+    if @user_input.is_the_input_history_tracked?
+      e 'The last user input was:'
+      e
+      e "  #{steelblue(@user_input.last_user_input?)}"
+      e
+    end
+  end
+
+  # ========================================================================= #
+  # === display                                                 (display tag)
+  #
+  # Bundle together several display-related actions.
+  #
+  # Usage examples:
+  #
+  #   display ram
+  #   display help
+  #
+  # ========================================================================= #
+  def display(
+      i = nil
+    )
+    if i.is_a? Array
+      i.each {|entry| display(entry) }
+    else
+      i = i.to_s unless i.is_a? String
+      case i
+      # ===================================================================== #
+      # === HELP
+      #
+      # Invocation example:
+      #
+      #   display --help
+      #
+      # ===================================================================== #
+      when /^-?-?help$/i # help tag
+        show_the_available_display_options
+      # ===================================================================== #
+      # === hardware
+      # ===================================================================== #
+      when 'hardware',
+           'hware'
+        display_hardware_information
+      # ===================================================================== #
+      # === contacts
+      # ===================================================================== #
+      when 'contacts',
+           'display_contacts'
+        display_contacts
+      # ===================================================================== #
+      # === ram
+      # ===================================================================== #
+      when 'ram'
+        display_ram
+      # ===================================================================== #
+      # === video
+      # ===================================================================== #
+      when 'video',
+           'video_resolution',
+           'res',
+           'vid'
+        display_video_resolution
+      # ===================================================================== #
+      # === display_host_information
+      # ===================================================================== #
+      when 'display_host_information',
+           'host'
+        display_host_information
+      else
+        e tomato('Not found: '+i)
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_whether_xorg_is_running
+  #
+  # Find out whether xorg is running or not.
+  # ========================================================================= #
+  def show_whether_xorg_is_running
+    if xorg_is_running?
+      e 'Yes, the xorg-server is running.'
+    else
+      e 'No, the xorg-server is '+tomato('NOT')+' running.'
+    end
+  end
+
+  # ========================================================================= #
+  # === show_games
+  #
+  # Show available games.
+  # ========================================================================= #
+  def show_games
+    cliner
+    _ = load_yaml(
+      localhost_to_data(
+        sanitize_url('available_games')
+      )
+    )
+    if _ and _.respond_to?(:each_with_index)
+      _.each_with_index { |game, index|
+        beautiful_index = '%3s' % (index+1).to_s
+        e "#{beautiful_index} - #{game}"
+      }
+    else
+      require 'roebe/classes/all_games.rb'
+      Roebe::AllGames.new
+    end
+    cliner
+  end
+
+  # ========================================================================= #
+  # === show_how_many_songs_are_available_locally
+  # ========================================================================= #
+  def show_how_many_songs_are_available_locally(
+      from_this_directory = '/home/x/songs/'
+    )
+    e steelblue(
+      Dir["#{from_this_directory}*"].select {|entry|
+        is_audio_file?(entry)
+      }.size
+    )
+  end
+
+  # ========================================================================= #
+  # === show_html_colours
+  #
+  # Here we show html colours. (show_html_colours tag, colours tag)
+  # ========================================================================= #  
+  def show_html_colours
+    efancy "  #{::Colours.random_html_colour?}"
+  end
+
+  # ========================================================================= #
+  # === show_mudaliases
+  #
+  # Output all mudaliases here. This will obviously only work if you
+  # have some aliases for MUDs (and if you do happen to play MUDs).
+  # ========================================================================= #
+  def show_mudaliases(
+      file_to_mud_aliases = shell_env?['MUDS'].to_s+'/YAML/std_mud_aliases.yml'
+    )
+    mud_aliases = file_to_mud_aliases
+    if File.exist? mud_aliases
+      _ = load_yaml(mud_aliases)
+      cliner { pp _ }
+      e 'We found '+sfancy(_.keys.size.to_s)+' keys in '+sfile(mud_aliases)+'.'
+    else
+      e "No file exists at #{mud_aliases} - thus we can not "\
+        "load the mud-aliases."
+    end
+  end
+
+  # ========================================================================= #
+  # === reading_now_from
+  # ========================================================================= #
+  def reading_now_from(target)
+    e "Reading now from `#{sfile(target)}`."
+  end
+
+  # ========================================================================= #
+  # === will_we_show_the_absolute_path?
+  # ========================================================================= #
+  def will_we_show_the_absolute_path?(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash 
+    e pad_this_string('Will we show the absolute paths in the prompt: ',counter)+
+      sfancy(
+        verbose_truth(config?.show_absolute_path)
+      )
+  end
+
+  # ========================================================================= #
+  # === show_valid_regexes
+  #
+  # This method shows which regexes are valid in ruby.
+  # ========================================================================= #
+  def show_valid_regexes
+    e
+    efancy '  . * + ? ^ $ { } [ ] ( ) \ |'
+    e
+  end
+
+  # ========================================================================= #
+  # === show_line_number_in_this_file
+  #
+  # This method will show the line number of a specific file.
+  #
+  # The first argument should be the line number at hand.
+  #
+  # The second argument shall be the target file.
+  #
+  # Specific usage example:
+  #
+  #   line 25 $RSRC/roebe/lib/roebe/shell/shell/core/show_display_feedback_and_report.rb
+  #
+  # ========================================================================= #
+  def show_line_number_in_this_file(
+      line_number,
+      this_file
+    )
+    line_number = line_number.to_i
+    if this_file.include? '$' # Sanitize '$' tokens.
+      this_file = convert_global_env(this_file)
+    end
+    if File.exist? this_file # File exists, thus we can continue.
+      dataset = File.readlines(this_file)
+      # ===================================================================== #
+      # Prevent out-of-bounds access next
+      # ===================================================================== #
+      if line_number > dataset.size
+        line_number = dataset.size
+      end
+      line = dataset[line_number - 1]
+      e line
+    else
+      opn; e "No file found at `#{sfile(this_file)}`."
+    end
+  end
+
+  # ========================================================================= #
+  # === show_task                                              (task tag)
+  #
+  # With show_task you can show some of the latest tasks. For example, if
+  # you are working on a topic, like pipes, and thus reading up on this
+  # issue, we may bundle some resources into this method.
+  # 
+  # You can replace this with whatever else you want to use.
+  # ========================================================================= #
+  def show_task
+    cliner
+    # open_in_browser_tab 'http://de.wikipedia.org/wiki/Windows_PowerShell#Cmdlets'
+    ask_study_question :random
+    e '- Capitals auswändig lernen.' # blcapitals
+    e '- English words durcharbeiten.' 
+    cliner
+  end
+
+  # ========================================================================= #
+  # === show_available_fonts
+  # ========================================================================= #
+  def show_available_fonts
+    cliner
+    esystem 'fc-list'
+    cliner
+  end
+
+  # ========================================================================= #
+  # === report_concise_documentation_for_this_method
+  #
+  # This will show documentation for a method.
+  #
+  # Usage example:
+  #
+  #   report_concise_documentation_for_this_method trainer
+  #
+  # ========================================================================= #
+  def report_concise_documentation_for_this_method(
+      i = :upcase
+    )
+    if i.is_a? Array
+      i.each {|entry|
+        report_concise_documentation_for_this_method(entry)
+      }
+    else
+      result = show_documentation_of?(i, false)
+      last = result.last
+      splitted = last.split(N).reject {|entry| entry.strip.empty? }
+      splitted.reject! {|entry| entry.include? '=' }
+      e
+      e 'Method called '+purple(i.to_s+'():')
+      e splitted.map {|entry| entry.delete('#') }.join(N)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_map                                                    (map tag)
+  #
+  # We use this to show a specific map, by default for Vienna.
+  # ========================================================================= #
+  def show_map(
+      which_map = :vienna,
+      strasse    = '',
+      hausnummer = ''
+    )
+    which_map = :vienna if which_map.nil? # Default.
+    if which_map.is_a? Array
+      hausnummer = which_map[2]
+      strasse    = which_map[1]
+      which_map  = :vienna
+    end
+    case which_map
+    # ======================================================================= #
+    # === vienna
+    # ======================================================================= #
+    when :vienna
+      efancy REALLIFE_KARTEN_WIEN+'WIEN_KARTE.png'
+      open_in_browser_tab REALLIFE_KARTEN_WIEN+'WIEN_KARTE.png'
+      open_in_browser_tab 'https://www.wien.gv.at/stadtplan/'
+    # ======================================================================= #
+    # === germany
+    # ======================================================================= #
+    when :germany
+      e(_ = REALLIFE_KARTEN_GERMANY+'DEUTSCHLAND_KARTE.png')
+      open_in_browser_tab _
+    end
+  end
+
+  # ========================================================================= #
+  # === do_we_use_readline?
+  #
+  # Show whether we will use readline or whether we will not.
+  # ========================================================================= #
+  def do_we_use_readline?(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash
+    _ = pad_this_string('Do we use readline: ',counter)
+    if readline_is_available?
+      if config?
+        _ << sfancy(verbose_truth(config?.use_readline))
+      else
+        _ << sfancy('Readline is at least available, so in theory we could.')
+      end
+    else
+      _ << sfancy(' No, because Readline is unavailable.')
+    end
+    e _
+  end
+
+  # ========================================================================= #
+  # === pad_this_string
+  # ========================================================================= #
+  def pad_this_string(
+      string, n_characters = 0
+    )
+    n_characters = 0 if n_characters.nil?
+    padded_string = string.ljust(n_characters)
+    # ======================================================================= #
+    # Colourize the String as well:
+    # ======================================================================= #
+    if use_colours?
+      padded_string = seagreen(padded_string)
+    end
+    return padded_string
+  end
+
+  # ========================================================================= #
+  # === display_host_information
+  #
+  # This displays several info about your host.
+  # ========================================================================= #
+  def display_host_information(
+      level = :all
+    )
+    if level.is_a? Array
+      level.each {|entry| display_host_information(entry) }
+    else
+      level = level.to_sym
+      case level
+      # ===================================================================== #
+      # === :default
+      # ===================================================================== #
+      when :default,
+           :all
+        cliner('=') { e 'CPUINFO'+N }
+        e read_file('/proc/cpuinfo', :do_not_be_verbose)
+        cliner '='
+        e 'RAM'+N
+        # =================================================================== #
+        # The next line has to be protected, for windows systems.
+        # =================================================================== #
+        e `free -l #{Roebe.error_line?}`
+        cliner '='
+        display_host_information :status
+      # ===================================================================== #
+      # === :status
+      # ===================================================================== #
+      when :status
+        _ = `uptime`[0, '20:45:11 up 4 days'.size]
+        e _
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === display_ram
+  #
+  # Display ram on a system (ram tag)
+  # ========================================================================= #
+  def display_ram
+    cliner
+    esystem 'free -m'
+    cliner 
+  end
+
+  # ========================================================================= #
+  # === display_video_resolution
+  # ========================================================================= #
+  def display_video_resolution
+    cliner
+    e 'Current Xorg Resolution:'
+    cliner
+    esystem :xrandr
+    cliner
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.ecap
+  #
+  # This is like e() but we will capitalize the first character passed.
+  # ========================================================================= #
+  def self.ecap(i)
+    i = i.dup if i.frozen?
+    i[0,1] = i[0,1].upcase # Upcase it here.
+    e i # And then we can delegate to e().
+  end
+
+  # ========================================================================= #
+  # === show_alias
+  #
+  # Use this method to show an alias.
+  # ========================================================================= #
+  def show_alias(i)
+    if i.is_a? Array
+      i.each {|entry| show_alias(entry) }
+    else
+      result = aliases?.show_alias(i) # bl $DIA/standalone_classes/aliases.rb
+      unless result
+        if program_exists? i
+          e "However, a binary called `#{sfancy(i)}` exists."
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_aliases
+  #
+  # This method will show all aliases.
+  # ========================================================================= #
+  def show_aliases
+    cliner
+    @_ = aliases?.show_aliases
+    e "We have #{sfancy(aliases?.size.to_s)} registered aliases."
+  end
+
+  # ========================================================================= #
+  # === display_protected_directories
+  #
+  # Use this method to properly display all protected directories.
+  #
+  # As of Jan 2014 we will colourize them.
+  # ========================================================================= #
+  def display_protected_directories(
+      array_protected_directories = config?.protected_directories
+    )
+    e steelblue('Protected directories')+' ('+
+      simp(
+        array_protected_directories.size.to_s
+      )+' '+
+      'of these were found) include:'
+    e '  ["'+array_protected_directories.map {|entry|
+        sdir(rds(entry))
+      }.join('", "')+'"]'
+  end
+
+  # ========================================================================= #
+  # === show_exams
+  #
+  # This will display the whole exams.yml file. One day I might change
+  # it to display only the upcoming exams.
+  # ========================================================================= #
+  def show_exams
+    e get_file_content(:exams)
+  end
+
+  # ========================================================================= #
+  # === show_hdd_info
+  #
+  # Shows information about the hdd.  
+  # ========================================================================= #
+  def show_hdd_info
+    cliner
+    esystem 'fdisk -l'
+    cliner
+    e
+    cliner
+    esystem 'df -T -a'
+    cliner
+  end
+
+  # ========================================================================= #
+  # === display_available_users
+  #
+  # This method will show the "available users" on a typical linux
+  # system.
+  # ========================================================================= #
+  def display_available_users
+    read_from_this_file = '/etc/passwd'
+    if File.exist? read_from_this_file
+      _ = read_file(read_from_this_file, :be_silent)
+      e N+'Reading from file '+col(read_from_this_file)+'.'+N
+      _ = _.join if _.is_a? Array
+      e _
+      return _ # return value
+    else
+      no_file_exists_at(read_from_this_file)
+    end
+  end
+
+  # ========================================================================= #
+  # === ee                                                           (ee tag)
+  #
+  # This is sort of synonymous with print.
+  # ========================================================================= #
+  def ee(i, make_newline = false)
+    e(i, make_newline)
+  end
+
+  # ========================================================================= #
+  # === show_n_lines?
+  # ========================================================================= #
+  def show_n_lines?
+    config?.show_n_lines.to_s
+  end
+
+  # ========================================================================= #
+  # === show_dichte
+  #
+  # Show the dichte of substances, as defined in the file dichte.yml.
+  # ========================================================================= #
+  def show_dichte(
+      this_file = shell_env?['SCIENCE'].to_s+'/YAML/dichte.yml'
+    )
+    if File.exist? this_file
+      sorted = load_yaml(this_file).sort_by {|key,value| value}
+      sorted.each {|inner, outer|
+        outer = outer.to_s.strip 
+        e '  '+sprintf('%-10s',inner+': ')+sprintf('%12s', outer)+' g/cm3'
+      }
+    else
+      e "But the file #{sfile(this_file)} does not exist."
+    end
+  end
+
+  # ========================================================================= #
+  # === notify_user
+  # ========================================================================= #
+  def notify_user(i)
+    e i
+  end; alias notify notify_user # === notify
+
+  # ========================================================================= #
+  # === show_how_many_lines_can_be_found_in_this_file
+  # ========================================================================= #
+  def show_how_many_lines_can_be_found_in_this_file(i)
+    if i.is_a? Array
+      i.each {|line| show_how_many_lines_can_be_found_in_this_file(line) }
+    else
+      if File.exist? i
+        amount_of_lines = File.readlines(i).size
+        e amount_of_lines # Report the amount of lines here.
+      else
+        e "No file called `#{sfile(i)}` exists."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_modification_time?
+  # ========================================================================= #
+  def show_modification_time?
+    config?.do_show_modification_time
+  end
+
+  # ========================================================================= #
+  # === do_not_show_modification_time
+  # ========================================================================= #
+  def do_not_show_modification_time(
+      be_verbose = false
+    )
+    be_verbose = true if be_verbose == :be_verbose
+    e 'We will not show the modification time.' if be_verbose
+    config?.do_show_modification_time = false
+  end
+
+  # ========================================================================= #
+  # === do_we_show_hidden_files?
+  # ========================================================================= #
+  def do_we_show_hidden_files?(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash 
+    e pad_this_string('Will we show hidden files: ',counter)+
+      sfancy(vt(config?.show_hidden_files.to_s))
+  end
+
+  # ========================================================================= #
+  # === show_message
+  #
+  # Show a message through this method.
+  # ========================================================================= #
+  def show_message(i = nil)
+    e 'Displaying something next:'
+    _ = Roebe::OnScreenDisplay.new(i)
+    _.display
+  end
+
+  # ========================================================================= #
+  # === report_how_many_lines_are_shown
+  #
+  # This method tells us how many lines will be shown by default in the
+  # DiamondShell, whenever we apply the "header" command. 
+  #
+  # Invoke this via:
+  #
+  #   n_lines?
+  #
+  # ========================================================================= #
+  def report_how_many_lines_are_shown
+    e 'The header in use for the '+sfancy('Roebe::Shell')+
+      ' to display the first n lines '
+    e "of files is set to #{sfancy(show_n_lines?)} "\
+      "lines right now."
+    e
+    e 'If you wish to set to another value, do this:'
+    e
+    e '  '+sfancy('header? new_value')+
+      ' # Where new_value should be a Number.'
+    e
+  end
+
+  # ========================================================================= #
+  # === show_array_threads
+  # ========================================================================= #
+  def show_array_threads
+    unless @array_threads.empty?
+      e 'The registered Tasks for the threads are:'
+      @array_threads.each { |entry| e " - #{entry[1]}" }
+    end if @array_threads
+  end
+
+  # ========================================================================= #
+  # === show_the_methods_in_this_file
+  # ========================================================================= #
+  def show_the_methods_in_this_file(i)
+    if i.is_a? Array
+      i = i.join(' ').strip
+    end
+    if File.exist? i
+      dataset = File.readlines(i) # Easier to work with an Array here.
+      dataset.select! {|line|
+        line.include?('def ') and line =~ /^\s*def /
+      }
+       e '  def self.project_base_dir?'
+      dataset.map! {|entry| entry.lstrip.chomp.gsub(/def /,'') }
+      # ===================================================================== #
+      # Ok, now we have the method names, but we also may have (),
+      # so we chop off before it.
+      # ===================================================================== #
+      dataset.map! {|entry|
+        if entry.include? '('
+          entry = entry[0, entry.index('(')]
+        end
+        if entry.include? ';'
+          entry = entry[0, entry.index(';')]
+        end
+        entry
+      }
+      if dataset.empty?
+        e 'This file does not seem to include any "def" entries.'
+      else
+        e "We did find these methods in the file #{sfile(i)}:"
+        dataset.sort.each_with_index {|the_method, index|
+          index += 1
+          e index.to_s.rjust(3)+') '+simp(the_method)
+        }
+      end
+    else
+      e "No file at #{sfile(i)} exists."
+    end
+  end
+
+  # ========================================================================= #
+  # === report_subdir_size
+  # ========================================================================= #
+  def report_subdir_size(
+      i = return_pwd
+    )
+    i = return_pwd if i.nil?
+    report_dirsize(i)
+    # ======================================================================= #
+    # And next, we do a more detailed analysis.
+    # ======================================================================= #
+    all_dirs = rds(Dir[i+'/**'].select {|entry| File.directory? entry })
+    all_dirs.each {|directory|
+      array = Dir[directory+'/**/*']
+      _ = array.inject(0) { |sum, entry|
+        sum + File.size(entry)
+      }
+      _ = (_ / 1000000.0).round(3) # This should now be in MB.
+      directory << '/' unless directory.end_with? '/'
+      padded = ("#{sdir(directory)}:").ljust(70,' ')
+      # ===================================================================== #
+      # Also show trailing '0'.
+      # ===================================================================== #
+      _ = '%.5f' % _ 
+      e padded+' total file size of '+sfancy(_.rjust(9))+ ' MB.'
+    }
+  end
+
+  # ========================================================================= #
+  # === show_various_configuration_keys
+  #
+  # We will display the different configuration keys that we will use.
+  # ========================================================================= #
+  def show_various_configuration_keys
+    e 'The various configuration |fancy|keys|_| are these here:'
+    config?.entries
+  end
+
+  # ========================================================================= #
+  # === show_all_parameters_of_all_methods_in_the_project
+  #
+  # This method will display all parameters of the DiamondShell.
+  # ========================================================================= #
+  def show_all_parameters_of_all_methods_in_the_project
+    array_all_methods = self.public_methods(false).sort # => [:test1, :test2]'
+    array_all_methods.each_with_index {|the_method, index|
+      index += 1
+      padded = index.to_s.rjust(3)
+      # ===================================================================== #
+      # Next, obtain all parameters to every method.
+      # ===================================================================== #
+      the_parameters = self.method(the_method.to_sym).parameters
+      the_parameters = '' if the_parameters.empty? # Clear it if it is empty.
+      unless the_parameters.empty?
+        the_parameters.map! {|name_of_the_method, b|
+          [':'+name_of_the_method.to_s, ':'+bold_blue(b).to_s]
+        }
+      end
+      if the_parameters.is_a? Array
+        the_parameters = the_parameters.join(', ')
+        the_parameters = "[#{the_parameters}]"
+      end
+      the_parameters = bold_blue('[No parameters to this method.]') if the_parameters.empty?
+      e padded+' - `'+simp(the_method.to_s)+'`: '+the_parameters
+    }
+  end
+
+  # ========================================================================= #
+  # === report_when_the_roebe_shell_was_last_updated
+  # ========================================================================= #
+  def report_when_the_roebe_shell_was_last_updated
+    e "The Roebe::Shell component was last updated at `#{simp(LAST_UPDATE)}`."
+  end
+
+  # ========================================================================= #
+  # === report_filesize
+  #
+  # This method will report the filesize of the target in question.
+  #
+  # The target is the first argument to this method. It should point
+  # to a file or directory that actually exists.
+  # ========================================================================= #
+  def report_filesize(i)
+    if i.is_a? Array
+      i.each {|entry| report_filesize(entry) }
+    else
+      e "File size of `#{i}`: #{royalblue(File.size?(i))} KB"
+      set_result("File size of `#{i}`: #{File.size?(i)} KB")
+    end
+  end
+
+  # ========================================================================= #
+  # === show_comment_from
+  #
+  # Use this to show a comment from a .mp3 or .ogg file.
+  # ========================================================================= #
+  def show_comment_from(i)
+    if i.is_a? Array
+      i.each {|entry| show_comment_from(entry) }
+    else
+      i = i.to_s
+      extname = File.extname(i).delete '.'
+      case extname
+      # ===================================================================== #
+      # === mp3
+      # ===================================================================== #
+      when 'mp3'
+        if Object.const_defined? :MultimediaParadise
+          MultimediaParadise.show_artist(i)
+          e '(Other tags are not yet supported.)'
+        else
+          e 'Please install the project called MultimediaParadise. We require'
+          e 'it in order to read .mp3 tags.'
+          e
+          e 'You can do this like so:'
+          e
+          e '  gem install multimedia_paradise'
+          e
+        end
+      # ===================================================================== #
+      # === ogg
+      # ===================================================================== #
+      when 'ogg'
+        esystem 'oggz-comment -l '+i
+      else
+        ewarn 'Not registered `'+extname.to_s+'`.'              
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_hidden
+  # ========================================================================= #
+  def show_hidden
+    e 'We will now show hidden files.'
+    show_directory_content(show_hidden_files: true)
+  end
+
+  # ========================================================================= #
+  # === last_command?
+  # ========================================================================= #
+  def last_command?
+    location = LAST_COMMANDS
+    last_command = YAML.load_file(location)
+    if last_command.is_a? Array
+      last_command = last_command.first
+    end
+    return last_command
+  end
+
+  # ========================================================================= #
+  # == report_operating_system_in_use
+  # ========================================================================= #
+  def report_operating_system_in_use(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash
+    e pad_this_string('The Operating system in use is: ', counter)+
+      sfancy(OPERATING_SYSTEM.to_s)
+  end
+
+  # ========================================================================= #
+  # === report_browser_in_use
+  # ========================================================================= #
+  def report_browser_in_use(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash 
+    e pad_this_string('Browser we will use: ',counter)+
+      sfancy(return_browser_in_use)
+  end
+
+  # ========================================================================= #
+  # === report_name_of_the_shell
+  # ========================================================================= #
+  def report_name_of_the_shell
+    e "The name of the shell is `#{simp(config?.shell_name)}`."
+  end
+
+  # ========================================================================= #
+  # === show_ftp_hosts
+  #
+  # Show FTP Hosts.
+  # ========================================================================= #
+  def show_ftp_hosts
+    begin
+      e '  '+shell_env?['A1FTP'].to_s
+      e '  '+shell_env?['WWWA1'].to_s
+      if config?.may_we_use_ftp == false
+        start :ftp
+      else
+        @ftp.report
+      end
+    rescue Exception
+    end
+  end
+
+  # ========================================================================= #
+  # === show_groups
+  # ========================================================================= #
+  def show_groups
+    cat('/etc/group', nil, true)
+  end
+
+  # ========================================================================= #
+  # === show_slogans
+  #
+  # This shows the slogans.
+  # ========================================================================= #
+  def show_slogans(
+      target = '/home/x/DATA/misc/yaml/slogans.yml'
+    )
+    reading_now_from(target)
+    begin
+      _ = load_yaml(target) # bl $MISC/YAML/slogans.yml  
+      puts
+      _.each {|entry|
+        # the following two lines are just to make the padding look nicer.
+        entry.word_wrap!(80,'  ') if entry.size > 78
+        entry = '  '+entry.gsub(/\n/,'') unless entry[0, '  '.size] == '  '
+        efancy(entry+N)
+      }
+    rescue Exception => error
+      cliner {
+        reading_now_from(target)
+        pp error
+        pp error.class
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === show_news
+  #
+  # This will trigger dcop to list all news webpages.
+  #
+  # The argument which_news can be of these valid arguments only:
+  #   :pc, :science, :all
+  # :all will invoke all the other arguments.
+  #
+  # Invoke examples:
+  #
+  #   rinvoke
+  #
+  # ========================================================================= #
+  def show_news(
+      i = :all
+    )
+    if i.is_a? Array
+      i.each {|entry| show_news(i) }
+    else
+      e 'Showing news related to `'+sfancy(i.to_s)+'` now.'
+      case i # case tag
+      # ===================================================================== #
+      # === :all
+      # ===================================================================== #
+      when :all # Call ourself recursively in this event.
+        show_news :pc
+        show_news :science
+      # ===================================================================== #
+      # === :pc
+      # ===================================================================== #
+      when :pc
+        _ = sanitize_url('pc_news')
+        _ = _.url? if _.respond_to? :url?
+        if _.is_a? Array
+          _.each { |url|
+            open_in_browser_tab(url) # bl base/browser.rb
+          }
+        else
+          open_in_browser_tab(_)
+        end
+      # ===================================================================== #
+      # === :science
+      # ===================================================================== #
+      when :science
+        result = sanitize_url('science_news')
+        [result].flatten.each { |url|
+          open_in_browser_tab(url)
+        }
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_default_pdf_viewer
+  #
+  # Use this method to show the default PDF viewer in place.
+  # ========================================================================= #
+  def show_default_pdf_viewer
+    e "We will use this program to open #{royalblue('.pdf')} files:"
+    e
+    efancy "  #{config?.pdf_viewer}"
+    e
+  end
+
+  # ========================================================================= #
+  # === consider_disabling_the_cyberweb_project
+  # ========================================================================= #
+  def consider_disabling_the_cyberweb_project
+    if Object.const_defined? :Cyberweb
+      Cyberweb.disable_cgi_exceptions if Cyberweb.respond_to? :disable_cgi_exceptions
+    end
+  end
+
+  # ========================================================================= #
+  # === show_last_command
+  #
+  # Use this method to show the last command used. We use .to_s in case
+  # there is a nil.
+  # ========================================================================= #
+  def show_last_command
+    e "The last command was `#{simp(last_command?.to_s)}`."
+  end
+
+  # ========================================================================= #
+  # === show_ruby_keywords
+  #
+  # Use this method to show the registered ruby keywords.
+  # ========================================================================= #
+  def show_ruby_keywords(show_index = true)
+    if show_index.is_a?(Array) and ! show_index.empty?
+      show_index = true
+    end
+    n_keywords = RUBY_KEYWORDS.size
+    e 'The '+simp(n_keywords.to_s)+' |fancy|Ruby Keywords|_| are:'
+    e
+    RUBY_KEYWORDS.each_with_index { |keyword, index|
+      index += 1
+      index = '%2s' % index
+      keyword[0,1] = swarn(keyword[0,1])
+      if show_index
+        e '  |fancy|'+index.to_s+')|_| '+keyword
+      else
+        e "  #{keyword}"
+      end
+    }
+    e
+  end
+
+  # ========================================================================= #
+  # === report_dirsize
+  #
+  # This method will try to read all entries in a directory and display
+  # the total file size.
+  # ========================================================================= #
+  def report_dirsize(
+      this_dir = return_pwd
+    )
+    this_dir = return_pwd if this_dir.nil?
+    if this_dir.is_a? Array
+      this_dir.each {|entry| report_dirsize(entry) }
+    else
+      e "Calculating total size of all directories "\
+        "in #{col(this_dir)}"
+      array = Dir[this_dir+'/**/*']
+      n_entries = array.size
+      _ = array.inject(0) { |sum, entry|
+        sum + File.size(entry)
+      }
+      _ = (_ / 1000.0).round(1) # This should now be in KB.
+      e 'Total Size: '+sfancy(_)+ ' KB, Entries: '+
+        simp(n_entries.to_s)+'.'
+    end
+  end
+
+  # ========================================================================= #
+  # === show_only_files
+  # ========================================================================= #
+  def show_only_files(optional_directory = :default)
+    @collapse = true
+    show_file_listing(optional_directory)
+    @collapse = false
+  end
+
+  # ========================================================================= #
+  # === show_file_listing
+  # ========================================================================= #
+  def show_file_listing(
+      of_this_directory = :default
+    )
+    if of_this_directory.is_a? Array
+      of_this_directory = of_this_directory.join(' ').strip
+    end
+    case of_this_directory
+    when :default, nil
+      of_this_directory = return_pwd
+    end
+    of_this_directory << '/' unless of_this_directory.end_with? '/'
+    get_file_listing(of_this_directory).select {|entry|
+      File.file?(entry)
+    }.each {|entry|
+      e entry
+    }
+  end
+
+  # ========================================================================= #
+  # === show_calendar
+  #
+  # This method will simply show a calendar, using the program 'cal' for
+  # this job.
+  #
+  # Usage example:
+  #
+  #   cal? Apr
+  #
+  # ========================================================================= #
+  def show_calendar(
+      which_month = ::Roebe::CURRENT_MONTH
+    )
+    which_month = ::Roebe::CURRENT_MONTH if which_month.nil?
+    # ======================================================================= #
+    # The first argument, `which_month`, must be a number.
+    # ======================================================================= #
+    unless which_month =~ /^\d+$/
+      months = Date::MONTHNAMES
+      if months.compact.any? {|entry| entry.include? which_month }
+        months.each_with_index {|month, index|
+          if month and month.start_with?(which_month)
+            which_month = index
+          end unless which_month.is_a? Integer
+        }
+      end 
+    end
+    cliner
+    cmd = N+'cal '+which_month.to_s+' '+::Roebe::Shell::CURRENT_YEAR+N
+    result = `#{cmd}`.chomp
+    if use_colours?
+      _ = "#{current_month?} #{current_year?}"
+      result.gsub!(/(^\s+#{_})/,
+        N+slateblue('\1')+N)
+    end
+    # ===================================================================== #
+    # Pad with two ' ' to the left next.
+    # ===================================================================== #
+    result = result.split(N).map {|entry| "  #{entry}" }.join(N)
+    e result
+    cliner
+  end
+
+  require 'roebe/classes/show_appointments.rb'
+  # ========================================================================= #
+  # === show_appointments                    (Termine tag, appointments tag)
+  #
+  # This method will show various appointments, through the class 
+  # ShowAppointments. Appointments can be found at:
+  #
+  #   blappointments
+  #
+  # Since 2011 we show Appointments only if they are not older than 2
+  # hours.
+  # ========================================================================= #
+  def show_appointments
+    ::Roebe::ShowAppointments.new
+  end
+
+  # ========================================================================= #
+  # === show_todo
+  # ========================================================================= #
+  def show_todo(
+      which_todo = :normal_todo
+    )
+    case which_todo
+    # ======================================================================= #
+    # === :normal_todo
+    # ======================================================================= #
+    when :normal_todo
+      e 'Displaying '+sfancy('todo')+' file next:'
+      this_file = shell_env?['RUBY_SRC']+'/roebe/doc/TODO_FOR_THE_ROEBE_SHELL.md'
+      if File.exist? this_file
+        _ = readlines(this_file)
+        e _.join()
+      else
+        ewarn "Could not find the file #{sfile(this_file)}."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === environment_output
+  #
+  # This method gives us the result of an environment variable.
+  #
+  # The leading "e_" indicates "environment".
+  #
+  # Usage example:
+  #
+  #   eoutput $RSRC
+  #
+  # ========================================================================= #
+  def environment_output(
+      i
+    )
+    if i.is_a? Array
+      i = i.first
+    end
+    _ = i
+    # ======================================================================= #
+    # Treat $ as ENV variables:
+    # ======================================================================= #
+    if _.include? '$'
+      env_var = _[1..-1]
+      if shell_env?.include?(env_var)
+        # Passthrough.
+      else
+        # Report to user.
+        ewarn "The environment variable `#{env_var}` was not found."
+        ewarn 'It most likely does not exist in your environment.'
+      end
+      _ = convert_global_env(_)
+    end
+    e _
+  end; alias e_output environment_output # === e_output
+
+  # ========================================================================= #
+  # === output_these_arguments
+  #
+  # This method will also try to honour @variables.
+  # ========================================================================= #
+  def output_these_arguments(i)
+    i = N if i.nil?
+    i = i.join(' ') if i.is_a? Array
+    if i.include? '$'
+      i = convert_global_env(i)
+    end
+    if i.start_with? '$' # Provide a hint to the user here.
+      e "It seems as if you may be trying to output an "\
+        "#{sfancy('undefined')} environment variable."
+      e 'We could not find any corresponding value for this variable.'
+      e 'This would usually mean that this variable was not set, '\
+        'thus does not exist.'
+    end
+    if i.include? '@'
+      if session?.has_this_key?(i.strip)
+        i = session?[i.strip]
+      end
+    end
+    e orchid(i)
+  end
+
+  # ========================================================================= #
+  # === feedback_use_irb_drop
+  # ========================================================================= #
+  def feedback_use_irb_drop
+    require 'roebe/shell/standalone_classes/irb_drop.rb'
+    e sfancy(VerboseTruth[use_irb_drop?])
+  end
+
+  # ========================================================================= #
+  # === feedback_enable_or_disable_actions
+  #
+  # An Array should be passed as input to this method.
+  # ========================================================================= #
+  def feedback_enable_or_disable_actions(array)
+    if ::Roebe.const_defined? :DisplayArray # bl $RUBY_TOOLS/display.rb
+      ::Roebe::DisplayArray.display(array, padding: '  ', token: ')')
+    else
+      array.each {|entry| e "  #{entry}" }
+    end
+  end
+
+  # ========================================================================= #
+  # === feedback                                               (feedback tag)
+  # ========================================================================= #
+  def feedback(i)
+    if i.is_a? Array
+      i.each {|entry|
+        feedback(entry)
+      }
+    else
+      case i
+      # ===================================================================== #
+      # === version_and_url
+      # ===================================================================== #
+      when 'version_and_url'
+        feedback_version_and_url_about
+      # ===================================================================== #
+      # === variables
+      # ===================================================================== #
+      when 'variables'
+        feedback_instance_variables
+      # ===================================================================== #
+      # === program
+      # ===================================================================== #
+      when 'program'
+        feedback_description_for_this_program
+      # ===================================================================== #
+      # === programs
+      # ===================================================================== #
+      when 'programs'
+        feedback_available_programs
+      # ===================================================================== #
+      # === colours
+      # ===================================================================== #
+      when 'colours'
+        feedback_all_about_colours
+      # ===================================================================== #
+      # === burn
+      # ===================================================================== #
+      when 'burn'
+        feedback_burn_program
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === feedback_burn_program
+  #
+  # This method will tell us which CD and DVD burn program is
+  # currently active.
+  # ========================================================================= #
+  def feedback_burn_program
+    e 'We will use this program to burn CDs:  '+
+       simp(config?.cd_burn_program)
+    e 'We will use this program to burn DVDs: '+
+       simp(config?.dvd_burn_program)
+  end
+
+  # ========================================================================= #
+  # === feedback_completion_proc
+  #
+  # This method feedbacks the shortcuts for the completion proc.
+  # ========================================================================= #
+  def feedback_completion_proc
+    display array_completion_proc?.sort
+  end
+
+  # ========================================================================= #
+  # === feedback_instance_variables
+  # ========================================================================= #
+  def feedback_instance_variables
+    cliner { e 'The instance variables are:'}
+    pp self.instance_variables.sort
+    cliner {
+      e 'The available |imp|instance variables|_| are:'
+      splitted = self.instance_variables.sort
+      splitted.each_with_index {|entry, index|
+        index += 1
+        index = '%3s' % index
+        e ' - '+index.to_s+') '+sfancy(entry.to_s)
+      }
+    }
+  end
+
+  # ========================================================================= #
+  # === feedback_available_programs
+  #
+  # Feedback available programs.
+  # ========================================================================= #
+  def feedback_available_programs
+    ::RBT.feedback_available_programs
+  end
+   
+  # ========================================================================= #
+  # === feedback_all_available_methods
+  #
+  # This method will feedback all available methods in the
+  # Roebe::Shell component.
+  # ========================================================================= #
+  def feedback_all_available_methods
+    first_character_shall_be_red = true
+    e
+    e 'The available methods are:'
+    e
+    self.methods.sort.each_with_index { |method_name, index|
+      index = index + 1
+      method_name = method_name.to_s
+      if first_character_shall_be_red
+        method_name[0,1] = swarn(method_name[0,1]) 
+      end
+      e sfancy(index.to_s)+' '+simp(method_name)
+    }
+  end
+
+  # ========================================================================= #
+  # === feedback_all_available_methods_or_just_one_method
+  # ========================================================================= #
+  def feedback_all_available_methods_or_just_one_method(i = nil)
+    i = i.first if i.is_a? Array
+    if i
+      show_documentation_of? i
+      e # Spacer.
+      show_source_of? i
+    else
+      feedback_all_available_methods
+    end
+  end   
+
+  # ========================================================================= #
+  # === feedback_will_we_use_colours?
+  # ========================================================================= #
+  def feedback_will_we_use_colours?(optional_hash = {})
+    counter = 0
+    counter = optional_hash.values.first if optional_hash.is_a? Hash
+    e pad_this_string('Will we use colours: ', counter)+
+      sfancy(will_we_use_colours?)
+  end
+
+  # ========================================================================= #
+  # === feedback_all_about_colours
+  #
+  # Feedback all about colours here.
+  #
+  # Invocation example:
+  #
+  #   feedback_all_about_colours
+  #
+  # ========================================================================= #
+  def feedback_all_about_colours
+    e N+'The colours for use in the '+simp('Roebe::Shell')+' are:'+N
+    _ = ColourCodes.new(colours?.pretty_inspect, false) # bl $DIA/CLASSES/colour_codes.rb
+    _.set_padding(config?.padding) if config?
+    _.run
+    result = _.result+N
+    e result
+    e
+    feedback_will_we_use_colours?
+  end
+
+  # ========================================================================= #
+  # === feedback_description_for_this_program
+  #
+  # We feedback description of a program with this method here.
+  #
+  # To get "help" listing for this commandlet, do this:
+  #   description ?
+  #
+  # To invoke this method, try:
+  #
+  #   description htop
+  #
+  # ========================================================================= #
+  def feedback_description_for_this_program(i)
+    available_programs = RBT.available_programs
+    if i.is_a? Array
+      i.each {|entry| feedback_description_for_this_program(entry) }
+    else
+      if %w( random rand ).include? i
+        selection = array_available_programs.sample
+        e selection
+        i = selection
+      elsif %w( help hel he h ? ).include? i
+        _ = ''.dup
+        e 'Listing available programs next:'
+        available_programs.each { |program| _ << program+' ' }
+        e _
+        return
+      end
+      if available_programs.include? i
+        e
+        e steelblue(
+            word_wrap( # Wrap it up a bit.
+              cookbook_dataset(i).description_of?.strip,80,'  '
+            )
+          )
+        e
+      else
+        ewarn "#{sfancy(i)} was not found in our database."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === feedback_version_and_url_about
+  #
+  # This method can be used to feedback the specific version of a
+  # program and its URL.
+  #
+  # Note that we will always downcase the given input.
+  #
+  # Usage example:
+  #
+  #   feedback_version_and_url_about :php
+  #
+  # ========================================================================= #
+  def feedback_version_and_url_about(i = 'wine')
+    i = %w( wine ) if i.nil?
+    if i.is_a? Array
+      i << 'wine' if i.empty?
+      i = i.join(' ').strip
+    end
+    i = i.to_s.downcase # Always downcase the input.
+    # ======================================================================= #
+    # From this point on, we have only a String.
+    # ======================================================================= #
+    if i.start_with? ':'
+      i.chop!
+    end
+    dataset = cookbook_dataset(i)
+    version = dataset.program_version?
+    url     = dataset.url?
+    e 'The version of '+sfancy(i)+' is: '+simp(version)
+    e 'The URL to this program is: '+simp(url)
+    # pp [version, url]
+    # This used to be:
+    #   feedback_version(i)
+    #   feedback_url_for_this_program(i)
+    # Unsure if we should re-enable this.
+  end
+
+  # ========================================================================= #
+  # === really_verbose_way_to_show_the_environment
+  # ========================================================================= # 
+  def really_verbose_way_to_show_the_environment
+    e
+    e "Showing the content of ENV (aka env] next ("\
+      "#{sfancy(shell_env?.size.to_s)} entries):"
+    e
+    show_environment # bl $DIA/core/show.rb
+    # ======================================================================= #
+    # Next we will also show a statistical "footer" so that the user can
+    # make sense of the shown environment in a more reproducible manner.
+    # ======================================================================= #
+    show_statistical_information_about_the_environment
+  end
+
+  # ========================================================================= #
+  # === show_statistical_information_about_the_environment
+  # ========================================================================= #
+  def show_statistical_information_about_the_environment(
+      i = shell_env?
+    )
+    e # Also display some more information next.
+    e "A total of #{simp(i.keys.size.to_s)} environment variables "\
+      "have been found."
+  end
+
+  # ========================================================================= #
+  # === show_environment                           (env tag, environment tag)
+  #
+  # This method shows the available environment-variables in a fairly
+  # convenient way to the user. The two-indent in the following display
+  # happens on purpose - we want to show this in a fairly easy-to-read
+  # manner.
+  # ========================================================================= #
+  def show_environment(
+      env                        = shell_env?,
+      n_padding_to_the_left_side = 32 # How much to pad onto the left side.
+    )
+    env.each { |key, value|
+      format_string_to_use = "%-#{n_padding_to_the_left_side}s"
+      key = (format_string_to_use % ("#{key}:"))
+      e "#{rev}  #{steelblue(key)} #{sfancy(value)}"
+    }
+  end
+
+  # ========================================================================= #
+  # === report_the_current_roebe_version_in_use
+  # ========================================================================= #
+  def report_the_current_roebe_version_in_use
+    e "#{rev}The current Roebe-version in use is "\
+      "#{sfancy(::Roebe.version?)}, "\
+      "last updated on the #{steelblue(LAST_UPDATE)}."
+  end
+
+end; end