directory_paradise 1.4.4

data/lib/directory_paradise/content/content.rb

@@ -0,0 +1,682 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === DirectoryParadise::Content
+#
+# This class can be used to keep track of the content of a directory.
+#
+# It can not directly be used to report its findings; if you need that
+# functionality then please use the class defined in the file
+# directory_paradise/report/report.rb instead.
+#
+# One goal of this class is to be as fast as possible. Because of this
+# goal, and because this class will not directly report anything to
+# the user, ever, it may not use colours.
+#
+# Usage example:
+#
+#   require 'directory_paradise'
+#
+#   DirectoryParadise::Content.new(ARGV)
+#
+# =========================================================================== #
+# require 'directory_paradise/content/content.rb'
+# =========================================================================== #
+require 'directory_paradise/base/base.rb'
+
+module DirectoryParadise
+
+class Content < Base # === DirectoryParadise::Content
+
+  require 'etc'
+  require 'directory_paradise/content/constants.rb'
+
+  begin
+    require 'roebe/classes/permission_ascii_format.rb'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === initialize
+  # ========================================================================= #
+  def initialize(
+      work_on_this_directory = ARGV,
+      run_already            = true
+    )
+    reset
+    set_work_on_this_directory(
+      work_on_this_directory
+    )
+    run if run_already
+  end
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :show_the_full_path
+    #
+    # If the next variable is true then the full filepath will be shown.
+    # ======================================================================= #
+    @internal_hash[:show_the_full_path] = true
+    # ======================================================================= #
+    # === :ignore_dot_only_entries
+    #
+    # If this variable is true then we will not keep '.' and '..'
+    # entries.
+    # ======================================================================= #
+    @internal_hash[:ignore_dot_only_entries] = true
+    # ======================================================================= #
+    # === :work_on_this_directory
+    #
+    # The variable :work_on_this_directory must always "point" to the
+    # directory we are interested in; this will be the directory that
+    # potentially contains other files, directories or symlinks. It
+    # will default to the current working directory on startup, so
+    # it must never be undefined really.
+    # ======================================================================= #
+    set_work_on_this_directory(return_pwd)
+  end
+
+  # ========================================================================= #
+  # === obtain_all_entries_as_specified_by_work_on_this_directory (obtain tag)
+  #
+  # This method will obtain through all entries found in the given
+  # directory, specified by :work_on_this_directory.
+  #
+  # Note that this method will NOT do any sorting at all whatsoever by
+  # default. If you need to sort then you should use the method
+  # called .do_sort().
+  # ========================================================================= #
+  def obtain_all_entries_as_specified_by_work_on_this_directory(
+      _ = work_on_this_directory?
+    )
+    _ = _.first if _.is_a? Array
+    case _ # case tag
+    # ======================================================================= #
+    # === :pwd
+    # ======================================================================= #
+    when :pwd,
+         :return_pwd,
+         :default,
+         nil
+      _ = return_pwd
+    # ======================================================================= #
+    # === :pwd_or_first_argument
+    # ======================================================================= #
+    when :pwd_or_first_argument
+      if @commandline_arguments.empty?
+        _ = return_pwd
+      else
+        _ = @commandline_arguments.first
+      end
+    end
+    # ======================================================================= #
+    # Make sure that a trailing '/' is used.
+    # ======================================================================= #
+    unless _.end_with? '/'
+      _ = _.dup if _.frozen?
+      _ << '/'
+    end
+    entries = Dir.glob(
+      "#{_}*",
+      File::FNM_DOTMATCH
+    )
+    set_content(entries)
+    sanitize_the_content
+  end; alias obtain                   obtain_all_entries_as_specified_by_work_on_this_directory # === obtain
+       alias determine_entries        obtain_all_entries_as_specified_by_work_on_this_directory # === determine_entries
+       alias obtain_directory_listing obtain_all_entries_as_specified_by_work_on_this_directory # === obtain_directory_listing
+       alias gather                   obtain_all_entries_as_specified_by_work_on_this_directory # === gather
+       alias gather_content           obtain_all_entries_as_specified_by_work_on_this_directory # === gather_content
+       alias run_main_loop            obtain_all_entries_as_specified_by_work_on_this_directory # === run_main_loop
+
+  # ========================================================================= #
+  # === internal_hash?
+  # ========================================================================= #
+  def internal_hash?
+    @internal_hash
+  end; alias hash  internal_hash? # === hash
+       alias hash? internal_hash? # === hash?
+
+  # ========================================================================= #
+  # === reset_the_main_hash
+  # ========================================================================= #
+  def reset_the_main_hash
+    @internal_hash = {} # This Hash will store everything.
+  end
+
+  # ========================================================================= #
+  # === set_work_on_this_directory
+  # ========================================================================= #
+  def set_work_on_this_directory(
+      i = :default
+    )
+    i = i.first if i.is_a? Array
+    case i
+    # ======================================================================= #
+    # === :default
+    # ======================================================================= #
+    when :default,
+         nil
+      i = return_pwd
+    end
+    i = i.dup if i.frozen?
+    if File.directory?(i) and !i.end_with?('/')
+      i << '/' 
+    end
+    i.squeeze!('/') if i.include? '//'
+    @internal_hash[:work_on_this_directory] = i
+  end; alias set_input            set_work_on_this_directory # === set_input
+       alias set_target_directory set_work_on_this_directory # === set_target_directory
+
+  # ========================================================================= #
+  # === work_on_this_directory?
+  # ========================================================================= #
+  def work_on_this_directory?
+    @internal_hash[:work_on_this_directory]
+  end; alias input_directory?         work_on_this_directory? # === input_directory?
+       alias input?                   work_on_this_directory? # === input?
+       alias target?                  work_on_this_directory? # === target?
+       alias input_dir?               work_on_this_directory? # === input_dir?
+       alias from_which_directory?    work_on_this_directory? # === from_which_directory?
+       alias work_on_which_directory? work_on_this_directory? # === work_on_which_directory?
+
+  # ========================================================================= #
+  # === use_current_directory
+  #
+  # This method will guarantee that the class will work with the current
+  # working directory, as-is.
+  # ========================================================================= #
+  def use_current_directory
+    set_work_on_this_directory(return_pwd)
+  end
+
+  # ========================================================================= #
+  # === sanitize_the_content
+  #
+  # This method will analyse information about the various entries in
+  # a given directory. It will turn the Array that should be stored at
+  # @internal_hash[:content] into a Hash.
+  #
+  # We need to keep in mind that a user may wish to show hidden files.
+  #
+  # The available entries for our main Hash are:
+  #
+  #   :size
+  #   :type
+  #   :is_executable
+  #   :gid
+  #   :inode_number
+  #   :uid
+  #   :access_mode
+  #   :last_modified
+  #   :name_of_owner
+  #   :name_of_group
+  #   :ascii_representation
+  #
+  # ========================================================================= #
+  def sanitize_the_content(
+      i = content?
+    )
+    _ = {} # Our new Hash.
+    # ======================================================================= #
+    # Specify some variables that will be checked against in the next
+    # .each clause.
+    # ======================================================================= #
+    show_the_full_path   = show_the_full_path?
+    i.each {|name_of_the_handle|
+      _[name_of_the_handle] = {}
+      # ===================================================================== #
+      # Next, we will populate our main hash here with the required
+      # datastructures.
+      # ===================================================================== #
+      # ===================================================================== #
+      # === :size
+      #
+      # This is also called the file_size.
+      # ===================================================================== #
+      _[name_of_the_handle][:size] = File.size?(name_of_the_handle)
+      # ===================================================================== #
+      # === :type
+      #
+      # This is also called "file_type" or "filetype".
+      # ===================================================================== #
+      _[name_of_the_handle][:type] = File.ftype(name_of_the_handle)
+      # ===================================================================== #
+      # === :is_executable
+      # ===================================================================== #
+      _[name_of_the_handle][:is_executable] = File.executable?(name_of_the_handle)
+      # ===================================================================== #
+      # Next, retain the full path, if it was so determined to.
+      # ===================================================================== #
+      if show_the_full_path
+        path = File.absolute_path(name_of_the_handle)
+      else
+        path = File.basename(name_of_the_handle)
+      end
+      path.squeeze!('/')
+      unless path.end_with? '/'
+        if File.directory?(path)
+          path = path.dup if path.frozen?
+          path << '/'
+        end
+      end
+      if path
+        unless File.exist? path
+          e "#{rev}No file exists at the target location `#{path}`."
+        end
+        if File.directory?(path) and !path.end_with?('/')
+          path << '/'
+        end
+      end
+      # ===================================================================== #
+      # === :path
+      #
+      # Keep track of the path-entry here, by assigning to :path. This is
+      # also known as the "filename".
+      # ===================================================================== #
+      _[name_of_the_handle][:path] = path
+      # ===================================================================== #
+      # === :ascii_representation
+      # ===================================================================== #
+      _[name_of_the_handle][:ascii_representation] = return_ascii_from(name_of_the_handle)
+      # ===================================================================== #
+      # Next, work with a stat object:
+      # ===================================================================== #
+      begin
+        stat_object = File.stat(path)
+        # =================================================================== #
+        # === :last_modified
+        #
+        # This is mtime, also known as the "modification_time."
+        # =================================================================== #
+        _[name_of_the_handle][:last_modified] = File.mtime(name_of_the_handle)
+        # =================================================================== #
+        # === :gid
+        # =================================================================== #
+        _[name_of_the_handle][:gid]           = stat_object.gid
+        # =================================================================== #
+        # === :inode_number
+        # =================================================================== #
+        _[name_of_the_handle][:inode_number]  = stat_object.ino
+        # =================================================================== #
+        # === :uid
+        # =================================================================== #
+        _[name_of_the_handle][:uid]           = stat_object.uid
+        # =================================================================== #
+        # === :access_mode
+        #
+        # This is, for example, "644". It is also called "permissions".
+        # =================================================================== #
+        _[name_of_the_handle][:access_mode]   = stat_object.mode.to_s(8)[3..5]
+        # =================================================================== #
+        # === :name_of_owner
+        #
+        # This is also called "inode_owner".
+        # =================================================================== #
+        _[name_of_the_handle][:name_of_owner] = return_owner(stat_object.uid)
+        # =================================================================== #
+        # On windows, the following may fail. Thus we guard against it
+        # next.
+        # =================================================================== #
+        if is_on_windows?
+          _[name_of_the_handle][:name_of_group] = UNKNOWN
+        else
+          begin
+            group_id = Etc.getgrgid(stat_object.gid)
+            if _
+              _[name_of_the_handle][:name_of_group] = group_id.name
+            end
+          rescue ArgumentError # This is an error such as "can't find group for 1107"
+            _[name_of_the_handle][:name_of_group] = UNKNOWN
+          end
+        end
+      rescue Exception => error
+        unless is_on_windows?
+          e 'An error occurred:'
+          pp error
+        end
+      end
+    }
+    @internal_hash[:content] = _
+  end; alias do_analyse_the_discovered_entries sanitize_the_content # === do_analyse_the_discovered_entries
+       alias populate_hash                     sanitize_the_content # === populate_hash
+
+  # ========================================================================= #
+  # === return_ascii_from
+  # 
+  #   r if reading   is permitted, - if it is not.
+  #   w if writing   is permitted, - if it is not.
+  #   x if execution is permitted, - if it is not.
+  #
+  # ========================================================================= #
+  def return_ascii_from(i)
+    if Object.const_defined?(:Roebe) and
+       Roebe.const_defined?(:PermissionAsciiFormat)
+      Roebe::PermissionAsciiFormat[i]
+    else
+      ''
+    end
+  end
+
+  # ========================================================================= #
+  # === show_the_full_path?
+  # ========================================================================= #
+  def show_the_full_path?
+    @internal_hash[:show_the_full_path]
+  end
+
+  # ========================================================================= #
+  # === directories?
+  #
+  # This method will return all directories found in the main directory-
+  # ========================================================================= #
+  def directories?
+    entries?.select {|key, value| value[:type] == 'directory' }.keys
+  end
+
+  # ========================================================================= #
+  # === retain_only_the_directories
+  #
+  # This method will filter away everything but the directories.
+  # ========================================================================= #
+  def retain_only_the_directories
+    entries?.select! {|key, value| value[:type] == 'directory' }
+  end
+
+  # ========================================================================= #
+  # === menu                                                      (menu tag)
+  # ========================================================================= #
+  def menu(
+      i = work_on_which_directory?
+    )
+    if i.is_a? Array
+      i.each {|entry| menu(entry) }
+    else
+      case i
+      # ======================================================================= #
+      # === --detail
+      # ======================================================================= #
+      when /^-?-?detail\??$/
+        set_work_on_this_directory(return_pwd)
+        run
+      end
+    end
+  end
+
+  # ========================================================================= #
+  # === reject_hidden_files
+  # ========================================================================= #
+  def reject_hidden_files
+    entries?.reject! {|key, value| value[:path].include?('/.') }
+  end
+
+  # ========================================================================= #
+  # === ignore_backups
+  # ========================================================================= #
+  def ignore_backups
+    entries?.reject! {|key, value| value[:path].end_with? '~' }
+  end
+
+  # ========================================================================= #
+  # === retain_only_the_symlinks
+  #
+  # This method will filter away everything but the symlinks.
+  # ========================================================================= #
+  def retain_only_the_symlinks
+    entries?.select! {|key, value| value[:type] == 'link' }
+  end
+
+  # ========================================================================= #
+  # === files?
+  # ========================================================================= #
+  def files?
+    entries?.select {|key, value| value[:type] == 'file' }.keys
+  end
+
+  # ========================================================================= #
+  # === symlinks?
+  #
+  # This method will return all symlink entries found in the main
+  # directory.
+  # ========================================================================= #
+  def symlinks?
+    entries?.select {|key, value| value[:type] == 'link' }.keys
+  end
+
+  # ========================================================================= #
+  # === do_sort                                                    (sort tag)
+  #
+  # This is the specific sorting-action of this class. Whenever you want
+  # to sort the kept dataset, make use of this method.
+  # ========================================================================= #
+  def do_sort(
+      sort_how = :default
+    )
+    case sort_how.to_sym # We only respond to Symbols.
+    # ======================================================================= #
+    # === :size
+    # ======================================================================= #
+    when :size, # Sort by size here.
+         :by_size
+      _ = entries?.sort_by {|filename, value| value[:size] }.reverse
+      _ = Hash[_]
+      set_content(_)
+    # ======================================================================= #
+    # === :default
+    #
+    # Default sorting will refer to date-based sorting, aka the modification
+    # date.
+    # ======================================================================= #
+    when :default,
+         :date, # Sort by date here. The modification date.
+         :sort_by_date
+      _ = entries?.sort_by {|filename, value| value[:last_modified] }.reverse
+      # ===================================================================== #
+      # This will be e. g.:
+      #
+      #   ["/Depot/j/BLACKCHA.TXT", {:size=>2652,
+      #
+      # but we need a Hash.
+      # ===================================================================== #
+      _ = Hash[_]
+      set_content(_)
+    # ======================================================================= #
+    # === modification_time
+    # ======================================================================= #
+    when :modification_time
+      _ = entries?.sort_by {|entry| entry[4] }.reverse
+      _ = Hash[_]
+      set_content(_)
+    # ======================================================================= #
+    # === :reversed
+    # ======================================================================= #
+    when :reversed
+      _ = entries?.sort_by {|filename, value| filename }.reverse
+      _ = Hash[_]
+      set_content(_)
+    else
+      e 'Unknown sorting mode: '+sort_how.to_s
+    end
+  end; alias consider_sorting_by do_sort # === consider_sorting_by
+
+  # ========================================================================= #
+  # === set_content
+  # ========================================================================= #
+  def set_content(i)
+    @internal_hash[:content] = i
+  end; alias set_entries set_content # === set_entries
+
+  # ========================================================================= #
+  # === do_ignore_dot_only_entries
+  #
+  # This is the method that will remove '.' and '..' from the entries.
+  # This will only be done if specified to do so, via the reset()
+  # method.
+  # ========================================================================= #
+  def do_ignore_dot_only_entries
+    # ======================================================================= #
+    # Next eliminate rid of '.' and '..'
+    # ======================================================================= #
+    content?.reject! { |entry|
+      entry =~ /\.{1,2}$/ # Remove "." and ".." entries here.
+    }
+  end
+
+  # ========================================================================= #
+  # === n_entries?
+  # ========================================================================= #
+  def n_entries?
+    directory_content?.size
+  end
+
+  # ========================================================================= #
+  # === clear_the_old_content
+  # ========================================================================= #
+  def clear_the_old_content
+    @internal_hash[:content] = {}
+  end
+
+  # ========================================================================= #
+  # === first_entry?
+  # ========================================================================= #
+  def first_entry?
+    return content?.keys.first
+  end
+
+  # ========================================================================= #
+  # === ignore_dot_only_entries?
+  # ========================================================================= #
+  def ignore_dot_only_entries?
+    @internal_hash[:ignore_dot_only_entries]
+  end
+
+  # ========================================================================= #
+  # === consider_discarding_dot_only_entries
+  #
+  # This method should be called by external classes, rather than be the
+  # default.
+  # ========================================================================= #
+  def consider_discarding_dot_only_entries
+    if ignore_dot_only_entries?
+      do_ignore_dot_only_entries
+    end
+  end
+
+  # ========================================================================= #
+  # === obtain_entries_from
+  #
+  # This is similar to obtain_all_entries_as_specified_by_work_on_this_directory,
+  # but it will also set @internal_hash[:work_on_this_directory].
+  # ========================================================================= #
+  def obtain_entries_from(i)
+    # ======================================================================= #
+    # Re-set the internal "pointer" next, by updating the relevant
+    # variable that keeps track of the directory we are working on.
+    # ======================================================================= #
+    @internal_hash[:work_on_this_directory] = i
+    determine_entries
+  end; alias determine_the_entries_from_this_directory obtain_entries_from # === determine_the_entries_from_this_directory
+       alias obtain_all_entries_in_that_directory      obtain_entries_from # === obtain_all_entries_in_that_directory
+       alias obtain_from                               obtain_entries_from # === obtain_from
+
+  # ========================================================================= #
+  # === build_up_a_hash_from_these_files
+  #
+  # The input argument should be an Array.
+  # ========================================================================= #
+  def build_up_a_hash_from_these_files(these_files)
+    clear_the_old_content
+    sanitize_the_content(these_files)
+  end
+
+  # ========================================================================= #
+  # === content?
+  # ========================================================================= #
+  def content?
+    @internal_hash[:content]
+  end; alias content            content? # === content
+       alias entries?           content? # === entries?
+       alias entries            content? # === entries
+       alias directory_content? content? # === directory_content?
+       alias return_entries     content? # === return_entries
+       alias data?              content? # === data?
+       alias data               content? # === data
+       alias results?           content? # === results?
+
+  # ========================================================================= #
+  # === keys?
+  # ========================================================================= #         
+  def keys?
+    content?.keys
+  end; alias keys keys? # === keys
+
+  # ========================================================================= #
+  # == filesize?
+  #
+  # This method will return the total filesize of all entries.
+  # ========================================================================= #
+  def filesize?
+    result = 0
+    content?.each_pair {|key, hash| result += hash[:size] }
+    return result
+  end
+
+  # ========================================================================= #
+  # === run                                                         (run tag)
+  # ========================================================================= #
+  def run
+    menu
+    obtain_all_entries_as_specified_by_work_on_this_directory
+  end
+
+  # ========================================================================= #
+  # === DirectoryContent.return_entries
+  # ========================================================================= #
+  def self.return_entries(from)
+    new(from).return_entries
+  end
+
+  # ========================================================================= #
+  # === DirectoryParadise::Content[]
+  # ========================================================================= #
+  def self.[](i = ARGV)
+    new(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  require 'colours/autoinclude'
+  _ = DirectoryParadise::Content.new(ARGV) # or DirectoryParadise::Content[]
+  e rev+
+    steelblue(_.n_entries?.to_s)+' entries were found in this directory.'
+  e 'The first entry is: '+royalblue(_.first_entry?)
+  # ========================================================================= #
+  # Next follows some debug-code:
+  # ========================================================================= #
+  # pp _.entries?
+  # _.do_sort :by_size
+  # pp _.entries?
+  # pp _.directories?
+  # _.retain_only_the_directories
+  # pp _.directories?
+  # pp _.entries?.size
+  # pp _.entries?
+  # pp _.hash?
+  # pp _.directory_content?
+  #pp _.entries?
+ # _.consider_sorting_by :sort_by_date
+  #pp _.entries?
+  # e 'Symlinks:'
+  # pp _.symlinks?
+  #pp _
+end # dcontent
+    # dcontent /home/Temp
+    # dcontent /Depot/jjj