extracter 1.2.32

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e45b6d80b96923bfd8bd5e73c3f6e65ad98e4346eabadfca63a24b74dbedf1fa
+  data.tar.gz: dc7b8883262c5f605eba796f10b9bb3956a66d0889d59140ce6ce02f318f922b
+SHA512:
+  metadata.gz: 726275b6eb718a9fcb8f8c1f1a03f9358cfbdfe1b3074e5bfecd5dba77dc9bb712ed6574f6f18fb8e87802e5c8fbb5d75b4679bfbbddb44425c1aebe41dee82b
+  data.tar.gz: dec795cfdff6ad71a6352537d775ad0fe4d4ef8f03567c869bb26f45a8de368f6c99632763e49df153e6c8787008b095e1c8b4408f308bbcb3735d14b86f1077

data/README.md

@@ -0,0 +1,210 @@
+[![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/extracter.svg)](https://badge.fury.io/rb/extracter)
+	
+# Extracter
+
+## The primary goal of the extracter gem
+
+This gem can help the user if said user wants to **extract a given
+archive**.
+
+## Scope of Extracter
+
+The scope (and goals) for **class Extracter** are really simple: throw
+any archive format at it, and the class will try to **extract** it.
+
+It can be used on the commandline as well, via **bin/extracter**.
+
+Note that in order to extract a given archive, some programs must
+be available still. On linux this tends to be **tar**, **bzip2**,
+**xz** and **gzip**. On windows it is recommended to use **7-zip**.
+
+## How to find out whether a given file is a valid archive
+
+You can find out whether a given input **xyz** is a valid archive by
+issuing the following toplevel-method:
+
+    Extracter.is_this_a_valid_archive?(path)
+
+This will return either true or false. In <b>August 2022</b> the
+code was adapted slightly to return true no matter if the
+file extension is upcased or lowercased. In other words: a
+file called <b>foobar.zip</b> will work fine, as will the same 
+file but this time called <b>foobar.ZIP</b>. I had the latter issue
+when I downloaded a BIOS Firmware update in August 2022 - the
+file was .ZIP and Extracter did not work. So that was a tiny
+bug in the extracter gem - it really should work on .ZIP
+files just fine as well, since these are simply .zip files
+anyway.
+
+Keep in mind that not all archive formats have been added so far,
+so this will return false even if it should instead return true.
+
+More support for archive formats will be added whenever possible,
+as time permits.
+
+## How to extract an archive through class Extracter, in pure ruby
+
+You can use the following method to extract an archive, in ruby,
+into a specific target location on the given computer system:
+
+    Extracter.extract_what_to('foo-1.0.tar.xz', '/tmp')
+
+The first argument is the local path to an archive. The second
+argument simply specifies the **target**, usually the target
+directory. Can't get any simpler than that!
+
+## Colour support
+
+If the **Colours** gem (**gem install colours**) is available then colour
+support is possible for **class Extracter::Extracter**.
+
+For class Extracter::Extracter, whether colours are supported is 
+determined via the method called **.colours?**. If true then colours
+will be used - at the least it will be tried.
+
+If you do not want to have colours, for whatever the reason or use case,
+then you can disable this, e. g. through the method call
+**.disable_colours** specifically, to give one example for doing so.
+
+## class Extracter::ExtractIt
+
+**class Extracter::ExtractIt** was a standalone .gem (named **extract_it**), 
+but since as of **September 2020** it is now part of "module Extracter".
+
+Basically this class is is a wrapper over the class Extracter, which will
+extract archives in general. The extraction step will go into the current
+working directory.
+
+## What archives and files can be extracted?
+
+**class Extracter** can extract .tar.xz, .tar.bz, .tar.gz, tar.Z,
+.zip and numerous other file formats. This requires that tools
+such as **tar** or **gzip** or **xz** are installed and available
+on the target computer-machine, as we will simply use ruby to
+shell out to these other programs. Ruby is the ultimate 'glue'
+language after all.
+
+This class can also **extract audio-files** if ffmpeg is installed and
+the multimedia_paradise project is available (**gem install
+multimedia_paradise**), as well as squashfs files (typically 
+.img files). In the latter case, such an .img file will be mounted 
+in the current directory. You could then simply copy the content,
+to have a 'full' archive situation (mounting means read-only by
+deafult in this regard, hence why the copy-operation has to be
+done).
+
+Support for extracting **.jar files** - used by Java - has been
+added in **May 2020**.
+
+Support for 'extracting' .pdf files has been added in **January 2021**.
+This depends on **poppler**, and it is not really an extraction; we
+simply convert the file to a .txt (text) file. For this functionality
+the **pdf_paradise** project has to be available.
+
+Support for extracting archives on windows via 7zip has been added
+in **August 2021**. This was done because I had problems with 'tar'
+on windows; using 7zip bypassed these problems, and I needed to
+be able to extract archives on windows easily.
+
+## Usage example:
+
+    _ = Extracter.extract_what_to('foobar-1.0.tar.bz2', '/tmp/')
+
+You can also use the .new variant, which goes like so::
+
+    _ = Extracter.new('foo.gz', '/tmp', false) # Yes, you can extract .gz files.
+    _.run
+
+The argument false means "do not yet run". You have to invoke
+the .run method in that case.
+
+The second argument to the above method is the target location,
+the directory where we will extract our archive to.
+
+## strip components
+
+Say that we have a path such as **/home/x/htop/htop-3.0.5.tar.xz**. You
+want to extract it, say, into **/tmp/**.
+
+Normally this would create the following directory:
+
+    /tmp/htop-3.0.5/
+
+In most cases this is what the user wants; at the least I expect this
+if an archive is correctly tarred up, such as a **.tar.xz** file.
+
+But there are use cases where this is not the case so. For instance,
+say that you already did creat such a directory, cd-ed into it and
+now just want to extract right **into** this directory. Then you 
+don't want to end up with:
+
+    /tmp/htop-3.0.5/htop-3.0.5/
+
+**tar** allows us to avoid this, by using the commandline flag
+called **--strip-components=1**.
+
+In **October 2021** I needed this for the rbt-project. Since the
+old class Extracter did not support it, and the code was very messy,
+I ended up re-writing the project. It should now be better -
+at the least cleaner than it once was. And support for the above
+is possible as well now; even with a specific method call
+(which is **.strip_components()**).
+
+## Extracter.remove_archive_type
+
+If you have a use case where you would like to remove the file
+suffix from an archive, such as turning
+"https://rubygems.org/rubygems/rubygems-3.3.14.tgz" into
+"rubygems-3.3.14" exactly, then you can use
+Extracter.remove_archive_type() for this.
+
+Example follows:
+
+    Extracter.remove_archive_type(File.basename("https://rubygems.org/rubygems/rubygems-3.3.14.tgz")) # => "rubygems-3.3.14"
+
+
+## Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
+
+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 the
+explanation here, allow me to just briefly state that I do not feel as if I
+want to promote any Google service anymore when the user becomes the end
+product (such as via data collection by upstream services, including other
+proxy-services). My feeling is that this is a hugely flawed business model
+to begin with, and I no longer wish to support this in any way, even if
+only indirectly so, such as by using services of companies that try to
+promote this flawed model.
+
+In regards to responding to emails: please keep in mind that responding 
+may take some time, depending on the amount of work I may have at that
+moment. So it is not that emails are ignored; it is more that I have not
+(yet) found the time to read and reply. This means there may be a delay
+of days, weeks and in some instances also months. There is, unfortunately,
+not much I can do when I need to prioritise my time investment, but I try
+to consider <b>all</b> feedback as an opportunity to improve my projects
+nonetheless.
+
+In <b>2022</b> rubygems.org decided to make 2FA mandatory for every
+gem owner eventually:
+
+see
+https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
+
+However had, that has been reverted again, so I decided to shorten
+this paragraph. Mandatory 2FA may exclude users who do not have a 
+smartphone device or other means to 'identify'. I do not feel it is
+a fair assumption by others to be made that non-identified people may
+not contribute code, which is why I reject it. Mandatory 2FA would mean
+an end to all my projects on rubygems.org, so let's hope it will never
+happen. (Keep in mind that I refer to mandatory 2FA; I have no qualms
+for people who use 2FA on their own, but this carrot-and-stick strategy
+by those who control the rubygems infrastructure is a very bad one to
+pursue.
+

data/bin/extract

@@ -0,0 +1,7 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'extracter'
+
+Extracter.what_to(ARGV, Dir.pwd)

data/bin/extract_it

@@ -0,0 +1,13 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+require 'extracter/requires/require_the_extracter_project.rb'
+
+_ = Extracter.extract_it(ARGV, false)
+if ARGV[1]
+  _.show_commands_used
+else 
+  _.be_silent
+end
+_.run # extractit

data/doc/README.gen

@@ -0,0 +1,165 @@
+ADD_RUBY_BADGE
+	
+# Extracter
+
+## The primary goal of the extracter gem
+
+This gem can help the user if said user wants to **extract a given
+archive**.
+
+## Scope of Extracter
+
+The scope (and goals) for **class Extracter** are really simple: throw
+any archive format at it, and the class will try to **extract** it.
+
+It can be used on the commandline as well, via **bin/extracter**.
+
+Note that in order to extract a given archive, some programs must
+be available still. On linux this tends to be **tar**, **bzip2**,
+**xz** and **gzip**. On windows it is recommended to use **7-zip**.
+
+## How to find out whether a given file is a valid archive
+
+You can find out whether a given input **xyz** is a valid archive by
+issuing the following toplevel-method:
+
+    Extracter.is_this_a_valid_archive?(path)
+
+This will return either true or false. In <b>August 2022</b> the
+code was adapted slightly to return true no matter if the
+file extension is upcased or lowercased. In other words: a
+file called <b>foobar.zip</b> will work fine, as will the same 
+file but this time called <b>foobar.ZIP</b>. I had the latter issue
+when I downloaded a BIOS Firmware update in August 2022 - the
+file was .ZIP and Extracter did not work. So that was a tiny
+bug in the extracter gem - it really should work on .ZIP
+files just fine as well, since these are simply .zip files
+anyway.
+
+Keep in mind that not all archive formats have been added so far,
+so this will return false even if it should instead return true.
+
+More support for archive formats will be added whenever possible,
+as time permits.
+
+## How to extract an archive through class Extracter, in pure ruby
+
+You can use the following method to extract an archive, in ruby,
+into a specific target location on the given computer system:
+
+    Extracter.extract_what_to('foo-1.0.tar.xz', '/tmp')
+
+The first argument is the local path to an archive. The second
+argument simply specifies the **target**, usually the target
+directory. Can't get any simpler than that!
+
+## Colour support
+
+If the **Colours** gem (**gem install colours**) is available then colour
+support is possible for **class Extracter::Extracter**.
+
+For class Extracter::Extracter, whether colours are supported is 
+determined via the method called **.colours?**. If true then colours
+will be used - at the least it will be tried.
+
+If you do not want to have colours, for whatever the reason or use case,
+then you can disable this, e. g. through the method call
+**.disable_colours** specifically, to give one example for doing so.
+
+## class Extracter::ExtractIt
+
+**class Extracter::ExtractIt** was a standalone .gem (named **extract_it**), 
+but since as of **September 2020** it is now part of "module Extracter".
+
+Basically this class is is a wrapper over the class Extracter, which will
+extract archives in general. The extraction step will go into the current
+working directory.
+
+## What archives and files can be extracted?
+
+**class Extracter** can extract .tar.xz, .tar.bz, .tar.gz, tar.Z,
+.zip and numerous other file formats. This requires that tools
+such as **tar** or **gzip** or **xz** are installed and available
+on the target computer-machine, as we will simply use ruby to
+shell out to these other programs. Ruby is the ultimate 'glue'
+language after all.
+
+This class can also **extract audio-files** if ffmpeg is installed and
+the multimedia_paradise project is available (**gem install
+multimedia_paradise**), as well as squashfs files (typically 
+.img files). In the latter case, such an .img file will be mounted 
+in the current directory. You could then simply copy the content,
+to have a 'full' archive situation (mounting means read-only by
+deafult in this regard, hence why the copy-operation has to be
+done).
+
+Support for extracting **.jar files** - used by Java - has been
+added in **May 2020**.
+
+Support for 'extracting' .pdf files has been added in **January 2021**.
+This depends on **poppler**, and it is not really an extraction; we
+simply convert the file to a .txt (text) file. For this functionality
+the **pdf_paradise** project has to be available.
+
+Support for extracting archives on windows via 7zip has been added
+in **August 2021**. This was done because I had problems with 'tar'
+on windows; using 7zip bypassed these problems, and I needed to
+be able to extract archives on windows easily.
+
+## Usage example:
+
+    _ = Extracter.extract_what_to('foobar-1.0.tar.bz2', '/tmp/')
+
+You can also use the .new variant, which goes like so::
+
+    _ = Extracter.new('foo.gz', '/tmp', false) # Yes, you can extract .gz files.
+    _.run
+
+The argument false means "do not yet run". You have to invoke
+the .run method in that case.
+
+The second argument to the above method is the target location,
+the directory where we will extract our archive to.
+
+## strip components
+
+Say that we have a path such as **/home/x/htop/htop-3.0.5.tar.xz**. You
+want to extract it, say, into **/tmp/**.
+
+Normally this would create the following directory:
+
+    /tmp/htop-3.0.5/
+
+In most cases this is what the user wants; at the least I expect this
+if an archive is correctly tarred up, such as a **.tar.xz** file.
+
+But there are use cases where this is not the case so. For instance,
+say that you already did creat such a directory, cd-ed into it and
+now just want to extract right **into** this directory. Then you 
+don't want to end up with:
+
+    /tmp/htop-3.0.5/htop-3.0.5/
+
+**tar** allows us to avoid this, by using the commandline flag
+called **--strip-components=1**.
+
+In **October 2021** I needed this for the rbt-project. Since the
+old class Extracter did not support it, and the code was very messy,
+I ended up re-writing the project. It should now be better -
+at the least cleaner than it once was. And support for the above
+is possible as well now; even with a specific method call
+(which is **.strip_components()**).
+
+## Extracter.remove_archive_type
+
+If you have a use case where you would like to remove the file
+suffix from an archive, such as turning
+"https://rubygems.org/rubygems/rubygems-3.3.14.tgz" into
+"rubygems-3.3.14" exactly, then you can use
+Extracter.remove_archive_type() for this.
+
+Example follows:
+
+    Extracter.remove_archive_type(File.basename("https://rubygems.org/rubygems/rubygems-3.3.14.tgz")) # => "rubygems-3.3.14"
+
+ADD_CONTACT_INFORMATION

data/extracter.gemspec

@@ -0,0 +1,109 @@
+# =========================================================================== #
+# Gemspec for Project Extracter.
+# =========================================================================== #
+require 'extracter/version/version.rb'
+begin
+#  require 'roebe'
+require 'roebe/toplevel_methods/misc.rb'
+rescue LoadError; end
+
+Gem::Specification.new { |s|
+
+  s.name    = 'extracter'
+  s.version = Extracter::VERSION
+  s.date    = Time.now.strftime('%Y-%m-%d')
+
+  DESCRIPTION = <<-EOF
+
+This fairly small project can be used to extract different
+archive formats such as .tar.bz2 or .tbz - archives such
+as .gem and .lzma will also work.
+
+You can also extract audio, by making use of class ExtractAudio
+(part of the multimedia_paradise gem. The latter is - and should
+be - optional, though. If you have no such use case then you 
+won't need to install the multimedia_paradise gem.
+
+Usage example:
+
+    require 'extracter'
+
+    Extracter.new('/foo/bla-1.0.tar.bz2')
+
+The second argument that can be passed to the method new()
+specifies where this should be extract to.
+
+For example:
+
+    Extracter.new('/foo/bla-1.0.tar.bz2', '/opt')
+
+This would extract to the /opt directory.
+
+You can query whether input is an archive or not via:
+
+  Extracter.is_archive? 'foo.tar.xz'
+
+As of April 2014 we also provide a bin/extract file, so that
+you can simply extract something from the commandline.
+
+Since as of November 2018, class Extracter can also "extract"
+.iso files. (The .iso will be mounted to a directory that
+will be created, actually.)
+
+EOF
+
+  s.summary     = DESCRIPTION
+  s.description = DESCRIPTION
+
+  s.authors  = ['Robert A. Heiler']
+  s.email    = Roebe.email?
+  s.files    = Dir['**/*']
+  s.licenses = 'MIT'
+  s.homepage = 'https://rubygems.org/gems/extracter'
+
+  # ========================================================================= #
+  # Show this when a user installs the project.
+  # ========================================================================= #
+  s.post_install_message = <<-EOF
+
+  class Extracter can be used to extract archives, such as .tar.gz or
+  .zip.
+
+  If you need some help, you can invoke bin/extract via:
+
+      extract --help
+
+  In general, the syntax for extract is kept simple. Just pass in the
+  archive that has to be extracted as the first argument to 
+  extract ( bin/extract) , and class Extracter will try to extract
+  it, if it is a registered archive format.
+
+  In ruby code, you may be able to use class Extracter in this manner:
+
+      require 'extracter'
+      Extracter[file_path_here]
+
+  or
+
+      require 'extracter'
+      Extracter.new(file_path_here)
+
+  Specific example:
+
+      require 'extracter'
+      Extracter.new('htop-2.2.0.tar.xz')
+
+  See the --help option.
+
+  EOF
+
+  s.required_ruby_version     = '>= '+'3.2.2' # Roebe.third_most_stable_version_of_ruby
+  s.required_rubygems_version = '>= '+Gem::VERSION
+  s.rubygems_version          = '>= '+Gem::VERSION
+
+  # ========================================================================= #
+  # Specify the dependencies for this gem:
+  # ========================================================================= #
+  s.add_dependency 'opn'
+
+}

data/lib/extracter/base/base.rb

@@ -0,0 +1,178 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === Extracter::Base
+#
+# Usage example:
+#
+#   Extracter::Base.new(ARGV)
+#
+# =========================================================================== #
+# require 'extracter/base/base.rb'; < ::Extracter::Base
+# =========================================================================== #
+module Extracter
+
+class Base # === Extracter::Base
+
+  begin
+    require 'colours/html_colours'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :use_colours
+    # ======================================================================= #
+    @internal_hash[:use_colours] = true
+    # Next check whether the Colours gem is available.
+    check_whether_the_colours_gem_is_available
+  end
+
+  # ========================================================================= #
+  # === check_whether_the_colours_gem_is_available
+  # ========================================================================= #
+  def check_whether_the_colours_gem_is_available
+    if Object.const_defined?(:Colours) and
+       Colours.respond_to?(:simp) and
+       Colours.respond_to?(:sfancy) and
+       Colours.respond_to?(:sdir) and
+       Colours.respond_to?(:simp)
+    else
+      @internal_hash[:use_colours] = false
+    end
+  end
+
+  # ========================================================================= #
+  # === cyan
+  # ========================================================================= #
+  def cyan?
+    return Colours::CYAN if Object.const_defined?(:Colours) and use_colours?
+    return ''
+  end
+
+  # ========================================================================= #
+  # === tomato
+  # ========================================================================= #
+  def tomato(i = '', use_colours = use_colours?)
+    return Colours.tomato(i) if use_colours
+    return i
+  end
+
+  # ========================================================================= #
+  # === simp
+  # ========================================================================= #
+  def simp(i = '')
+    return Colours.simp(i) if use_colours?
+    return i
+  end
+
+  # ========================================================================= #
+  # === steelblue
+  # ========================================================================= #
+  def steelblue(i = '')
+    return ::Colours.steelblue(i) if use_colours? and ::Colours.respond_to?(:steelblue)
+    return i
+  end
+
+  # ========================================================================= #
+  # === ewarn
+  # ========================================================================= #
+  def ewarn(i = '')
+    if use_colours? and Object.const_defined?(:Colours)
+      e Colours.swarn(i)
+    else
+      e i
+    end
+  end
+
+  # ========================================================================= #
+  # === sfile
+  # ========================================================================= #
+  def sfile(i = '')
+    return Colours.sfancy(i) if use_colours?
+    return i
+  end
+
+  # ========================================================================= #
+  # === sfancy
+  # ========================================================================= #
+  def sfancy(i = '')
+    return Colours.sfancy(i) if use_colours?
+    return i
+  end
+
+  # ========================================================================= #
+  # === sdir
+  # ========================================================================= #
+  def sdir(i = '')
+    return Colours.sdir(i) if use_colours?
+    return i
+  end
+
+  # ========================================================================= #
+  # === use_colours?
+  #
+  # Determine whether we will use colours in class Extracter.
+  # ========================================================================= #
+  def use_colours?
+    @internal_hash[:use_colours]
+  end; alias colours? use_colours? # === colours?
+
+  # ========================================================================= #
+  # === e                                                             (e tag)
+  # ========================================================================= #
+  def e(i = '')
+    puts i
+  end
+
+  # ========================================================================= #
+  # === cpr
+  # ========================================================================= #
+  def cpr(a, b)
+    require 'fileutils' unless Object.const_defined?(:FileUtils)
+    FileUtils.cp_r(a, b)
+  end
+
+  # ========================================================================= #
+  # === move
+  # ========================================================================= #
+  def move(a, b)
+    require 'fileutils' unless Object.const_defined?(:FileUtils)
+    FileUtils.mv(a, b)
+  end; alias mv move # === mv
+
+  # ========================================================================= #
+  # === remove_this_directory
+  # ========================================================================= #
+  def remove_this_directory(i)
+    if File.directory? i
+      FileUtils.rm_r(i) unless i == '/'
+    end
+  end
+
+  # ========================================================================= #
+  # === change_directory
+  # ========================================================================= #
+  def change_directory(i)
+    Dir.chdir(i)
+  end; alias cd change_directory # === cd
+
+  # ========================================================================= #
+  # === rev
+  # ========================================================================= #
+  def rev
+    ::Colours.rev
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Extracter::Extracter.new(ARGV)
+end # base.rb