rcfiles 1.3.54

data/lib/rcfiles/directory_aliases/directory_aliases.rb

@@ -0,0 +1,868 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Rcfiles::DirectoryAliases
+#
+# The purpose of this class is to map between e. g. "pwdj" to "/Depot/j".
+#
+# On my home system "pwdj" is an alias to cd into the directory "/Depot/j/",
+# if said directory exists.
+#
+# Thus the class will expand my cd-aliases, which are usually stored
+# in the file "cd_aliases.yml". These are also part of the Rcfiles
+# project, for convenience reasons mostly.
+#
+# The benefit of being able to expand from my local aliases is that we
+# can provide these aliases to other ruby projects easily. In fact, this
+# has been a primary reason for creating this class in the first place -
+# it was to make all cd_aliases available within the Roebe::Shell project,
+# specifically. Since the latter can be used on windows, I can then use
+# vanilla "cmd.exe" and have my shell work with support for all my
+# custom cd ("change directory") operations. So I can type "tosongs",
+# and hit the enter-key, and it will change directory to the directory
+# where I keep all my songs. How convenient! \o/
+#
+# Usage example for this class:
+#
+#   Rcfiles::DirectoryAliases.new(ARGV)
+#   Rcfiles::DirectoryAliases.is_included?('pwdsongs') # => true
+#
+# =========================================================================== #
+# require 'rcfiles/directory_aliases/directory_aliases.rb'
+# Rcfiles::DirectoryAliases.is_included?('ABC')
+# =========================================================================== #
+module Rcfiles
+
+class DirectoryAliases # === Rcfiles::DirectoryAliases
+
+  alias e puts
+
+  require 'rcfiles/constants/constants.rb'
+  require 'rcfiles/colours/colours.rb'
+  require 'rcfiles/version/version.rb'
+
+  begin
+    require 'opn'
+  rescue LoadError; end
+
+  begin
+    require 'convert_global_env'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases::NAME_OF_FILE
+  # ========================================================================= #
+  NAME_OF_FILE = 'directory_aliases.rb'
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases::SHALL_WE_SHOW_EXCEPTIONS
+  # ========================================================================= #
+  SHALL_WE_SHOW_EXCEPTIONS = false
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases::DEFAULT_RUN_MODE
+  # ========================================================================= #
+  DEFAULT_RUN_MODE = true # or false
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument is typically the key that is sought. It is optional,
+  # though, as the method .find() or .points_at?() can be used with an
+  # argument at any moment in time. That way a cd-alias can be used to
+  # query the dataset.
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV,
+      run_already           = DEFAULT_RUN_MODE
+    )
+    reset
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    # ======================================================================= #
+    # === Handle blocks given to this class next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :run
+      # ===================================================================== #
+      when :run
+        run_already = true
+      end
+    end
+    case run_already
+    # ======================================================================= #
+    # === :be_silent
+    # ======================================================================= #
+    when :be_silent
+      be_silent
+      run_already = DEFAULT_RUN_MODE
+    # ======================================================================= #
+    # === :do_not_report_errors
+    # ======================================================================= #
+    when :do_not_report_errors
+      set_report_errors(false)
+      run_already = DEFAULT_RUN_MODE
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :be_verbose
+    # ======================================================================= #
+    @internal_hash[:be_verbose] = true
+    # ======================================================================= #
+    # === :report_errors
+    #
+    # The next variable determines whether we will report errors or
+    # whether we will not. By default this class will report errors.
+    #
+    # An example error may be Encoding::InvalidByteSequenceError being
+    # raised due to the .yml file being incorrect. In my own yaml files
+    # this error no longer happens, so the class no longer has to handle
+    # this - but in the event that we may re-enable this feature one
+    # day, for other users, I considered it useful in May 2022 to
+    # still retain the :report_errors flag.
+    #
+    # The old code looked something like this:
+    #
+    #   rescue Encoding::InvalidByteSequenceError => error
+    #     if be_verbose? and show_exceptions? and report_errors?
+    #       opnn; e "#{NAME_OF_FILE}: An exception/error happened for → #{simp(key.to_s)}"
+    #       opnn; e 'We will now feedback this error:'
+    #       pp error
+    #     end
+    #   end
+    #
+    # ======================================================================= #
+    @internal_hash[:report_errors] = true
+    be_quiet # Do not be too noisy by default.
+    load_the_dataset_from_the_file_cd_aliases
+  end
+
+  # ========================================================================= #
+  # === be_verbose
+  # ========================================================================= #
+  def be_verbose
+    @internal_hash[:be_verbose] = true
+  end
+
+  # ========================================================================= #
+  # === be_silent
+  # ========================================================================= #
+  def be_silent
+    @internal_hash[:be_verbose] = false
+  end; alias be_quiet be_silent # === be_quiet
+
+  # ========================================================================= #
+  # === be_verbose?
+  # ========================================================================= #
+  def be_verbose?
+    @internal_hash[:be_verbose]
+  end
+
+  # ========================================================================= #
+  # === dataset?
+  #
+  # This is the query-method to access the main dataset of this class,
+  # which is a Hash.
+  # ========================================================================= #
+  def dataset?
+    @internal_hash[:dataset]
+  end; alias hash?       dataset? # === hash?
+       alias hash        dataset? # === hash
+       alias cd_aliases? dataset? # === cd_aliases?
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = '')
+    i = [i].flatten.compact
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first?          first_argument? # === first?
+       alias seek_this_key?  first_argument? # === seek_this_key?
+       alias seek_which_key? first_argument? # === seek_which_key?
+
+  # ========================================================================= #
+  # === report_version
+  # ========================================================================= #
+  def report_version
+    e "The version is: #{sfancy(version?)}"
+  end
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn
+    if Object.const_defined? :Opn
+      Opn.opn(namespace: NAMESPACE)
+    end
+  end; alias opn opnn # === opn
+
+  # ========================================================================= #
+  # === report_errors?
+  # ========================================================================= #
+  def report_errors?
+    @internal_hash[:report_errors]
+  end
+
+  # ========================================================================= #
+  # === set_report_errors
+  # ========================================================================= #
+  def set_report_errors(i)
+    @internal_hash[:report_errors] = i
+  end
+
+  # ========================================================================= #
+  # === translate_key_into_value
+  #
+  # This method will NOT do any additional sanitizing. It will simply
+  # query the main hash, as-is, and return the result.
+  # ========================================================================= #
+  def translate_key_into_value(key)
+    @internal_hash[:dataset][key]
+  end; alias translate_this translate_key_into_value # === translate_this
+
+  # ========================================================================= #
+  # === rds
+  # ========================================================================= #
+  def rds(i)
+    i.squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === version?
+  #
+  # This is mostly a convenience method, to quickly query the current
+  # version of the rcfiles gem in use.
+  # ========================================================================= #
+  def version?
+    ::Rcfiles::VERSION
+  end
+
+  # ========================================================================= #
+  # === keys?
+  # ========================================================================= #
+  def keys?
+    dataset?.keys
+  end; alias keys keys? # === keys
+
+  # ========================================================================= #
+  # === size?
+  #
+  # Query how many keys we have registered.
+  # ========================================================================= #
+  def size?
+    keys?.size
+  end; alias size size? # === size
+       alias keys size? # === keys
+
+  # ========================================================================= #
+  # === is_this_key_included?
+  #
+  # This method can be used to query whether our expanded directory-aliases
+  # contains the given key (first input argument to this method) or
+  # whether it does not. 
+  # ========================================================================= #
+  def is_this_key_included?(
+      key = first_argument?
+    )
+    key = key.to_s unless key.is_a?(String)
+    dataset?.has_key?(key)
+  end; alias included?                 is_this_key_included? # === included?
+       alias is_included?              is_this_key_included? # === is_included?
+       alias is_this_input_a_cd_alias? is_this_key_included? # === is_this_input_a_cd_alias?
+       alias is_this_key_registered?   is_this_key_included? # === is_this_key_registered?
+       alias is_this_alias_included?   is_this_key_included? # === is_this_alias_included?
+       alias has_key?                  is_this_key_included? # === has_key?
+       alias has_this_alias?           is_this_key_included? # === has_key?
+
+  # ========================================================================= #
+  # === file?
+  #
+  # Delegate to the main yaml file in use.
+  # ========================================================================= #
+  def file?
+    ::Rcfiles::DirectoryAliases.yaml_file?
+  end
+
+  # ========================================================================= #
+  # === test
+  # ========================================================================= #
+  def test(
+      i = seek_this_key?
+    )
+    verbose_points_to?(i)
+  end
+
+  # ========================================================================= #
+  # === show_exceptions?
+  # ========================================================================= #
+  def show_exceptions?
+    SHALL_WE_SHOW_EXCEPTIONS
+  end
+
+  # ========================================================================= #
+  # === do_sanitize_the_loaded_dataset                         (sanitize tag)
+  #
+  # This method will sanitize the dataset at hand.
+  #
+  # All changes will be copied back onto the main hash, as-is - thus
+  # we lose the original data.
+  # ========================================================================= #
+  def do_sanitize_the_loaded_dataset(
+      hash               = hash?,
+      # ===================================================================== #
+      # Use a yaml-file containing the correct variables next:
+      # ===================================================================== #
+      use_this_yaml_file = ::Rcfiles.project_base_directory?+
+        'yaml/global_variables/'\
+        'global_variables_extracted_from_the_file_cd_aliases.yml'
+    )
+    dataset_from_the_global_variables = YAML.load_file(
+      use_this_yaml_file
+    )
+    _ = {}
+    hash.each {|key, value|
+      # ===================================================================== #
+      # Next, work on all value-entries that include a '$' character. This
+      # will work on Linux, but on Windows this may not work, so we may
+      # have to use another solution for windows specifically. However
+      # had, we actually do not need to use ConvertGlobalEnv here,
+      # as the autogenerated .yml file already contains the sanitized
+      # dataset. The line has been commented out in May 2022.
+      #
+      # Examples for a key and value pair may be the following:
+      #
+      #  'to_valheru' => 'cd $VALHERU'
+      #  'pwdshell'   => 'cd $LINUX/SHELL/
+      #
+      # We need to map it towards e. g.:
+      #
+      #   ROEBE_SRC: '/home/x/programming/ruby/src/roebe/lib/roebe'
+      #   LINUX:     '/home/x/programming/ruby/src/roebe/lib/roebe/www/linux'
+      #   UNI_WIEN:  '/home/x/studium/UNI_WIEN'
+      #
+      # ===================================================================== #
+      if value.include? '$'
+        value = value.dup # Work on a copy past this point.
+        value.gsub!(/cd /,'')  if value.include? 'cd '
+        value.gsub!(/ ll/,'')  if value.include? ' ll'
+        value.gsub!(/ ls/,'')  if value.include? ' ls'
+        value.gsub!(/> \/dev\/null/,'') if value.include? '> /dev/null'
+        value.gsub!(/2>&1/,'') if value.include? '2>&1'
+        # =================================================================== #
+        # The next line has been commented out on 03.05.2022:
+        #
+        #   value = ConvertGlobalEnv.convert(value, report_errors?)
+        #
+        # =================================================================== #
+        shortened_value = value.delete_prefix('cd ').dup # Now it is e. g. '$LINUX/SHELL/'.
+        # =================================================================== #
+        # In the past, until May 2014, we chopped off trailing occurences
+        # of 'pwd', but I decided that this is no longer wanted. Certain
+        # aliases such as "pwdusb4" would misfunction as a result of 
+        # the following .gsub:
+        #
+        #   value.gsub!(/pwd$/,'') if value.include? 'pwd'
+        #
+        # =================================================================== #
+        # =================================================================== #
+        # As of May 2014, we no longer get rid of ; characters.
+        #
+        #   value.gsub!(/;/,'')    if value.include? ';'
+        #
+        # =================================================================== #
+        if value and value.include?('/') # In this case it is more complicated.
+          shortened_value = value.scan(/\$(\w+)\//).flatten.first.to_s # See: https://rubular.com/r/L2rAbtKVnnmBfd
+          value.sub!(/\$#{shortened_value}/, dataset_from_the_global_variables[shortened_value].to_s)
+        else # else no modification is necessary. 
+          replace_via = dataset_from_the_global_variables[shortened_value.delete('$')].to_s
+          value.gsub!(/#{Regexp.quote(value)}/, replace_via)
+        end
+      end
+      if hash.has_key?(value)
+        value = hash[value]
+      end
+      value = rds(value) if value.include? '//'
+      _[key] = value.strip # We don't need trailing empty characters.
+    }
+    @internal_hash[:dataset] = _
+  end; alias sanitize_hash       do_sanitize_the_loaded_dataset # === sanitize_hash
+       alias sanitize_the_hash   do_sanitize_the_loaded_dataset # === sanitize_the_hash
+       alias sanitize_cd_aliases do_sanitize_the_loaded_dataset # === sanitize_cd_aliases
+
+  # ========================================================================= #
+  # === report_to_user
+  #
+  # This is a "poor man's" debug variant.
+  # ========================================================================= #
+  def report_to_user
+    pp hash?
+  end
+
+  # ========================================================================= #
+  # === load_the_dataset_from_the_file_cd_aliases
+  #
+  # An alternative argument to this method would be
+  # ::Rcfiles.file_cd_aliases?. 
+  # ========================================================================= #
+  def load_the_dataset_from_the_file_cd_aliases(
+      file_cd_aliases = 
+        ::Rcfiles::DirectoryAliases.yaml_file?
+    )
+    if File.exist? file_cd_aliases
+      @internal_hash[:dataset] = 
+        YAML.load_file(file_cd_aliases)
+    end
+  end
+
+  # ========================================================================= #
+  # === replacement_or_original_input?
+  # ========================================================================= #
+  def replacement_or_original_input?(
+      _ = first_argument?
+    )
+    if is_this_key_included?(_)
+      translate_key_into_value(_)
+    else
+      return _
+    end
+  end; alias corresponds_to               replacement_or_original_input? # === corresponds_to
+       alias corresponds_to?              replacement_or_original_input? # === corresponds_to?
+       alias find_this_cd_alias           replacement_or_original_input? # === find_this_cd_alias
+       alias find_this_sanitized_cd_alias replacement_or_original_input? # === find_this_sanitized_cd_alias
+       alias find                         replacement_or_original_input? # === find
+       alias points_at                    replacement_or_original_input? # === points_at
+       alias points_at?                   replacement_or_original_input? # === points_at?
+       alias result?                      replacement_or_original_input? # === result?
+       alias convert                      replacement_or_original_input? # === convert
+       alias _                            replacement_or_original_input? # === _
+
+  # ========================================================================= #
+  # === n_entries?
+  # ========================================================================= #
+  def n_entries?
+    dataset?.size
+  end
+
+  # ========================================================================= #
+  # === verbose_points_to?
+  # ========================================================================= #
+  def verbose_points_to?(i = seek_which_key?)
+    i = i.to_s
+    if is_included? i
+      opnn; e "#{::Rcfiles.rev}Yes, the key `#{::Rcfiles.sfancy(i)}` is included."
+      opnn; e "#{::Rcfiles.rev}It points to the directory: #{::Rcfiles.sdir(hash?[i])}"
+    else
+      opnn; e "#{::Rcfiles.rev}No, the key `#{::Rcfiles.sfancy(i)}` is not "\
+              "included in the cd-aliases."
+    end
+  end
+
+  # ========================================================================= #
+  # === cd_into
+  # ========================================================================= #
+  def cd_into(i)
+    Dir.chdir(translate_key_into_value(i))
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    # ======================================================================= #
+    # We will do several clean-ups. This is extremely hackish, but also
+    # very simple and it kind of works. We got rid of all the $ values.
+    # How often to call it? Well, it seems 4x is more than enough; 
+    # perhaps we can reduce it even more, but for now this is the way
+    # it is.
+    # ======================================================================= #
+    do_sanitize_the_loaded_dataset
+    do_sanitize_the_loaded_dataset
+    do_sanitize_the_loaded_dataset
+    do_sanitize_the_loaded_dataset
+    # do_sanitize_the_loaded_dataset
+  end
+  require 'rcfiles/files/file_cd_aliases.rb'
+
+  # ========================================================================= #
+  # === @yaml_file_used_by_class_directory_aliases
+  #
+  # This variable will keep track of the main yaml file, that is, the
+  # file that holds the dataset for "cd-aliases".
+  #
+  # It is nil initially here, but will be changed lateron through a method
+  # call.
+  # ========================================================================= #
+  @yaml_file_used_by_class_directory_aliases = nil
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.set_yaml_file_used_by_class_directory_aliases
+  #
+  # The user can modify which yaml file is to be used, via this method call.
+  # ========================================================================= #
+  def self.set_yaml_file_used_by_class_directory_aliases(
+      i = :default
+    )
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         :default_yaml_file
+      i = ::Rcfiles.file_cd_aliases
+    end
+    @yaml_file_used_by_class_directory_aliases = i
+  end
+
+  # ========================================================================= #
+  # Define the main cd-aliases file next. The constant FILE_CD_ALIASES
+  # must be defined for this to work.
+  # ========================================================================= #
+  DirectoryAliases.set_yaml_file_used_by_class_directory_aliases(:default_yaml_file)
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.yaml_file?
+  #
+  # On my home system this defaults to:
+  #
+  #   /usr/lib/ruby/site_ruby/3.1.0/rcfiles/yaml/cd_aliases.yml
+  #
+  # ========================================================================= #
+  def self.yaml_file?
+    @yaml_file_used_by_class_directory_aliases
+  end
+
+  # ========================================================================= #
+  # === []
+  # ========================================================================= #
+  def [](i)
+    replacement_or_original_input?(i)
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.is_included?
+  #
+  # Note that this instantiates a new DirectoryAliases object, so it
+  # is more expensive than instantiating on your own and then simply
+  # using .is_included? on that object. The reason why this method
+  # still exists, then, is mostly because it is convenient to NOT
+  # have to instantiate something specifically, as that normally
+  # takes two lines of code.
+  # ========================================================================= #
+  def self.is_included?(i)
+    _ = new(i)
+    return _.is_included?(i)
+  end; self.instance_eval { alias does_include?             is_included? } # === Rcfiles::DirectoryAliases.does_include?
+       self.instance_eval { alias is_this_alias_included?   is_included? } # === Rcfiles::DirectoryAliases.is_this_alias_included?
+       self.instance_eval { alias is_this_input_a_cd_alias? is_included? } # === Rcfiles::DirectoryAliases.is_this_input_a_cd_alias?
+       # Rcfiles::DirectoryAliases.include? # ← This here would conflict, hence we can not use it.
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.e
+  # ========================================================================= #
+  def self.e(i = '')
+    ::Rcfiles.e(i)
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases[]
+  #
+  # This must return a String - either the original input, or the
+  # replacement.
+  #
+  # Usage example:
+  #
+  #  Rcfiles::DirectoryAliases['pwdj'] # => '/Depot/j/'
+  #
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i).replacement_or_original_input?
+  end
+
+  require 'yaml'
+  require 'rcfiles/toplevel_methods/e.rb'
+  require 'rcfiles/toplevel_methods/no_file_exists_at.rb'
+  require 'rcfiles/toplevel_methods/save_file.rb'
+
+  # ========================================================================= #
+  # === @toplevel_stored_dataset
+  #
+  # This variable will hold the whole cd-aliases dataset. It should be
+  # kept as a Hash at all times. It also should be empty, initially.
+  #
+  # In the event that it is filled with content it will be copied
+  # onto any new instance of DirectoryAliases. That way we can
+  # use a substitute hash, or allow the user to fill it up on
+  # his or her own.
+  #
+  # Note that before May 2022 this was called @cd_aliases, but
+  # I think the new name is more logical.
+  # ========================================================================= #
+  @toplevel_stored_dataset = {}
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.toplevel_stored_dataset?
+  #
+  # Main getter over the cd-aliases. This will be our main datastructure.
+  # ========================================================================= #
+  def self.toplevel_stored_dataset?
+    @toplevel_stored_dataset
+  end; self.instance_eval { alias cd_aliases?       toplevel_stored_dataset? } # === Rcfiles::DirectoryAliases.cd_aliases?
+       self.instance_eval { alias toplevel_dataset? toplevel_stored_dataset? } # === Rcfiles::DirectoryAliases.toplevel_dataset?
+       self.instance_eval { alias hash?             toplevel_stored_dataset? } # === Rcfiles::DirectoryAliases.hash?
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.points_at?
+  # ========================================================================= #
+  def self.points_at?(i)
+    _ = new(i)
+    return _.points_at?
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.n_entries?
+  #
+  # How many entries can be found in class DirectoryAliases is answered
+  # by this toplevel method.
+  # ========================================================================= #
+  def self.n_entries?
+    toplevel_stored_dataset?.keys.size
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.set_toplevel_stored_dataset (set_cd_aliases tag)
+  #
+  # The @toplevel_stored_dataset should always be a Hash. This is an
+  # explicit setter here, though, so the user could always assign a
+  # non-Hash. No error will be raised in this case.
+  # ========================================================================= #
+  def self.set_toplevel_stored_dataset(i = {})
+    @toplevel_stored_dataset = i
+  end; self.instance_eval { alias set_cd_aliases  set_toplevel_stored_dataset } # === Rcfiles::DirectoryAliases.set_cd_aliases=
+       self.instance_eval { alias set_cd_aliases= set_toplevel_stored_dataset } # === Rcfiles::DirectoryAliases.set_cd_aliases=
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.clear
+  #
+  # Reset the main Hash again.
+  # ========================================================================= #
+  def self.clear
+    @toplevel_stored_dataset.clear
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.load_dataset_from_main_file
+  #
+  # Load up the dataset next
+  #
+  # This determines the main cd-aliases file.
+  # ========================================================================= #
+  def self.load_dataset_from_main_file(
+      i = yaml_file?
+    )
+    if File.exist? i
+      dataset = YAML.load_file(i) # This may be UTF-8 encoding.
+      # ===================================================================== #
+      # Assign the cd-aliases via a toplevel method next:
+      # ===================================================================== #
+      set_toplevel_stored_dataset(dataset)
+    else # Else use an empty dataset instead.
+      if is_on_roebe?
+        ::Rcfiles.no_file_exists_at(i)
+      end
+      set_toplevel_stored_dataset({})
+    end
+  end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.initialize_main_hash
+  # ========================================================================= #
+  def self.initialize_main_hash
+    clear # First empty the old dataset, should it be non-empty.
+    if toplevel_dataset?.empty?
+      load_dataset_from_main_file
+    end
+  end; self.instance_eval { alias initialize_main_dataset initialize_main_hash } # === Rcfiles::DirectoryAliases.initialize_main_dataset
+       self.instance_eval { alias run                     initialize_main_hash } # === Rcfiles::DirectoryAliases.run
+    # ======================================================================= #
+    # Initialize the main dataset if it has not been loaded up yet.
+    # ======================================================================= #
+    if ::Rcfiles::DirectoryAliases.cd_aliases?.empty?
+      ::Rcfiles::DirectoryAliases.load_dataset_from_main_file
+    end
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.register_sigint
+  # ========================================================================= #
+  def self.register_sigint
+    Signal.trap('SIGINT') { exit }
+  end
+
+  register_sigint # ← And call it at once.
+
+  # ========================================================================= #
+  # === Rcfiles::DirectoryAliases.save_into_ruby_file
+  #
+  # This method will store the hash in a CONSTANT, into a file (normally
+  # a .rb file).
+  #
+  # The first argument to this method denotes where to store this file,
+  # so you have the possibility to save into some special location
+  # instead.
+  #
+  # The name of the hash is provided via the the second argument to
+  # this method.
+  # ========================================================================= #
+  def self.save_into_ruby_file(
+      store_into_this_file  = '/Depot/j/expand_cd_aliases_hash.rb',
+      name_of_the_main_hash = 'EXPAND_CD_ALIASES_HASH'
+    )
+    _ = ::Rcfiles::DirectoryAliases.new
+    dataset = _.cd_aliases?
+    # ======================================================================= #
+    # First add the header:
+    # ======================================================================= #
+    what = '#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+'.dup
+    what << "#{name_of_the_main_hash} = {\n"
+    what = ::Rcfiles.ensure_main_encoding(what)
+    dataset.each_pair {|key, value|
+      key = key.to_s unless key.is_a? String
+      value = ConvertGlobalEnv.convert(value)
+      key = ::Rcfiles.ensure_main_encoding(key)
+      value = ::Rcfiles.ensure_main_encoding(value)
+      what << "  \"#{key}\": \"#{value}\",\n"
+    }
+    what << "}\n"
+    into = store_into_this_file
+    if block_given?
+      yielded = yield
+      case yielded
+      when :be_verbose
+        puts 'Storing into the file `'+into+'`.'
+      end
+    end
+    ::Rcfiles.write_what_into(what, into)
+  end; self.instance_eval { alias generate_cd_aliases save_into_ruby_file } # === Rcfiles::DirectoryAliases.generate_cd_aliases
+
+end
+
+# ========================================================================= #
+# === Rcfiles.is_this_alias_included?
+#
+# This method can be used to determine whether a given key is included
+# or not.
+#
+# Usage example:
+#
+#   Rcfiles.is_this_alias_included? 'pwdsongs'
+#   Rcfiles.is_this_alias_included? 'todoc'
+#
+# ========================================================================= #
+def self.is_this_alias_included?(i)
+  ::Rcfiles::DirectoryAliases.is_this_alias_included?(i)
+end; self.instance_eval { alias is_this_input_a_cd_alias? is_this_alias_included? } # === Rcfiles.is_this_input_a_cd_alias? 
+     self.instance_eval { alias is_this_key_available?    is_this_alias_included? } # === Rcfiles.is_this_key_available?
+     self.instance_eval { alias is_this_key_registered?   is_this_alias_included? } # === Rcfiles.is_this_key_registered?
+
+# =========================================================================== #
+# === Rcfiles.directory_aliases
+#
+# This method will instantiate a new DirectoryAliases object.
+# =========================================================================== #
+def self.directory_aliases(i)
+  ::Rcfiles::DirectoryAliases.new(i)
+end; self.instance_eval { alias cd_alias          directory_aliases } # === Rcfiles.cd_alias
+     self.instance_eval { alias expand_cd_aliases directory_aliases } # === Rcfiles.expand_cd_aliases
+
+# =========================================================================== #
+# === Rcfiles.find_this_cd_alias
+#
+# Usage example for this method:
+#
+#   Rcfiles.find_this_cd_alias('pwdj') # => "cd /Depot/j"
+#   Rcfiles.find_this_cd_alias('todoc') # => "/documentation/"
+#
+# =========================================================================== #
+def self.find_this_cd_alias(i)
+  ::Rcfiles::DirectoryAliases[i]
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME # Testing class Rcfiles::DirectoryAliases here.
+  alias e puts
+  require 'colours'
+  directory_aliases = Rcfiles::DirectoryAliases.new(ARGV)
+  print ::Colours.rev
+  e '='*80
+  e 'The version of the rcfiles gem in use is: '+directory_aliases.version?.to_s
+  e directory_aliases.n_entries?.to_s+
+    ' keys are registered as being cd-aliases.'
+  e 'Is the key `tova` included:  '+directory_aliases.is_this_key_included?('tova').to_s
+  e 'It corresponds to: '+directory_aliases.corresponds_to('tova')
+  e 'Is the key `tovaa` included: '+directory_aliases.is_this_key_included?('tovaa').to_s
+  e 'Is the key `pwdsongs` included:  '+directory_aliases.is_this_key_included?('pwdsongs').to_s
+  e 'It corresponds to: '+directory_aliases.corresponds_to('pwdsongs')
+  # e 'The expanded value is: '+
+  #   directory_aliases.expanded_key?('pwdsongs')
+  e 'Is the key `tosongs` included:  '+directory_aliases.is_this_key_included?('tosongs').to_s
+  e 'It corresponds to: '+directory_aliases.corresponds_to('tosongs')
+  # e 'The expanded value is: '+
+  #  directory_aliases.expanded_key?('tosongs')
+  e 'Next testing Rcfiles.is_this_alias_included?(): is
+  "pwdsongs" included? '+
+  Rcfiles.is_this_alias_included?('pwdsongs').to_s
+  e 'Next testing  Rcfiles.find_this_cd_alias() - pwdj equals '\
+    ' '+Rcfiles.find_this_cd_alias('pwdj') # => "cd /Depot/j" # => "cd /Depot/j"
+  e '='*80
+  directory_aliases.test('toxx')
+  e '='*80
+  directory_aliases._.class
+  Rcfiles::DirectoryAliases.initialize_main_hash
+  pp Rcfiles::DirectoryAliases.n_entries?
+  # Rcfiles::DirectoryAliases.save_into_ruby_file
+end # directoryaliases
+    # ecdaliases
+    # exda pwwdusr; exda pwddwwd
+    # exda pwdusb4