directory_paradise 1.4.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a9d6aaf616b92f7e2fcdbe01335b59fb54a4c754e3bf208ee2ef42c9eff961c
+  data.tar.gz: 487b2c07cc240cb7ef01bd5f05791f139763b8781cab95387d00f5002be3675d
+SHA512:
+  metadata.gz: 337d80156b3150f15dd99ac6e1cabb3455c97b0ff23b47cfe28aeecd5f057594148640d5b59b7bd2bbdb079c0b4d268a5da51ffbc9c9a8c687b022cc69e82b39
+  data.tar.gz: 496af2302209e8716c0512822fbf116ff068212c1638580cd8787e25a4754cea63a7209297c1510d2035f34faa689868c6fa2c1c3c8942672d606e27f4a4a0b0

data/README.md

@@ -0,0 +1,228 @@
+# @title Directory Content
+# @markup kramdown
+
+[![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](https://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">06.08.2022</span> (dd.mm.yyyy notation), at <span style="color: steelblue; font-weight: bold">00:57:31</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 and mandatory 2FA coming up in 2022
+
+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 order to limit this
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore, for various reasons.
+
+Do keep in mind that responding to emails may take some time, depending on
+the amount of work I may have at that moment.
+
+In 2022 rubygems.org decided to make 2FA mandatory for every gem owner:
+see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+As I can not use 2FA, for reasons I will skip explaining here (see
+various github issue discussions in the past), this effectively means that
+Betty Li and others who run the show at rubygems.org will perma-ban me
+from using rubygems as a developer.
+
+As I disagree with that decision completely, this will mean that all my
+gems will be removed from rubygems.org prior to that sunset date, e. g.
+before they permanently lock me out from the code that I used
+to maintain. It is pointless to want to discuss this with them anymore -
+they have made up their minds and decided that you can only use
+the code if 2FA is in place, even though the code itself works just
+fine. If you don't use 2FA you are effectively locked out from your
+own code; I consider this a malicious attack. See also how they limited
+discussions to people with mandatory 2FA on the ruby-bugtracker, thus
+banning everyone permanently without 2FA:  
+
+https://bugs.ruby-lang.org/issues/18800
+
+Guess it may indeed be time to finally abandon ruby - not because
+ruby is a bad language, but there are people now in charge who
+really should not be part of ruby in the first place.
+

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)