extracter 1.2.32

data/lib/extracter/class/extracter.rb

@@ -0,0 +1,1069 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Extracter::Extracter
+#
+# The primary purpose of this class is to abstract extracting source files
+# to a target location. You just pass the argument of the file that has
+# to be extracted to this class, and it should handle the rest.
+#
+# The class can be used to "extract" audio files as well, by calling the
+# module ExtractAudio, which is part of MultimediaParadise. You can try
+# this - just pass a .mp4 file as first argument to this class. Make sure
+# to have installed that gem before, via: gem install multimedia_paradise
+#
+# Usage examples:
+#
+#   Extracter::Extracter.new(ARGV)
+#   Extracter.new('foo.mp3')
+#   Extracter.new('xyz-1.0.tar.gz')
+#
+# =========================================================================== #
+# require 'extracter/class/extracter.rb'
+# =========================================================================== #
+require 'extracter/base/base.rb'
+
+module Extracter
+
+class Extracter < ::Extracter::Base # === Extracter::Extracter
+
+  require 'fileutils'
+  require 'extracter/toplevel_methods/is_this_a_valid_archive.rb'
+  require 'extracter/toplevel_methods/misc.rb'
+  require 'extracter/version/version.rb'
+  require 'extracter/class/extract_this_archive.rb'
+
+  begin
+    require 'opn'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === SHOW_ONLY_THE_SHORT_NAME_OF_THE_ARCHIVE
+  #
+  # If this constant is set to true then we will only show the shortened
+  # name of the archive in question by default.
+  # ========================================================================= #
+  SHOW_ONLY_THE_SHORT_NAME_OF_THE_ARCHIVE = true
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument to this method should be the archive that the user
+  # wants to extract. This must be a (locally) existing archive, such as
+  # foobar.tar.xz or something similar.
+  #
+  # The second argument to this method, called `extract_to`, specifies the
+  # target location, where this class will extract the archive into, if
+  # available. Some keywords and shortcuts exist for this option - for
+  # instance, TEMP means $MY_TEMP, which can be set by the user.
+  #
+  # Specific usage example in pure Ruby:
+  #
+  #   x = Extracter.what_to('pry-0.9.9.4.gem', '/home/Temp')
+  #
+  # ========================================================================= #
+  def initialize(
+      commandline_arguments = ARGV,
+      extract_to            = nil,
+      run_already           = true,
+      &block
+    )
+    register_sigint
+    reset
+    @internal_hash[:run_already] = run_already
+    set_commandline_arguments(
+      commandline_arguments
+    )
+    if debug? # Some debug-information in this case.
+      e "The first argument what is:       `#{commandline_arguments}`"
+      e "The second argument where_to is:  `#{extract_to}`"
+    end
+    case run_already
+    # ======================================================================= #
+    # === :dont_run_yet
+    # ======================================================================= #
+    when :dont_run_yet,
+         :do_not_run_yet,
+         :default
+      @internal_hash[:run_already] = false
+    end
+    set_extract_to(extract_to) if extract_to
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      case yielded
+      # ===================================================================== #
+      # === :be_silent
+      # ===================================================================== #
+      when :be_silent,
+           :be_quiet
+        do_be_quiet
+      # ===================================================================== #
+      # === :dont_run_yet
+      # ===================================================================== #
+      when :dont_run_yet,
+           :do_not_run_yet,
+           :default
+        @internal_hash[:run_already] = false
+      # ===================================================================== #
+      # === :show_the_full_name_of_the_archive
+      # ===================================================================== #
+      when :show_the_full_name_of_the_archive
+        do_show_the_full_name_of_the_archive
+      end
+    end
+    run if run_already?
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === :try_to_use_colours
+    # ======================================================================= #
+    @internal_hash[:try_to_use_colours] = true
+    # ======================================================================= #
+    # === :colour_to_use_for_directories
+    # ======================================================================= #
+    @internal_hash[:colour_to_use_for_directories] = 'cyan'
+    # ======================================================================= #
+    # === :use_opn
+    # ======================================================================= #
+    @internal_hash[:use_opn] = true # ← Whether to use make use of Opn by default or not.
+    # ======================================================================= #
+    # === :show_the_full_name_of_the_archive
+    # ======================================================================= #
+    @internal_hash[:show_the_full_name_of_the_archive] = false
+    # ======================================================================= #
+    # === :debug
+    # ======================================================================= #
+    @internal_hash[:debug] = false
+    # ======================================================================= #
+    # === :append_this_to_the_commandline
+    #
+    # This variable can always be used to append onto the commandline.
+    # That way we can pass additional options to "tar", for instance.
+    # ======================================================================= #
+    @internal_hash[:append_this_to_the_commandline] = ''.dup
+    # ======================================================================= #
+    # === :namespace
+    #
+    # Specify the main namespace to be used. This setting can be modified
+    # at "runtime".
+    # ======================================================================= #
+    @internal_hash[:namespace] = NAMESPACE
+    # ======================================================================= #
+    # === :be_verbose
+    # ======================================================================= #
+    @internal_hash[:be_verbose] = true
+    # ======================================================================= #
+    # === :show_the_name
+    #
+    # If this variable is true then the name of the class will be shown
+    # on the commandline, via opn().
+    # ======================================================================= #
+    @internal_hash[:show_the_name] = false
+    # ======================================================================= #
+    # === :show_only_the_short_name_of_the_archive
+    # ======================================================================= #
+    @internal_hash[:show_only_the_short_name_of_the_archive] =
+      SHOW_ONLY_THE_SHORT_NAME_OF_THE_ARCHIVE
+    # ======================================================================= #
+    # === :run_simulation
+    # ======================================================================= #
+    @internal_hash[:run_simulation] = false # ← Whether to run in simulation, or for "real".
+    # ======================================================================= #
+    # === :extract_to
+    # ======================================================================= #
+    @internal_hash[:extract_to] = return_pwd
+    do_show_name # We will show the name usually.
+    prepare_the_hash_for_opn
+    # ======================================================================= #
+    # === :use_colours
+    # ======================================================================= #
+    enable_colours
+  end
+
+  # ========================================================================= #
+  # === do_not_show_name
+  #
+  # Tells us whether to use opn() or not.
+  # ========================================================================= #
+  def do_not_show_name
+    @internal_hash[:show_the_name] = false
+  end
+
+  # ========================================================================= #
+  # === show_the_name?
+  # ========================================================================= #
+  def show_the_name?
+    @internal_hash[:show_the_name]
+  end
+
+  # ========================================================================= #
+  # === check_whether_rar_is_available
+  #
+  # We try to find out whether unrar is available.
+  # ========================================================================= #
+  def check_whether_rar_is_available
+    is_available = false
+    ENV['PATH'].split(':').each {|entry|
+      is_available = true if File.exist? "#{entry}/unrar"
+    }
+    unless is_available
+      copn; e 'Sorry, unrar is not available. Please install it first.'
+    end
+  end
+
+  # ========================================================================= #
+  # === debug?
+  # ========================================================================= #
+  def debug?
+    @internal_hash[:debug]
+  end
+
+  # ========================================================================= #
+  # === run_already?
+  # ========================================================================= #
+  def run_already?
+    @internal_hash[:run_already]
+  end
+
+  # ========================================================================= #
+  # === enable_debug
+  # ========================================================================= #
+  def enable_debug
+    @internal_hash[:debug] = true
+  end
+
+  # ========================================================================= #
+  # === return_pwd
+  # ========================================================================= #
+  def return_pwd
+    "#{Dir.pwd}/".squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === set_use_opn
+  # ========================================================================= #
+  def set_use_opn(i = true)
+    @internal_hash[:use_opn] = i
+  end
+
+  # ========================================================================= #
+  # === use_opn?
+  # ========================================================================= #
+  def use_opn?
+    @internal_hash[:use_opn]
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = '')
+    i = [i].flatten.compact
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first? first_argument? # === first?
+
+  # ========================================================================= #
+  # === padded_extract_to?
+  # ========================================================================= #
+  def padded_extract_to?
+    " -C #{extract_to?} "
+  end
+
+  # ========================================================================= #
+  # === set_colour_for_directories
+  #
+  # Set the colour for directories to use.
+  # ========================================================================= #
+  def set_colour_for_directories(i)
+    @internal_hash[:colour_to_use_for_directories] = ::Colours.beautify(i)
+  end
+
+  # ========================================================================= #
+  # === extract_to?
+  #
+  # Note that this method is guaranteed to return a String.
+  # ========================================================================= #
+  def extract_to?
+    @internal_hash[:extract_to].to_s
+  end; alias source_package_location   extract_to? # === source_package
+       alias extract_to_this_location? extract_to? # === extract_to_this_location?
+       alias extracted_to?             extract_to? # === extracted_to?
+       alias extracted_path?           extract_to? # === extracted_path?
+
+  # ========================================================================= #
+  # === opnn
+  #
+  # This variant will also check whether we should show the name or not.
+  # ========================================================================= #
+  def opnn(
+      use_this_hash = use_this_opn_hash?
+    )
+    if use_opn? and Object.const_defined?(:Opn) and show_the_name?
+      Opn.opn(use_this_hash)
+    end
+  end; alias opn  opnn # === opn
+       alias copn opnn # === copn
+  
+  # ========================================================================= #
+  # === use_this_opn_hash?
+  # ========================================================================= #
+  def use_this_opn_hash?
+    @internal_hash[:use_this_opn_hash]
+  end; alias main_hash? use_this_opn_hash? # === main_hash?
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # This method will show the available - and documented - help options
+  # for class Extracter.
+  #
+  # To call this method via the commandline try:
+  #
+  #   extract --help
+  #
+  # ========================================================================= # 
+  def show_help
+    e
+    opnn; e 'How to extract archives, without helper scripts?'
+    e
+    e '  tar -zxvf foobar.tar.gz                                        # for .tar.gz'
+    e '  tar xvzf foobar.tgz                                            # for .tgz'
+    e '  tar xvfJ foobar.tar.xz                                         # for .tar.xz'
+    e '  tar jxf foobar.tar.bz2                                         # for .tar.bz2'
+    e '  tar -xf foobar.tar.bz2                                         # for .tbz'
+    e '  tar --lzip -xvf zutils-1.5.tar.lz                              # for .tar.lz'
+    e '  unsquashfs foobar-1.2.3.sxz                                    # for .sxz'
+    e '  7z x -so C:\home\x\src\htop\htop-3.0.5.tar.xz | 6z x -si -ttar # on windows'
+    e
+    opnn; e 'Furthermore, there are some commandline options '\
+            'that can'
+    opnn; e 'be used for this class (class Extracter).'
+    e
+    e '  --to=/home/Temp # extract into the '\
+      'directory /home/Temp/'
+    e
+  end
+
+  # ========================================================================= #
+  # === pad                                                         (pad tag)
+  #
+  # This method must be able to deal with ' ' as well as with '()'.
+  #
+  # The second character is the character that will be used for the
+  # padding.
+  # ========================================================================= #
+  def pad(
+      i, with_this_character = "'"
+    )
+    if i.include?('(') or i.include?(')')
+      i.tr!('(','\(')
+      i.tr!(')','\)') if i.include? ')'
+      i = pad(i, '"')
+    else
+      return with_this_character+
+             i+
+             with_this_character
+    end
+  end
+
+  # ========================================================================= #
+  # === namespace?
+  # ========================================================================= #
+  def namespace?
+    @internal_hash[:namespace]
+  end
+
+  # ========================================================================= #
+  # === set_be_verbose
+  #
+  # This sets the verbosity level of the class. Use only this method
+  # when you wish to modify the @be_verbose instance variable.
+  # ========================================================================= #
+  def set_be_verbose(i = false)
+    @internal_hash[:be_verbose] = i
+  end; alias set_verbosity set_be_verbose # === set_verbosity
+
+  # ========================================================================= #
+  # === be_verbose?
+  #
+  # Getter method for whether we will be verbose or not.
+  # ========================================================================= #
+  def be_verbose?
+    @internal_hash[:be_verbose]
+  end
+
+  # ========================================================================= #
+  # === register_sigint
+  # ========================================================================= #
+  def register_sigint
+    Signal.trap('SIGINT') {
+      e sfancy('Requesting a graceful exit from ')+
+        colour_to_use_for_directories?+
+        'class Extracter'+
+        sfancy('. Exiting now.')
+      exit
+    }
+  end
+
+  # ========================================================================= #
+  # === colour_to_use_for_directories?
+  # ========================================================================= #
+  def colour_to_use_for_directories?
+    if use_colours?
+      return @internal_hash[:colour_to_use_for_directories]
+    else
+      return ''
+    end
+  end
+
+  # ========================================================================= #
+  # === do_show_the_full_name_of_the_archive
+  # ========================================================================= #
+  def do_show_the_full_name_of_the_archive
+    @internal_hash[:show_the_full_name_of_the_archive] = true
+  end
+
+  # ========================================================================= #
+  # === prefix_namespace_with
+  # ========================================================================= #
+  def prefix_namespace_with(i)
+    @internal_hash[:namespace] = "#{i}#{@internal_hash[:namespace].dup}"
+    update_the_main_hash # Also update the opn-hash here.
+  end
+
+  # ========================================================================= #
+  # === pad_opn_with_n_tokens
+  # ========================================================================= #
+  def pad_opn_with_n_tokens(n_tokens = nil)
+    if n_tokens
+      determine_default_opn_hash # Update this, just in case.
+      main_hash?.update(padding: n_tokens)
+    end
+  end; alias set_pad_opn_with_n_tokens pad_opn_with_n_tokens # === set_pad_opn_with_n_tokens
+
+  # ========================================================================= #
+  # === prepare_the_hash_for_opn
+  # ========================================================================= #  
+  def prepare_the_hash_for_opn(
+      use_this_hash = {
+        namespace:   namespace?,
+        use_colours: use_colours?
+      }
+    )
+    # ======================================================================= #
+    # === :use_this_opn_hash
+    # ======================================================================= #
+    @internal_hash[:use_this_opn_hash] = use_this_hash
+    return @internal_hash[:use_this_opn_hash]
+  end; alias update_the_opn_hash            prepare_the_hash_for_opn # === update_the_opn_hash
+       alias determine_default_opn_hash     prepare_the_hash_for_opn # === determine_default_opn_hash
+       alias determine_the_default_opn_hash prepare_the_hash_for_opn # === determine_the_default_opn_hash
+       alias update_the_main_hash           prepare_the_hash_for_opn # === update_the_main_hash
+
+  # ========================================================================= #
+  # === show_only_the_short_name_of_the_archive?
+  # ========================================================================= #
+  def show_only_the_short_name_of_the_archive?
+    @internal_hash[:show_only_the_short_name_of_the_archive]
+  end
+
+  # ========================================================================= #
+  # === set_run_simulation
+  # ========================================================================= #
+  def set_run_simulation(i = false) # false is the default here.
+    @internal_hash[:run_simulation] = i
+  end
+
+  # ========================================================================= #
+  # === run_simulation=
+  # ========================================================================= #
+  def run_simulation=(i)
+    @internal_hash[:run_simulation] = i
+  end
+
+  # ========================================================================= #
+  # === run_simulation?
+  # ========================================================================= #
+  def run_simulation?
+    @internal_hash[:run_simulation]
+  end
+
+  # ========================================================================= #
+  # === strip_components
+  #
+  # The first argument to this method will determine how far "down" tar
+  # will strip the components.
+  # ========================================================================= #
+  def strip_components(
+      by_n = 1
+    )
+    @internal_hash[:append_this_to_the_commandline] <<
+      " --strip-components=#{by_n}"
+  end
+
+  # ========================================================================= #
+  # === do_show_name
+  #
+  # If this method is called then the class here will show the name of
+  # the file on the commandline, via opn().
+  # ========================================================================= #
+  def do_show_name
+    @internal_hash[:show_the_name] = true
+  end
+
+  # ========================================================================= #
+  # === enable_colours
+  # ========================================================================= #
+  def enable_colours
+    set_use_colours(true)
+    @internal_hash[:colour_to_use_for_directories] = cyan?
+  end
+
+  # ========================================================================= #
+  # === disable_colours
+  #
+  # Use this method if you want to disable colour-support of this class.
+  # ========================================================================= #
+  def disable_colours
+    set_use_colours(false)
+    @internal_hash[:colour_to_use_for_directories] = ''.dup
+  end
+
+  # ========================================================================= #
+  # === set_use_colours
+  # ========================================================================= #
+  def set_use_colours(i)
+    # ======================================================================= #
+    # We must also sync this towards our main Hash, for opn(). The next
+    # line of code achieves precisely that.
+    # ======================================================================= #
+    main_hash?.update(use_colours: i)
+    @internal_hash[:try_to_use_colours] = i
+  end
+
+  # ========================================================================= #
+  # === try_to_use_colours?
+  # ========================================================================= #
+  def try_to_use_colours?
+    @internal_hash[:try_to_use_colours]
+  end
+
+  # ========================================================================= #
+  # === remove_file_extension
+  # ========================================================================= #
+  def remove_file_extension(i)
+    _ = File.basename(i)
+    return ::Extracter.remove_archive_type(_)
+  end; alias remove_extension remove_file_extension # === remove_extensions
+       alias remove_ext       remove_file_extension # === remove_ext
+
+  # ========================================================================= #
+  # === rds
+  # ========================================================================= #
+  def rds(i)
+    return i.squeeze('/') if i.respond_to? :squeeze
+    return i
+  end
+
+  # ========================================================================= #
+  # === set_extract_to
+  #
+  # This is the method that should be used to determine into which
+  # directory this class will extract archives into.
+  #
+  # Note that this target can be modified from the commandline, if
+  # the user wants to do so.
+  # ========================================================================= #
+  def set_extract_to(
+      i = :temp_dir
+    )
+    if i.is_a?(Hash) and i.empty?
+      i = :temp_dir
+    end
+    if i.is_a? Hash
+      # ===================================================================== #
+      # === :run_already
+      # ===================================================================== #
+      if i.has_key? :run_already
+        @internal_hash[:run_already] = i.delete(:run_already)
+      end
+      # ===================================================================== #
+      # === :prepend_this_namespace
+      # ===================================================================== #
+      if i.has_key? :prepend_this_namespace
+        prefix_with_this = i.delete(:prepend_this_namespace) # Get rid of it from the Hash as well.
+        prefix_namespace_with(prefix_with_this)
+      end
+      # ===================================================================== #
+      # === :use_colours
+      # ===================================================================== #
+      if i.has_key? :use_colours
+        set_use_colours(i.delete(:use_colours))
+      end
+      # ===================================================================== #
+      # === :verbosity
+      #
+      # Handle how verbose the class shall be.
+      # ===================================================================== #
+      if i.has_key? :verbosity
+        set_be_verbose(i.delete(:verbosity))
+      # ===================================================================== #
+      # === :be_verbose
+      # ===================================================================== #
+      elsif i.has_key? :be_verbose
+        set_be_verbose(i.delete(:be_verbose))
+      end
+      # ===================================================================== #
+      # === :append_this_to_the_commandline
+      # ===================================================================== #
+      if i.has_key? :append_this_to_the_commandline
+        @internal_hash[:append_this_to_the_commandline] = 
+          i.delete(:append_this_to_the_commandline)
+      end
+      # ===================================================================== #
+      # === :use_opn
+      # ===================================================================== #
+      if i.has_key? :use_opn
+        set_use_opn(i.delete(:use_opn))
+      end
+      # ===================================================================== #
+      # === :pad_opn_with_n_tokens
+      # ===================================================================== #
+      if i.has_key? :pad_opn_with_n_tokens
+        set_pad_opn_with_n_tokens(i.delete(:pad_opn_with_n_tokens))
+      end
+      # ===================================================================== #
+      # === :run_simulation
+      # ===================================================================== #
+      if i.has_key? :run_simulation
+        set_run_simulation(i.delete(:run_simulation))
+      end
+      # ===================================================================== #
+      # === :use_colours
+      # ===================================================================== #
+      if i.has_key? :use_colours
+        set_use_colours(i.delete(use_colours))
+      end
+      # ===================================================================== #
+      # === :extract_to
+      #
+      # This entry point allows the user to specify another extract-to
+      # directory. Note that :to is treated the same way as :extract_to.
+      #
+      # This entry point must come last. The idea is that it will then
+      # become the new value for i.
+      # ===================================================================== #
+      if i.has_key? :extract_to
+        i = i.delete(:extract_to)
+      # ===================================================================== #
+      # === :to
+      # ===================================================================== #
+      elsif i.has_key? :to
+        i = i.delete(:to)
+      end
+    end
+    case i # case tag
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default
+      i = return_pwd
+    # ======================================================================= #
+    # === TEMP
+    # ======================================================================= #
+    when 'TEMP',
+         'MY_TEMP',
+         'MYTEMP',
+         :temp_dir,
+         nil
+      i = TEMP_DIR
+    end
+    i = rds(i)
+    i.gsub!(/--to=/,'') if i.include? '--to='
+    i = i.to_s.dup # We expect a String most definitely.
+    @internal_hash[:extract_to] = i
+  end; alias set_extract_to_this_location set_extract_to # === set_extract_to_this_location
+       alias extract_to=                  set_extract_to # === extract_to=
+       alias extract_to                   set_extract_to # === extract_to
+
+  # ========================================================================= #
+  # === try_to_extract_this_iso_file
+  # ========================================================================= #
+  def try_to_extract_this_iso_file(i)
+    opnn; e 'Extracting an .iso file is a bit more complicated '\
+            'than extracting a .tar.gz tarball'
+    opnn; e 'archive. This class will first create a helper '\
+            'directory; then mount the .iso there,'
+    opnn; e 'then copy the content to the main directory.'
+    helper_directory = File.dirname(i)+
+                       '/READ_ONLY_DIRECTORY_'+
+                       File.basename(
+                         i.delete_suffix(File.extname(i))
+                       )+
+                       '/'
+    mkdir(helper_directory) unless File.directory? helper_directory
+    esystem 'mount -o loop '+i+' '+helper_directory
+    e 'The helper directory in use is '\
+      '`'+sdir(File.absolute_path(helper_directory))+'`.'
+    main_directory = File.dirname(i)+
+                     '/'+
+                     File.basename(
+                       i.delete_suffix(File.extname(i))
+                     )+
+                     '/'
+    e 'Next creating the main directory at `'+sdir(main_directory)+'`.'
+    mkdir(main_directory) unless File.directory? main_directory
+    e 'Next copying the content of the helper directory recursively '
+    e 'from `'+sdir(helper_directory)+'`'
+    e 'onto `'+sdir(
+      main_directory+File.basename(helper_directory)+'/'
+    )+'`.'
+    cpr(
+      helper_directory,
+      main_directory+File.basename(helper_directory)+'/'
+    )
+    a = main_directory+File.basename(helper_directory)+'/'
+    e 'Relocating the files next from:'
+    e
+    e "  #{sdir(a)}"
+    e
+    Dir[a+'*'].each {|entry|
+      mv(
+        entry,
+        main_directory
+      )
+    }
+    # ======================================================================= #
+    # And remove the directory:
+    # ======================================================================= #
+    remove_this_directory(a)
+    e 'The content of the extracted (or rather, mounted) archive is:'
+    e
+    pp Dir["#{main_directory}*"]
+    e
+  end
+
+  # ========================================================================= #
+  # === work_on_the_given_input
+  # ========================================================================= #
+  def work_on_the_given_input(
+      array      = commandline_arguments?,
+      extract_to = extract_to?
+    )
+    # ======================================================================= #
+    # If the user supplied a directory then a random entry will be grabbed
+    # from said directory.
+    # ======================================================================= #
+    if array.is_a?(String) and File.directory?(array)
+      array = Dir[rds("#{array}/")+'*'].sample
+    end
+    case extract_to
+    when nil
+      extract_to = extract_to?
+    end
+    if array.empty?
+      opnn; e 'No archive (input) was provided. Please provide the file'
+      opnn; e 'that is to be extracted.'
+    else
+      array.each {|this_file|
+        # =================================================================== #
+        # Create the directory if it does not yet exist.
+        # =================================================================== #
+        create_directory(extract_to) unless File.directory?(extract_to)
+        # =================================================================== #
+        # Handle the case when the user did input a number.
+        # =================================================================== #
+        begin
+          if this_file =~ /^\d$/
+            this_file = Dir['*'][( this_file.to_i - 1 )] unless File.exist?(this_file)
+          end
+        rescue ArgumentError => error
+          e 'Error for '+sfancy(this_file)+':'
+          pp error
+        end
+        # =================================================================== #
+        # If the user supplied a directory then a random entry will be
+        # grabbed from said directory.
+        #
+        # Usage example:
+        #
+        #  rubyextracter /home/x/src/htop/
+        #
+        # =================================================================== #
+        if File.directory? this_file
+          this_file = Dir[rds("#{this_file}/")+'*'].sample
+        end
+        extract_this_archive(this_file, extract_to)
+        report_to_the_user(this_file, extract_to)
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === create_directory                                          (mkdir tag)
+  #
+  # Use this to create directories.
+  # ========================================================================= #
+  def create_directory(i)
+    FileUtils.mkdir_p(i) unless File.directory?(i)
+  end; alias mkdir create_directory # === mkdir
+
+  # ========================================================================= #
+  # === notify_the_user_that_this_extension_has_not_been_registered_yet
+  # ========================================================================= #
+  def notify_the_user_that_this_extension_has_not_been_registered_yet(i)
+    opnn; e "The archive at `#{i}` is #{tomato('not')}"
+    opnn; e "registered as a permissive extension."
+    fail_message_not_registered(i)
+  end
+
+  # ========================================================================= #
+  # === fail_message_not_registered
+  #
+  # Output a fail message when the archive format is not registered. 
+  # ========================================================================= #
+  def fail_message_not_registered(i)
+    copn; e "#{rev}Can not extract `#{sfancy(i)}#{rev}` - it is "\
+            "not registered."
+  end
+
+  # ========================================================================= #
+  # === try_to_extract_this_img_file
+  # ========================================================================= #
+  def try_to_extract_this_img_file(i)
+    opnn; e 'Handling a squashfs .img file format next:'
+    name_without_extension = i.delete_suffix(File.extname(i))
+    mkdir(name_without_extension) unless File.directory? name_without_extension
+    esystem "mount -o loop -t squashfs #{i} #{name_without_extension}"
+    e 'The content of the extracted (or rather, mounted) archive is:'
+    pp Dir["#{name_without_extension}*"]
+  end
+
+  # ========================================================================= #
+  # === menu                                                       (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = commandline_arguments?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i
+      # ===================================================================== #
+      # === --help
+      # ===================================================================== #
+      when /^-?-?help$/i
+        show_help
+        exit
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === esystem                                     (system tag, esystem tag)
+  # ========================================================================= #
+  def esystem(
+      i, try_to_use_colours = try_to_use_colours?
+    )
+    i = i.dup if i.frozen?
+    # ======================================================================= #
+    # Next, consider appending something onto the commandline.
+    # ======================================================================= #
+    _ = @internal_hash[:append_this_to_the_commandline]
+    unless _.empty?
+      if i.include? ' '
+        splitted = i.split(' ')
+        splitted[0] << " #{_}"
+        i = splitted.join(' ')
+      else
+        i << " #{_}"
+      end
+    end 
+    if run_simulation?
+      copn; e 'As we are running in simulation mode, the following command '
+      copn; e 'is the one that we would have been used if we were to not run '
+      copn; e 'in simulation mode:'
+      if be_verbose?
+        if try_to_use_colours
+          e steelblue(i)
+        else
+          e i
+        end
+      end
+    else
+      if be_verbose?
+        if try_to_use_colours
+          e steelblue(i)
+        else
+          e i
+        end
+      end
+      # ===================================================================== #
+      # Next, run the sys-command.
+      # ===================================================================== #
+      begin
+        system i
+        # =================================================================== #
+        # We have to rescue here because unrar might not be available and
+        # so on.
+        # =================================================================== #
+      rescue Exception => error
+        e 'An error has happened upon attempting to run this system command:'
+        e
+        e "  #{i}"
+        e
+        pp error
+        e '-----------'
+        pp error.class
+        e '-----------'
+      end
+    end
+  end; alias run_this_system_command esystem # === run_this_system_command
+
+  # ========================================================================= #
+  # === report_to_the_user
+  #
+  # This method reports to the user. Usually this is done only via this
+  # file here though.
+  # ========================================================================= #
+  def report_to_the_user(
+      i,
+      extract_to = extract_to?
+    )
+    if be_verbose?
+      target = extract_to+
+               remove_file_extension(
+                 File.basename(i)
+               )+
+               '/'
+       opnn; e "#{rev}Finished extracting to `"\
+               "#{sdir(target)}#{rev}`." # This is an Array.
+    end
+  end
+
+  # ========================================================================= #
+  # === be_verbose
+  # ========================================================================= #
+  def be_verbose
+    set_be_verbose(true)
+  end
+
+  # ========================================================================= #
+  # === do_be_quiet
+  # ========================================================================= #
+  def do_be_quiet
+    set_be_verbose(false)
+  end; alias be_silent do_be_quiet # === be_silent
+       alias be_quiet  do_be_quiet # === be_quiet
+
+  # ========================================================================= #
+  # === run                                                (run tag, def tag)
+  # ========================================================================= #
+  def run
+    menu
+    work_on_the_given_input
+  end
+
+  # ========================================================================= #
+  # === Extracter::Extracter.extract_this
+  #
+  # This method provides a convenient API to extract something to a 
+  # specified directory, as a class method. It defaults to the
+  # current working directory, as that is by far the most convenient
+  # way to extract a source tarball/archive.
+  #
+  # ========================================================================= #
+  def self.extract_this(
+      i  = ARGV,
+      to = {}, # This may also be a String rather than a Hash.
+      &block
+    )
+    ::Extracter::Extracter.new(ARGV, to, &block)
+  end; self.instance_eval { alias what_to         extract_this } # === Extracter::Extracter.what_to
+       self.instance_eval { alias extract         extract_this } # === Extracter::Extracter.extract
+       self.instance_eval { alias extract_what_to extract_this } # === Extracter::Extracter.extract_what_to
+
+  # ========================================================================= #
+  # === Extracter::Extracter[]
+  # ========================================================================= #
+  def self.[](i = ARGV, extract_where_to = Dir.pwd)
+    new(i, extract_where_to)
+  end
+
+end
+
+# ========================================================================= #
+# === Extracter.extract_what_to
+#
+# Useage example goes like this:
+#
+#   Extracter.extract_what_to('foo-1.0.tar.xz', '/tmp')
+#   Extracter.extract_what_to('/Depot/jjjj/tesseract-5.1.0.tar.xz', Dir.pwd+'/')
+#
+# ========================================================================= #
+def self.extract_what_to(
+    what        = ARGV,
+    extract_to  = :default, # ← This can also be a Hash. It denotes where we want to extract to.
+    run_already = true, # :do_not_run_yet,
+    &block
+  )
+  _ = ::Extracter::Extracter.new(
+        what,
+        extract_to,
+        run_already,
+        &block
+      )
+  return _ # We must return the class, as other projects may depend on this.
+end; self.instance_eval { alias extract_this extract_what_to } # === Extracter.extract_this
+     self.instance_eval { alias extract      extract_what_to } # === Extracter.extract
+     self.instance_eval { alias what_to      extract_what_to } # === Extracter.what_to
+     self.instance_eval { alias new          extract_what_to } # === Extracter.new
+     self.instance_eval { alias []           extract_what_to } # === Extracter[]
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  _ = Extracter::Extracter.new(ARGV) { :do_not_run_yet }
+  if ARGV.size > 2
+    _ = Extracter::Extracter.new(ARGV, :default) { :do_not_run_yet }
+  else
+    _ = Extracter::Extracter.new(ARGV[0], ARGV[1]) { :do_not_run_yet }
+  end
+  # _.enable_debug
+  _.be_verbose
+  # _.strip_components # This would be equivalent to: --strip-components=1
+  _.run
+end # rubyextracter
+    # extracter
+    # extracter htop-1.0.2.tar.xz
+    # extracter xfig-3.2.5.tar.bz2
+    # extract htop* /Depot/
+    # extract recode-3.7.tar.xz /Depot/
+    # extract qt-4.8.6.tar.xz --to=/home/Temp