extracter 1.1.7

data/lib/extracter/extract_it/extract_it.rb

@@ -0,0 +1,237 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Extracter::ExtractIt
+#
+# If no input was provided to this class, but a .zip file exists in
+# the current working directory, then that .zip file will be used.
+#
+# Usage example:
+#
+#   Extracter::ExtractIt.new(ARGV)
+#
+# =========================================================================== #
+# require 'extracter/extract_it/extract_it.rb'
+# =========================================================================== #
+module Extracter
+
+class ExtractIt # === Extracter::ExtractIt
+
+  begin
+    require 'opn'
+  rescue LoadError; end
+
+  begin
+    require 'remove_file_suffix'
+  rescue LoadError; end
+
+  begin
+    require 'colours'
+    include Colours if Object.const_defined? :Colours
+  rescue LoadError; end
+
+  require 'extracter/extracter.rb'
+
+  # ========================================================================= #
+  # === NAMESPACE
+  # ========================================================================= #
+  NAMESPACE = inspect
+
+  # ========================================================================= #
+  # === ExtractIt::ARRAY_ARCHIVE_TYPES
+  #
+  # Register the available (and handled) archive types here.
+  # ========================================================================= #
+  ARRAY_ARCHIVE_TYPES = %w(
+    .apkg
+    .xz
+    .zip
+    .tar
+    .bz2
+    .7z
+  )
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      optional_set_input = nil,
+      run_already        = true
+    )
+    reset
+    set_input(optional_set_input)
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    @debug = false
+  end
+
+  # ========================================================================= #
+  # === set_input
+  #
+  # We will work on an Array as value to @input, at the end of this
+  # method.
+  # ========================================================================= #
+  def set_input(i = N)
+    case i
+    # ======================================================================= #
+    # === extract_it --help
+    # ======================================================================= #
+    when /-?-?help$/i # Show some help stuff here.
+      e 'We will show a little bit help, then exit.'
+      e
+      e 'To extract .tar.xz, do:'
+      e
+      efancy '  -> tar -xJf *.tar.xz'
+      exit
+    end
+    i = [i] if i.is_a? String # Need an Array.
+    if @debug
+      opn; e 'The input given to us is: `'+sfile(i)+'`'
+    end
+    if i.is_a?(Array) and i.empty?
+      # ===================================================================== #
+      # In this case, try to see if the current directory has a .zip
+      # file. We will use this in that case.
+      # ===================================================================== #
+      is_there_a_zip_file = Dir['*.zip']
+      unless is_there_a_zip_file.empty?
+        use_this_zip_file = is_there_a_zip_file.first
+        notify_the_user_that_no_input_was_given_but_this_file_was_found(use_this_zip_file)
+        i << use_this_zip_file
+      end
+      is_there_at_the_least_one_tar_xz_file = Dir['*.tar.xz']
+      unless is_there_at_the_least_one_tar_xz_file.empty?
+        i << is_there_at_the_least_one_tar_xz_file.first
+      end
+    end
+    @input = i # Should be an array, always.
+  end
+
+  # ========================================================================= #
+  # === be_silent
+  # ========================================================================= #
+  def be_silent
+    @be_silent = true
+  end
+
+  # ========================================================================= #
+  # === be_verbose
+  # ========================================================================= #
+  def be_verbose
+    @be_silent = false
+  end; alias show_commands_used be_verbose # === show_commands_used
+
+  # ========================================================================= #
+  # === notify_the_user_that_no_input_was_given_but_this_file_was_found
+  # ========================================================================= #
+  def notify_the_user_that_no_input_was_given_but_this_file_was_found(
+      this_file
+    )
+    opn; e 'No input was given to '+sfancy(NAMESPACE)+' but a '\
+           '.zip file was'
+    opn; e 'found in this directory ('+sdir(Dir.pwd)+'): '+
+            sfancy(this_file)
+    opn; e 'We will use this zip file.'
+  end
+
+  # ========================================================================= #
+  # === extract_input
+  # ========================================================================= #
+  def extract_input
+    pp @input if @debug
+    @input.each {|entry|
+      to_this_dir = Dir.pwd
+      to_this_dir << '/' unless to_this_dir.end_with? '/'
+      unless File.exist? entry
+        entry = try_to_glob_on(entry)
+      end
+      # ===================================================================== #
+      # Delegate to class Extracter next.
+      # ===================================================================== #
+      Extracter.extract_what_to(
+        entry,
+        to_this_dir,
+        @be_silent
+      )
+      _ = RemoveFileSuffix[entry]
+      if File.exist? entry
+        # =================================================================== #
+        # Must also check whether the extracted directory exists.
+        # =================================================================== #
+        name_of_the_extracted_archive = to_this_dir+_
+        ARRAY_ARCHIVE_TYPES.each {|extension_name|
+          if name_of_the_extracted_archive.include? extension_name
+            quoted = Regexp.quote(extension_name)
+            name_of_the_extracted_archive.sub!(/#{quoted}$/,'')
+          end
+        }
+        if File.exist?(name_of_the_extracted_archive) and
+          # ================================================================= #
+          # The following check ensures that we really have another name
+          # for the extracted directory.
+          # ================================================================= #
+          !(entry == name_of_the_extracted_archive)
+          opn; e "Finished extracting #{sfile(_)} to `#{sdir(to_this_dir)}`."
+        else
+          opn; e "No file called `#{sfile(name_of_the_extracted_archive)}"\
+                 "` appears to exist."
+        end
+      end
+    }
+  end
+
+  # ========================================================================= #
+  # === is_archive?
+  # ========================================================================= #
+  def is_archive?(i)
+    ARRAY_ARCHIVE_TYPES.include?(
+      File.extname(File.basename(i))
+    )
+  end
+
+  # ========================================================================= #
+  # === try_to_glob_on
+  # ========================================================================= #
+  def try_to_glob_on(i)
+    result = Dir["#{i}*"]
+    # ======================================================================= #
+    # Next, sort this result to put archives on the beginning of the Array.
+    # ======================================================================= #
+    result = result.partition {|entry| is_archive?(entry) }
+    result.flatten!
+    unless result.empty?
+      # ===================================================================== #
+      # Ok, we grab the first entry next.
+      # ===================================================================== #
+      i = result.first
+      opn; e "No result could be found for the given input, thus "\
+             "using #{sfancy(i)} instead."
+    end
+    i
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    extract_input
+  end
+
+  # ========================================================================= #
+  # === Extracter::ExtractIt[]
+  # ========================================================================= #
+  def self.[](i = '')
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Extracter::ExtractIt.new(ARGV)
+end # extract_it.rb

data/lib/extracter/extracter.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Extracter
+#
+# The 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.
+#
+# We can also "extract" Audio files, by calling the module ExtractAudio.
+# You can try this - just pass a .mp4 file as first argument to
+# this class.
+#
+# Usage examples for class Extracter:
+#
+#   Extracter.new('foo.mp3')
+#   Extracter.new('xyz-1.0.tar.gz')
+#
+# Usage example:
+#
+#   Extracter.new
+#
+# =========================================================================== #
+# require 'extracter/extracter.rb'
+# =========================================================================== #
+
+# =========================================================================== #
+# Next, load up .rb files that belong to extracter/.
+# =========================================================================== #
+require 'extracter/version/version.rb'
+require 'extracter/constants/constants.rb'
+require 'extracter/class_methods.rb'
+require 'extracter/colours.rb'
+require 'extracter/do_extract_what_to.rb'
+require 'extracter/help.rb'
+require 'extracter/initialize.rb'
+require 'extracter/misc.rb'
+require 'extracter/reset.rb'
+require 'extracter/opn.rb'
+
+module Extracter
+
+class Extracter # === Extracter
+end
+
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # The second argument to Extracter.new is where we will
+  # extract to.
+  if ARGV.size > 2
+    _ = Extracter::Extracter.new(ARGV, :default, false)
+  else
+    _ = Extracter::Extracter.new(ARGV[0], ARGV[1], false)
+  end
+  _.extract_to Dir.pwd unless ARGV[1]
+  # _.enable_debug
+  _.be_verbose
+  _.run
+end # 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

data/lib/extracter/help.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+module Extracter
+
+class Extracter
+
+  # ========================================================================= #
+  # === show_help                                                  (help tag)
+  #
+  # This method will show the available - and documented - help options
+  # for class Extracter.
+  # ========================================================================= # 
+  def show_help
+    e
+    opnn; e 'How to extract archives, without helper scripts?'
+    e
+    opnn; e '  tar -zxvf foobar.tar.gz           # for .tar.gz'
+    opnn; e '  tar xvzf foobar.tgz               # for .tgz'
+    opnn; e '  tar xvfJ foobar.tar.xz            # for .tar.xz'
+    opnn; e '  tar jxf foobar.tar.bz2            # for .tar.bz2'
+    opnn; e '  tar -xf foobar.tar.bz2            # for .tbz'
+    opnn; e '  tar --lzip -xvf zutils-1.5.tar.lz # for .tar.lz'
+    opnn; e '  unsquashfs foobar-1.2.3.sxz       # for .sxz'
+    e
+    opnn; e 'Furthermore, there are some commandline options '\
+            'that can be used for this class (class Extracter).'
+    e
+    opnn; e '  --to=/home/Temp # extract into the '\
+            'directory /home/Temp/'
+    e
+  end
+
+end; end

data/lib/extracter/initialize.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'extracter/initialize.rb'
+# =========================================================================== #
+module Extracter
+
+class Extracter
+
+  # ========================================================================= #
+  # === initialize
+  #
+  # The first argument to this method is the archive that should be extracted.
+  # This must be a (locally) existing archive, such as foobar.tar.xz or
+  # something similar.
+  #
+  # The second argument to this method, called `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', '/Depot/Temp')
+  #
+  # ========================================================================= #
+  def initialize(
+      what        = nil,
+      where_to    = nil, # Where to extract into.
+      run_already = true
+    )
+    register_sigint
+    reset
+    if where_to.is_a? Symbol
+      if where_to.to_s.include? 'dont' # This also covers :dont_run_yet
+        where_to    = nil # This is ok because we expect the user to provide the target location.
+        run_already = false
+      end
+    end
+    if debug? # Some debug-information.
+      e "The first argument what is: `#{what}`"
+      e "The second argument to is:  `#{to}`"
+    end
+    set_source_location(what)
+    set_extract_to(where_to)
+    # ======================================================================= #
+    # === Handle blocks next
+    # ======================================================================= #
+    if block_given?
+      yielded = yield
+      # ===================================================================== #
+      # === Handle Hash input next:
+      # ===================================================================== #
+      if yielded.is_a? Hash
+        if yielded.has_key? :run_already
+          run_already = yielded.delete(:run_already)
+        end
+        # =================================================================== #
+        # === :use_colours
+        # =================================================================== #
+        if yielded.has_key? :use_colours
+          set_use_colours yielded.delete(:use_colours)
+        end
+        if yielded.has_key? :extract_to
+          set_extract_to yielded.delete(:extract_to)
+        end
+        if yielded.has_key? :run_simulation
+          set_run_simulation(yielded.delete(:run_simulation))
+        end
+        if yielded.has_key? :use_opn
+          set_use_opn(yielded.delete(:use_opn))
+        end
+      else
+        case yielded
+        when :dont_run_yet,
+             :do_not_run_yet
+          run_already = false
+        end
+      end
+    end
+    case run_already
+    when :dont_run_yet,
+         :do_not_run_yet
+      run_already = false
+    end
+    run if run_already
+  end
+
+end; end

data/lib/extracter/misc.rb

@@ -0,0 +1,430 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# require 'extracter/misc.rb'
+# =========================================================================== #
+module Extracter
+
+class Extracter # === Extracter
+
+  require 'fileutils'
+
+  begin
+    require 'multimedia_paradise/audio/extract_audio/extract_audio.rb'
+  rescue LoadError; end
+
+  begin
+    require 'remove_file_suffix'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # Shall we run in simulation mode or not.
+  # ========================================================================= #
+  attr_accessor :run_simulation
+
+  # ========================================================================= #
+  # === debug?
+  # ========================================================================= #
+  def debug?
+    @debug
+  end
+
+  # ========================================================================= #
+  # === enable_debug
+  # ========================================================================= #
+  def enable_debug
+    @debug = true
+  end
+
+  # ========================================================================= #
+  # === do_not_show_name
+  #
+  # Tells us whether to use opn() or not.
+  # ========================================================================= #
+  def do_not_show_name
+    @do_not_show_name = true
+  end
+
+  # ========================================================================= #
+  # === do_show_name
+  #
+  # If this is enabled, we will show the name of the file when we invoke
+  # copn().
+  # ========================================================================= #
+  def do_show_name
+    @do_not_show_name = false
+  end
+
+  # ========================================================================= #
+  # === sanitize_input
+  # ========================================================================= #
+  def sanitize_input(i)
+    if i.include? '('
+      i.gsub!(/\(/,'\(')
+      i.gsub!(/\)/,'\)') if i.include? ')'
+      i = pad(i, '"')
+    end
+    return i
+  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
+
+  # ========================================================================= #
+  # === run_simulation?
+  # ========================================================================= #
+  def run_simulation?
+    @run_simulation
+  end
+
+  # ========================================================================= #
+  # === set_run_simulation
+  # ========================================================================= #
+  def set_run_simulation(i)
+    @run_simulation = i
+  end
+
+  # ========================================================================= #
+  # === pad
+  # ========================================================================= #
+  def pad(i, with_this_character = "'")
+    return with_this_character+i+with_this_character
+  end
+
+  # ========================================================================= #
+  # === extract_to?
+  #
+  # Simply output the result of @extract_to_this_location variable.
+  # ========================================================================= #
+  def extract_to?
+    @extract_to_this_location.to_s
+  end; alias source_package_location extract_to? # === source_package
+
+  # ========================================================================= #
+  # === set_source_location
+  #
+  # Use this method to designate the source location of a given (input)
+  # program. In other words - the tarball or archive that must be
+  # extracted. It will however be stored as Array.
+  #
+  # If we pass a hash to this method, we assume that the user wants
+  # to also populate some other values.
+  # ========================================================================= #
+  def set_source_location(i = nil)
+    if i.nil?
+      copn; e 'You should set a file.'
+    end
+    if i.is_a? Array
+      i = i.flatten
+    else
+      i = [i]
+    end # After this point, we will have an Array.
+    case i.first # case tag
+    when /^-?-?help$/i
+      show_help
+      exit
+    end
+    i.map! {|entry| # Iterate over our Array next.
+      # ======================================================================= #
+      # Handle the case when the user did input a number.
+      # ======================================================================= #
+      begin
+        if entry =~ /^\d$/
+          entry = Dir['*'][( entry.to_i - 1 )] unless File.exist?(entry)
+        end
+      rescue ArgumentError => error
+        e 'Error for '+sfancy(entry)+':'
+        pp error
+      end
+      entry = rds(entry.to_s)
+      # ======================================================================= #
+      # Next, find the proper working directory.
+      # ======================================================================= #
+      unless entry.include? '/'
+        entry = rds( (Dir.pwd+'/'+entry) )
+      end
+      # ======================================================================= #
+      # If the user supplied a directory instead, we will randomly grab an
+      # entry from said directory.
+      # ======================================================================= #
+      if File.directory? entry
+        entry = Dir[rds(entry+'/')+'*'].sample
+      end
+      entry
+    } # Sanitize the result, just in case.
+    i = [i] unless i.is_a? Array # Much more convenient to work with an array.
+    @source_location = i
+  end; alias set_what set_source_location # === set_what
+
+  # ========================================================================= #
+  # === source_location?
+  # ========================================================================= #
+  def source_location?
+    @source_location.first
+  end; alias input? source_location? # === input?
+
+  # ========================================================================= #
+  # === did_we_extract_already?
+  #
+  # Whether we already did extract or whether we did not.
+  # ========================================================================= #
+  def did_we_extract_already?
+    @did_we_extract_already
+  end; alias did_we_extract_already did_we_extract_already? # === did_we_extract_already
+
+  # ========================================================================= #
+  # === extract_to_this_location?
+  #
+  # Extract to this location.
+  # ========================================================================= #
+  def extract_to_this_location?
+    @extract_to_this_location
+  end; alias extract_to_this_location extract_to_this_location? # === extract_to_this_location
+
+  # ========================================================================= #
+  # === extracted_to?
+  #
+  # This method is different from extract_to?.
+  #
+  # It will keep track of the directory to where we extracted to
+  # exactly.
+  # ========================================================================= #
+  def extracted_to?
+    rds(
+      extract_to?+
+      File.basename(input?).sub(/\.xz$/,'').sub(/\.gz$/,'').
+                            sub(/\.tar$/,'')+'/'
+    )
+  end; alias extracted_path? extracted_to? # === extracted_path?
+
+  # ========================================================================= #
+  # === namespace?
+  # ========================================================================= #
+  def namespace?
+    @namespace
+  end
+
+  # ========================================================================= #
+  # === set_extract_to_this_location
+  #
+  # Use this when setting the variable @extract_to_this_location.
+  #
+  # This can be modified from the commandline such as by doing this:
+  # ========================================================================= #
+  def set_extract_to_this_location(
+      i = TEMP_DIR
+    )
+    if i.is_a? Hash
+      if i.has_key? :to
+        i = i.delete :to
+      elsif i.has_key? :extract_to
+        i = i.delete :extract_to
+      end
+    end
+    case i # case tag
+    when :default
+      i = Dir.pwd
+    when 'TEMP',
+         'MY_TEMP',
+         'MYTEMP'
+      i = TEMP_DIR
+    end
+    i = TEMP_DIR if i.nil?
+    i = i.to_s.dup
+    i << '/' unless i.end_with? '/'
+    i = rds(i)
+    i.gsub!(/--to=/,'') if i.include? '--to='
+    @extract_to_this_location = i
+  end; alias set_extract_to set_extract_to_this_location # === set_extract_to
+       alias extract_to=    set_extract_to_this_location # === extract_to=
+       alias extract_to     set_extract_to_this_location # === extract_to
+
+  # ========================================================================= #
+  # === run_this_system_command
+  # ========================================================================= #
+  def run_this_system_command(
+      i, instruction = :do_nothing_special
+    )
+    if instruction == :also_show_what_we_will_do
+      copn; e i
+    end
+    return `#{i}` # system tag
+  end
+
+  # ========================================================================= #
+  # === prefix_namespace_with
+  # ========================================================================= #
+  def prefix_namespace_with(i)
+    @namespace = "#{i}#{@namespace.dup}"
+    update_the_opn_hash # Also update the opn-hash here.
+  end
+
+  # ========================================================================= #
+  # === 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
+    if @be_verbose
+      unless @skip_extracting
+        copn; e 'Finished extracting to `'+sdir(
+          extract_to?+remove_file_extension(
+            @source_location.first # This is an Array.
+          )+'/'
+        )+'`.'
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === be_verbose?
+  #
+  # Getter method for whether we will be verbose or not.
+  # ========================================================================= #
+  def be_verbose?
+    @be_verbose
+  end
+
+  # ========================================================================= #
+  # === be_verbose
+  # ========================================================================= #
+  def be_verbose
+    set_be_verbose(true)
+  end
+
+  # ========================================================================= #
+  # === be_silent
+  # ========================================================================= #
+  def be_silent
+    set_be_verbose(false)
+  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)
+    @be_verbose = i
+  end; alias set_verbosity set_be_verbose # === set_verbosity
+
+  # ========================================================================= #
+  # === determine_default_opn_hash
+  # ========================================================================= #
+  def determine_default_opn_hash
+    @use_this_opn_hash = {
+      namespace:   namespace?,
+      use_colours: use_colours?
+    }
+  end; alias update_the_opn_hash determine_default_opn_hash # === update_the_opn_hash
+
+  # ========================================================================= #
+  # === 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
+
+  # ========================================================================= #
+  # === create_directory
+  #
+  # Use this to create directories.
+  # ========================================================================= #
+  def create_directory(i)
+    FileUtils.mkdir_p(i)
+  end; alias mkdir create_directory # === mkdir
+
+  # ========================================================================= #
+  # === remove_file_extension
+  # ========================================================================= #
+  def remove_file_extension(i)
+    _ = File.basename(i)
+    return RemoveFileSuffix[_]
+  end
+
+  # ========================================================================= #
+  # === rds
+  # ========================================================================= #
+  def rds(i)
+    i.squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === esystem
+  # ========================================================================= #
+  def esystem(i)
+    e i
+    system i
+  end
+
+  # ========================================================================= #
+  # === e
+  # ========================================================================= #
+  def e(i = '')
+    puts i
+  end
+
+  # ========================================================================= #
+  # === do_show_the_full_name_of_the_archive
+  # ========================================================================= #
+  def do_show_the_full_name_of_the_archive
+    @show_only_the_short_name_of_the_archive = false
+  end
+
+  # ========================================================================= #
+  # === fail_message_not_registered
+  #
+  # Output a fail message when the archive format is not registered. 
+  # ========================================================================= #
+  def fail_message_not_registered(i)
+    copn; e "Can not extract `#{sfancy(i)}` - it is not "\
+            "registered."
+  end
+
+  # ========================================================================= #
+  # === work_on_the_given_input
+  # ========================================================================= #
+  def work_on_the_given_input
+    if @source_location.empty?
+      copn; e 'Can not extract anything as no input has been given.'
+    else
+      @source_location.each {|entry|
+        if Extracter.is_this_a_valid_archive?(entry)
+          do_extract_what_to(entry)
+          report_to_the_user
+        else
+          fail_message_not_registered(entry)
+        end
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === run                                                (run tag, def tag)
+  # ========================================================================= #
+  def run
+    work_on_the_given_input
+  end
+
+end; end