extracter 1.2.21

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4dd1b2c2a31905a0e465da5168dc38aac97090433c01b1778c441264907b7f2
+  data.tar.gz: 9a0b0a5aafaba2ba966f6582f31f89591673572130d1fe47477352e477dbfbff
+SHA512:
+  metadata.gz: ca21cc9c72020968bc4c5fdddea44213a2ce7328cba03c91b3286dac67351cd8c6d9d13747b9a5aede3c4a724ff6d32b3b36554c05ba4dcbccf48ff7fa8b521b
+  data.tar.gz: a5a76451755727807c2e13887f7e106959e2bde7237fc98df62ec0f873aa72f06e642adfef470197c87e5b8c733716d391941c40be9a4df84d6931a9ef41f727

data/README.md

@@ -0,0 +1,207 @@
+[![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 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/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,106 @@
+# =========================================================================== #
+# Gemspec for Project Extracter.
+# =========================================================================== #
+require 'extracter/version/version.rb'
+require 'roebe'
+
+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     = '>= '+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,140 @@
+#!/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'
+  rescue LoadError; end
+
+  # ========================================================================= #
+  # === reset
+  # ========================================================================= #
+  def reset
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :use_colours
+    # ======================================================================= #
+    @internal_hash[:use_colours] = true
+  end
+
+  # ========================================================================= #
+  # === cyan
+  # ========================================================================= #
+  def cyan?
+    return Colours::CYAN if Object.const_defined?(:Colours) and use_colours?
+    return ''
+  end
+
+  # ========================================================================= #
+  # === tomato
+  # ========================================================================= #
+  def tomato(i = '')
+    return Colours.tomato(i) if use_colours?
+    return i
+  end
+
+  # ========================================================================= #
+  # === simp
+  # ========================================================================= #
+  def simp(i = '')
+    return Colours.simp(i) if use_colours?
+    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
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  Extracter::Extracter.new(ARGV)
+end # base.rb