directory_paradise 1.4.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98d8042374552eb167d6a769c301a21a4bdae7bbde61f10d9294970c69e6d42d
+  data.tar.gz: a16bd8df8cf43b35faa3d34846a504d805dac960458c6e7f81822ace0e62a325
+SHA512:
+  metadata.gz: 6bbaf3b5bcb77ede94cd8e0033b8185ee98b24975d2a6067a76529625dd58bf9e7ee8b1b3cb0cf0962c45bd271d987aecf98e9a4953ee465b06415f4df742493
+  data.tar.gz: c17b8722ad749160c9b47841ddedbbbb44102958e6917756bda6adc85cc13135ecf21294757de458d8abe961d6fc2ae06fe649f014333b38aa74dc257dbf7f44

data/README.md

@@ -0,0 +1,213 @@
+# @title Directory Content
+# @markup kramdown
+
+[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](http://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/directory_paradise.svg)](https://badge.fury.io/rb/directory_paradise)
+
+This gem was <b>last updated</b> on the <span style="color: darkblue; font-weight: bold">15.05.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">07:13:57</span> o'clock.
+
+<img src="https://i.imgur.com/hbGDM7i.jpg">
+
+## The directory_paradise gem - an introduction
+
+The directory_paradise gem originated from the older directory_content gem.
+
+I got tired of trying to fix bugs derived from the old code base, though,
+so I decided to just start a new project altogether, while re-using the
+parts of the code that works.
+
+As I gained a bit of experience, I decided to adapt the old approach.
+This will be mentioned at a later time in this document.
+
+This small gem may be useful whenever you wish to display the content 
+of a (local) directory, similar to how the linux/unix program called
+**ls** operates.
+
+I needed a variant of **ls** for my ruby-shell (the **roebe-shell**),
+so this project here was created years ago. Unfortunately over
+the years I changed parts of the code, without properly 
+designing it, leading to quite some confusion as to what the
+project really should do, and how it should achieve this.
+
+Thus, this README here shall not only explain the use cases of the
+project as such, but document a few internal decisions as well,
+including the rationale behind having made that decision.
+
+That way we can use the **documentation** as some form of 
+specification as well, and check to see that the code 
+adheres to this specification. This may be helpful in the
+future, because I already rewrote this project several times
+before already.
+
+There are now two main classes for the **directory_paradise** project:
+
+(1) **class Report**, which will be in the **report/** subdirectory.
+
+This class will be responsible for displaying the content of a directory
+to the user.
+
+(2) **class Content** which will reside in the **content/** directory.
+
+This class will be responsible for obtaining all the necessary 
+information to provide data to class Report. It may no longer
+report anything to the user, except for debug output when we
+test or modify it.
+
+Hopefully these design choices will make it easier to maintain the
+code base. In the past the old class that was similar to class
+Content also displayed some information, which led to code duplication
+and confusion, aka where to put new code in.
+
+Furthermore, a new class called Base will now exist that can be used
+to share code between these two classes, such return_pwd (which is
+similar to Dir.pwd, but always ensures that a trailing / will be
+there).
+
+## class Content
+
+This is the main class of module DirectoryParadise. It will not report
+anything to the user, but it will parse the entries in a given directory
+and store these entries in a hash that is available via .entries?.
+
+The method .entries? will return which entries (files, directories
+or symlinks) were found in the given directory.
+
+The method .n_entries? will return a number, indicating how many
+such entries could be found.
+
+The method .obtain_entries_from() can be used to fill up the 
+entries. If you also want to change the target directory, 
+make use of the method .set_target_directory().
+
+The method .report() can be used to report the content. It is,
+however had, not called by default for class DirectoryContent.
+Note that another class, called ShowDirectoryContent, is the
+one that is more apt and adjusted to displaying content.
+
+This class is the one that should be used when you wish to display
+the content of a directory. It will make use of class DirectoryContent,
+so there is a **separation-of-concern**.
+
+Note that you could also use class DirectoryContent to display
+content too, via the .report() method - but this is mostly just
+as a way to quickly debug something. For a more advanced display
+of files and directories, use class DirectoryContent::ShowDirectoryContent
+as it has been created precisely for that use case.
+
+## Specification for class Content - the individual entries explained
+
+Essentially class Content has a hash that describes the content
+of a directory. This subsection will explain some of the entries that
+can be found in that hash, and thus may serve as some kind of
+specification.
+
+First, the path to the file or directory at hand will be the main key.
+So, for example, if you have an archive called Images.tar.xz at
+the directory /Depot/, then the key to the description of that
+entry will be **/Depot/Images.tar.xz**. That way we always know
+where class DirectoryContent 'points' at.
+
+Now knowing this key, let's have a look at the individual entries:
+
+    :type=>"file"                       # keep track of the file type, e. g. file, directory or link.
+    :size=>47626780                     # we want to know the file size too, so that we don't have to call any other method querying this again.
+    :is_executable=>false               # is our file executable? Typically entries in /usr/bin/ will be executables
+    :path=>"/Depot/Images.tar.xz"       # here we store the path again, to simplify querying the path.
+    :ascii_representation=>"-rw-r--r--" # This is mostly used to keep compatibility to GNU coreutils "ls"
+    :last_modified=>2021-03-09 01:20:09.432056708 +0000 # Keep track as to when this entry was last modified.
+    :gid=>0                             # group id
+    :inode_number=>93857180             # its inode number
+    :uid=>0                             # user id
+    :access_mode=>"644"                 # access mode
+    :name_of_owner=>"root"              # name of the current owner of that entry
+    :name_of_group=>"root"              # name of the current group of that entry
+
+## Behaviour on missing symlinks
+
+If a missing symlink (that is, the target to which this symlink points
+to does not exist) is encountered, then class ShowDirectoryContent 
+will either ignore this, or display to the user that a symlink is
+missing. Additionally it may stop altogether when a missing 
+symlink is discovered. That way the user is sort of forced to
+fix this issue - I needed this once on **GoboLinux**, which is why
+this functionality had to exist.
+
+This is handled internally via the method call **stop_on_missing_symlink?**.
+
+The next subsection deals with class DirectoryParadise::Report, which
+is the main class when you wish to display the content of a directory.
+
+## Display only directory in the current working directory
+
+If you only wish to display all directories in the current
+working directory then you can use the method called
+<b>.only_directories</b>, or, from the commandline:
+
+    sdc --only-directories
+
+## Do not show the header
+
+By default, class DirectoryParadise::Report will show a header on
+top, to explain some of the options.
+
+This may not always be wanted, so a commandline option exists
+to NOT show the header.
+
+Example for this:
+
+    sdc --noheader
+    sdc --no-header
+
+This is more similar to how "ls" works by default too, by the
+way.
+
+## Show hidden files
+
+This should show hidden files aka those with a leading '.':
+
+    sdc --show
+
+Several aliases exist to this. Have a look at **menu.rb** to
+see all aliases to it, at **directory_paradise/report/menu.rb**.
+
+# Customising colours via the yaml file called colours_for_bytes_values.yml
+
+You can customize the existing colours for KB, MB and GB values,
+via the yaml file called **colours_for_bytes_values.yml**. Currently
+only a few colours are supported, though. This may be extended one
+day, if people want to use other colours by default for the KB,
+MB and GB entries.
+
+Since as of **January 2022** the code will also check whether the
+colour names are correct. I had a typo called **mediumpurples**
+which did not exist, leading to another project break. This
+is bad, so now the directory_paradise gem will verify whether
+the colours exist or not.
+
+
+## Contact information
+
+If your creative mind has ideas and specific suggestions to make this
+gem more useful in general, feel free to drop me an email at any
+time, via:
+
+    shevy@inbox.lt
+
+Before that email I used an email account at Google gmail, but in **2021** I
+decided to slowly abandon gmail for various reasons. In part this is because
+the UI annoys me (on non-chrome browser loading takes too long), but also
+because of Google's attempt to establish mass surveillance via its
+federated cohorts sniffing (FLoC). I do not know what happened at Google,
+but enough is enough - there is only so much you can take while supporting
+greed. When it comes to data mining done by private groups, ultimately
+the user became the product.
+
+Do keep in mind that responding to emails may take some time,
+depending on the amount of work I may have at that moment, due
+to reallife time constraints. I will, however had, read feedback
+eventually. Patches and code changes are welcome too, of course,
+as long as they are in the spirit of the project at hand, e. g.
+fitting to the general theme. For this I may make use of github
+as a discussion site, but this has a low priority right now.
+

data/bin/show_directory_content

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'directory_paradise'
+
+DirectoryParadise.show(ARGV)

data/directory_paradise.gemspec

@@ -0,0 +1,45 @@
+require 'directory_paradise/version/version.rb'
+require 'roebe/toplevel_methods/misc.rb'
+
+Gem::Specification.new { |s|
+
+  s.name    = 'directory_paradise'
+  s.version = DirectoryParadise::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+This class will display the content of a directory. It
+can also give back a data-object that describes the 
+content of a directory, e. g. all files or directories
+found in that directory.
+
+The class aims to function somewhat similar to the
+UNIX/coreutils program called "ls".
+
+The latest version now comes with a test/ directory.
+
+The method apply_filter() was added, so now we can
+filter almost like "ls *foo*" could filter.
+
+As of version 1.0.3, showing the Index is optional.
+
+  EOF
+
+  s.summary     = DESCRIPTION 
+  s.description = DESCRIPTION
+ 
+  s.authors  = ['Robert A. Heiler']
+  s.email    = Roebe.email?
+  s.files    = Dir['**/*']
+  s.homepage = 'https://rubygems.org/gems/directory_paradise'
+  s.licenses = 'MIT'
+
+  s.required_ruby_version     = '>= '+Roebe.third_most_stable_version_of_ruby
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  s.add_dependency 'colours'
+  s.add_dependency 'opn'
+
+}

data/doc/README.gen

@@ -0,0 +1,185 @@
+# @title Directory Content
+# @markup kramdown
+
+ADD_RUBY_BADGE
+ADD_TIME_STAMP
+
+<img src="https://i.imgur.com/hbGDM7i.jpg">
+
+## The directory_paradise gem - an introduction
+
+The directory_paradise gem originated from the older directory_content gem.
+
+I got tired of trying to fix bugs derived from the old code base, though,
+so I decided to just start a new project altogether, while re-using the
+parts of the code that works.
+
+As I gained a bit of experience, I decided to adapt the old approach.
+This will be mentioned at a later time in this document.
+
+This small gem may be useful whenever you wish to display the content 
+of a (local) directory, similar to how the linux/unix program called
+**ls** operates.
+
+I needed a variant of **ls** for my ruby-shell (the **roebe-shell**),
+so this project here was created years ago. Unfortunately over
+the years I changed parts of the code, without properly 
+designing it, leading to quite some confusion as to what the
+project really should do, and how it should achieve this.
+
+Thus, this README here shall not only explain the use cases of the
+project as such, but document a few internal decisions as well,
+including the rationale behind having made that decision.
+
+That way we can use the **documentation** as some form of 
+specification as well, and check to see that the code 
+adheres to this specification. This may be helpful in the
+future, because I already rewrote this project several times
+before already.
+
+There are now two main classes for the **directory_paradise** project:
+
+(1) **class Report**, which will be in the **report/** subdirectory.
+
+This class will be responsible for displaying the content of a directory
+to the user.
+
+(2) **class Content** which will reside in the **content/** directory.
+
+This class will be responsible for obtaining all the necessary 
+information to provide data to class Report. It may no longer
+report anything to the user, except for debug output when we
+test or modify it.
+
+Hopefully these design choices will make it easier to maintain the
+code base. In the past the old class that was similar to class
+Content also displayed some information, which led to code duplication
+and confusion, aka where to put new code in.
+
+Furthermore, a new class called Base will now exist that can be used
+to share code between these two classes, such return_pwd (which is
+similar to Dir.pwd, but always ensures that a trailing / will be
+there).
+
+## class Content
+
+This is the main class of module DirectoryParadise. It will not report
+anything to the user, but it will parse the entries in a given directory
+and store these entries in a hash that is available via .entries?.
+
+The method .entries? will return which entries (files, directories
+or symlinks) were found in the given directory.
+
+The method .n_entries? will return a number, indicating how many
+such entries could be found.
+
+The method .obtain_entries_from() can be used to fill up the 
+entries. If you also want to change the target directory, 
+make use of the method .set_target_directory().
+
+The method .report() can be used to report the content. It is,
+however had, not called by default for class DirectoryContent.
+Note that another class, called ShowDirectoryContent, is the
+one that is more apt and adjusted to displaying content.
+
+This class is the one that should be used when you wish to display
+the content of a directory. It will make use of class DirectoryContent,
+so there is a **separation-of-concern**.
+
+Note that you could also use class DirectoryContent to display
+content too, via the .report() method - but this is mostly just
+as a way to quickly debug something. For a more advanced display
+of files and directories, use class DirectoryContent::ShowDirectoryContent
+as it has been created precisely for that use case.
+
+## Specification for class Content - the individual entries explained
+
+Essentially class Content has a hash that describes the content
+of a directory. This subsection will explain some of the entries that
+can be found in that hash, and thus may serve as some kind of
+specification.
+
+First, the path to the file or directory at hand will be the main key.
+So, for example, if you have an archive called Images.tar.xz at
+the directory /Depot/, then the key to the description of that
+entry will be **/Depot/Images.tar.xz**. That way we always know
+where class DirectoryContent 'points' at.
+
+Now knowing this key, let's have a look at the individual entries:
+
+    :type=>"file"                       # keep track of the file type, e. g. file, directory or link.
+    :size=>47626780                     # we want to know the file size too, so that we don't have to call any other method querying this again.
+    :is_executable=>false               # is our file executable? Typically entries in /usr/bin/ will be executables
+    :path=>"/Depot/Images.tar.xz"       # here we store the path again, to simplify querying the path.
+    :ascii_representation=>"-rw-r--r--" # This is mostly used to keep compatibility to GNU coreutils "ls"
+    :last_modified=>2021-03-09 01:20:09.432056708 +0000 # Keep track as to when this entry was last modified.
+    :gid=>0                             # group id
+    :inode_number=>93857180             # its inode number
+    :uid=>0                             # user id
+    :access_mode=>"644"                 # access mode
+    :name_of_owner=>"root"              # name of the current owner of that entry
+    :name_of_group=>"root"              # name of the current group of that entry
+
+## Behaviour on missing symlinks
+
+If a missing symlink (that is, the target to which this symlink points
+to does not exist) is encountered, then class ShowDirectoryContent 
+will either ignore this, or display to the user that a symlink is
+missing. Additionally it may stop altogether when a missing 
+symlink is discovered. That way the user is sort of forced to
+fix this issue - I needed this once on **GoboLinux**, which is why
+this functionality had to exist.
+
+This is handled internally via the method call **stop_on_missing_symlink?**.
+
+The next subsection deals with class DirectoryParadise::Report, which
+is the main class when you wish to display the content of a directory.
+
+## Display only directory in the current working directory
+
+If you only wish to display all directories in the current
+working directory then you can use the method called
+<b>.only_directories</b>, or, from the commandline:
+
+    sdc --only-directories
+
+## Do not show the header
+
+By default, class DirectoryParadise::Report will show a header on
+top, to explain some of the options.
+
+This may not always be wanted, so a commandline option exists
+to NOT show the header.
+
+Example for this:
+
+    sdc --noheader
+    sdc --no-header
+
+This is more similar to how "ls" works by default too, by the
+way.
+
+## Show hidden files
+
+This should show hidden files aka those with a leading '.':
+
+    sdc --show
+
+Several aliases exist to this. Have a look at **menu.rb** to
+see all aliases to it, at **directory_paradise/report/menu.rb**.
+
+# Customising colours via the yaml file called colours_for_bytes_values.yml
+
+You can customize the existing colours for KB, MB and GB values,
+via the yaml file called **colours_for_bytes_values.yml**. Currently
+only a few colours are supported, though. This may be extended one
+day, if people want to use other colours by default for the KB,
+MB and GB entries.
+
+Since as of **January 2022** the code will also check whether the
+colour names are correct. I had a typo called **mediumpurples**
+which did not exist, leading to another project break. This
+is bad, so now the directory_paradise gem will verify whether
+the colours exist or not.
+
+ADD_CONTACT_INFORMATION

data/doc/todo/todo.md

@@ -0,0 +1,4 @@
+(1) At the display of the file size,
+    consider using:
+
+      to_human_readable(file_size)

data/lib/directory_paradise/base/base.rb

@@ -0,0 +1,195 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === DirectoryParadise::Base
+#
+# Usage example:
+#
+#   DirectoryParadise::Base.new(ARGV)
+#
+# =========================================================================== #
+# require 'directory_paradise/base/base.rb'
+# =========================================================================== #
+require 'directory_paradise/constants/newline.rb'
+
+module DirectoryParadise
+
+class Base
+
+  alias e  puts
+  alias ee print
+
+  require 'directory_paradise/base/colours.rb'
+  require 'directory_paradise/to_human_readable/to_human_readable.rb'
+
+  # ========================================================================= #
+  # === is_on_windows?
+  # ========================================================================= #
+  def is_on_windows?
+    if RUBY_PLATFORM.include?('win') or # if on windows.
+       RUBY_PLATFORM.include?('mingw')
+      return true
+    end
+    return false # ← Otherwise we are evidently NOT on windows, if we reach this point here.
+  end
+
+  # ========================================================================= #
+  # === rds
+  # ========================================================================= #
+  def rds(i)
+    i.squeeze '/'
+  end
+
+  # ========================================================================= #
+  # === register_sigint
+  # ========================================================================= #
+  def register_sigint
+    Signal.trap('SIGINT') { exit }
+  end
+
+  # ========================================================================= #
+  # === return_chmod_value_of_this_file
+  # ========================================================================= #
+  def return_chmod_value_of_this_file(i)
+    if File.exist? i
+      File.stat(i).mode.to_s(8).split('')[-4..-1].join # => "0755"
+    else
+      '0000'
+    end
+  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
+
+  # ========================================================================= #
+  # === commandline_arguments_starting_with_two_hyphens?
+  # ========================================================================= #
+  def commandline_arguments_starting_with_two_hyphens?
+    @commandline_arguments.select {|entry| entry.start_with? '--' }
+  end
+
+  # ========================================================================= #
+  # === return_non_hyphen_entries_from
+  # ========================================================================= #
+  def return_non_hyphen_entries_from(i)
+    if i.is_a? Array
+      i.select {|entry| !entry.start_with?('--') }
+    else
+      nil
+    end
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first? first_argument? # === first?
+
+  # ========================================================================= #
+  # === return_pwd
+  # ========================================================================= #
+  def return_pwd
+    "#{Dir.pwd}/".squeeze('/')
+  end
+
+  # ========================================================================= #
+  # === eliner
+  # ========================================================================= #
+  def eliner
+    e '―' * 80
+  end
+
+  # ========================================================================= #
+  # === liner
+  # ========================================================================= #
+  def liner # adds a line.
+    if block_given?
+      liner
+      yield
+    end
+    return ('*' * 80)+N
+  end
+
+  # ========================================================================= #
+  # === return_owner
+  #
+  # This method determines the owner of a file or directory.
+  # ========================================================================= #
+  def return_owner(
+      of_this_uid
+    )
+    _ = ''.dup # The _ is the return value.
+    # ======================================================================= #
+    # The next block of code can fail on windows, hence why this is
+    # wrapped carefully.
+    # ======================================================================= #
+    begin
+      if of_this_uid.is_a? String
+        of_this_uid = of_this_uid.to_i
+      end
+      # ===================================================================== #
+      # The next line must be rescued because the filesystem may be faulty.
+      # ===================================================================== #
+      begin
+        result_from_getpwuid = Etc.getpwuid(of_this_uid)
+      rescue TypeError
+        result_from_getpwuid = false
+      end
+      if result_from_getpwuid
+        _ << result_from_getpwuid.name
+      else
+        _ << '(unknown)'
+      end
+    rescue ArgumentError
+      _ << '(unknown)'
+    rescue Errno::ENOENT
+      _ << '(missing)'
+    end
+    _ # Return it here.
+  end; alias owner? return_owner # === owner?
+
+  # ========================================================================= #
+  # === return_assumed_modification_time
+  # ========================================================================= #
+  def return_assumed_modification_time(i)
+    month = Date::MONTHNAMES[i.month][0,3] # => "Jun"
+    "#{month} #{i.day.to_s.rjust(2)}"
+  end
+
+  # ========================================================================= #
+  # === clear_the_internal_hash
+  # ========================================================================= #
+  def clear_the_internal_hash
+    @internal_hash.clear
+  end; alias clear clear_the_internal_hash # === clear
+
+  # ========================================================================= #
+  # === to_human_readable
+  #
+  # The strange thing is, in bash, we seem to round up.
+  #
+  # How many MB (megabyte) are in 1 GB (gigabyte)? 1024.
+  # ========================================================================= #
+  def to_human_readable(i)
+    return DirectoryParadise.to_human_readable(i)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  DirectoryParadise::Base.new(ARGV)
+end # base.rb