ftp_paradise 1.4.5 → 1.5.4

data/lib/ftp_paradise/connection/connection.rb

@@ -2,34 +2,2801 @@
 # Encoding: UTF-8
 # frozen_string_literal: true
 # =========================================================================== #
+# === FtpParadise::Connection
+#
 # This is the "connection class". It will have methods that can be use
-# when we are connected to a remote site (via the FTP protocol).
+# when the user is connected to a remote site (via the FTP protocol).
 #
 # Rather than keeping FTP-related state within this class, such as remote
-# URL and such, we will instead use FtpParadise module methods.
+# URL and such, we will instead use FtpParadise toplevel-module methods.
+# Or, at the least, we will tap into that dataset if it has been
+# assigned by the user.
+#
+# Usage example:
+#
+#   FtpParadise::Connection.new(ARGV)
+#
 # =========================================================================== #
 # Possible errors and failures when we are trying to connect:
 #
 #   Net::FTPPermError: 530 Please login with USER and PASS.
 #
-#   Net::FTPConnectionError is raised if we are no longer connected to
-#   the remote FTP site.
+#   Net::FTPConnectionError is raised if we are no longer connected
+#   to the remote FTP site.
 #
 #   Errno::ETIMEDOUT is raised when a timeout event occurred.
+#
 # =========================================================================== #
 # The official documentation for Ruby-FTP can be found here:
 #
 #   https://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html
 #
 # =========================================================================== #
-require 'ftp_paradise/connection/initialize.rb'
-require 'ftp_paradise/connection/data.rb'
-require 'ftp_paradise/connection/debug.rb'
-require 'ftp_paradise/connection/misc.rb'
-require 'ftp_paradise/connection/notify.rb'
-require 'ftp_paradise/connection/remote_pwd.rb'
-require 'ftp_paradise/connection/remove.rb'
-require 'ftp_paradise/connection/show.rb'
-require 'ftp_paradise/connection/upload.rb'
-require 'ftp_paradise/version/version.rb'
-require 'ftp_paradise/configuration/configuration.rb'
+# require 'ftp_paradise/connection/connection.rb'
+# =========================================================================== #
+module FtpParadise
+
+class Connection # === FtpParadise::Connection
+
+  require 'ftp_paradise/base/base.rb'
+  include ::FtpParadise::Base
+
+  require 'ftp_paradise/requires/require_net_ftp.rb'
+  require 'ftp_paradise/requires/require_the_toplevel_methods.rb'
+  require 'ftp_paradise/entry/entry.rb'
+  require 'ftp_paradise/configuration/configuration.rb'
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === BE_VERBOSE
+  # ========================================================================= #
+  BE_VERBOSE = true
+
+  # ========================================================================= #
+  # === DEFAULT_TRANSFER_MODE
+  # ========================================================================= #
+  DEFAULT_TRANSFER_MODE = :ascii # Which transfer mode to use by default.
+
+  # ========================================================================= #
+  # === DEFAULT_PORT
+  # ========================================================================= #
+  DEFAULT_PORT = 21
+
+  # ========================================================================= #
+  # === DEFAULT_USER_NAME
+  #
+  # In the past this was set to a String (the user name); but since as
+  # of October 2018, it will default to nil, so that we really initialize
+  # the whole project to a nil-state (as the default). This thus allows
+  # us to determine whether this has been changed, aka initialized.
+  # ========================================================================= # 
+  DEFAULT_USER_NAME = nil
+
+  # ========================================================================= #
+  # === RUN_ALREADY
+  # ========================================================================= #
+  RUN_ALREADY = true
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument to this method should be the remote host's URL.
+  # ========================================================================= #
+  def initialize(
+      i           = ARGV,
+      run_already = RUN_ALREADY
+    )
+    reset
+    # ======================================================================= #
+    # - If we pass in a Hash as the first argument, then we will use
+    #   set_data(), otherwise we will set individually it all individually.
+    # ======================================================================= #
+    if i.is_a? Hash
+      set_data(i)
+    else
+      set_input(i)
+    end
+    case i
+    # ======================================================================= #
+    # === :dont_run_yet
+    # ======================================================================= #
+    when :dont_run_yet,
+         :do_not_run_yet
+      run_already = false
+    end
+    case run_already
+    # ======================================================================= #
+    # === :dont_run_yet
+    # ======================================================================= #
+    when :dont_run_yet
+      run_already = false
+    end
+    if run_already.is_a? Hash
+      _ = run_already
+      if _.has_key? :connect_to_this_host
+        set_this_host(
+          _.delete(:connect_to_this_host)
+        )
+      end
+      run_already = RUN_ALREADY # Restore to the default in this case.
+    end
+    # ======================================================================= #
+    # === Handle blocks given to this method next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :do_not_run_yet
+      # ===================================================================== #
+      when :do_not_run_yet
+        run_already = false
+      # ===================================================================== #
+      # The "default" dataset defaults to my personal FTP login dataset.
+      # ===================================================================== #
+      when :use_default_dataset,
+           :default_dataset,
+           :default
+        use_default_dataset
+      end
+    end
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @namespace
+    # ======================================================================= #
+    @namespace = NAMESPACE
+    # ======================================================================= #
+    # === @ftp_object
+    # ======================================================================= #
+    @ftp_object = nil
+    # ======================================================================= #
+    # === @input
+    # ======================================================================= #
+    @input = nil
+    populate_internal_hash_with_default_values
+    # ======================================================================= #
+    # The next method-call must come after
+    # populate_internal_hash_with_default_values().
+    # ======================================================================= #
+    set_be_verbose if BE_VERBOSE
+    set_port
+    set_array_available_hosts
+    set_default_transfer_mode :be_quiet
+    set_username
+  end
+
+  # ========================================================================= #
+  # === binary=
+  # ========================================================================= #
+  def binary=(i = true)
+    @internal_hash[:transfer_mode] = :binary
+    ftp_object?.binary = i
+  end
+
+  # ========================================================================= #
+  # === binary_mode?
+  # ========================================================================= #
+  def binary_mode?
+    @internal_hash[:transfer_mode] == :binary
+  end
+
+  # ========================================================================= #
+  # === passive=
+  # ========================================================================= #
+  def passive=(i = true)
+    if ftp_object?
+      ftp_object?.passive = i
+    else
+      e 'In .passive=: No ftp-object has been instantiated yet.'
+    end
+  end; alias set_passive passive= # === set_passive
+
+  # ========================================================================= #
+  # === try_to_download_this_remote_file
+  # ========================================================================= #
+  def try_to_download_this_remote_file(
+      i, be_verbose = false, &block
+    )
+    if block_given?
+      yielded = yield
+      case yielded
+      when :be_verbose
+        be_verbose = true
+      end
+    end
+    e 'Trying to download `'+steelblue(i)+'` next.' if be_verbose
+    @ftp_object.getbinaryfile(i)
+    if be_verbose
+      e 'Download of '+steelblue(i)+' has finished! It is '\
+        'now at '+sfile(return_pwd+i)
+    end
+  end; alias getbinaryfile        try_to_download_this_remote_file # === getbinaryfile
+       alias download_binary_file try_to_download_this_remote_file # === download_binary_file
+
+  # ========================================================================= #
+  # === list                                                        (raw tag)
+  #
+  # This method must yield the result of .list(), as Array.
+  # ========================================================================= #
+  def list(i = '*')
+    ftp_object?.list(i)
+  end; alias raw_list list # === raw_list
+
+  # ========================================================================= #
+  # === nlst?
+  #
+  # This method will return an array of filenames in the remote
+  # directory. This will yield less information than the "ls -l"
+  # variant, aka list().
+  #
+  # Documentation:
+  #
+  #   https://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-nlst
+  #
+  # ========================================================================= #
+  def nlst?
+    ftp_object?.nlst
+  end; alias nlst nlst? # === nlst
+
+  # ========================================================================= #
+  # === sendcmd
+  #
+  # Sends a command and returns the response of the server.
+  #
+  # This has to be rescued, because there are lots of different errors
+  # possible.
+  # ========================================================================= #
+  def sendcmd(i)
+    begin
+      ftp_object?.sendcmd(i)
+    rescue Exception => error
+      pp error
+      e '(This error may be due to the remote file not existing.)'
+    end
+  end
+
+  # ========================================================================= #
+  # === remove_file
+  #
+  # This method will delete a remote file.
+  #
+  # The API should remain fairly flexible.
+  #
+  # Example:
+  #
+  #   ftp_connection?.remove_file(i.text?) { :be_verbose }
+  #
+  # ========================================================================= #
+  def remove_file(
+      i, be_verbose = false, &block
+    )
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_verbose
+      # ===================================================================== #
+      when :be_verbose
+        be_verbose = true
+      end
+    end
+    e 'Deleting the remote file at '+steelblue(i)+' next:' if be_verbose
+    ftp_connection?.delete(i)
+    e 'Deleting the remote file at '+steelblue(i)+' has been completed.' if be_verbose
+  end; alias delete_file remove_file # === delete_file
+       alias delete      remove_file # === delete
+
+  # ========================================================================= #
+  # === option
+  #
+  # This method will issue an OPTS command. The first argument should
+  # be the name of the option that is to be set. Additional arguments
+  # are treated as parameter to that command.
+  #
+  # Example:
+  #
+  #   option('UTF8', 'ON') => 'OPTS UTF8 ON'
+  #
+  # ========================================================================= #
+  def option(i, optional_argument = nil)
+    ftp_connection?.option(i, optional_argument)
+  end
+
+  # ========================================================================= #
+  # === set_remote_url
+  #
+  # This method will do some sanitizing before it sets a proper and
+  # valid hostname. Remember to keep the 'default' entry at the
+  # current main FTP host you use.
+  # ========================================================================= #
+  def set_remote_url(
+      i          = :default,
+      be_verbose = true
+    )
+    i = :default? if i.nil?
+    if i.is_a? Hash # Handle Hash as input here.
+      if i.has_key?(:to)
+        i = i[:to]
+      end
+    end
+    # ======================================================================= #
+    # The next block is mostly for my custom constants.
+    # You can simply pass in your own Hash.
+    # ======================================================================= #
+    case i # Do some sanitizing. This is a String here. (case tag)
+    # ======================================================================= #
+    # === bplaced (this is equivalent to shevy)
+    # ======================================================================= #
+    when /^-?-?bplaced$/i,
+         /^-?-?shevy$/i,
+         'default'
+      set_data(:bplaced)
+      i = BPLACED.first
+    # ======================================================================= #
+    # === ?
+    # ======================================================================= #
+    when '?'
+      feedback_login_hosts
+    # ======================================================================= #
+    # === uniwien_homepage
+    # ======================================================================= #
+    when /^uniwien_?homepage/
+      set_data(UNIWIEN_HOMEPAGE)
+      i = UNIWIEN_HOMEPAGE.first
+    # ======================================================================= #
+    # === unet
+    # ======================================================================= #
+    when 'unet','uni',
+         'uniftp'
+      set_data(UNIVIE)
+      i = UNIVIE.first   
+    # ======================================================================= #
+    # === a1
+    # ======================================================================= #
+    when /^a1/
+      set_data(A1)
+      i = A1.first
+    # ======================================================================= #
+    # === byte
+    # ======================================================================= #
+    when /^byte/ # This also includese bytehost.
+      set_data(BYTEHOST)
+      i = BYTEHOST.first
+    # ======================================================================= #
+    # === zerofees
+    # ======================================================================= #
+    when 'ZEROFEES','zero','ZERO'
+      set_data(ZEROFEES)
+      i = ZEROFEES.first
+    # ======================================================================= #
+    # === ucoz
+    # ======================================================================= #
+    when 'ucoz','UCOZ',
+         'LAST',
+         /tanriel/i,
+         'last'
+      set_data(UCOZ)
+      i = UCOZ.first
+    end
+    case i.to_s
+    # ======================================================================= #
+    # === shevy
+    # ======================================================================= #
+    when 'shevy','5','default' # Current default entry.
+      i = SQUARE7.first
+    # ======================================================================= #
+    # === a1
+    # ======================================================================= #
+    when '1','a1'
+      i = A1.first
+    # ======================================================================= #
+    # === unet
+    # ======================================================================= #
+    when '2','unet','uni','uniftp'
+      i = UNIVIE.first
+    # ======================================================================= #
+    # === geas
+    # ======================================================================= #
+    when '3',
+         'geas'
+      i = GEAS.first
+    # ======================================================================= #
+    # === byte
+    # ======================================================================= #
+    when '4',
+         'byte'
+      i = BYTEHOST.first
+    end
+    i = i.to_s # Need a String here.
+    # ======================================================================= #
+    # === Provide more information to the user
+    # ======================================================================= #
+    if debug?
+      opnn; e "The remote URL was set to: #{sfancy(i)}"
+    end
+    if be_verbose
+      e "Setting url to #{sfancy(i)} now."
+    end
+    FtpParadise.set_remote_url(i)
+    # ======================================================================= #
+    # And we will always initialize a new ftp-object as well, whenever
+    # we call this method:
+    # ======================================================================= #
+    initialize_a_new_net_ftp_object_with_this_remote_url(i)
+  end; alias set_this_host   set_remote_url # === set_this_host
+       alias set_host        set_remote_url # === set_host
+       alias set_url         set_remote_url # === set_url
+       alias host=           set_remote_url # === host=
+       alias url=            set_remote_url # === url=
+       alias set_remote_host set_remote_url # === set_remote_host
+
+  # ========================================================================= #
+  # === show_host_user_name_port_and_password
+  #
+  # Inform us about the basic settings.
+  # ========================================================================= #
+  def show_host_user_name_port_and_password(
+      do_use_spacer_around_the_output = true
+    )
+    ljust = 15
+    e if do_use_spacer_around_the_output
+    e ('Host: '     ).ljust(ljust)+sfancy(host?)
+    e ('User-Name: ').ljust(ljust)+sfancy(user_name?.to_s)
+    e ('Port: '     ).ljust(ljust)+sfancy(port?)
+    e ('Password: ' ).ljust(ljust)+sfancy(password?)
+    e if do_use_spacer_around_the_output
+  end
+
+  # ========================================================================= #
+  # === use_default_dataset
+  #
+  # This method will just take the default dataset for my FTP connections, 
+  # hence the "File.exist?" check.
+  #
+  # Additionally we will initialize the default net-ftp object.
+  #
+  # Up to 20.07.2022 we also automatically tried to log in, but since
+  # that day we no longer do this.
+  # ========================================================================= #
+  def use_default_dataset(
+      i = :default # ← This is the default.
+    )
+    if File.exist? FILE_ROEBE_FTP
+      dataset = YAML.load_file(FILE_ROEBE_FTP)
+      # ===================================================================== #
+      # Set remote-url, username and password through the following method:
+      # ===================================================================== #
+      FtpParadise.determine_user_dataset_from_this_hash(dataset, i)
+      # do_login
+    end
+  end
+
+  # ========================================================================= #
+  # === show_full_names?
+  # ========================================================================= #
+  def show_full_names?
+    @internal_hash[:show_full_names]
+  end
+
+  # ========================================================================= #
+  # === show_remote_listing
+  #
+  # Use this method whenever you want to show the remote entries.
+  #
+  # As of June 2016, you can pass in your own dataset into this method
+  # as well. It must conform to the Array with the four entries, which
+  # is also returned via the method sanitized_remote_directory_content?.
+  # ========================================================================= #
+  def show_remote_listing(
+      dataset    = sanitized_remote_directory_content?,
+      be_verbose = be_verbose?
+    )
+    n_rjust = 10
+    _ = dataset
+    if show_full_names?
+      _.map! {|entry|
+        filename = entry[0]
+        entry[0] = remote_pwd?+filename # This is the file size.
+        entry
+      }
+    end
+    _.each_with_index { |array, index|
+      if be_verbose # Display only when in verbose mode, which is the default.
+        file_or_directory = array[1]
+        name_of_the_file = array.first
+        # =================================================================== #
+        # Get a pointer to the filesize as well.
+        # =================================================================== #
+        filesize = array[2].to_s.rjust(n_rjust)
+        if file_or_directory == 'directory'
+          name_of_the_file << '/' unless name_of_the_file.end_with? '/'
+        end
+        # =================================================================== #
+        # === Put a proper padding to the index
+        # =================================================================== #
+        new_index = (index+1).to_s.rjust(_.size.to_s.size)
+        n_pad = 125
+        case file_or_directory
+        when 'directory' # Display for directories.
+          name_of_the_file = sdir(name_of_the_file)
+          e (padding?+sdir(new_index+') ')+name_of_the_file).ljust(n_pad)+' '+
+            filesize
+        else
+          e (padding?+sfancy(new_index+') ')+sfancy(name_of_the_file)).ljust(n_pad)+' '+
+            filesize
+        end
+      end
+    }
+  end; alias show_file_listing        show_remote_listing # === show_file_listing
+       alias show_remote_file_listing show_remote_listing # === show_remote_file_listing
+
+  # ========================================================================= #
+  # === show_remote_directories
+  # ========================================================================= #
+  def show_remote_directories
+    show_remote_directory_listing :default, :show_only_directories
+  end
+
+  # ========================================================================= #
+  # === show_full_names=
+  # ========================================================================= #
+  def show_full_names=(i = true)
+    @internal_hash[:show_full_names] = i
+  end; alias show_full_names show_full_names= # === show_full_names
+
+  # ========================================================================= #
+  # === show_user_and_password
+  # ========================================================================= #
+  def show_user_and_password
+    ljust = 12
+    e
+    e ('User-Name: ').ljust(ljust)+sfancy(user_name?.to_s)
+    e ('Password: ' ).ljust(ljust)+sfancy(password?)
+    e
+  end; alias show_user_name_and_password show_user_and_password # === show_user_name_and_password
+
+  # ========================================================================= #
+  # === sync_ftp_object_onto_the_main_namespace
+  #
+  # Invoke this method only after having made sure that ftp_object?
+  # returns a non-nil object.
+  # ========================================================================= #
+  def sync_ftp_object_onto_the_main_namespace
+    ::FtpParadise.ftp_object = self
+  end
+
+  # ========================================================================= #
+  # === upload_binary_file
+  #
+  # Use this method to upload a binary file to a remote host.
+  #
+  # The first argument `i` is the file that we wish to upload.
+  #
+  # The method will make use of the method .putbinaryfile().
+  #
+  # Documentation for that file can be found here:
+  #
+  #   https://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-putbinaryfile
+  #
+  # ========================================================================= #
+  def upload_binary_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    be_verbose = false if be_verbose == :be_silent
+    if i.is_a? Array
+      i.each {|entry| upload_binary_file(entry, be_verbose) }
+    else
+      i = i.strip.delete(N) # Added Feb 2014.
+      if be_verbose
+        notify_the_user_about(i, __method__)
+      end
+      begin
+        # =================================================================== #
+        # Next we will delegate towards the @ftp_object:
+        # =================================================================== #
+        ftp_object?.putbinaryfile(i) # We will use the method .putbinaryfile()
+        @internal_hash[:uploaded_these_files] << i
+        if be_verbose
+          remote_path = rds(remote_path?+'/'+File.basename(i))
+          opnn; e 'Done uploading! The remote path is: '
+          e "  #{simp(remote_path)}"
+          report_finished_uploading_of_this_file(i)
+        end
+      rescue Exception => error
+        e 'An error happened as we tried to use the method '+simp('upload_binary()')+'.'
+        e 'The method we used was: '+simp('ftp?.putbinaryfile(i)')
+        e 'We will feedback this error now (of class '+sfancy(error.class.to_s)+'):'
+        pp error
+      end
+    end
+  end; alias upload_binary           upload_binary_file # === upload_binary
+       alias upload_this_binary_file upload_binary_file # === upload_this_binary_file()
+
+  # ========================================================================= #
+  # === upload_file
+  #
+  # This method will distinguish between a binary file or a text file,
+  # based on the transfer mode in use. The default is to work on a
+  # text file.
+  # ========================================================================= #
+  def upload_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    if File.exist? i
+      case transfer_mode?
+      # ===================================================================== #
+      # === :ascii
+      # ===================================================================== #
+      when :ascii,
+           :text,
+           :default
+        upload_this_text_file(i, be_verbose)
+      # ===================================================================== #
+      # === :binary
+      # ===================================================================== #
+      when :binary
+        upload_this_binary_file(i, be_verbose)
+      end
+      update_raw_listing(:be_quiet)
+    else
+      opnn; e "No file called `#{sfile(i)}` appears to exist locally." 
+    end
+  end; alias upload_this_file upload_file # === upload_this_file
+
+  # ========================================================================= #
+  # === set_array_available_hosts
+  #
+  # Use this method if you wish to define the available hosts. This is
+  # useful whenever you already have some pre-defined hosts that you wish
+  # to use.
+  # ========================================================================= #
+  def set_array_available_hosts(i = nil)
+    i = [i].flatten.compact
+    @internal_hash[:array_available_hosts] = i
+  end
+
+  # ========================================================================= #
+  # === set_input
+  # ========================================================================= #
+  def set_input(i)
+    if is_a? Symbol
+      i = '' # For now all Symbols are ignored here.
+    end
+    @input = i
+  end
+
+  # ========================================================================= #
+  # === set_username
+  #
+  # Set the username that you wish to use here. If the input is nil, a
+  # default name will be used instead.
+  # ========================================================================= #
+  def set_username(
+      i = DEFAULT_USER_NAME
+    )
+    i = i.first if i.is_a? Array
+    i = DEFAULT_USER_NAME if i.nil?
+    # ======================================================================= #
+    # The username will be stored on the toplevel-module.
+    # ======================================================================= #
+    FtpParadise.set_username(i)
+  end; alias set_user_name  set_username # === set_user_name
+       alias login_name=    set_username # === login_name?
+       alias set_name       set_username # === set_name
+       alias set_user       set_username # === set_user
+       alias set_login_name set_username # === set_login_name
+       alias user_name=     set_username # === user_name?
+
+  # ========================================================================= #
+  # === username?
+  # ========================================================================= #
+  def username?
+    FtpParadise.username?.to_s
+  end; alias user_name? username? # === user_name?
+
+  # ========================================================================= #
+  # === download_remote_file                                   (download tag)
+  #
+  # Use this method to download a remote file. If you are sure to have
+  # a binary file, the method download_binary_file() could be used
+  # instead.
+  #
+  # gettextfile(remotefile, localfile = File.basename(remotefile)) {|line| ...}
+  # ========================================================================= #
+  def download_remote_file(
+      i, be_verbose = be_verbose?
+    )
+    if i.is_a? Array # Handle arrays first.
+      i.each {|entry| download_remote_file(entry, be_verbose) }
+    else
+      if i =~ /^\d+$/ # if is a number
+        update_file_listing
+        i = return_remote_files[i.to_i - 1].first
+      end
+      if i == '*' # Here we want to download all files, as we passed in '*'.
+        i = []
+        update_file_listing
+        return_remote_files.each { |a,b| i << FtpParadise.rds(a) }
+      end
+      if be_verbose
+        notify_the_user_about(i, __method__)
+      end
+      set_file(i) # This assigns to @internal_hash[:file].
+      begin # We can use @file because we called set_file() before.
+        ftp_object?.gettextfile(file?)
+        basename = File.basename(file?)
+        e "Finished downloading `#{sandybrown(file?)}`"
+        e 'into `'+sdir(rds(Dir.pwd+'/'+basename))+'`.'
+        return file?
+      rescue Net::FTPPermError => error
+        pp error
+        e 'An exception occurred in the method '+sfancy('download()')+'.'
+        e 'The error was a '+sfancy('Permission Error')+', the input '\
+          'to the method was: `'+simp(i)+'`.'
+        e 'Is the file that you are trying to download really '\
+          'existing on the remote server?'
+        return false
+      end
+    end
+  end; alias download                  download_remote_file # === download
+       alias download_this_remote_file download_remote_file # === download_this_remote_file
+       alias download_this_file        download_remote_file # === download_this_file
+
+  # ========================================================================= #
+  # === create_remote_file                                        (touch tag)
+  #
+  # This "touches" a remote file.
+  # ========================================================================= #
+  def create_remote_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    if i.is_a? Array
+      i.each {|entry| create_remote_file(entry, be_verbose) }
+    else
+      FileUtils.touch(i)
+      if be_verbose
+        notify_the_user_about(i, __method__)
+      end
+      upload_this_text_file(i, :be_quiet)
+      File.delete(i) if File.zero? i # And get rid of that file too.
+    end
+  end; alias touch create_remote_file # === touch
+
+  # ========================================================================= #
+  # === fancy_remote_listing
+  #
+  # This method will obtain the (remote) directory listing and then
+  # display it.
+  # ========================================================================= #
+  def fancy_remote_listing(
+      be_verbose = be_verbose?
+    )
+    update_file_listing
+    case be_verbose
+    when :be_silent,
+         :be_quiet
+      be_verbose = false
+    when :also_show_filesize
+      be_verbose = true
+    end
+    if be_verbose
+      e ('=' * 55)+' '+
+        FtpParadise.yellow('REMOTE FILES')+' '+('=' * 12)
+      if remote_directory_is_empty?
+        e "Remote `#{sdir(remote_path?)}` is empty."
+        e 'No files or directories can be found therein.'
+      else
+        e 'Remote content of `'+sdir(remote_path?)+'` is:'+N+N
+        e 'Index  Filename                           '\
+          '                                    Filesize'
+        show_remote_file_listing
+      end
+      cliner
+    end
+    return remote_directory_content
+  end
+
+  # ========================================================================= #
+  # === rename
+  #
+  # This method will attempt to rename a file on the remote server.
+  #
+  # Note that this is equivalent to moving a file, which is why the alias
+  # move_file can also be used. Any move-file actioni s simply a rename()
+  # action.
+  #
+  # The first argument passed to this method should be the name of an 
+  # existing (remote) file. The second second argument should be the
+  # new name of that file, or its full (remote) path.
+  #
+  # Also note that it seems as if the FTP protocol requires the full
+  # target location, otherwise errors such as the following might
+  # happen:
+  #
+  #   ftp.rb in `getresp': 451 Rename/move failure: Is a directory (Net::FTPTempError)
+  #
+  # The command used by .rename() command should be equivalent to this code:
+  #
+  #   SITE mv oldpath newpath
+  #
+  # Documentation for the functionality can be found here:
+  #
+  #   http://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-rename
+  #        
+  # ========================================================================= #
+  def rename(
+      from,
+      to,
+      be_verbose = be_verbose?
+    )
+    to = to.first if to.is_a? Array
+    if from.is_a? Array # Support batch-transfer.
+      from.each {|entry| rename(entry, to) }
+    else
+      from = rds(from)
+      to   = rds(to)
+      begin
+        ftp_object?.rename(from, to)
+        if be_verbose
+          opnn; e "Renamed the remote entry `#{sfancy(from)}"\
+                  "` to `#{sfancy(to)}`."
+        end
+      rescue Net::FTPTempError => error
+        e "An error (#{simp('Net::FTPTempError')}) occurred "\
+          "in the method #{simp('rename()')}:"
+        pp error
+      end
+    end
+  end; alias rename_file        rename # === rename_file
+       alias move_file          rename # === move_file
+       alias rename_remote_file rename # === rename_remote_file
+
+  # ========================================================================= #
+  # === update_remote_file_listing
+  # ========================================================================= #
+  def update_remote_file_listing(
+      be_verbose = be_verbose?
+    )
+    case be_verbose
+    when :be_quiet
+      be_verbose = false
+    end
+    if is_connected?
+      begin
+        # =================================================================== #
+        # Make use of a method that will skip a few entries, such as
+        # "." or "..".
+        # =================================================================== #
+        @internal_hash[:raw_entries] = return_slightly_sanitized_entries_ignoring_a_few
+      rescue Exception => error
+        opnn; e swarn('An error happened in the method '\
+                'update_remote_file_listing(), at '\
+                'line: '+__LINE__.to_s+'.')
+        pp error.class
+        pp error
+      end
+    else
+      if be_verbose
+        opnn; e 'Can not update the remote file listing '\
+                'because we are not connected.'
+      end
+    end
+  end; alias update_file_listing update_remote_file_listing # === update_file_listing
+       alias update_raw_listing  update_remote_file_listing # === update_raw_listing
+       alias get_listing         update_remote_file_listing # === get_listing
+       alias get_remote_listing  update_remote_file_listing # === get_remote_listing
+       alias update              update_remote_file_listing # === update
+
+  # ========================================================================= #
+  # === does_this_remote_file_exist?
+  # ========================================================================= #
+  def does_this_remote_file_exist?(i)
+    i = File.basename(i).strip
+    array = return_all_remote_files
+    if array.is_a?(Array) and
+       array.first.is_a?(String)
+      array.map! {|entry|
+        entry = FtpParadise::Entry.new(entry)
+      }
+      array.select! {|entry| entry.is_a_file? }
+      array.map! {|entry| entry.filename? }
+    end
+    return array.include?(i)
+  end
+
+  # ========================================================================= #
+  # === show_remote_directory_listing
+  #
+  # This will simply show the content of a remote directory.
+  #
+  # Invocation examples:
+  #
+  #   show_remote_directory_listing
+  #   show_remote_directory_listing :default, :show_only_directories
+  #
+  # ========================================================================= #
+  def show_remote_directory_listing(
+      i             = list,
+      array_options = []
+    )
+    unless array_options.is_a? Array
+      array_options = [array_options]
+    end
+    case i
+    when :default
+      i = list
+    end
+    if i.is_a? Array
+      # ===================================================================== #
+      # Get rid of '.' and '..'.
+      # ===================================================================== #
+      i.reject! {|entry| entry.end_with?('..') or entry.end_with?('.') }
+      # ===================================================================== #
+      # First, turn them into entries.
+      # ===================================================================== #
+      i.map! {|entry| FtpParadise::Entry.new(entry) }
+      # ===================================================================== #
+      # Next, we can use different behaviours.
+      # ===================================================================== #
+      if array_options.include? :show_only_directories
+        i.select! {|entry| entry.is_a_directory? }
+      end
+      i.each {|entry| entry.show_the_line }
+    end
+  end; alias show_remote_files show_remote_directory_listing # === show_remote_files
+
+  # ========================================================================= #
+  # === upload                                                   (upload tag)
+  #
+  # This method can upload binary files, text files and whole directories.
+  # Based on that check, the method body will behave differently, and
+  # delegate to other methods such as upload_directory() or upload_file().
+  #
+  # A single file (as String) can be uploaded, or an Array of files. The
+  # upload activity will transfer the file or the files onto the remote host.
+  #
+  # The second argument specifies whether the method will be verbose and
+  # report back to the user, or whether the method will be quiet,
+  # defaulting to the return value of the method `be_verbose?`.
+  # ========================================================================= #
+  def upload(
+      i,
+      be_verbose = be_verbose?
+    )
+    be_verbose = false if be_verbose == :be_silent
+    if i.is_a? Array
+      i.each {|entry| upload(entry, be_verbose) }
+    else
+      if i == '*' # Here we want to upload all files.
+        i = get_all_local_files
+        upload(i, be_verbose) 
+      else
+        # =================================================================== #
+        # === Handle upload of directories first
+        # =================================================================== #
+        if File.directory? i
+          upload_directory(i, be_verbose)
+        # =================================================================== #
+        # === Handle uploading of files next
+        # =================================================================== #
+        else
+          upload_file(i, be_verbose)
+        end
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === uploaded_these_files?
+  # ========================================================================= #
+  def uploaded_these_files?
+    @internal_hash[:uploaded_these_files]
+  end
+
+  # ========================================================================= #
+  # === list?                                            (list tag)
+  #
+  # Returns an array of file information in the directory (the output
+  # is like `ls -l`). If a block is given, it iterates through the
+  # listing.
+  # ========================================================================= #
+  def list?(i = '*')
+    # ======================================================================= #
+    # We will also sanitize this a bit.
+    # ======================================================================= #
+    @internal_hash[:raw_entries] = return_slightly_sanitized_entries_ignoring_a_few
+    return @internal_hash[:raw_entries] # And return the result here.
+  end; alias ls                   list? # === ls
+       alias populate_raw_entries list? # === populate_raw_entries
+
+  # ========================================================================= #
+  # === list_content                                       (list tag, ls tag)
+  #
+  # List available data.
+  # ========================================================================= #
+  def list_content
+    report_current_remote_dir
+    result = list?
+    cliner { pp result }
+    _ = result.first[0, 1]
+    case _
+    when 'd'
+      e "Directory #{result.first}"
+      # @array_directories
+    when 'l'
+      e "Link #{result.first}"
+    else
+      e "File #{result.first}"
+    end
+  end; alias do_list_content list_content # === list
+       alias listing?        list_content # === listing?
+
+  # ========================================================================= #
+  # === file_listing_as_entries?
+  # ========================================================================= #
+  def file_listing_as_entries?
+    _ = remote_file_listing?
+    if _
+      return _.map {|entry| FtpParadise::Entry.new(entry) }
+    end
+    return nil
+  end
+
+  # ========================================================================= #
+  # === closed?
+  #
+  # Returns true if the connection to our remote host is closed.
+  # ========================================================================= #
+  def closed?
+    begin
+      ftp_object?.closed? if ftp_object?
+    rescue Net::FTPConnectionError
+      true
+    end
+  end
+
+  # ========================================================================= #
+  # === dataset?
+  # ========================================================================= #
+  def dataset?
+    FtpParadise.data?
+  end
+
+  # ========================================================================= #
+  # === return_slightly_sanitized_entries_ignoring_a_few
+  # ========================================================================= #
+  def return_slightly_sanitized_entries_ignoring_a_few(
+      i = '*'
+    )
+    ftp_object?.list(i).reject {|entry|
+      entry.to_s.strip.empty? or entry.end_with?(' .') or entry.end_with?(' ..')
+    }.map {|line|
+      if line.end_with? ':' # <- Some remote FTP-hosts use ':' for a directory.
+        line[-1,1] = '/'
+      end
+      line
+    }
+  end; alias list return_slightly_sanitized_entries_ignoring_a_few # === list
+
+  # ========================================================================= #
+  # === populate_internal_hash_with_default_values
+  # ========================================================================= #
+  def populate_internal_hash_with_default_values
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :transfer_mode
+    # ======================================================================= #
+    @internal_hash[:transfer_mode] = :binary
+    # ======================================================================= #
+    # === :port
+    #
+    # The internal Hash keeps track of some configure-settings and slots
+    # to be used that are of relevance to this class.
+    # ======================================================================= #
+    @internal_hash[:port] = nil     # Has to be nil initially.
+    # ======================================================================= #
+    # === :be_verbose
+    # ======================================================================= #
+    @internal_hash[:be_verbose] = nil
+    # ======================================================================= #
+    # === :raw_entries
+    # ======================================================================= #
+    @internal_hash[:raw_entries] = nil
+    @internal_hash[:file] = nil
+    @internal_hash[:show_full_names] = false # Is false on startup.
+    @internal_hash[:debug] = false
+    # ======================================================================= #
+    # === :array_available_hosts
+    # ======================================================================= #
+    @internal_hash[:array_available_hosts] = []
+    # ======================================================================= #
+    # === :padding
+    # ======================================================================= #
+    @internal_hash[:padding] = '  ' # This padding value is used for remote directory listing.
+    # ======================================================================= #
+    # The following Array keeps track over the files that were uploaded 
+    # successfully. This gives us the possibility to query this from other
+    # classes.
+    # ======================================================================= #
+    @internal_hash[:uploaded_these_files] = []
+  end
+
+  # ========================================================================= #
+  # === is_a_directory?
+  #
+  # This method queries whether the given input is a (remote) directory.
+  # For this to work, the given input must obviously exist as file or
+  # directory.
+  # ========================================================================= #
+  def is_a_directory?(i)
+    update_file_listing
+    candidates = file_listing_as_entries?.select {|entry|
+      entry.is_a_directory?
+    }.map(&:last)
+    candidates.include? i
+  end; alias is_directory?                 is_a_directory? # === is_directory?
+       alias is_a_directory?               is_a_directory? # === is_a_directory?
+       alias this_remote_directory_exists? is_a_directory? # === this_remote_directory_exists?
+       alias is_dir?                       is_a_directory? # === is_dir?
+
+  # ========================================================================= #
+  # === remote_directory_is_empty?
+  #
+  # This method will return a Boolean - true if the remote directory
+  # is empty, and false otherwise.
+  # ========================================================================= #
+  def remote_directory_is_empty?
+    _ = return_remote_directory_content
+    _.reject! {|entry|
+      (entry == '.') or (entry == '..')
+    }
+    _.empty?
+  end
+
+  # ========================================================================= #
+  # === create_this_remote_directory                              (mkdir tag)
+  #
+  # This method will attempt to create a remote directory.
+  #
+  # A Net::FTPPermError may result if the permission does not allow for
+  # that action.
+  # ========================================================================= #
+  def create_this_remote_directory(
+      i, be_verbose = be_verbose?
+    )
+    if i.is_a? Array
+      i.each {|entry| create_this_remote_directory(entry, be_verbose) }
+    else
+      i = rds(i+'/')
+      if be_verbose
+        notify_the_user_about(i, __method__)
+        if is_directory?(i)
+          opnn; e swarn('Warning - the remote directory ')+
+                  sdir(i)+swarn(' already exists.')
+          opnn; e swarn('We thus can not create a new directory.')
+        end
+      end
+      begin
+        ftp_object?.mkdir(i)
+      rescue Net::FTPConnectionError
+        opnn; e 'Not connected - is the network down/available?'
+      rescue Net::FTPPermError
+        opnn; e "Net::FTPPermError: Can not create the remote "\
+                "directory `#{remote_path?}#{sdir(i)}`"
+        opnn; e 'as it - or a file with the same name - already exists.'
+      end
+    end
+  end; alias mkdir                           create_this_remote_directory # === mkdir
+       alias rmkdir                          create_this_remote_directory # === rmkdir
+       alias remote_mkdir                    create_this_remote_directory # === remote_mkdir
+       alias create_directory                create_this_remote_directory # === create_directory
+       alias create_these_remote_directories create_this_remote_directory # === create_these_remote_directories
+       alias remote_create_directory         create_this_remote_directory # === remote_create_directory
+       alias create_remote_directory         create_this_remote_directory # === create_remote_directory
+
+  # ========================================================================= #
+  # === sanitize_remote_directory_content
+  #
+  # The purpose of this method is to clean up the remote dataset.
+  #
+  # Keep in mind that the output comes in something like:
+  #
+  #    "-rw-rw-rw-   1 web      netscape     6820 May 30  2011 AppendToCookbook.rb"
+  #    "drwxrwxrwx   2 web      netscape     8192 Oct 29  2007 CSS"
+  #    "-rw-rw-rw-   1 web      netscape    10548 May 30  2011 Chained.rb" 
+  #    "-rw-r--r--   1 330        330      237904 Jun  9 14:24 11.03.2003_UniWien_Biologie_EinfuehrungInDieMikrobiologie.jpg",
+  #
+  # This should contain all the information that is needed.
+  # ========================================================================= #
+  def sanitize_remote_directory_content
+    _ = []
+    raw_entries?.each { |e|
+      next if e.empty?
+      entry = FtpParadise::Entry.new(e)
+      filesize  = entry.filesize?
+      timestamp = entry.parsed_timestamp?
+      # ===================================================================== #
+      # === Exclude 3 entries next
+      # ===================================================================== #
+      next if e.include? 'total' or
+              entry.name? == '.' or
+              entry.name? == '..' # Batch next.
+      # ===================================================================== #
+      # === Build up the final Array
+      #
+      # Our Array will have four entries:
+      #
+      #   (1) Filename
+      #   (2) File or Directory (String)
+      #   (3) Filesize
+      #   (4) Timestamp
+      #
+      # ===================================================================== #
+      _ << [ rds(entry.filename?), entry.file_or_directory, filesize, timestamp ]
+    }
+    @internal_hash[:sanitized_remote_directory_content] = _ #.compact
+  end
+
+  # ========================================================================= #
+  # === sanitized_remote_directory_content?
+  # ========================================================================= #
+  def sanitized_remote_directory_content?
+    update_remote_file_listing
+    sanitize_remote_directory_content
+    @internal_hash[:sanitized_remote_directory_content]
+  end
+
+  # ========================================================================= #
+  # === download_binary_file
+  #
+  # Use this method to download a binary file, by calling the method
+  # getbinaryfile(). You can download as many files as you want to
+  # through this method, but we expect this method to be a binary
+  # file.
+  #
+  # Specific usage example:
+  #
+  #   ftp?.download_binary_file('photos_2009-03-29.zip', 'ftp_photos/photos.zip')
+  #
+  # ========================================================================= #
+  def download_binary_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    if i.is_a? Array
+      i.each {|entry| download_binary_file(entry) }
+    else
+      ftp?.getbinaryfile(i) # Delegate towards .getbinaryfile()
+      if be_verbose
+        e "Downloaded file #{sfile(i)}."
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === empty?
+  # ========================================================================= #
+  def empty?
+    array_remote_files.empty?
+  end
+
+  # ========================================================================= #
+  # === find_matches_for
+  #
+  # This method will return an array of files and directories that match
+  # to the provided input (which we will assume to be a query).
+  # ========================================================================= #
+  def find_matches_for(i)
+    i = i.delete '*'
+    update_file_listing
+    _ = return_remote_directory_content.map(&:first)
+    _ = _.grep(/#{i}/)
+    return _
+  end
+
+  # ========================================================================= #
+  # === output_sorted_by_time
+  #
+  # This method will output the remote content in a time-sorted manner.
+  # ========================================================================= #
+  def output_sorted_by_time
+    _ = sanitized_remote_directory_content?
+    sorted_result = _.sort_by {|array|
+      array.last
+    }.reverse
+    sorted_result.each_with_index {|array, index| index += 1
+      file_or_directory = array[1]
+      name_of_the_file = array.first
+      if file_or_directory == 'directory'
+        name_of_the_file << '/' unless name_of_the_file.end_with? '/'
+      end
+      index = simp( (index.to_s+') ').rjust(6))
+      e index+sfancy(name_of_the_file)
+    }
+  end
+
+  # ========================================================================= #
+  # === last_response
+  #
+  # The server's last response is available through this method here.
+  # ========================================================================= #
+  def last_response
+    ftp_object?.last_response
+  end; alias last_response?        last_response # === last_response?
+       alias last_server_response? last_response # === last_server_response?
+
+  # ========================================================================= #
+  # === raw_entries?
+  # ========================================================================= #
+  def raw_entries?
+    @internal_hash[:raw_entries]
+  end; alias remote_file_listing? raw_entries? # === remote_file_listing?
+       alias file_listing?        raw_entries? # === file_listing?
+       alias raw_listing?         raw_entries? # === raw_listing?
+
+  # ========================================================================= #
+  # === return_local_directories
+  #
+  # Return all local directories.
+  # ========================================================================= #
+  def return_local_directories
+    Dir['*'].select {|entry| File.directory?(entry) }
+  end
+
+  # ========================================================================= #
+  # === modification_time_of?
+  #
+  # This method will give us the last modification time of a remote
+  # file, by issuing the mdtm() command.
+  #
+  # The format returned will be in YYYMMDDhhmmss.
+  #
+  # If you require a parsed Time instance, you can use mtime()
+  # on the ftp object.
+  #
+  # Symbols could also be used, such as "pp modification_time_of? :a".
+  # ========================================================================= #
+  def modification_time_of?(i)
+    if i.is_a? Array
+      i.each {|entry| modification_time_of(entry) } # <- Recursive call.
+    else
+      ftp_object?.mdtm(i.to_s)
+    end
+  end; alias mdtm modification_time_of? # === mdtm
+
+  # ========================================================================= #
+  # === set_file
+  #
+  # Use only this to modify the @file variable.
+  # ========================================================================= #    
+  def set_file(i = nil)
+    @internal_hash[:file] = i
+  end
+
+  # ========================================================================= #
+  # === is_file?
+  #
+  # This method will check whether the input is a file or not.
+  # It will call the method .is_directory?()
+  # ========================================================================= #
+  def is_file?(i)
+    !is_a_directory?(i)
+  end
+
+  # ========================================================================= #
+  # === logged_in?
+  # ========================================================================= #
+  def logged_in?
+    ftp_object?.instance_variable_get('@logged_in') and
+    (ftp_object?.instance_variable_get('@logged_in') == true)
+  end
+
+  # ========================================================================= #
+  # === available_hosts?
+  # ========================================================================= #
+  def available_hosts?
+    @internal_hash[:array_available_hosts]
+  end; alias array_available_hosts  available_hosts? # === array_available_hosts
+       alias array_available_hosts? available_hosts? # === array_available_hosts?
+
+  # ========================================================================= #
+  # === open_timeout?
+  # ========================================================================= #
+  def open_timeout?
+    ftp_object?.open_timeout.to_s if ftp_object?.respond_to? :open_timeout
+  end
+
+  # ========================================================================= #
+  # === feedback_login_hosts
+  #
+  # Feedback all available login hosts, based on the information stored
+  # in the Array @array_available_hosts.
+  # ========================================================================= #
+  def feedback_login_hosts
+    opnn; e 'The followings hosts are easily available:'
+    e
+    available_hosts?.each { |host| e "  - #{sfancy(host)}" }
+    e
+  end
+
+  # ========================================================================= #
+  # === help?
+  # ========================================================================= #
+  def help?
+    ftp_object?.help
+  end; alias help help? # === help
+
+  # ========================================================================= #
+  # === close                                                     (close tag)
+  #
+  # Close the connection here.
+  #
+  # Further operations will be impossible until a new connection
+  # is opened up again, via connect().
+  # ========================================================================= #
+  def close
+    ftp_object?.close
+  end
+
+  # ========================================================================= #
+  # === mlsd
+  # ========================================================================= #
+  def mlsd(i)
+    ftp_object?.mlsd(i)
+  end
+
+  # ========================================================================= #
+  # === site
+  # ========================================================================= #
+  def site(i = nil)
+    ftp_object?.site(i)
+  end
+
+  # ========================================================================= #
+  # === file?
+  # ========================================================================= #
+  def file?
+    @internal_hash[:file]
+  end
+
+  # ========================================================================= #
+  # === system_command
+  #
+  # This will return system information from the remote host.
+  #
+  # Stuff like:
+  #   UNIX Type: L8
+  # ========================================================================= #
+  def system_command
+    ftp_object?.system
+  end; alias system system_command # === system
+
+  # ========================================================================= #
+  # === report_host_port_user_name_and_password
+  # ========================================================================= #
+  def report_host_port_user_name_and_password
+    ljust = 15
+    e '- Now trying to log in to '+simp(host?)+
+      ' (Port: '+swarn(port?)+') using:'
+    e '  '+('Login Name: ').ljust(ljust)+sfancy(user_name?)
+    e '  '+('Password: ').ljust(ljust)+sfancy(password?)
+  end
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn
+    super(NAMESPACE)
+  end
+
+  # ========================================================================= #
+  # === read_timeout=
+  #
+  # Setter-method for the #read_timeout attribute.
+  # ========================================================================= #
+  def read_timeout=(i)
+    ftp_object?.read_timeout = i
+  end
+
+  # ========================================================================= #
+  # === size?
+  #
+  # This method will return the size of the given (remote) filename.
+  # ========================================================================= #
+  def size?(i)
+    ftp_object?.size(i)
+  end; alias size size? # === size
+
+  # ========================================================================= #
+  # === padding?
+  # ========================================================================= #
+  def padding?
+    @internal_hash[:padding]
+  end
+
+  # ========================================================================= #
+  # === be_verbose?
+  # ========================================================================= #
+  def be_verbose?
+    @internal_hash[:be_verbose]
+  end
+
+  # ========================================================================= #
+  # === server_welcome_message?
+  #
+  # This method will return the remote server's welcome message.
+  # ========================================================================= #
+  def server_welcome_message?
+    ftp_object?.welcome
+  end; alias welcome? server_welcome_message? # === welcome?
+       alias welcome  server_welcome_message? # === welcome
+
+  # ========================================================================= #
+  # === noop
+  # ========================================================================= #
+  def noop
+    ftp_object?.noop
+  end
+
+  # ========================================================================= #
+  # === last_response_code?
+  #
+  # Return the server's last response code.
+  # ========================================================================= #
+  def last_response_code?
+    ftp_object?.last_response_code
+  end; alias last_response_code last_response_code? # === last_response_code
+
+  # ========================================================================= #
+  # === []
+  # ========================================================================= #
+  def [](i)
+    update_file_listing
+    if i =~ /^\d+$/ # If is a number.
+      i = remote_file_listing.size if i.to_i > remote_file_listing.size
+      i = remote_file_listing[i.to_i - 1].first
+    end
+    return i
+  end
+
+  # ========================================================================= #
+  # === notify_the_user_about
+  #
+  # This method is a general "user notifier". It will notify the user
+  # about doing certain actions within the FtpParadise project.
+  # ========================================================================= #
+  def notify_the_user_about(
+      i, method
+    )
+    case method
+    # ======================================================================= #
+    # === :set_transfer_mode
+    # ======================================================================= #
+    when :set_transfer_mode
+      opnn; e "Setting mode to #{orange(i.to_s)} now."
+    # ======================================================================= #
+    # === :remove_remote_files
+    # ======================================================================= #
+    when :remove_remote_files
+      opnn; e "Deleting the remote file `#{sdir(i)}` now."
+    # ======================================================================= #
+    # === :upload_binary_file
+    # ======================================================================= #
+    when :upload_binary_file
+      opnn; e 'Now trying to upload the binary file `'+sfile(i)+'`'
+      opnn; e 'to the remote host `'+sfancy(remote_host?)+'`.'
+    # ======================================================================= #
+    # === :create_this_remote_directory
+    # ======================================================================= #
+    when :create_this_remote_directory
+      opnn; e 'Creating the remote directory `'+sdir(i)+'` now.'
+    # ======================================================================= #
+    # === :remote_cd
+    # ======================================================================= #
+    when :remote_cd
+      opnn; e 'Trying to remote-change directory into `'+sdir(i)+'`.'
+    # ======================================================================= #
+    # === :download_this_remote_file
+    # ======================================================================= #
+    when :download_this_remote_file
+      opnn; e "Downloading the remote file `#{sdir(i)}` now."
+    # ======================================================================= #
+    # === :upload_this_text_file
+    # ======================================================================= #
+    when :upload_this_text_file
+      opnn; e 'Uploading the local text file `'+sfile(i)+'` to '\
+              'the remote host at `'+sfancy(remote_pwd?)+'`.'
+    # ======================================================================= #
+    # === :create_remote_file
+    # ======================================================================= #
+    when :create_remote_file
+      opnn; e 'Creating the remote file `'+sdir(i)+'` now.'
+    # ======================================================================= #
+    # === :remove_remote_directory
+    # ======================================================================= #
+    when :remove_remote_directory
+      opnn; e 'Removing the remote directory `'+sdir(i)+'` now.'
+    end
+  end
+
+  # ========================================================================= #
+  # === report_finished_uploading_of_this_file
+  #
+  # Report that we have finished uploading a file.
+  #
+  # We should also denote the leading http part.
+  # ========================================================================= #
+  def report_finished_uploading_of_this_file(i)
+    if is_connected?
+      remote_path = "http://#{rds(remote_path?+File.basename(i))}"
+      opnn; e "Done uploading `#{sfile(i)}` to `"\
+              "#{sdir(remote_path)}`!"
+    end
+  end
+
+  # ========================================================================= #
+  # === password?
+  # ========================================================================= #
+  def password?
+    ::FtpParadise.password?.to_s
+  end; alias password password? # === password
+
+  # ========================================================================= #
+  # === set_password
+  #
+  # Use only this method when attempting to modify the @password.
+  #
+  # This @ivar keeps track of the password we will use.
+  # ========================================================================= #
+  def set_password(
+      i = :try_to_use_a_default_password
+    )
+    case i
+    # === try_to_use_a_default_password
+    when :try_to_use_a_default_password,
+         :default
+      _ = return_password_from_bplaced
+      _.chop! if _.end_with? '_'
+      i = _
+    when :anonymous
+      i = nil
+    else
+      i = i.to_s
+    end
+    ::FtpParadise.set_password(i)
+    i # Return the password here as well, so that we can use it for assignments.
+  end; alias password= set_password # === password=
+
+  # ========================================================================= #
+  # === return_password_from_bplaced
+  # ========================================================================= #
+  def return_password_from_bplaced
+    dataset = YAML.load_file(FILE_ROEBE_FTP)['bplaced']
+    return dataset['password']
+  end
+
+  # ========================================================================= #
+  # === set_port
+  #
+  # Use this method to set the port. The port will be stored on the
+  # toplevel-"namespace".
+  # ========================================================================= #
+  def set_port(
+      i = DEFAULT_PORT
+    )
+    FtpParadise.set_port(i)
+  end
+
+  # ========================================================================= #
+  # === port?
+  # ========================================================================= #
+  def port?
+    FtpParadise.port?.to_s
+  end; alias port port? # === port
+
+  require 'ftp_paradise/toplevel_methods/remote_url.rb'
+  # ========================================================================= #
+  # === remote_url?
+  #
+  # This method is guaranteed to return a String - except when an
+  # error happens.
+  # ========================================================================= #
+  def remote_url?
+    begin
+      return FtpParadise.remote_url?.to_s
+    rescue Interrupt
+      exit # User interrupted, so we exit as requested.
+    rescue Exception => error
+      opnn; e 'We did encounter an error in the method '+
+              simp(__method__.to_s)
+      opnn; pp error
+      return error.to_s # Return that exception.
+    end
+  end; alias remote_host? remote_url? # === remote_host?
+       alias remote_url   remote_url? # === remote_url
+       alias url?         remote_url? # === url?
+       alias host?        remote_url? # === host?
+       alias host         remote_url? # === host
+
+  # ========================================================================= #
+  # === remove                                                   (remove tag)
+  # ========================================================================= #
+  def remove(i)
+    if i.is_a? Array
+      i.each {|entry| remove(entry) }
+    else
+      if is_a_directory?(i)
+        remove_remote_directory(i)
+      elsif is_a_file?(i)
+        remove_remote_file(i, be_verbose?)
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === original_delete
+  #
+  # This method will remove the file, without doing any additional
+  # checks.
+  # ========================================================================= #
+  def original_delete(i)
+    ftp_object?.delete(i)
+  end
+
+  # ========================================================================= #
+  # === remove_remote_directory
+  #
+  # This method will remove a remote directory. For this to work, as
+  # operation, the remote directory has to exist.
+  #
+  # This operation may fail e. g. when the remote directory is not empty.
+  # This explains why we attempt to rescue some errors.
+  # ========================================================================= #
+  def remove_remote_directory(
+      i,
+      be_verbose   = be_verbose?,
+      force_remove = false
+    )
+    case force_remove
+    when :force_remove
+      force_remove = true
+    when :do_not_force_remove
+      force_remove = false
+    end
+    if i.is_a? Array
+      i.each {|entry| remove_remote_directory(entry, be_verbose) }
+    else
+      if be_verbose
+        notify_the_user_about(i, __method__)
+      end
+      if is_a_directory? i
+        begin
+          ftp_object?.rmdir(i)
+        rescue Net::FTPPermError => error
+          opnn; e swarn('We could not remove the remote directory at ')+
+                  sdir(i)+swarn(' as it is not empty.')
+          pp error
+          if force_remove
+            opnn; e 'We will now try to enter into this directory'
+            opnn; e 'and then remove all files of that directory.'
+            rcd(this_dir)
+            update_file_listing
+            all_remote_files?.each {|file| remove(file) } # Now it should be removed.
+            rcd('..') # Go back again.
+            rmdir(i, be_verbose, :do_not_force_remove) # But we won't force again, to avoid recursive loops.
+            opnn; e "The remote directory at #{sdir(i)} has been removed."
+          end
+        end
+      else
+        if be_verbose
+          opnn; e "The given input #{sfancy(i)} is not a directory."
+        end
+      end
+    end
+  end; alias rmdir                           remove_remote_directory # === rmdir
+       alias remove_these_remote_directories remove_remote_directory # === remove_these_remote_directories
+       alias remove_directory                remove_remote_directory # === remove_directory
+
+  # ========================================================================= #
+  # === puttextfile
+  #
+  # This method will transfer a localfile to the remote server in
+  # ASCII (text) mode. The result will be stored in "remotefile".
+  #
+  # If a callback or an associated block is supplied, calls it, passing
+  # in the transmitted data one line at a time.
+  # ========================================================================= #
+  def puttextfile(
+      local_file, remotefile = File.basename(local_file)
+    )
+    begin
+      ftp_object?.puttextfile(local_file)
+      @internal_hash[:uploaded_these_files] << local_file
+    rescue Net::FTPPermError => error
+      opnn; e swarn('Can not upload `')+sfile(local_file)+swarn('`.')
+      opnn; e swarn('Reason provided to this method was:')
+      opnn; e "  → #{sfancy(error.to_s)}"
+    rescue Exception => error
+      opnn; e "An error happened in the method #{__method__}"
+      pp error
+    end
+  end
+
+  # ========================================================================= #
+  # === upload_this_text_file
+  #
+  # This method can be used to upload one or several text files.
+  #
+  # The first argument should be an Array or a String, denoting the
+  # name/path of the local text file that you wish to upload.
+  # ========================================================================= #
+  def upload_this_text_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    be_verbose = false if be_verbose == :be_silent
+    if i.is_a? Array
+      i.each {|entry| upload_this_text_file(entry, be_verbose) }
+    else
+      i = i.strip.delete(N) # Added in February 2014.
+      case i
+      when :default
+        ENV['MISC'].to_s+'/SITEMAP.cgi' # <- Makes only sense for text-files anyway.
+      end
+      case be_verbose
+      when :be_quiet
+        be_verbose = false
+      end
+      if be_verbose
+        notify_the_user_about(i, __method__)
+      end
+      puttextfile(i) # <- Delegate towards the method puttextfile().
+      report_finished_uploading_of_this_file(i) if be_verbose
+    end
+  end
+
+  # ========================================================================= #
+  # === upload_this_directory
+  #
+  # This method can be used to upload a local directory to a remote host.
+  #
+  # If the first input argument is an Array, then the method will call
+  # itself recursively. This allows us to transfer several directories
+  # in one go.
+  #
+  # If the input is a (local and existing) directory, then this method
+  # will also have to create a remote directory, then chdir into it,
+  # and then upload the content of that local directory to the remote
+  # host.
+  # ========================================================================= #
+  def upload_this_directory(
+      i,
+      be_verbose = be_verbose?
+    )
+    if i.is_a? Array
+      i.each {|entry| upload_this_directory(i, be_verbose) }
+    else
+      if File.directory? i
+        unless this_remote_directory_exists?(i)
+          remote_create_directory(i, be_verbose)
+        end
+        change_local_directory(i)
+        change_remote_directory(i)
+        report_remote_directory
+        content = return_directory_content(i) # Last but not least, copy all files to that dir.
+        content.each {|this_file| upload(this_file) }
+      else
+        opnn; e "The given input `#{sfancy(i)}` is not a directory."
+        opnn; e 'This method can only upload directories.'
+      end
+    end
+  end; alias upload_directory         upload_this_directory # === upload_directory
+       alias upload_these_directories upload_this_directory # === upload_these_directories
+
+  # ========================================================================= #
+  # === set_transfer_mode
+  #
+  # This method will set to either one of two different possibles modes:
+  #
+  #   (1) :ascii
+  #   (2) :binary
+  #   (3) :passive
+  #
+  # Note that :passive "mode" is ascii, with an additional invocation to
+  # change the transfer mode to .passive.
+  #
+  # It will also change passive mode. The argument :default will default
+  # to the more commonly used ASCII mode.
+  #
+  # When would you want to use ASCII mode?
+  #
+  # Use ascii mode for:
+  #
+  #   txt, rtf, html, php
+  #
+  # Use binary mode for:
+  #
+  #   images, videos and similar.
+  #
+  # ========================================================================= #
+  def set_transfer_mode(
+      i          = DEFAULT_TRANSFER_MODE, # Will usually default to :ascii
+      be_verbose = be_verbose?
+    )
+    case be_verbose
+    when :be_verbose
+      be_verbose = true
+    when :be_quiet
+      be_verbose = false
+    end
+    i = :ascii if i == :default
+    case i
+    # ======================================================================= #
+    # === :ascii
+    # ======================================================================= #
+    when :ascii
+      notify_the_user_about(i, __method__) if be_verbose
+      @internal_hash[:transfer_mode] = :ascii
+      ftp_object?.binary = false if ftp_object?
+    # ======================================================================= #
+    # === :binary
+    # ======================================================================= #
+    when :binary
+      notify_the_user_about(i, __method__) if be_verbose
+      @internal_hash[:transfer_mode] = :binary
+    # ======================================================================= #
+    # === :passive
+    # ======================================================================= #
+    when :passive,
+         :pass
+      notify_the_user_about(i, __method__) if be_verbose
+      @internal_hash[:transfer_mode] = :ascii
+      ftp_object?.passive = true if ftp_object?
+    else
+      opnn; e swarn('Not found the following mode: ')+
+              sfancy(i.to_s)
+    end
+  end; alias mode_to_use= set_transfer_mode # === mode_to_use=
+       alias set_mode     set_transfer_mode # === set_mode
+
+  # ========================================================================= #
+  # === report_transfer_mode_in_use
+  # ========================================================================= #
+  def report_transfer_mode_in_use
+    e "Transfer mode: #{sfancy(transfer_mode?.to_s)}"
+  end
+
+  # ========================================================================= #
+  # === set_active
+  # ========================================================================= #
+  def set_active
+    ftp_object?.passive = false
+  end
+  
+  # ========================================================================= #
+  # === passive_transfer?
+  # ========================================================================= #
+  def passive_transfer?
+    ftp_object?.passive
+  end; alias passive? passive_transfer? # === passive?
+
+  # ========================================================================= #
+  # === transfer_mode?
+  #
+  # This method will return the currently used transfer_mode. This mode
+  # can be either :binary, or :ascii. By default it will be :binary.
+  #
+  # The transfer mode can be :binary or :text. :ascii is an alias to
+  # :text.
+  # ========================================================================= #
+  def transfer_mode?
+    @internal_hash[:transfer_mode]
+  end; alias transfer_mode transfer_mode? # === transfer_mode
+       alias mode?         transfer_mode? # === mode?
+       alias type          transfer_mode? # === type
+       alias type?         transfer_mode? # === type?
+
+  # ========================================================================= #
+  # === set_ascii
+  #
+  # Easier wrapper method.
+  # ========================================================================= #
+  def set_ascii
+    set_transfer_mode :ascii
+  end; alias set_ascii_mode set_ascii # === set_ascii_mode
+
+  # ========================================================================= #
+  # === binary?
+  #
+  # When this is true, then then all FTP-transfers will be performed in
+  # binary mode.
+  #
+  # Deaults to true.
+  # ========================================================================= #
+  def binary?
+    ftp_object?.binary
+  end; alias binary binary? # === binary
+
+  # ========================================================================= #
+  # === set_binary_mode
+  # ========================================================================= #
+  def set_binary_mode
+    set_transfer_mode :binary
+    ftp_object?.binary = true
+  end; alias set_binary         set_binary_mode # === set_binary
+       alias set_to_binary_mode set_binary_mode # === set_to_binary_mode
+
+  # ========================================================================= #
+  # === set_passive_mode
+  #
+  # Use this when modifying the passive setting.
+  # ========================================================================= #
+  def set_passive_mode
+    set_transfer_mode :ascii
+    ftp_object?.passive = true if ftp_object?
+  end; alias set_passive set_passive_mode # === set_passive
+
+  # ========================================================================= #
+  # === set_default_transfer_mode
+  # ========================================================================= #
+  def set_default_transfer_mode(
+      be_verbose = :be_quiet
+    )
+    set_transfer_mode(DEFAULT_TRANSFER_MODE, be_verbose)
+  end
+
+  # ========================================================================= #
+  # === set_debug
+  # ========================================================================= #
+  def set_debug(i = SHALL_WE_DEBUG)
+    @internal_hash[:debug] = i
+  end
+
+  # ========================================================================= #
+  # === enable_debug_mode
+  #
+  # When the debug mode is set to true, then all traffic to and from
+  # the server is written to $stdout. By default, this will NOT
+  # be the case.
+  # ========================================================================= #
+  def enable_debug_mode
+    ftp_object?.debug_mode = true
+  end
+
+  # ========================================================================= #
+  # === enable_debug
+  #
+  # Set the @debug variable to true, and also invoke enable_debug_mode().
+  # ========================================================================= #
+  def enable_debug
+    enable_debug_mode
+    set_debug(true)
+  end
+
+  # ========================================================================= #
+  # === debug?
+  # ========================================================================= #
+  def debug?
+    @internal_hash[:debug]
+  end
+
+  # ========================================================================= #
+  # === disable_debug
+  # ========================================================================= #
+  def disable_debug
+    ftp_object?.debug_mode = false
+    @internal_hash[:debug] = false
+  end
+
+  # ========================================================================= #
+  # === debug                                                     (debug tag)
+  #
+  # This method can be used for some debugging output.
+  # ========================================================================= #
+  def debug(
+      shall_we_debug = debug?
+    )
+    cliner {
+      pp ftp?
+      show_host_user_name_port_and_password
+      update_file_listing
+      if shall_we_debug
+        opnn; e 'File Listing:'
+        show_file_listing
+      end
+      if remote_file_listing?.empty?
+        opnn; e 'No file could be found. The remote directory '\
+                'is most likely empty.'
+      end
+    } if shall_we_debug
+  end; alias feedback debug # === feedback
+       alias report   debug # === report
+
+  # ========================================================================= #
+  # === remote_pwd
+  # ========================================================================= #
+  def remote_pwd
+    ftp_object?.pwd
+  end; alias rpwd   remote_pwd # === rpwd
+       alias getdir remote_pwd # === getdir
+
+  # ========================================================================= #
+  # === return_remote_pwd
+  #
+  # This method will return the (remote) pwd, including the remote working
+  # directory - including the subpath..
+  #
+  # This method will ensure that a trailing '/' will be returned here.
+  #
+  # The official documentation can be seen here:
+  #   https://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-pwd
+  # ========================================================================= #
+  def return_remote_pwd
+    begin
+      if is_connected?
+        remote_pwd = remote_url?.dup
+        # ===================================================================== #
+        # Need to safeguard, in the event that we are not connected to a
+        # remote FTP server.
+        # ===================================================================== #
+        if ftp_object? and is_connected? and logged_in?
+          remote_pwd << ftp_object?.pwd.to_s
+        end
+        remote_pwd << '/'
+        return rds(remote_pwd)
+      else
+        opnn; e 'No FTP connection is open.'
+        ''
+      end
+    rescue Net::FTPReplyError
+      opnn; e 'Error Net::FTPReplyError received. May be due to user interrupting.'
+      opnn; e 'Exiting now at once either way.'
+      exit
+    rescue SystemExit, Interrupt
+      opnn; e 'User requested to exit, thus exiting now.'
+      exit
+    end
+  end; alias pwd?                return_remote_pwd # === pwd?
+       alias pwd                 return_remote_pwd # === pwd (pwd tag)
+       alias getdir              return_remote_pwd # === get_dir
+       alias remote_pwd          return_remote_pwd # === remote_pwd
+       alias remote_pwd?         return_remote_pwd # === remote_pwd?
+       alias connected_to?       return_remote_pwd # === connected_to?
+       alias remote?             return_remote_pwd # === remote?
+       alias base_dir?           return_remote_pwd # === base_dir?
+       alias remote_directory?   return_remote_pwd # === remote_directory?
+       alias remote_dir?         return_remote_pwd # === remote_dir?
+       alias remote_path?        return_remote_pwd # === remote_path?
+       alias return_subdirectory return_remote_pwd # === return_subdirectory
+       alias current_directory   return_remote_pwd # === current_directory
+       alias return_remote_dir   return_remote_pwd # === return_remote_dir
+       alias get_remote_dir      return_remote_pwd # === get_remote_dir
+       alias remote_host?        return_remote_pwd # === remote_host?
+
+  # ========================================================================= #
+  # === report_current_remote_dir
+  #
+  # Gives you the current dir.
+  # ========================================================================= #
+  def report_current_remote_dir(
+      be_verbose = be_verbose?
+    )
+    begin
+      if be_verbose
+        opnn; e 'The remote directory is:'
+        e "  #{sdir(return_remote_pwd)}"
+      end
+    rescue Exception => error
+      opnn; e error.class
+      opnn; e error
+    end
+  end; alias report_remote_directory report_current_remote_dir # === report_remote_directory
+       alias dir?                    report_current_remote_dir # === dir?
+       alias report_remote_pwd       report_current_remote_dir # === report_remote_pwd
+
+  # ========================================================================= #
+  # === remote_chdir                                      (cd tag, chdir tag)
+  #
+  # This method allows us to cd to another remote directory, on the
+  # remote FTP server (our main connection). 
+  #
+  # The method must be able to check whether we are connected to the
+  # remote host.
+  # ========================================================================= #
+  def remote_chdir(
+      i,
+      be_verbose = be_verbose?,
+      &block
+    )
+    if block_given?
+      case yield
+      # ===================================================================== #
+      # === :be_verbose
+      # ===================================================================== #
+      when :be_verbose
+        be_verbose = true
+      end
+    end
+    i = i.dup if i.frozen?
+    # ======================================================================= #
+    # Sanitize odd entries ending with ':'
+    # ======================================================================= #
+    i[-1,1] = '/' if i.end_with? ':'
+    i = rds("#{i}/") # <- Always ensure that a '/' is the last character.
+    if be_verbose
+      notify_the_user_about(i, __method__)
+    end
+    if is_connected?
+      # ===================================================================== #
+      # If we cd to a non-existing target, the exception Net::FTPPermError
+      # will be raised.
+      # ===================================================================== #
+      begin
+        ftp_object?.chdir(i)
+        update_remote_file_listing
+      # ===================================================================== #
+      # The user may have insufficient permissions:
+      # ===================================================================== #
+      rescue Net::FTPPermError => error
+        pp error
+      rescue Net::ReadTimeout => error
+        opnn; e 'An error was encountered in the method '\
+                'remote_chdir().'
+        opnn; e 'The error-class was Net::ReadTimeout.'
+        e
+        opnn; e 'The specific error will be displayed next.'
+        e
+        pp error
+      end
+    else
+      opnn; e 'We are not connected to a remote host right now.'
+      opnn; e 'Thus we can not change the directory.'
+    end
+    report_current_remote_dir if be_verbose # right now mandatory
+  end; alias rcd                           remote_chdir # === rcd
+       alias remote_cd                     remote_chdir # === remote_cd
+       alias chdir                         remote_chdir # === chdir
+       alias cd                            remote_chdir # === cd
+       alias chdir                         remote_chdir # === chdir
+       alias rcd                           remote_chdir # === rcd
+       alias change_directory              remote_chdir # === change_directory
+       alias change_remote_directory       remote_chdir # === change_remote_directory
+       alias cd_into_this_remote_directory remote_chdir # === cd_into_this_remote_directory
+       alias remote_change_directory       remote_chdir # === remote_change_directory
+
+  # ========================================================================= #
+  # === return_remote_directories
+  #
+  # Give us a list of (remote) directories - only directories, not
+  # files.
+  #
+  # An Array will be returned as a result.
+  # ========================================================================= #
+  def return_remote_directories
+    _ = []
+    update_file_listing # Populate the file listing anew, so we will always get proper results back.
+    raw_listing?.each {|entry|
+      entry = FtpParadise::Entry.new(entry)
+      _ << rds(entry.return_name) if entry.is_a_directory?
+    }
+    # ======================================================================= #
+    # Directories must end with '/'. Ensure this to be the case next.
+    # ======================================================================= #
+    _.map! {|entry|
+      entry << '/' unless entry.end_with? '/'
+      entry
+    }
+    return _
+  end; alias directories?       return_remote_directories # === directories?
+       alias return_directories return_remote_directories # === return_directories
+
+  # ========================================================================= #
+  # === return_remote_directory_content
+  #
+  # This method will return ALL remote entries, no matter if file or
+  # directory.
+  # ========================================================================= #
+  def return_remote_directory_content
+    raw_entries = raw_entries?
+    if raw_entries.nil?
+      populate_raw_entries
+      raw_entries = raw_entries?
+    end
+    if raw_entries
+      _ = raw_entries.reject {|line|
+        line.empty?
+      }.map {|entry|
+        FtpParadise::Entry.new(entry).name?
+      }
+    end
+    return _
+  end; alias array_file_listing?      return_remote_directory_content # === array_file_listing?
+       alias array_file_listing       return_remote_directory_content # === array_file_listing
+       alias remote_directory_content return_remote_directory_content # === remote_directory_content
+       alias list?                    return_remote_directory_content # === list?
+
+  # ========================================================================= #
+  # === quit                                                       (quit tag)
+  #
+  # Use this method to quit (and disconnect) from the FTP Connection
+  # again.
+  # ========================================================================= #
+  def quit
+    begin
+      if is_connected?
+        if ftp_object?
+          FtpParadise.clear_user_dataset
+          ftp_object?.quit
+        end
+      end
+    rescue Exception => error
+      opnn; e "An error happened in the method #{sfancy(__method__)}()"
+      pp error
+    end
+  end
+
+  # ========================================================================= #
+  # === FtpParadise::Connection[]
+  # ========================================================================= #
+  def self.[](i = '')
+    new(i)
+  end
+
+  # ========================================================================= #
+  # === chdir                                             (cd tag, chdir tag)
+  # ========================================================================= #
+  def chdir(i)
+    @ftp_object.chdir(i)
+  end; alias cd        chdir # === cd
+       alias remote_cd chdir # === remote_cd
+
+  # ========================================================================= #
+  # === pwd
+  #
+  # Returns the current remote directory.
+  # ========================================================================= #
+  def pwd
+    "#{@ftp_object.pwd}/".squeeze('/')
+  end; alias getdir            pwd # === getdir
+       alias remote_directory? pwd # === remote_directory?
+
+  # ========================================================================= #
+  # === ftp_connection?
+  # ========================================================================= #
+  def ftp_connection?
+    @ftp_object
+  end; alias ftp_object? ftp_connection? # === ftp_object?
+       alias net_ftp?    ftp_connection? # === net_ftp?
+       alias ftp?        ftp_connection? # === ftp?
+       alias ftp         ftp_connection? # === ftp?
+       alias ftp_object  ftp_connection? # === ftp_object
+
+  # ========================================================================= #
+  # === do_login
+  #
+  # This method is responsible for the login-action.
+  #
+  # The method signature for the net-ftp class' .login() is:
+  #
+  #   login(user = "anonymous", passwd = nil, acct = nil)
+  #
+  # This method here accepts a Hash as first argument.
+  #
+  # For official information about .login(), see here:
+  #
+  #   https://ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-login
+  #
+  # ========================================================================= #
+  def do_login(
+      to_this_url          = nil,         # The remote URL.
+      use_this_as_username = username?,   # The login-name.
+      use_this_as_password = password?,   # The password for that user.
+      be_verbose           = be_verbose?
+    )
+    if to_this_url.nil?
+      to_this_url = FtpParadise.remote_url?
+    elsif to_this_url.is_a? Hash
+    end
+    # ======================================================================= #
+    # Rescue nil-passwords here.
+    # ======================================================================= #
+    if use_this_as_password.to_s.empty?
+      use_this_as_password = set_password(:try_to_use_a_default_password)
+    end
+    if be_verbose
+      # ===================================================================== #
+      # Display some info to the user here.
+      # ===================================================================== #
+      e; cliner
+      opnn; e "Using the URL #{royalblue(to_this_url)} (remote FTP host)."
+      e
+      e "  Username: #{slateblue(use_this_as_username)}"
+      e "  Password: #{slateblue(use_this_as_password)}"
+      e
+      report_transfer_mode_in_use
+      e
+      cliner
+    end
+    if ftp_object?.nil? and !to_this_url.nil?
+      initialize_a_new_net_ftp_object_with_this_url(to_this_url)
+    end
+    use_this_as_username = use_this_as_username.to_s
+    # ======================================================================= #
+    # The following code must be rescued because the login() method
+    # may fail in various ways.
+    # ======================================================================= #
+    begin
+      ftp_object?.login(
+        use_this_as_username,
+        use_this_as_password
+      )
+      # =================================================================== #
+      # Next, assign towards the toplevel reference to the ftp-connection.
+      # =================================================================== #
+      sync_ftp_object_onto_the_main_namespace if ftp_object?
+      if be_verbose and is_connected?
+        e
+        cliner {
+          e "- #{sfancy('Successfully')} logged into "\
+            "the remote FTP host at `#{simp(to_this_url)}`"
+        }
+      end
+    rescue Net::FTPPermError => error
+      opnn; e "We could not connect and login to `#{sfancy(to_this_url)}`."
+      opnn; e 'It may be that you lack the proper permissions.'
+      opnn; e 'This may happen because the user/password combination was'
+      opnn; e 'incorrect. User and password combination will be shown next:'
+      show_user_and_password
+      opnn; e "Feedbacking that error next, of class #{error.class.to_s}:"
+      opnn; e orange(error.to_s)
+    rescue Net::FTPConnectionError => error
+      opnn; e 'We do not seem to be connected. An error happened.'
+      pp error
+      pp error.class
+    end
+  end; alias do_connect do_login # === do_connect
+       alias connect_to do_login # === connect_to
+       alias connect    do_login # === connect
+       alias login      do_login # === login
+       alias login_to   do_login # === login_to
+       alias reconnect  do_login # === reconnect
+
+  # ========================================================================= #
+  # === remove_remote_file
+  #
+  # Remove a (remote) file, via the delete() method of the FTP protocol.
+  #
+  # Note that this method will only delete files.
+  #
+  # The official documentation for the Ruby-FTP delete() method can be
+  # found here:
+  #
+  #   https://www.ruby-doc.org/stdlib/libdoc/net/ftp/rdoc/Net/FTP.html#method-i-delete
+  #
+  # ========================================================================= #
+  def remove_remote_file(
+      i,
+      be_verbose = be_verbose?
+    )
+    case be_verbose
+    when :be_verbose
+      be_verbose = true
+    end
+    if i.is_a? Array
+      i.each {|entry| remove_remote_file(entry, be_verbose) }
+    else
+      if does_this_remote_file_exist?(File.basename(i))
+        i = File.basename(i)
+        if i =~ /^\d+$/ # if is a number
+          update_file_listing
+          _ = return_remote_file_listing[i.to_i - 1].first
+          _ = File.basename(_)
+          e "Performing a substitution of #{sfancy(i)}"\
+            " to #{simp(_)}."
+          i = _
+        end
+        if be_verbose
+          notify_the_user_about(i, __method__)
+        end
+        ftp_object?.delete(i)
+        update_file_listing
+        return i # Also return the file that was deleted.
+      else
+        opnn; e "No remote file called `#{sfile(i)}` was "\
+                "found at `#{sfancy(remote_pwd)}`."
+      end
+    end
+  end; alias remote_remove           remove_remote_file # === remote_remove
+       alias remote_remove_files     remove_remote_file # === remote_remove_files
+       alias remote_remove_file      remove_remote_file # === remote_remove_files
+       alias delete                  remove_remote_file # === delete
+       alias remove_file             remove_remote_file # === remove_file
+       alias rm_file                 remove_remote_file # === rm_file
+       alias rmfile                  remove_remote_file # === rmfile
+       alias delete_this_remote_file remove_remote_file # === delete_this_remote_file
+
+  # ========================================================================= #
+  # === return_all_remote_files
+  #
+  # This method will return an Array with all remote files.
+  # ========================================================================= #
+  def return_all_remote_files
+    results = []
+    if file_listing?
+      results = file_listing?.select {|entry|
+        if entry.is_a?(String) and !entry.empty?
+          entry = FtpParadise::Entry.new(entry)
+        end
+        entry.is_a_file?
+      }
+    end
+    return results
+  end; alias remote_file_listing?       return_all_remote_files # === remote_file_listing?
+       alias all_remote_files?          return_all_remote_files # === all_remote_files?
+       alias array_remote_files         return_all_remote_files # === array_remote_files
+       alias return_remote_files        return_all_remote_files # === return_remote_files
+       alias return_remote_file_listing return_all_remote_files # === return_remote_file_listing
+       alias remote_files?              return_all_remote_files # === remote_files
+       alias files?                     return_all_remote_files # === files?
+
+  # ========================================================================= #
+  # === open?
+  #
+  # This method can also be used to determine whether we are still
+  # connected to the remote site.
+  #
+  # This method will return true if the connection is open.
+  #
+  # If you want to determine whether you are still connected to the
+  # remote host, you can alias use the alias are_we_connected? - it
+  # may read nicer.
+  # ========================================================================= #
+  def open?
+    !closed?
+  end; alias are_we_connected? open? # === are_we_connected?
+       alias is_connected?     open? # === is_connected?
+       alias is_connected      open? # === is_connected
+       alias connected?        open? # === connected?
+       alias did_we_connect?   open? # === did_we_connect?
+
+  # ========================================================================= #
+  # === status?
+  #
+  # Report the status here. This is equivalent to the STAT command.
+  # ========================================================================= #
+  def status?
+    ftp_object?.status.to_s
+  end; alias status         status? # === status
+       alias remote_status? status? # === remote_status?
+
+  # ========================================================================= #
+  # === initialize_a_new_net_ftp_object_with_this_remote_url
+  #
+  # This method is the only one allowed to create a new Net::FTP instance.
+  # ========================================================================= #
+  def initialize_a_new_net_ftp_object_with_this_remote_url(i)
+    @ftp_object = Net::FTP.new(i) # ftp = Net::FTP.new(YAML.load_file(ENV['FTP_YAML_FILE'])['freehosting']['url'])
+  end; alias initialize_a_new_net_ftp_object               initialize_a_new_net_ftp_object_with_this_remote_url # === initialize_a_new_net_ftp_object
+       alias initialize_a_new_net_ftp_object_with_this_url initialize_a_new_net_ftp_object_with_this_remote_url # === initialize_a_new_net_ftp_object_with_this_url
+
+  # ========================================================================= #
+  # === connect_via_this_dataset
+  # ========================================================================= #
+  def connect_via_this_dataset(hash)
+    set_data(hash)
+    if ::FtpParadise.remote_host?.nil? and hash.has_key?(:remote_url)
+      ::FtpParadise.set_remote_host(hash[:remote_url])      
+    end
+    do_login(FtpParadise.remote_url?)
+  end
+
+  # ========================================================================= #
+  # === set_data                                   (all in one, set_data tag)
+  #
+  # This method sets:
+  #
+  #   - host
+  #   - user name
+  #   - port and
+  #   - password
+  #
+  # This method is thus a nifty little convenience method. You can pass
+  # a hash to it too, which is the recommended way to use this method.
+  #
+  # You can also use an Array (with 4 elements), in which case we will
+  # process it one after the other. The reason for this procedure is
+  # because we can also use yaml files that way, that also use the
+  # exact order of elements.
+  #
+  # If you add a new entry to the case menu below, also add this to 
+  # ARRAY_AVAILABLE_HOSTS, please. That Array can be found in the
+  # file 'constants/roebe_ftp_constants.rb'.
+  # ========================================================================= #
+  def set_data(
+      i = 'default'
+    ) # set the default here.
+    if debug?
+      opnn; e 'We will debug next, as the @debug variable was set to true.'
+      pp i
+    end
+    # ======================================================================= #
+    # === Handle Hash as input first
+    # ======================================================================= #
+    if i.is_a? Hash # Hash is treated differently.
+
+      # ===================================================================== #
+      # === :host
+      # ===================================================================== #
+      if   i.has_key? :host
+        set_host i.fetch(:host)
+      # ===================================================================== #
+      # === :remote_host
+      # ===================================================================== #
+      elsif i.has_key? :remote_host
+        set_host i.fetch(:remote_host)
+      elsif i.has_key? :to # :to is an alias to :host.
+        set_host i.fetch(:to)
+      elsif i.has_key? :remote_url
+        set_host i.fetch(:remote_url)
+      end      
+
+      # ===================================================================== #
+      # === :user_name
+      # ===================================================================== #
+      if    i.has_key? :user_name
+        set_user_name i.fetch(:user_name)
+      elsif i.has_key? :login_name
+        set_user_name i.fetch(:login_name)
+      end
+
+      # ===================================================================== #
+      # === :password
+      # ===================================================================== #
+      if i.has_key? :password
+        set_password i.fetch(:password)
+      # ===================================================================== #
+      # === :login_password
+      # ===================================================================== #
+      elsif i.has_key? :login_password
+        set_password i.fetch(:login_password)
+      end
+
+      # ===================================================================== #
+      # === :port
+      # ===================================================================== #
+      if i.has_key? :port
+        set_port i.fetch(:port)
+      end
+    # ======================================================================= #
+    # === Handle Array as input next
+    # ======================================================================= #
+    elsif i.is_a? Array # Example-Array: ["ftp.byethost33.com", "b33_14144659", "1aaaaaa", 21]
+      set_host      i.first
+      set_user_name i[1]
+      set_password  i[2]
+      set_port      i[3]
+    # ======================================================================= #
+    # === Else, use simple toggle commands, such as 1,2,3,4,5 and so forth.
+    # ======================================================================= #
+    else # In the following case menu you can toggle your FTP.
+      case i.to_s # Work on strings only. Assumes shortcuts as well.
+      # ===================================================================== #
+      # === bplaced
+      # ===================================================================== #
+      when '1',
+           'bplaced',
+           /shevy/i,
+           'default',
+           'top' # Current default.
+        dataset = YAML.load_file(FILE_ROEBE_FTP)['bplaced']
+        set_host      dataset['host']
+        set_user_name dataset['user_name']
+        set_password  dataset['password']
+        set_port      dataset['port']
+      # ===================================================================== #
+      # === shevy
+      #
+      # This defaults to my home system.
+      # ===================================================================== #
+      when '2',
+           'square',
+           'square7',
+           'podserver'
+        _ = FILE_ROEBE_FTP
+        if File.exist? _
+          data = YAML.load_file(_)['bplaced']
+          set_host      data['url']
+          set_user_name data['user_name']
+          this_password = data['password']
+          this_password.chop! if this_password.end_with? '_'
+          set_password  this_password
+          set_port      data['port']
+        end
+      # ===================================================================== #
+      # === a1
+      # ===================================================================== #
+      when '3',
+           'a1',
+           'a1_ftp' # A1 FTP host. No longer in use but still kept.
+        set_host      A1.first
+        set_user_name A1[1]
+        set_password  A1[2]
+        set_port      A1[3]
+      # ===================================================================== #
+      # === zymix
+      # ===================================================================== #
+      when '4',
+           'zymix',
+           'standard'
+        set_host      ZYMIX.first
+        set_user_name ZYMIX[1]
+        set_password  ZYMIX[2]
+        set_port      ZYMIX[3]
+      # ===================================================================== #
+      # === uniwien
+      # ===================================================================== #
+      when '5',
+           'univie',
+           'uniwien' # Uni Wien FTP Account.
+        set_host      UNIVIE.first
+        set_user_name UNIVIE[1]
+        set_password  UNIVIE[2]
+        set_port      UNIVIE[3]
+      # ===================================================================== #
+      # === byte
+      # ===================================================================== #
+      when '6',
+           'byte',
+           'bytehost'
+        dataset = YAML.load_file(FILE_ROEBE_FTP)['bytehost']
+        set_host      dataset['host']
+        set_user_name dataset['user_name']
+        set_password  dataset['password']
+        set_port      dataset['port']
+      else
+        set_data(:default) # Go back to default again if not found.
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === upload_this_local_file
+  # ========================================================================= #
+  def upload_this_local_file(i)
+    i = i.join if i.is_a? Array
+    ftp_connection?.putbinaryfile(i)
+  end; alias putbinaryfile upload_this_local_file # === putbinaryfile
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    do_connect
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  if FtpParadise.is_on_roebe?
+    FtpParadise::Connection.new(ARGV) { :use_default_dataset }
+  else
+    FtpParadise::Connection.new(ARGV)
+  end
+end # connection.rb