roebe 0.5.123

data/lib/roebe/shell/shell/shell.rb

@@ -0,0 +1,2153 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Roebe::Shell
+#
+# This class has been specifically rewritten in April 2022 to test how to
+# load add-ons in the background.
+#
+# The Roebe::Shell class represents a shell that should function like irb
+# and bash - so it is not necessarily using pure ruby code as-is, but may
+# have to mediate between ruby, and simpler user input (commands).
+#
+# THe method menu() is the main entry point into the Roebe::Shell,
+# in regards to interactive user-input.
+#
+# Usage example:
+#
+#   Roebe::Shell.new(ARGV)
+#
+# =========================================================================== #
+# require 'roebe/shell/shell/shell.rb'
+# =========================================================================== #
+require 'roebe/base/base.rb'
+
+module Roebe
+
+class Shell < Base # === Roebe::Shell
+
+  begin
+    require 'directory_paradise'
+  rescue LoadError; end
+
+  begin
+    require 'ascii_countdown' # This is specifically used for the prompt.
+  rescue LoadError; end
+
+  begin
+    require 'cyberweb/utility_scripts/create_standalone_html_page.rb'
+  rescue LoadError; end
+
+  require 'roebe/shell/project/project.rb'
+  require 'roebe/constants/roebe.rb'
+  require 'roebe/toplevel_methods/e.rb'
+  require 'roebe/toplevel_methods/files.rb'
+  require 'roebe/toplevel_methods/is_on_roebe.rb'
+  require 'roebe/toplevel_methods/rds.rb'
+  require 'roebe/toplevel_methods/to_bool.rb'
+  require 'roebe/toplevel_methods/verbose_truth.rb'
+  require 'roebe/toplevel_methods/write_what_into.rb' # Needed for the permanent-save functionality here.
+  require 'roebe/shell/module_methods/anmeldung.rb'
+  require 'roebe/shell/module_methods/available_components.rb'
+  require 'roebe/shell/module_methods/benchmarks.rb'
+  require 'roebe/shell/module_methods/commandline_arguments.rb'
+  require 'roebe/shell/module_methods/encoding.rb'
+  require 'roebe/shell/module_methods/home_directory.rb'
+  require 'roebe/shell/module_methods/main_file.rb'
+  require 'roebe/shell/session/session.rb'
+  require 'roebe/shell/colours/colours.rb'
+  require 'roebe/shell/shell/constants.rb'
+  require 'roebe/shell/shell/menu.rb'
+  require 'roebe/shell/shell/misc.rb'
+  require 'roebe/shell/shell/reset.rb'
+  # ========================================================================= #
+  # Important shell-core files are required next:'
+  # ========================================================================= #
+  require 'roebe/shell/shell/core/act_filetype_specific.rb'
+  require 'roebe/shell/shell/core/action.rb'
+  require 'roebe/shell/shell/core/aliases.rb'
+  require 'roebe/shell/shell/core/arguments.rb'
+  require 'roebe/shell/shell/core/ascii.rb'
+  require 'roebe/shell/shell/core/audio.rb'
+  require 'roebe/shell/shell/core/backup.rb'
+  require 'roebe/shell/shell/core/birthdays.rb'
+  require 'roebe/shell/shell/core/browser.rb'
+  require 'roebe/shell/shell/core/calculate.rb'
+  require 'roebe/shell/shell/core/call.rb'
+  require 'roebe/shell/shell/core/cat.rb'
+  require 'roebe/shell/shell/core/change_directory.rb'
+  require 'roebe/shell/shell/core/checks.rb'
+  require 'roebe/shell/shell/core/clear_and_purge.rb'
+  require 'roebe/shell/shell/core/clipboard.rb'
+  require 'roebe/shell/shell/core/configuration.rb'
+  require 'roebe/shell/shell/core/conversions.rb'
+  require 'roebe/shell/shell/core/count.rb'
+  require 'roebe/shell/shell/core/create.rb'
+  require 'roebe/shell/shell/core/cut.rb'
+  require 'roebe/shell/shell/core/delay.rb'
+  require 'roebe/shell/shell/core/directory_actions.rb'
+  require 'roebe/shell/shell/core/disable.rb'
+  require 'roebe/shell/shell/core/download.rb'
+  require 'roebe/shell/shell/core/dump.rb'
+  require 'roebe/shell/shell/core/e.rb'
+  require 'roebe/shell/shell/core/editor.rb'
+  require 'roebe/shell/shell/core/enable.rb'
+  require 'roebe/shell/shell/core/ensure.rb'
+  require 'roebe/shell/shell/core/env.rb'
+  require 'roebe/shell/shell/core/exit.rb'
+  require 'roebe/shell/shell/core/find_and_search.rb'
+  require 'roebe/shell/shell/core/file_actions.rb'
+  require 'roebe/shell/shell/core/gems.rb'
+  require 'roebe/shell/shell/core/generate.rb'
+  require 'roebe/shell/shell/core/get_file_listing.rb'
+  require 'roebe/shell/shell/core/get_var.rb'
+  require 'roebe/shell/shell/core/google.rb'
+  require 'roebe/shell/shell/core/help.rb'
+  require 'roebe/shell/shell/core/history.rb'
+  require 'roebe/shell/shell/core/hostname.rb'
+  require 'roebe/shell/shell/core/images.rb'
+  require 'roebe/shell/shell/core/install.rb'
+  require 'roebe/shell/shell/core/irb.rb'
+  require 'roebe/shell/shell/core/is.rb'
+  require 'roebe/shell/shell/core/iso.rb'
+  require 'roebe/shell/shell/core/make.rb'
+  require 'roebe/shell/shell/core/misc.rb'
+  require 'roebe/shell/shell/core/move.rb'
+  require 'roebe/shell/shell/core/mount.rb'
+  require 'roebe/shell/shell/core/open.rb'
+  require 'roebe/shell/shell/core/path.rb'
+  require 'roebe/shell/shell/core/personal.rb'
+  require 'roebe/shell/shell/core/pid.rb'
+  require 'roebe/shell/shell/core/ping.rb'
+  require 'roebe/shell/shell/core/pkgconfig.rb'
+  require 'roebe/shell/shell/core/play.rb'
+  require 'roebe/shell/shell/core/queries.rb'
+  require 'roebe/shell/shell/core/question_answer.rb'
+  require 'roebe/shell/shell/core/register.rb'
+  require 'roebe/shell/shell/core/ruby.rb'
+  require 'roebe/shell/shell/core/shellrc_file.rb'
+  require 'roebe/shell/shell/core/show_display_feedback_and_report.rb'
+  require 'roebe/shell/shell/core/set.rb'
+  require 'roebe/shell/shell/core/stat.rb'
+  require 'roebe/shell/shell/core/tab.rb'
+  require 'roebe/shell/shell/core/time.rb'
+  require 'roebe/shell/shell/core/toggle.rb'
+  require 'roebe/shell/shell/core/update.rb'
+  require 'roebe/shell/shell/core/upload.rb'
+  require 'roebe/shell/shell/core/url.rb'
+  require 'roebe/shell/shell/core/use.rb'
+  require 'roebe/shell/shell/core/video.rb'
+  require 'roebe/shell/shell/core/webrick.rb'
+  require 'roebe/shell/shell/core/whoami.rb'
+  require 'roebe/shell/shell/core/windows.rb'
+  require 'roebe/shell/shell/core/wlan.rb'
+  require 'roebe/shell/shell/core/yaml.rb'
+  require 'roebe/shell/help/documented_help_options.rb'
+
+  # ========================================================================= #
+  # === Roebe::Shell::YAML_NETWORK
+  #
+  # We need to put the following into a begin-rescue clause as it is
+  # not available on many other computer systems.
+  #
+  # It will be a Hash, containing key→value pairs such as ...
+  # {"core"=>"192. and more.
+  # ========================================================================= #
+  begin
+    _ = ENV['LINUX'].to_s+'/yaml/network.yml'
+    if File.exist? _
+      YAML_NETWORK = YAML.load_file(_)
+    else
+      YAML_NETWORK = {}
+    end
+  rescue; end
+
+  require 'roebe/toplevel_methods/keywords.rb'
+  # ========================================================================= #
+  # === Roebe::Shell::RUBY_KEYWORDS
+  #
+  # Collect all ruby keywords here. This depends on the gem keywords.
+  # ========================================================================= #
+  RUBY_KEYWORDS = ::Roebe.ruby_keywords?
+
+  # ========================================================================= #
+  # === @array_roebe_shell_case_options
+  # ========================================================================= #
+  @array_roebe_shell_case_options = []
+
+  # ========================================================================= #
+  # === Roebe::Shell.array_roebe_shell_case_options
+  # ========================================================================= #
+  def self.array_roebe_shell_case_options
+    @array_roebe_shell_case_options
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.append_to_the_array_roebe_shell_case_options
+  # ========================================================================= #
+  def self.append_to_the_array_roebe_shell_case_options(i)
+    @array_roebe_shell_case_options << i
+    # ======================================================================= #
+    # And always sanitize it afterwards.
+    # ======================================================================= #
+    @array_roebe_shell_case_options.flatten!
+    @array_roebe_shell_case_options.compact!
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.registered_case_options
+  #
+  # Return all available slots from the DiamondShell menu.
+  # ========================================================================= #
+  def self.registered_case_options
+    @array_roebe_shell_case_options
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.valid_help_options
+  # ========================================================================= #
+  def self.valid_help_options
+    ARRAY_VALID_HELP_OPTIONS
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell::ROEBE_SHELL_YAML_LOG_DIRECTORY
+  #
+  # Here we store the log directory for yaml files.
+  # ========================================================================= #
+  ROEBE_SHELL_YAML_LOG_DIRECTORY =
+    "#{Roebe::Shell.log_directory?}yaml/"
+
+  # ========================================================================= #
+  # === Roebe::Shell::LAST_COMMANDS
+  #
+  # Where we store our last commands.
+  # ========================================================================= #
+  LAST_COMMANDS =
+    "#{ROEBE_SHELL_YAML_LOG_DIRECTORY}last_commands.yml"
+
+  # ========================================================================= #
+  # === RUBY_ASSUMED_VERSION
+  #
+  # This is e. g. "2.7.1". It must come before we define the RI_DIRECTORY
+  # constant.
+  # ========================================================================= #
+  RUBY_ASSUMED_VERSION = RbConfig::CONFIG['MAJOR']+'.'+
+                         RbConfig::CONFIG['MINOR']+'.'+
+                         RbConfig::CONFIG['TEENY']
+
+  # ========================================================================= #
+  # === Roebe::Shell::RI_DIRECTORY
+  #
+  # Where ri stores it's docu normally.
+  # ========================================================================= #
+  RI_DIRECTORY = "#{RbConfig::CONFIG['datarootdir']}/ri/#{RUBY_ASSUMED_VERSION}/system"
+
+  # ========================================================================= #
+  # === ARRAY_KEYWORD_EXCEPTIONS_FOR_ALL_AS_AN_ARGUMENT
+  #
+  # A list of exceptions for when the argument is 'all'.
+  # ========================================================================= #
+  ARRAY_KEYWORD_EXCEPTIONS_FOR_ALL_AS_AN_ARGUMENT = %w(
+    play_song
+    playsong
+    playsongs
+    play rsong
+  )
+
+  # ========================================================================= #
+  # === ARRAY_ALLOWED_MODES
+  # ========================================================================= #
+  ARRAY_ALLOWED_MODES = %w(
+    browser display edit play
+  )
+
+  # ========================================================================= #
+  # === AUDIO_FILE_TYPES
+  # ========================================================================= #
+  AUDIO_FILE_TYPES = %w(
+    .mp3
+    .wav
+    .ogg
+    .mp4
+  )
+
+  # ========================================================================= #
+  # === ARRAY_POSSIBLE_CHMOD_VALUES
+  #
+  # All possible chmod-values are registered here.
+  # ========================================================================= #
+  ARRAY_POSSIBLE_CHMOD_VALUES = %w(
+    000
+    111 110 101 100 011 010 001
+    333
+    444 400
+    555
+    644 655
+    777 775 757 755 744 741 714 711 700
+  )
+
+  # ========================================================================= #
+  # === ARRAY_POSSIBLE_INSTALL_ACTIONS
+  #
+  # List which install actions are allowed in the following Array.
+  # 
+  # PLEASE KEEP THIS ARRAY ALWAYS UP-TO-DATE!
+  # ========================================================================= #
+  ARRAY_POSSIBLE_INSTALL_ACTIONS = %w( 
+    default
+    wlan
+    grub
+    mp3directcut
+    starter_pack
+    nvidia
+    flash
+    windows
+    pdf
+    debian_package
+  )
+
+  # ========================================================================= #
+  # === ARRAY_WAYS_TO_EXIT
+  #
+  # The following Array keeps track how to exit from the Diamond Shell.
+  # ========================================================================= #
+  ARRAY_WAYS_TO_EXIT = %w(
+    q   exit quit break bye
+    out exi  rdia eit   exti 
+    rda toq  ra   da    cq
+    eq  w    qq   qu    aus
+    ende
+  )
+
+  # ========================================================================= #
+  # === ARRAY_REGISTERED_ENTRIES_FOR_GENERATE
+  # ========================================================================= #
+  ARRAY_REGISTERED_ENTRIES_FOR_GENERATE = %w(
+    xorg
+    www_colours
+    images
+    keys
+    feedback
+    inputrc
+    spreadsheet
+  )
+
+  # ========================================================================= #
+  # === ARRAY_AVAILABLE_OPTIONS_FOR_GENERATE
+  #
+  # Next, we gather all options available for generate.
+  # ========================================================================= #
+  ARRAY_AVAILABLE_OPTIONS_FOR_GENERATE = %w(
+    xorg
+    rcfiles
+    www_colours
+    image
+    keys
+    feedback
+    inputrc
+    spreadsheet
+    aliases
+  )
+
+  # ========================================================================= #
+  # === ARRAY_AVAILABLE_DISPLAY_OPTIONS
+  # ========================================================================= #
+  ARRAY_AVAILABLE_DISPLAY_OPTIONS = %w(
+    hardware_information
+    contacts
+    ram
+    video_resolution
+    host_information
+  ).sort
+
+  # ========================================================================= #
+  # === ARRAY_RUBY_CORE_CONSTANTS
+  #
+  # As of ruby 2.4, Bignum is no longer a part of ruby.
+  # ========================================================================= #
+  ARRAY_RUBY_CORE_CONSTANTS = [
+    String,
+    Hash,
+    Array,
+    BasicObject,
+    Object,
+    Module,
+    Class,
+    Numeric,
+    Integer,
+    Float,
+    Fiber,
+    Dir,
+    File,
+    Encoding,
+    Enumerator
+  ]
+
+  # ========================================================================= #
+  # === ARRAY_COMMANDS_FOR_THE_ROEBE_SHELL_HISTORY
+  # ========================================================================= #
+  ARRAY_COMMANDS_FOR_THE_ROEBE_SHELL_HISTORY = %w(
+    show_logfile_for_history
+    show_history
+    showhistory
+    handle_history
+    history?
+    history
+    commands?
+    use_command_at_history_position
+    hh
+    hist
+    h?
+    h
+    history_file?
+    hist?
+  )
+
+  # ========================================================================= #
+  # === Roebe::Shell::HELP_OPTIONS
+  #
+  # Which help options are valid? Typically these are help, h and ?
+  # and a few more. They will be defined in the following Array.
+  # ========================================================================= #
+  HELP_OPTIONS = %w(
+    HELP
+    ?
+    h
+    help
+    help?
+    elp
+    hel
+    he
+    h?
+    hep
+    show_help_options
+    --help hlep
+    helpoptions?
+    help_options?
+    hoptions?
+    hopt?
+    hop?
+  )
+
+  # ========================================================================= #
+  # === Roebe::Shell::FILE_HOME_DIR
+  #
+  # This is a yaml file but normally it does not exist, on purpose. The
+  # user may enable this through a commandline switch.
+  #
+  # If this constant is ported then we also have to modify the file
+  # called 'home_directory.rb'.  
+  # ========================================================================= #
+  FILE_HOME_DIR =
+    "#{::Roebe::Shell.project_base_directory?}configuration/home_dir.yml"
+
+  # ========================================================================= #
+  # === Roebe::Shell.array_help_options
+  # ========================================================================= #
+  def self.array_help_options
+    HELP_OPTIONS
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell::LOCALHOST
+  #
+  # The localhost has which URLs?
+  # ========================================================================= #
+  LOCALHOST = 'http://localhost/'
+
+  # ========================================================================= #
+  # === Roebe::Shell::SITELIBDIR
+  #
+  # The Ruby sitelib directory.
+  # ========================================================================= #
+  SITELIBDIR = RbConfig::CONFIG['sitelibdir']
+
+  # ========================================================================= #
+  # === Roebe::Shell::MSG_PROVIDE_ONE_ARGUMENT
+  # ========================================================================= #
+  MSG_PROVIDE_ONE_ARGUMENT = 'Please provide at least one argument.'
+
+  # ========================================================================= #
+  # === Roebe::Shell::WINDOWS_HOMEDIR
+  #
+  # This might also be USERPROFILE variable.
+  # ========================================================================= #
+  WINDOWS_HOMEDIR = "#{ENV['HOMEDRIVE']}/"
+
+  # ========================================================================= #
+  # === @array_exceptions_keep_numbers
+  #
+  # Keep numbers for these method calls here every time, as otherwise we
+  # would substite a number with a file position in a given directory.
+  # ========================================================================= #
+  @array_exceptions_keep_numbers = %w(
+
+    google
+
+    sleep pause sle
+    remove_jumper removejumper remove_setpoint rmjumper rmj removejumper
+
+    jump_to jumpto jumping jto jmpto jot? j jot jt
+
+    rand random
+
+    remove
+
+    in
+    pounds pds pound
+    chmod
+    history hist h
+    haupstadt capital capitals qz quiz qui cap
+
+    create_webpage createwebpage createw create_html_page chp cwp cwb cwebpage cweb splitpage
+
+    circle? kreis? kreis circle
+
+    cut_start cutstart cut_end cutend cend cutend cute
+    
+    moleculargewicht
+    ls ll ls?
+    header? head?
+    padding
+    convert conv con
+    random_string randomstring
+    celsius_to_fahrenheit celsiustofahrenheit
+    set_head sethead
+
+    display_environment_information
+    displayenvironmentinformation
+    envi? env envi
+
+    get_ivar getivar gvar get_var getvar
+
+    touch toouch create_file erstelle_verzeichnis tou
+
+    unalias unset aliases? ali aliases alias alais
+
+    pyth pythagoras
+
+    play
+
+    imdb_search_for imdbsearchfor imdb
+
+    anyone_has_a_birthday? birthday? birthday bday?
+    gebursttag geburtstag purzel birthdays? bday
+   
+    make_screenshot mshot img snapshot screenshot
+    shot scrot ksnap snap makeshot
+    makescreenshot shotter
+
+    url? url ur u
+
+    wecker wekcer
+
+    countdown cdown count_down count- countup
+    cup count_up count count
+
+    wien? wien vienna? vienna karte map stadtplan showmap
+
+    rename_tab tab title change_tab_title renametab ctt tabtitle titel rti rit rtio rtitle
+
+    replay
+
+    user user? uid? uid userid? userid user-id user_id
+
+    play_video video playvideo
+
+    handle_mp3 mp3 handle_this_mp3_file mp3-modify mp3modify modifymp3 handlethismp3file
+
+    line line? show_line_number_in_this_file showlinenumberinthisfile
+
+    playlist playlist?
+
+    alias
+
+    rf
+
+  )
+
+  # ========================================================================= #
+  # === Roebe::Shell.exceptions_keep_numbers
+  #
+  # Reader method over @array_exceptions_keep_numbers.
+  # ========================================================================= #
+  def self.exceptions_keep_numbers
+    @array_exceptions_keep_numbers
+  end
+
+  # ========================================================================= #
+  # The keycodes for alt + arrow keys are stored in these constants.
+  # ========================================================================= #
+
+  # ========================================================================= #
+  # === Roebe::Shell::LEFT_ARROW_KEY_AND_ALT_KEY
+  # ========================================================================= #
+  LEFT_ARROW_KEY_AND_ALT_KEY   = "\e[1;3D\n"
+
+  # ========================================================================= #
+  # === Roebe::Shell::TOP_ARROW_KEY_AND_ALT_KEY
+  # ========================================================================= #
+  TOP_ARROW_KEY_AND_ALT_KEY    = "\e[1;3A\n"
+
+  # ========================================================================= #
+  # === Roebe::Shell::RIGHT_ARROW_KEY_AND_ALT_KEY
+  # ========================================================================= #
+  RIGHT_ARROW_KEY_AND_ALT_KEY  = "\e[1;3C\n"
+
+  # ========================================================================= #
+  # === BOTTOM_ARROW_KEY_AND_ALT
+  # ========================================================================= #
+  BOTTOM_ARROW_KEY_AND_ALT_KEY = "\e[1;3B\n"
+
+  # ========================================================================= #
+  # === Roebe::Shell::ARRAY_ARROW_KEYS
+  #
+  # Collect the arrow-keys into an Array.
+  # ========================================================================= #
+  ARRAY_ARROW_KEYS = [
+    LEFT_ARROW_KEY_AND_ALT_KEY,
+    TOP_ARROW_KEY_AND_ALT_KEY,
+    RIGHT_ARROW_KEY_AND_ALT_KEY,
+    BOTTOM_ARROW_KEY_AND_ALT_KEY
+  ]
+
+  # ========================================================================= #
+  # === ARRAY_REQUIRE_THESE_PROJECT_INTERNAL_FILES
+  #
+  # Unsure whether we will retain this Array in the long run.
+  # ========================================================================= #
+  ARRAY_REQUIRE_THESE_PROJECT_INTERNAL_FILES =  
+  %w(
+    act_filetype_specific
+    action
+    add
+    aliases
+    all
+    append
+    archives
+    ascii
+    audio
+    autostart
+    backup
+    become
+    browser
+    buffer
+    calculate
+    initialize
+    cat
+    call
+    change_directory
+    checks
+    chmod
+    clear_and_purge
+    cliner
+    collapse
+    compile
+    conversions
+    count
+    copy
+    cracks
+    create
+    cut
+    defaults
+    delay
+    disable
+    documentation
+    downcase
+    download
+    dump
+    e
+    editor
+    email
+    empty
+    enable
+    ensure
+    esystem
+    exit
+    extract
+    feedback
+    file_actions
+    find_and_search
+    ftp
+    generate
+    get_var
+    hardware
+    help
+    history
+    hostname
+    information
+    install
+    irb
+    irc
+    iso
+    jumpers
+    merge
+    misc
+    mode
+    move
+    mount
+    open
+    optimize
+    passwords
+    pdf
+    personal
+    pid
+    ping
+    play
+    pkgconfig
+    protect
+    queries
+    question_answer
+    random
+    record
+    repackage
+    repair
+    replay
+    require
+    rbt
+    ruby
+    save
+    screenshot
+    serve
+    set
+    show_display_and_report
+    split
+    stat
+    strip
+    switch
+    tab
+    time
+    toggle
+    treeview
+    upcase
+    update
+    upload
+    url
+    use
+    video
+    wecker
+    whoami
+    windows
+    wlan
+    yaml
+  )
+
+  # ========================================================================= #
+  # === Roebe::Shell::OPERATING_SYSTEM
+  #
+  # Keep track of which operating system is used, through this constant.
+  # ========================================================================= #
+  case RUBY_PLATFORM.downcase
+  when /mswin/
+    OPERATING_SYSTEM = :microsoft
+  else
+    OPERATING_SYSTEM = :linux
+  end
+
+  # ========================================================================= #
+  # === FILE_DIAMONDRC
+  #
+  # Deprecated as of June 2020. This will probably be removed at some
+  # later point in time.
+  # ========================================================================= #
+  # FILE_DIAMONDRC = "#{log_directory?}diamondrc"
+
+  # ========================================================================= #
+  # === Roebe::Shell::FILE_IGNORE_THESE_LAST_COMMANDS
+  #
+  # This constant may expand to a value such as:
+  #
+  #  /home/Programs/Ruby/2.7.1/lib/ruby/site_ruby/2.7.0/roebe/shell/yaml/ignore_these_last_commands.yml
+  #
+  # ========================================================================= #
+  FILE_IGNORE_THESE_LAST_COMMANDS =
+    "#{Roebe::Shell.yaml_directory?}ignore_these_last_commands.yml"
+
+  # ========================================================================= #
+  # === Roebe::Shell.file_check_upcoming_exams
+  # ========================================================================= #
+  def self.file_check_upcoming_exams
+    "#{Roebe::Shell.yaml_directory?}configuration/check_upcoming_exams.yml"
+  end
+
+  # ========================================================================= #
+  # === yaml_configuration?
+  #
+  # Point to the yaml-configuration setting, within the yaml/ subdirectory.
+  # ========================================================================= #
+  def yaml_configuration?
+    "#{Roebe::Shell.yaml_directory?}configuration/"
+  end
+
+  # ========================================================================= #
+  # === ROEBE_SHELL_BUFFER_FILE
+  # ========================================================================= #
+  ROEBE_SHELL_BUFFER_FILE = 
+    "#{Roebe::Shell.yaml_directory?}configuration/buffer.yml"
+
+  # ========================================================================= #
+  # === Roebe::Shell::ROEBE_SHELL_DOC_DIRECTORY
+  # ========================================================================= #
+  ROEBE_SHELL_DOC_DIRECTORY =
+    "#{HOME_OF_THE_USER_CALLED_X}programming/ruby/src/roebe/doc/"
+
+  # ========================================================================= #
+  # === Roebe::Shell::ROEBE_SHELL_TODO_FILE
+  # ========================================================================= #
+  ROEBE_SHELL_TODO_FILE  =
+    "#{ROEBE_SHELL_DOC_DIRECTORY}todo/roebe_shell_todo.md"
+
+  # ========================================================================= #
+  # === Time
+  #
+  # Time related constants will be stored in this file next.
+  # ========================================================================= #
+  _ = ::Time.now.strftime('%d.%m.%Y').split '.' # => "12.08.2020"
+
+  # ========================================================================= #
+  # === CURRENT_DAY
+  # ========================================================================= #
+  CURRENT_DAY   = _[0].to_s
+
+  # ========================================================================= #
+  # === CURRENT_MONTH
+  # ========================================================================= #
+  CURRENT_MONTH = _[1].to_s
+
+  # ========================================================================= #
+  # === CURRENT_YEAR
+  # ========================================================================= #
+  CURRENT_YEAR  = _[2].to_s
+
+  # ========================================================================= #
+  # === CURRENT_DATE
+  # ========================================================================= #
+  CURRENT_DATE  = ::Time.now.strftime('%d.%m.%Y')
+
+  # ========================================================================= #
+  # === Roebe::Shell.file_shellrc
+  #
+  # Return the location towards the shellrc file.
+  # ========================================================================= #
+  def self.file_shellrc
+    "#{log_directory?}shellrc"
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell::HASH_CONTAINING_THE_HELP_OPTIONS
+  #
+  # This is stored in a separate Hash so that we can access this content
+  # from Roebe::Shell embedded in a gtk-widget too.
+  #
+  # To show this via the commandline do:
+  #
+  #   dia --help
+  #
+  # ========================================================================= #
+  HASH_CONTAINING_THE_HELP_OPTIONS = {
+    '--benchmarks'                 => 'show some benchmarks while starting '\
+                                      'the Roebe::Shell',
+    '--extract'                    => "extract something with aid of the Roebe::Shell,\n"\
+                                      "such as in: `roebeshell --extract=foo.tar.xz`",
+    '--enable-roebe'               => "will enable home-system support. This will enable "\
+                                      "all features.\n",
+    '--generate-tab-completion'    => 'generate the tab-completable shortcuts '\
+                                      'for the Roebe::Shell',
+    '--help'                       => 'show this menu here',
+    '--home-dir?'                  => 'show where the Roebe::Shell '\
+                                      'assumes the home\ndirectory to be',
+    '--home-dir=(new_value)'       => "permanently set a new home directory, such as via:\n"\
+                                      "  roebeshell --home-dir=/opt/shell/\n",
+    '--no-colours'                 => 'do not use colours',
+    '--no-startup'                 => "skip the startup() method invocation, thus "\
+                                      "loading a bit\n"\
+                                      "faster, but missing out on extra-functionality "\
+                                      "as well\n",
+    '--norc'                       => 'do not load the configuration file on startup',
+    '--noreadline'                 => 'do not make use of the ruby readline module',
+    '--nohistory'                  => 'do not make use of history',
+    '--run-method'                 => 'invoke a specific method in the Roebe::Shell',
+    '--silent-startup'             => "do a rather quiet startup of the "\
+                                      "Roebe::Shell, which means \n"\
+                                      "that we won't report too much information",
+    '--time'                       => 'simply show the current time '\
+                                      '(in HH:MM:SS format); a convenience flag mostly',
+    '--yaml-directory?'            => "query the path to the local yaml-directory "\
+                                      "for\nthe Roebe::Shell",
+    '--silent-start'               => "do a silent start, e. g. suppress all output\n"\
+                                      "until the shell is running",
+    '--version'                    => 'show the version of the Roebe::Shell, then exit'
+  }
+
+  if ::Roebe.is_on_roebe?
+    HASH_CONTAINING_THE_HELP_OPTIONS['--disable-anmeldungen'] =
+      'do not be show upcoming exams'
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell::FILE_ROEBE_SHELL_HELP
+  #
+  # This constant will point to a location such as:
+  #
+  #  /home/Programs/Ruby/2.7.1/lib/ruby/site_ruby/2.7.0/roebe/shell/help/help.rb
+  #
+  # ========================================================================= #
+  FILE_ROEBE_SHELL_HELP =
+    "#{::Roebe::Shell.project_base_directory?}help/help.rb"
+
+  # ========================================================================= #
+  # === FILE_ADDITIONAL_REQUIRE_FILES
+  #
+  # This constant points to the file which may have additional require
+  # files, in other words, user-defined require files.
+  #
+  # This constant will probably be deprecated in the long run - let's see.
+  #
+  # Yup - since as of May 2022 it was decided to get rid of it. It will
+  # be removed at a later moment in time.
+  # ========================================================================= #
+  #FILE_ADDITIONAL_REQUIRE_FILES =
+  #  "#{DIAMOND_SHELL_YAML_LOG_DIRECTORY}additional_require_files.yml"
+
+  # ========================================================================= #
+  # === Roebe::Shell::LOGFILE_FOR_HISTORY
+  #
+  # The next line should work because we already defined the constant
+  # just above before. This was disabled since as of May 2022.
+  # ========================================================================= #
+  #  LOGFILE_FOR_HISTORY =
+  #    "#{log_directory?}diamond_shell_history"
+
+  # ========================================================================= #
+  # === DIRECTORY_FOR_THE_CONFIGURATION_FILES
+  # ========================================================================= #
+  DIRECTORY_FOR_THE_CONFIGURATION_FILES = "#{Roebe::Shell.yaml_directory?}configuration/"
+
+  # ========================================================================= #
+  # === Roebe::Shell::LAST_DOWNLOADED_FILE
+  #
+  # We store into this file here.
+  # ========================================================================= #
+  LAST_DOWNLOADED_FILE =
+    "#{Roebe::Shell.yaml_directory?}last_downloaded_file.yml"
+
+  # ========================================================================= #
+  # === Roebe::Shell::FILE_APPOINTMENT_DATES
+  # ========================================================================= #
+  FILE_APPOINTMENT_DATES = "#{::Roebe::HOME_OF_THE_USER_CALLED_X}misc/yaml/appointment_dates.yml"
+    LOCATION_APPOINTMENT_DATES = FILE_APPOINTMENT_DATES # === LOCATION_APPOINTMENT_DATES
+
+  # ========================================================================= #
+  # === FILE_DEFAULT_APPS
+  # ========================================================================= #
+  FILE_DEFAULT_APPS = 
+    "#{Roebe::Shell.yaml_directory?}default_apps.yml"
+
+  # ========================================================================= #
+  # === HELLO_WORLD
+  # ========================================================================= #
+  HELLO_WORLD = 'Hello world!'
+
+  # ========================================================================= #
+  # === Roebe::Shell::FILE_NOTIFICATIONS
+  # ========================================================================= #
+  FILE_NOTIFICATIONS = 'NOTIFICATIONS.md'
+
+  # ========================================================================= #
+  # === Roebe::Shell::IGNORE_THESE_LAST_COMMANDS
+  #
+  # Which commands to ignore for last command treatment.
+  #
+  # This will not be stored in the yaml-log directory.
+  #
+  # The original file can be found here:
+  #
+  #   bl $DIA_SHELL/yaml/ignore_these_last_commands.yml
+  #
+  # ========================================================================= #
+  if File.exist? FILE_IGNORE_THESE_LAST_COMMANDS
+    IGNORE_THESE_LAST_COMMANDS = YAML.load_file(
+      FILE_IGNORE_THESE_LAST_COMMANDS
+    )
+  elsif ::Roebe.is_on_roebe?
+    puts "The file at #{sfile(FILE_IGNORE_THESE_LAST_COMMANDS)} "\
+         "does not exist."
+    IGNORE_THESE_LAST_COMMANDS = []
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.permanently_set_home_dir
+  #
+  # This method will also modify the yaml file.
+  # ========================================================================= #
+  def self.permanently_set_home_dir(
+      what = ::Roebe::Shell.home_dir?,
+      into = FILE_HOME_DIR
+    )
+    unless what.end_with? '/' # Ensure a trailing '/'.
+      what = what.dup if what.frozen?
+      what << '/'
+    end
+    puts "Designating #{::Roebe.sdir(what)} as the current home directory."
+    puts "Saving into the file `#{::Roebe.sfile(into)}`."
+    ::Roebe.write_what_into(what, into)
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell::TV_CHANNELS
+  # ========================================================================= #
+  require 'roebe/toplevel_methods/is_on_roebe.rb'
+  if ::Roebe.is_on_roebe?
+    require 'yaml'
+    begin # This is rescued because the file may not exist.
+      _ = "#{MY_VIDEO}yaml/tv_channels.yml"
+      if File.exist? _
+        TV_CHANNELS = YAML.load_file(_)
+      else
+        TV_CHANNELS = {}
+      end
+    rescue Exception => error
+      puts error
+    end
+  else
+    TV_CHANNELS = {}
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.individual_cookbooks_directory?
+  # ========================================================================= #
+  def self.individual_cookbooks_directory?
+    if Object.const_defined?(:RBT) and
+       RBT.respond_to?(:individual_cookbooks_directory?)
+      _ = RBT.individual_cookbooks_directory?
+    else
+      _ = ENV['COOKBOOK_DIRECTORY'].to_s+'/cookbooks/'
+    end
+    _
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.pid_file?
+  # ========================================================================= #
+  def self.pid_file?
+    "#{log_directory?}pid.yml"
+  end
+
+  # ========================================================================= #
+  # Next, add support for FILE_VIDEO_COLLECTION. This is only useful
+  # on my home-setup though.
+  # ========================================================================= #
+  if ::Roebe.is_on_roebe?
+    begin
+      require 'multimedia_paradise/constants/file_constants.rb'
+      # ===================================================================== #
+      # === FILE_VIDEO_COLLECTION
+      #
+      # This constant
+      # ===================================================================== #
+      FILE_VIDEO_COLLECTION = MultimediaParadise.file_video_collection?
+    rescue LoadError; end
+    # ======================================================================= #
+    # === MultimediaParadise.file_video_collection
+    #
+    # This method will simply return where the yaml file is kept.
+    # ======================================================================= #
+    def self.file_video_collection(
+        i = FILE_VIDEO_COLLECTION
+      )
+      i
+    end
+  end
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV,
+      run_already           = true,
+      &block
+    )
+    register_custom_sigint
+    reset
+    # ======================================================================= #
+    # Register the commandline arguments next:
+    # ======================================================================= #
+    ::Roebe::Shell.set_commandline_arguments(
+      commandline_arguments
+    )
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    # ======================================================================= #
+    # The following check also ensures that symbol-instructions such as
+    # :do_not_run_main_loop will be honoured. This may be revisited at
+    # a later time, but for now it will remain as it is. (If a problem
+    # is encountered, it will be mentioned here.)
+    # ======================================================================= #
+    if commandline_arguments.to_s.include?('dont') or
+       commandline_arguments.to_s.include?('do_not')
+      commandline_arguments = nil
+      run_already = false
+    end
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_quiet
+      # ===================================================================== #
+      when :be_quiet,
+           :be_silent
+        be_quiet
+      # ===================================================================== #
+      # === :do_not_enter_the_main_loop
+      # ===================================================================== #
+      when :do_not_enter_the_main_loop
+        run_already = false
+        # =================================================================== #
+        # We will still run startup() actions, though.
+        # =================================================================== #
+        startup
+      else
+        # =================================================================== #
+        # Next handle Hashes
+        # =================================================================== #
+        if yielded.is_a? Hash
+          # ================================================================= #
+          # === :be_quiet
+          #
+          # We must use ! because "yes, be quiet" is opposite to "yes,
+          # be verbose", as implied by the setter-method set_be_verbose().
+          # ================================================================= #
+          if yielded.has_key? :be_quiet
+            set_be_verbose(!yielded[:be_quiet])
+          end
+          # ================================================================= #
+          # === :enable_debug
+          # ================================================================= #
+          if yielded.has_key? :enable_debug
+            Roebe::Shell.set_debug(yielded[:enable_debug])
+          end
+          # ================================================================= #
+          # === :use_history
+          # ================================================================= #
+          if yielded.has_key? :use_history
+            set_use_history(yielded[:use_history])
+          end
+          # ================================================================= #
+          # === :enable_readline
+          # ================================================================= #
+          if yielded.has_key? :enable_readline
+            set_use_readline(yielded[:enable_readline])
+          end
+          # ================================================================= #
+          # === :use_configuration
+          # ================================================================= #
+          if yielded.has_key? :use_configuration
+            set_use_configuration(yielded[:use_configuration])
+          end
+          # ================================================================= #
+          # === :use_colours
+          # ================================================================= #
+          if yielded.has_key? :use_colours
+            if yielded[:use_colours] == false
+              disable_colours(true, :be_quiet)
+            end
+          end
+          # ================================================================= #
+          # === :skip_startup
+          # ================================================================= #
+          if yielded.has_key? :skip_startup
+            set_skip_startup(yielded[:skip_startup])
+          end
+          # ================================================================= #
+          # === :is_roebe
+          # ================================================================= #
+          if yielded.has_key? :is_roebe
+            set_is_roebe(yielded[:is_roebe])
+          end
+          # ================================================================= #
+          # === :assign_to_this_file
+          # ================================================================= #
+          if yielded.has_key? :assign_to_this_file
+            set_this_file(yielded[:assign_to_this_file])
+          end
+          # ================================================================= #
+          # === :run_this_method
+          #
+          # This will run the method, if found, then exit the shell.
+          # ================================================================= #
+          if yielded.has_key? :run_this_method
+            be_quiet
+            try_to_invoke_this_method(yielded[:run_this_method], true)
+            exit_shell
+          end
+        end
+      end
+    end
+    case run_already
+    # ======================================================================= #
+    # === :do_not_run_yet
+    # ======================================================================= #
+    when :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset_last_result
+  #
+  # Reset the :last_result entry in our main Hash.
+  # ========================================================================= #
+  def reset_last_result
+    @internal_hash[:last_result].clear
+  end
+
+  # ========================================================================= #
+  # === reset_user_input
+  #
+  # Consistently use this method whenever you wish to reset the user input.
+  #
+  # The variable @user_input contains the user input, very aptly named so.
+  # ========================================================================= #
+  def reset_user_input
+    @internal_hash[:user_input] = nil
+  end; alias clear_user_input reset_user_input # === clear_user_input
+
+  # ========================================================================= #
+  # === strip_user_input
+  # ========================================================================= #
+  def strip_user_input(
+      i = user_input?
+    )
+    if i.is_a? Array
+      i.map! {|entry| entry.strip }
+    else
+      i.strip! if i
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_reporting_how_long_it_took_us_loading_the_whole_shell_project
+  # ========================================================================= #
+  def consider_reporting_how_long_it_took_us_loading_the_whole_shell_project(
+      use_benchmark_while_loading =
+        ::Roebe::Shell.use_benchmark_while_loading?
+    )
+    if use_benchmark_while_loading
+      start = ::Roebe::Shell.startup_time_at?
+      time_now = ::Time.now
+      difference = time_now - start
+      e "Loading the whole project took #{steelblue(difference.to_s)} seconds."
+    end
+  end
+
+  # ========================================================================= #
+  # === do_not_notify_about_upcoming_anmeldungen
+  # ========================================================================= #
+  def do_not_notify_about_upcoming_anmeldungen
+    ::Roebe::Shell.disable_check_for_upcoming_exams
+  end
+
+  # ========================================================================= #
+  # === do_startup_related_tasks_via_a_thread                   (startup tag)
+  #
+  # This method is run when the Roebe::Shell "starts up". All the various
+  # startup-related actions should be bundled into this method here.
+  #
+  # The proper order is somewhat important, so be mindful when making
+  # changes to this method.
+  #
+  # Since as of May 2022 it will be loaded via a Thread.new {}, to
+  # allow the other parts of the shell to continue to work.
+  #
+  # To show the comments belonging to this method, do:
+  #
+  #   show-comments do_startup_actions
+  #
+  # ========================================================================= #
+  def do_startup_related_tasks_via_a_thread
+    Thread.new {
+      # ===================================================================== #
+      # === roebeshellrc
+      #
+      # Try to use a roebeshellrc file next. This should come before any
+      # output is issued, because output may be colourized, and the
+      # roebeshellrc file may also disable coloured output altogether.
+      # ===================================================================== #
+      attempt_to_find_and_use_a_shellrc_file
+      # load_dictionary # Load dictionary dataset. No longer in use either. Disabled as of May 2022.
+      # report_shell_version # ← Disabled as of February 2016. Don't think
+                             # this is too overly useful.
+      if config?
+        disable_colours(:be_silent) unless config?.use_colours
+      end
+      # ===================================================================== #
+      # Next, ensure that the log-directory exists. Ideally use this before
+      # checking for local .iso files.
+      # ===================================================================== #
+      ensure_that_the_log_directory_exists
+      consider_using_readline
+      # ===================================================================== #
+      # Next we will load the aliases. This should come after the configuration
+      # was loaded already.
+      # ===================================================================== #
+      consider_loading_the_aliases
+      # ===================================================================== #
+      # Next, check whether the defult browser is available or whether
+      # it is not. This should come after the check for the log-directory.
+      # ===================================================================== #
+      check_for_available_browser
+      # ===================================================================== #
+      # === Reassign to the configuration value of @check_for_isos here.
+      # ===================================================================== #
+      do_check_for_isos if config?.check_for_isos if config?
+      action_check_for_isos
+      # ===================================================================== #
+      # Next we will consider installing missing gems. This should come last
+      # or at the least close to the last steps related to startup.
+      # ===================================================================== #
+      consider_installing_missing_gems
+      # ===================================================================== #
+      # Next the clipboard will be instantiated.
+      # ===================================================================== #
+      create_clipboard
+      check_if_this_is_the_first_time_that_we_run_the_shell
+      # ===================================================================== #
+      # Update the file listing the first time the shell is started.
+      # ===================================================================== #
+      update_file_listing
+      # ======================================================================= #
+      # The next method will generate the help options for e. g. "?grabc"
+      # and so forth.
+      # ======================================================================= #
+      populate_inbuilt_hash_help_options
+      generate_cd_aliases_hash
+      check_for_available_browser
+      consider_autogenerating_completion_for_roebe_shell_file
+      store_pid # We keep the PID in a local file.
+      # ======================================================================= #
+      # The next clause is only triggered when it is a "roebe-system", aka
+      # on my home system.
+      # ======================================================================= #
+      if is_on_roebe?
+        # =================================================================== #
+        # Next we could restore the gem-credentials file. This should
+        # probably be done only on original startup of the shell, but
+        # for now (May 2022) it is disabled.
+        # =================================================================== #
+        # try_to_restore_the_gem_credentials_file
+        # =================================================================== #
+        # Enable rescue-env variables on my home system.
+        # =================================================================== #
+        load_personal_settings
+        populate_the_environment_variables if are_we_on_windows?
+        check_for_upcoming_exams # I check for upcoming exams on my system.
+        check_for_holidays
+        check_whether_i_have_an_appointment
+        check_whether_anyone_has_a_birthday
+      end
+      consider_reporting_how_long_it_took_us_loading_the_whole_shell_project
+    }
+  end; alias startup            do_startup_related_tasks_via_a_thread # === startup
+       alias do_startup_actions do_startup_related_tasks_via_a_thread # === do_startup_actions
+
+  # ========================================================================= #
+  # === do_not_report_the_version
+  # ========================================================================= #
+  def do_not_report_the_version
+    @internal_hash[:report_the_version] = false
+  end; alias do_not_report_version do_not_report_the_version # === do_not_report_version
+
+  # ========================================================================= #
+  # === do_not_show_iso_files
+  # ========================================================================= #
+  def do_not_show_iso_files
+    @internal_hash[:check_for_isos] = false
+  end
+
+  # ========================================================================= #
+  # === try_to_restore_the_gem_credentials_file
+  #
+  # This method can be used to restore the credentials file. This makes
+  # it easier for me to publish my gems quickly.
+  # ========================================================================= #
+  def try_to_restore_the_gem_credentials_file(
+      this_file = '/home/x/programming/ruby/src/gem/credentials'
+    )
+    target = home_dir?+'.gem/'+File.basename(this_file)
+    if File.exist?(this_file) and
+      !File.exist?(target)
+      create_directory(File.dirname(target))
+      copy_file(this_file, target)
+    end
+  end
+
+  # ========================================================================= #
+  # === return_user_input_without_trailing_comments
+  #
+  # This method must return an Array. The trailing '#', if found, will
+  # NOT be ignored.
+  #
+  # Example input to test the behaviour of this method may go like this:
+  #
+  #   mkdir /Depot/CCC /Depot/DDD # You can provide more than one argument here.
+  #
+  # ========================================================================= #
+  def return_user_input_without_trailing_comments
+    _ = all_arguments?
+    if _.include? '#'
+      position = _.index('#')
+      _ = _[0 .. (position-1)]
+    end
+    return _
+  end
+
+  # ========================================================================= #
+  # === run_sys_command
+  #
+  # Run a system command. This is basically just a fancified system()
+  # wrapper really.
+  # ========================================================================= #
+  def run_sys_command(i = nil)
+    if i
+      i.delete!('`') if i.include? '`'
+      system i
+    end
+  end; alias run_this_system_command run_sys_command # === run_this_system_command
+
+  # ========================================================================= #
+  # === run_program
+  #
+  # Right now this is just a wrapper over esystem().
+  #
+  # With this method we will run a specific program.
+  #
+  # Usage Example:
+  #
+  #   run_program ls
+  #
+  # ========================================================================= #
+  def run_program(
+      i, report_the_action_to_the_user = true
+    )
+    if i.include? '$' # Added this on 06.09.2014 - it is better to display the absolute path.
+      i = convert_global_env(i)
+    end
+    if i.include? ';'
+      i.split(';').each {|entry|
+        run_program(entry, report_the_action_to_the_user) # Recursive call.
+      }
+    else # Check on the single actions here.
+      case i
+      when 'cliner'
+        cliner # An exception for cliner comes here.
+      else # Either we report to the user.
+        do_not_continue = false
+        # =================================================================== #
+        # Since as of 24.08.2015, we will attempt to find out whether the
+        # input includes a ' ', and if so, we try to find out whether the
+        # first command is a menu option. If so then we use the menu
+        # instead.
+        # =================================================================== #
+        if i.include? ' '
+          _ = i.split(' ')
+          if ::Roebe::Shell.registered_case_options.include? _.first
+            # =============================================================== #
+            # When we enter here, we know that it is included. We thus
+            # call the menu again.
+            # =============================================================== #
+            do_not_continue = true
+            menu(_.join(' '))
+          end
+        end
+        unless do_not_continue
+          if report_the_action_to_the_user
+            esystem(i)
+          else # Or we don't.
+            system(i)
+          end
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === show_prompt_help_options
+  #
+  # This method will show the available prompts.
+  #
+  # To show these options, do:
+  #
+  #   show prompt
+  #
+  # ========================================================================= #
+  def show_prompt_help_options
+    e 'These options are currently available for the |imp|DiaShell Prompt|_|:'
+    e
+    e "  -- #{simp('ASCII')}"
+    e
+    e '     |fancy|Display an ASCII Counter-Countdown (the default is|_|'
+    e '     |fancy|3600 seconds, but you can set it to another value by doing|_|'
+    e '     |fancy|something like: prompt ASCII 100).|_|'
+    e
+    e "  -- #{simp('CWD')}"
+    e
+    e '     |fancy|Include the current working dir in the string.|_|'
+    e
+    e "  -- #{simp('revert')}"
+    e
+    e '     |fancy|Revert to the default prompt again.|_|'
+    e
+    e "  -- #{simp('nil')}"
+    e
+    e '     |fancy|Set the prompt to an empty line.|_|'
+    e
+    e "  -- #{simp('disco')}"
+    e
+    e '     |fancy|Set the prompt to become a disco prompt, changing|_|'
+    e '     |fancy|the colours after every enter-keypress event.|_|'
+    e
+  end
+
+  # ========================================================================= #
+  # === get_instance_variables
+  # ========================================================================= # 
+  def get_instance_variables
+    self.instance_variables.sort
+  end; alias return_instance_variables get_instance_variables # === return_instance_variables
+
+  # ========================================================================= #
+  # === print_pwd
+  # ========================================================================= #
+  def print_pwd(
+      colourize_the_directory = true
+    )
+    _ = return_pwd
+    if colourize_the_directory
+      _ = sdir(_)+rev
+    end
+    print _
+  end
+
+  # ========================================================================= #
+  # === feedback_prompt                                           (Prompt tag)
+  #
+  # Use this method to feedback which prompt is currently in use.
+  # ========================================================================= #
+  def feedback_prompt
+    # set_prompt
+    # print @prompt
+    e 'The currently set prompt in the Roebe::Shell component is:'
+    e "  → #{simp(return_prompt)}"
+  end; alias show_prompt feedback_prompt # === show_prompt
+
+  # ========================================================================= #
+  # === use_this_prompt                                 (set tag, prompt tag)
+  #
+  # Use this method to modify the shell_prompt variable.
+  #
+  # This in turn will be used to set our prompt.
+  #
+  # Note that whenever you set the prompt, we will store it in our
+  # configuration (if the configuration object is available).
+  # ========================================================================= #
+  def set_use_this_prompt(
+      i          = DEFAULT_PROMPT,
+      be_verbose = false
+    )
+    if i.is_a? Array
+      i.each {|entry| set_prompt(entry) }
+    else
+      i = i.to_s
+      if i.include? '//'
+        i = remove_double_slashes(i)
+      end
+      case i.downcase
+      # ===================================================================== #
+      # === default
+      # ===================================================================== #
+      when 'default','revert'
+        i = DEFAULT_PROMPT
+      # when 'pwd'
+      #   i = sdir(
+      #         rds(get_pwd)
+      #       )
+      # ===================================================================== #
+      # === disco
+      # ===================================================================== #
+      when 'disco'
+        i = Colours.translate(
+          Colours.all_available_colours.reject {|_|
+            _.to_s == 'black'
+          }.sample
+        )
+      # ===================================================================== #
+      # === mixed
+      # ===================================================================== #
+      when 'mixed',
+           'mixed_colourized'
+        i = 'MIXED'
+      # ===================================================================== #
+      # === help
+      # ===================================================================== #
+      when *HELP_OPTIONS # Feedback the special options.
+        show_prompt_help_options
+      end
+      if be_verbose
+        e 'Setting the prompt to '+simp(i)+' now.'
+      end
+      @internal_hash[:use_this_prompt] = i
+      unless HELP_OPTIONS.include? i
+        if config?
+          config?.shell_prompt = i
+          save_config # Save the new prompt here.
+        end
+      end
+    end
+  end; alias set_prompt        set_use_this_prompt # === set_prompt
+       alias initialize_prompt set_use_this_prompt # === initialize_prompt
+
+  # ========================================================================= #
+  # === user_interaction_change_prompt
+  #
+  # Use this method to change the default prompt in an interactive manner.
+  # 
+  # If the first argument `ask_user` is false, we will not use any user
+  # input at all. Otherwise, ask_user can be an Array or a String.
+  # ========================================================================= #
+  def user_interaction_change_prompt(
+      ask_user = true
+    )
+    if ask_user.is_a? Array
+      ask_user = ask_user.first
+    end
+    case ask_user # case tag
+    # ======================================================================= #
+    # === help
+    # ======================================================================= #
+    when *HELP_OPTIONS # Feedback the special options.
+      show_prompt_help_options
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         true
+      cliner {
+        eimp N+'You wish to change the prompt.'
+        eimp 'Input how the new prompt should look like now. If you want to '
+        eimp 'include possible information about the current working'
+        eimp 'directory then use the macro |imp|CWD|_|.'
+        e
+        eimp 'If you do |warn|not|_| want to do any change, just hit enter'
+        e
+        eimp "for an empty prompt now.#{N}"
+      }
+      set_prompt($stdin.gets.chomp)
+    else
+      _ = ask_user.to_s
+      emphasis "Setting shell prompt to #{sfancy(_)}." unless _ == 'ASCII'
+      set_prompt(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === return_prompt
+  #
+  # This method will return a proper prompt.
+  #
+  # You can test this such as by doing:
+  #
+  #   set_prompt ASCII
+  #
+  # ========================================================================= #
+  def return_prompt(
+      optional_argument = '60 min'
+    )
+    if config?
+      result = config?.shell_prompt
+    else
+      result = 'PWD'
+    end
+    case result
+    # ======================================================================= #
+    # === PWD
+    #
+    # This entry point is the "default" prompt to use.
+    # ======================================================================= #
+    when 'PWD',
+         'DEF',
+         'REV',
+         'def',
+         'default',
+         'revert',
+         'CWD'
+      result = sdir(return_current_directory) # in bl $DIA/base/directory_actions.rb
+    # ======================================================================= #
+    # === nil
+    # ======================================================================= #
+    when 'nil',
+         nil
+      @internal_hash[:show_absolute_path] = false # Also disable this here.
+      result = ''
+    # ======================================================================= #
+    # === ASCII
+    # ======================================================================= #
+    when /ASCII/i,
+         'A' # bl $RUBY_ASCII/ascii_countdown.rb
+      result = AsciiCountdown.new(optional_argument)+
+               ' |dir|'+get_pwd+'|_|'
+    # ======================================================================= #
+    # === MIXED
+    # ======================================================================= #
+    when 'MIXED'
+      _ = return_current_directory
+      splitted = _.split('/')
+      splitted = splitted.map {|entry| sdir(entry) }
+      result = splitted.join(YELLOW+'/'+rev)
+      result << YELLOW+'/'+rev
+    end
+    return result
+  end; alias return_default_prompt return_prompt # === return_default_prompt
+
+  # ========================================================================= #
+  # === do_open_in_background
+  # ========================================================================= #
+  def do_open_in_background
+    @internal_hash[:open_in_background]
+  end
+
+  # ========================================================================= #
+  # === Roebe::Shell.external_requires
+  #
+  # This method will show which external requires are used.
+  # ========================================================================= #
+  def self.external_requires
+    file_lazy_load_these_components = ::Roebe.project_base_directory?+
+                                      'shell/yaml/lazy_load_these_components.yml'
+    YAML.load_file(file_lazy_load_these_components).sort
+  end
+
+  # ========================================================================= #
+  # === obtain_user_input
+  #
+  # This method will fetch input given by the user. It either makes use
+  # of readline or simply just $stdin.gets().
+  # ========================================================================= #
+  def obtain_user_input(
+      use_readline = shall_we_use_readline_for_the_user_input?
+    )
+    # ======================================================================= #
+    # Check whether we can - and want to use - readline first:
+    # ======================================================================= #
+    if can_we_use_readline_in_principle? and use_readline?
+      @internal_hash[:user_input] = Readline.readline('', true)
+      Readline::HISTORY.pop if @internal_hash[:user_input] =~ /^\s*$/ # Get rid of empty lines.
+    else
+      @internal_hash[:user_input] = $stdin.gets.chomp
+    end
+    # ======================================================================= #
+    # First, retain a copy to the original user input. This should NOT
+    # be modified in any way.
+    # ======================================================================= #
+    set_original_user_input(@internal_hash[:user_input].to_s.dup)
+    # ======================================================================= #
+    # Since as of 17.11.2011 the user-input will be stripped. This should
+    # come after the check to '&' for background-related tasks.
+    # ======================================================================= #
+    strip_user_input
+    # ======================================================================= #
+    # === ;                                                           (; tag)
+    #
+    # Next, split on ';' if these were provided. They are assumed to be
+    # several instructions in one go.
+    #
+    # However had, the given input may also be an URL, and some URLs
+    # contain ';'. So splitting on this would yield incorrect information.
+    # Thus we will have an exception for input like this. Furthermore,
+    # sometimes you may accidentally hit the arrow key on the keyboard,
+    # and you may then send input such as ';3', e. g. the right arrow
+    # key (together with ESCAPE code, or ALT+arrow key). In this
+    # case we will also NOT split on the given input. More exceptions
+    # may have to be added to this in the future, but for now this
+    # is how it is.
+    # ======================================================================= #
+    if @internal_hash[:user_input].include? ';'
+      _ = @internal_hash[:user_input]
+      unless _.include?('http:') or _.include?('https:') or # This adds an exception for URLs.
+             _.include?(';3')
+        @internal_hash[:user_input] = _.split(';').map(&:strip)
+      end
+    end
+    # ======================================================================= #
+    # And keep the user input as an Array at all times.
+    # ======================================================================= #
+    convert_the_user_input_into_an_array
+  end
+
+  # ========================================================================= #
+  # === fetch_multiline_user_input
+  # ========================================================================= #
+  def fetch_multiline_user_input
+    delimiter_token = '//'
+    e "You wish to input more than one line. Enter "\
+      "#{simp(delimiter_token)} to stop input again."
+    $stdin.gets(delimiter_token).chomp
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  #
+  # This is the general run() method that gets invoked normally when a new
+  # instance of Roebe::Shell is started.
+  #
+  # The method enter_main_loop() is defined in another .rb file.
+  # ========================================================================= #
+  def run
+    consider_loading_the_addons_lazily
+    enter_the_main_loop
+  end
+
+  # ========================================================================= #
+  # === consider_loading_the_addons_lazily
+  #
+  # This method will try to lazy-load the described components.
+  #
+  # By default the loading process will NOT be verbose - see the second
+  # argument to this method.
+  # ========================================================================= #
+  def consider_loading_the_addons_lazily(
+      use_benchmark = Roebe::Shell.use_benchmark_while_loading?,
+      be_verbose    = false
+    )
+    _OLD_VERBOSE_VALUE = $VERBOSE
+    $VERBOSE = nil # Disable for now.
+    case use_benchmark
+    # ======================================================================= #
+    # === :use_benchmark_while_loading
+    # ======================================================================= #
+    when :use_benchmark_while_loading
+      ::Roebe::Shell.do_use_benchmark_while_loading
+      use_benchmark = true
+    end
+
+    total_time_passed = 0 if use_benchmark # Keep track of the time passed.
+    file_lazy_load_these_components =
+      ::Roebe.project_base_directory?+'shell/yaml/lazy_load_these_components.yml'
+
+    if File.exist?(file_lazy_load_these_components)
+      dataset = YAML.load_file(file_lazy_load_these_components)
+      if dataset # Protect against empty .yml files here.
+        dataset.each {|this_project|
+          sleep 0.0001
+          Thread.new {
+            if use_benchmark
+              s = ::Time.now
+            end
+            begin
+              require this_project
+              Roebe::Shell.register_this_component(this_project, :is_available)
+              if use_benchmark
+                n_seconds = ::Time.now - s
+                total_time_passed += n_seconds
+                n_seconds = '%.4f' % n_seconds
+                ljusted_file = yellow(this_project.ljust(32))
+                # ============================================================= #
+                # Next we may display some information to the user as to how
+                # long it took to load a specific component.
+                # ============================================================= #
+                if be_verbose?
+                  e "#{ljusted_file} took #{sfancy(n_seconds)}s to load."
+                end
+              end
+              case this_project
+              when /^case_parser/
+                prepare_the_case_parser_with_the_entries_from_the_menu_file
+              end
+              # =================================================================== #
+              # Register that this component was loaded next:
+              # =================================================================== #
+              unless @internal_hash[:array_these_components_were_lazy_loaded].include? this_project
+                unless this_project.include?('/')
+                  @internal_hash[:array_these_components_were_lazy_loaded] << this_project
+                  if be_verbose
+                    e tomato('DEBUG NOTICE ')+
+                      steelblue(this_project).to_s+
+                      ' has been loaded ...'
+                  end
+                end
+              end
+            rescue LoadError => error
+              Roebe::Shell.register_this_component(this_project, :is_not_available)
+              e 'The file/gem called "'+sfile(this_project)+'" could not be '\
+                'loaded. It probably has not been installed.'
+              pp error
+              if is_on_roebe?
+                e 'Error while trying to load '+tomato(this_project)+'.'
+                Roebe::Shell.register_this_missing_gem(this_project) # in $DIA/base/gems.rb
+              end
+            # =============================================================== #
+            # === Missing gem dependency
+            #
+            # We register which part of a gem is failing. If we are on roebe,
+            # then we will also install this automatically (if found locally). 
+            # =============================================================== #
+            rescue Gem::LoadError => error
+              if is_on_roebe?
+                regex = /Could not find '(.+)'/ # See: https://rubular.com/r/asov7KZFg9
+                error.to_s =~ regex
+                e "The gem (#{sfile(this_project)}) has failed to load, most "\
+                  "likely because it does not exist."
+                e 'But there may be another error as well.'
+                if $1
+                  result = $1.to_s.dup
+                  e 'We will show the specific error at hand, for the faulty '\
+                    'program called '+result+', next:'
+                  e orange(error.inspect)
+                  pp error.class
+                  Roebe::Shell.register_this_missing_gem(result)
+                end
+              end
+            end
+          }
+        }
+        # =================================================================== #
+        # Report the total time passed.
+        # =================================================================== #
+        if use_benchmark
+          e 'In total it took us '+
+            simp(total_time_passed.round(5).to_s)+
+            ' seconds to load these requires / add ons.'
+        end
+      end
+    end
+    $VERBOSE = _OLD_VERBOSE_VALUE # And re-enable it again.
+  end; alias load_external_requires                    consider_loading_the_addons_lazily # === load_external_requires
+       alias try_to_lazy_load_all_described_components consider_loading_the_addons_lazily # === try_to_lazy_load_all_described_components
+
+  # ========================================================================= #
+  # === return_coloured_pwd
+  # ========================================================================= #
+  def return_coloured_pwd(
+      use_colours = use_colours?
+    )
+    if use_colours
+      return sdir(return_pwd)
+    else
+      return return_pwd
+    end
+  end
+
+  # ========================================================================= #
+  # === display_prompt
+  #
+  # This method will display the prompt in use.
+  # ========================================================================= #
+  def display_prompt
+    _ = @internal_hash[:use_this_prompt]
+    case _
+    # ======================================================================= #
+    # === :pwd
+    # ======================================================================= #
+    when :pwd,
+         :default
+      _ = return_coloured_pwd
+    when Symbol
+    end
+    print _ # , :no_newline
+  end; alias show_prompt          display_prompt # === show_prompt
+       alias show_pwd             display_prompt # === show_pwd
+       alias report_pwd           display_prompt # === report_pwd
+       alias show_the_main_prompt display_prompt # === show_the_main_prompt
+       alias display_the_prompt   display_prompt # === display_the_prompt
+
+  # ========================================================================= #
+  # === enter_the_main_loop                                        (loop tag)
+  #
+  # This method contains the main logic of this class.
+  # ========================================================================= #
+  def enter_the_main_loop(
+      be_verbose = be_verbose?
+    )
+    # ======================================================================= #
+    # Keep track as to whether we will use readline:
+    # ======================================================================= #
+    use_readline = use_readline?
+    do_startup_related_tasks_via_a_thread unless skip_startup?
+    if be_verbose
+      report_the_current_roebe_version_in_use
+      e "#{rev}You can input instructions now." # if skip_startup?
+      # e "#{rev}Startup processes finished. You can input instructions now."
+    end
+    loop {
+      # ===================================================================== #
+      # Next query for the exit-condition, that is how to exit from the
+      # REPL again.
+      # ===================================================================== #
+      break if may_we_exit_from_the_user_input_loop?
+      display_the_prompt
+      try_to_build_up_the_readline_completion_proc if use_readline
+      obtain_user_input(use_readline)
+      # ===================================================================== #
+      # The user input may include ';' tokens. If this is the case then
+      # the user input will be split into whatever is separated by ';'.
+      # Thus, we need the following iteration to work on an Array of
+      # assumed user-input next.
+      # ===================================================================== #
+      user_input?.each {|use_this_as_user_input|
+        # =================================================================== #
+        # We must also store the user input in the input-history, which
+        # comes next.
+        # =================================================================== #
+        store_the_user_input_in_the_input_history(use_this_as_user_input)
+        clear_the_old_arguments # Always reset them onto a pristine state.
+        use_this_as_user_input = analyse_the_user_input(use_this_as_user_input) # This entry point will assign to the arguments as well.
+        # =================================================================== #
+        # Next, delegate to the menu() interface.
+        # =================================================================== #
+        menu(use_this_as_user_input)
+        register_last_command(use_this_as_user_input)
+      }
+    }
+  end; alias enter_main_loop enter_the_main_loop # === enter_main_loop
+       alias run_main_loop   enter_the_main_loop # === run_main_loop
+
+  # ========================================================================= #
+  # === analyse_the_user_input
+  #
+  # This method in particular has to set the arguments from the
+  # user input.
+  # ========================================================================= #
+  def analyse_the_user_input(
+      _ = user_input?
+    )
+    # ======================================================================= #
+    # Next we must split the arguments up.
+    # ======================================================================= #
+    if _ and _.include? ' '
+      splitted = _.split(' ')
+      set_all_arguments(
+        splitted[1 .. -1]
+      )
+      user_input = splitted.first
+      set_user_input(user_input)
+      # ===================================================================== #
+      # If the arguments include a '# ' then pass them into the
+      # following clause again. Note that 
+      # ===================================================================== #
+      if _.include? '# '
+        set_all_arguments(
+          return_user_input_without_trailing_comments
+        )
+      end
+      return user_input # We need to return this here, so it can be used in the second loop.
+    end
+    return _
+  end; alias process_user_input analyse_the_user_input # === process_user_input
+
+  # ========================================================================= #
+  # === convert_the_user_input_into_an_array
+  # ========================================================================= #
+  def convert_the_user_input_into_an_array
+    @internal_hash[:user_input] = [
+      @internal_hash[:user_input]
+    ].flatten.map {|entry| entry.lstrip } # .lstrip to sanitize e. g. " cd foobar"
+  end
+
+  # ========================================================================= #
+  # === process_the_user_input
+  # ========================================================================= #
+  def process_the_user_input(
+      i = user_input?
+    )
+    store_the_user_input_in_the_input_history(i)
+    analyse_the_user_input(i)
+  end; alias process_user_input process_the_user_input # === process_user_input
+
+  # ========================================================================= #
+  # === prepare_the_case_parser_with_the_entries_from_the_menu_file
+  # ========================================================================= #
+  def prepare_the_case_parser_with_the_entries_from_the_menu_file
+    # ======================================================================= #
+    # We need to read this up only on startup of the roebe-shell.
+    # ======================================================================= #
+    _ = "#{::Roebe::Shell.project_base_directory?}shell/menu.rb"
+    if File.exist? _
+      if Object.const_defined? :CaseParser
+        Roebe::Shell.append_to_the_array_roebe_shell_case_options(
+          CaseParser.return_array(_)
+        )
+      else
+        # Else do nothing.
+      end
+    else
+      if ::Roebe.is_on_roebe?
+        puts "No file exists at #{_}"
+      end
+      Roebe::Shell.array_roebe_shell_case_options.clear
+    end
+  end
+
+  # ========================================================================= #
+  # === set_user_input_and_decide_on_action
+  #
+  # This conglomerate method wraps over various other methods, such as
+  # set_user_input() or menu(). It will pass the first argument more or
+  # less straight into the menu() method. This allows the user to
+  # give specific commands to the roebe-shell instance. It also allows
+  # for scripted-use or batch-use, in principle.
+  #
+  # The first argument to this method here should naturally be the
+  # (new) user-input that you wish to use.
+  # ========================================================================= #
+  def set_user_input_and_decide_on_action(i)
+    set_original_user_input(i)
+    strip_user_input
+    set_user_input(i)
+    convert_the_user_input_into_an_array
+    user_input?.each {|use_this_as_user_input|
+      # ===================================================================== #
+      # We must also store the user input in the input-history, which
+      # comes next.
+      # ===================================================================== #
+      store_the_user_input_in_the_input_history(use_this_as_user_input)
+      clear_the_old_arguments # Always reset them onto a pristine state.
+      use_this_as_user_input = analyse_the_user_input(use_this_as_user_input) # This entry point will assign to the arguments as well.
+      # ===================================================================== #
+      # Next, delegate to the menu() interface.
+      # ===================================================================== #
+      menu(use_this_as_user_input)
+      register_last_command(use_this_as_user_input)
+    }
+  end; alias suiadoa set_user_input_and_decide_on_action # === suiadoa
+
+end
+
+# =========================================================================== #
+# === Roebe.run_shell
+#
+# This toplevel-method can be used to start a new roebe-shell instance.
+#
+# This method was changed in February 2022, aka renamed from "run"
+# to "run_shell", as it conflicted with "class Roebe::Run". This was
+# announced to be a possibility for a rename-operation back in
+# September 2020, so it should not have come as a surprise.
+# =========================================================================== #
+def self.run_shell(i = ARGV)
+  ::Roebe::Shell.new(i)
+end; self.instance_eval { alias shell       run_shell } # === Roebe.shell
+     self.instance_eval { alias start_shell run_shell } # === Roebe.start_shell
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # alias e puts
+  # e Roebe::Shell::FILE_NOTIFICATIONS
+  # pp Roebe::Shell::ARRAY_ARROW_KEYS
+  Roebe::Shell.new(ARGV)
+end # roebeshell