tardotgz 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9acd07e3ea9d916e486115af4896ff6429134978
+  data.tar.gz: 88cfd8afdb870471c0bda5c470369594570840fc
+SHA512:
+  metadata.gz: f62e00b6fb2d2459ef105959a8fb1ffcab87573f16fc3cab9ea8a3d56e4fd1066a4ef4914c53f8a30fa5b7b4899b57ec8950402035e8bd8c9242d440dea09244
+  data.tar.gz: 5e7ebb7f89d0fe411acb368633a78fe1037620b0c497901fbfa2091ee22149e1c5fc6ff80f3e4dad5878283a73eb4aea58fc6025acaa470a2ec37b2b1e3a2452

data/.gitignore

@@ -0,0 +1,23 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+scratchpad

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in ..gemspec
+gemspec

data/README.md

@@ -0,0 +1,163 @@
+# Tardotgz
+
+Tardotgz is an extraction of a few archive utility methods I wrote while working on a project at GitHub. These methods simplify the creation of gzipped tarball archives and the reading and extraction of files from those archives.
+
+One of the unique features of the #read_from_archive and #extract_from_archive utility methods is the ability to pass them a block (in fact `#extract_from_archive` just calls `#read_from_archive` and passes it a block).
+
+And in case you were wondering, I've been pronouncing it "tar-dot-jeez" :grin:
+
+## Installation
+
+You can install at the command line:
+
+```bash
+$ gem install tardotgz
+```
+
+Or add the gem to your Gemfile:
+
+```ruby
+source "https://rubygems.org"
+
+gem "tardotgz"
+```
+
+## Usage
+
+Start by including the module into the class where you'll use it.
+
+```ruby
+require "tardotgz"
+
+class FruitRollup
+  include Tardotgz
+end
+```
+
+### Create an archive
+
+Create an archive from a folder by calling `#create_archive` with the source path (the directory or file you want to archive) and the target path (the path and filename for the archive that it creates).
+
+```ruby
+> fr = FruitRollup.new
+=> #<FruitRollup:0x007fc0e4acf538>
+> source_path = File.expand_path("~/Notes")
+=> "/Users/jonmagic/Notes"
+> archive_path = File.expand_path("~/Dropbox/notes.tar.gz")
+=> "/Users/jonmagic/Dropbox/notes.tar.gz"
+> fr.create_archive(source_path, archive_path)
+=> "/Users/jonmagic/Dropbox/notes.tar.gz"
+```
+
+### Read file(s) from an archive
+
+You can read the contents of a file (or files) in an archive without unzipping or untarring the archive by using the `#read_from_archive` method. It's use is also fairly flexible.
+
+#### Read the contents of a single file
+
+```ruby
+> fr.read_from_archive(archive_path, "testing1.md")
+=> "hello world\n"
+```
+
+#### Read the contents of files matching a pattern
+
+```ruby
+> fr.read_from_archive(archive_path, /testing\d.md/) # read all files matching pattern
+=> "hello world\nfoobarbaz\n"
+```
+
+#### Passing a block yields the block with each tarfile that matches the pattern
+
+```ruby
+> fr.read_from_archive(archive_path, /testing\d.md/) do |tarfile| # pass a block
+*   puts tarfile.read.upcase
+* end
+HELLO WORLD
+
+FOOBARBAZ
+
+=> nil
+```
+
+### Extract file(s) from an archive
+
+You can extract the contents of an archive with #extract_from_archive.
+
+#### Extract a single file
+
+```ruby
+> destination_path = File.expand_path("~/Restored notes")
+=> "/Users/jonmagic/Restored notes"
+> fr.extract_from_archive(archive_path, destination_path, "testing1.md")
+=> "/Users/jonmagic/Restored notes"
+> File.exist?("#{destination_path}/testing1.md")
+=> true
+> File.exist?("#{destination_path}/testing2.md")
+=> false
+```
+
+#### Extract all files matching a pattern
+
+```ruby
+> fr.extract_from_archive(archive_path, destination_path, /testing\d\.md/)
+=> "/Users/jonmagic/Restored notes"
+> File.exist?("#{destination_path}/testing1.md")
+=> true
+> File.exist?("#{destination_path}/testing2.md")
+=> true
+```
+
+#### Passing a block cleans up extracted files after extracting and then yielding the block
+
+```ruby
+> fr.extract_from_archive(archive_path, destination_path, /testing\d\.md/) do
+*   puts File.exist?("#{destination_path}/testing1.md")
+*   puts File.exist?("#{destination_path}/testing2.md")
+* end
+true
+true
+=> nil
+> File.exist?(destination_path)
+=> false
+```
+
+## Contribute
+
+If you'd like to hack on Tardotgz, start by forking the repo on GitHub:
+
+https://github.com/jonmagic/tardotgz
+
+The best way to get your changes merged back into core is as follows:
+
+1. Clone down your fork
+1. Create a thoughtfully named topic branch to contain your change
+1. Hack away
+1. If you are adding new functionality, document it in the README
+1. If necessary, rebase your commits into logical chunks, without errors
+1. Push the branch up to GitHub
+1. Send a pull request for your branch
+
+## LICENSE
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Jonathan Hoyt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Rakefile

@@ -0,0 +1,8 @@
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task :default => :test

data/lib/tardotgz.rb

@@ -0,0 +1,135 @@
+require "fileutils"
+require "pathname"
+require "rubygems/package"
+require "tempfile"
+require "zlib"
+
+module Tardotgz
+  # Public: Create a gzipped archive with the contents of source_path.
+  #
+  # source_path  - Pathname or String path to files that need archived.
+  # archive_path - Pathname or String path and filename for created archive.
+  #
+  # Returns Pathname or String archive_path.
+  def create_archive(source_path, archive_path)
+    unless File.readable?(source_path)
+      raise Errno::ENOENT.new(source_path.to_s)
+    end
+
+    unless File.writable?(Pathname(archive_path).dirname)
+      raise Errno::EACCES.new(archive_path.to_s)
+    end
+
+    tarfile = Tempfile.new(Pathname(archive_path).basename.to_s)
+
+    Gem::Package::TarWriter.new(tarfile) do |tar|
+      Dir[File.join(source_path.to_s, "**/*")].each do |file|
+        mode = File.stat(file).mode
+        relative_file = file.sub /^#{Regexp::escape source_path.to_s}\/?/, ''
+
+        if File.directory?(file)
+          tar.mkdir relative_file, mode
+        else
+          tar.add_file relative_file, mode do |tf|
+            File.open(file, "rb") { |f| tf.write f.read }
+          end
+        end
+      end
+    end
+
+    tarfile.rewind
+
+    File.open(archive_path, "wb") do |gz|
+      z = Zlib::GzipWriter.new(gz)
+      z.write tarfile.read
+      z.close
+      tarfile.close
+    end
+
+    return archive_path
+  end
+
+  # Public: Read and return file(s) contents from archive or yield block
+  # with each files contents as it is read.
+  #
+  # archive_path - Pathname or String path to archive.
+  # pattern      - String relative file path or Regexp pattern for selecting
+  #                multiple files.
+  #
+  # Returns a String (or NilClass if block given).
+  def read_from_archive(archive_path, pattern)
+    results = []
+
+    Zlib::GzipReader.open(archive_path) do |gz|
+      Gem::Package::TarReader.new(gz) do |tar|
+        case pattern
+        when String
+          tarfile = tar.detect do |tarfile|
+            tarfile.full_name == pattern
+          end
+
+          if tarfile
+            if block_given?
+              yield(tarfile)
+              return nil
+            else
+              results << tarfile.read
+            end
+          end
+        when Regexp
+          tar.each do |tarfile|
+            if tarfile.full_name =~ pattern
+              if block_given?
+                yield(tarfile)
+              else
+                results << tarfile.read
+              end
+            end
+          end
+
+          return nil if block_given?
+        end
+      end
+    end
+
+    if results.empty?
+      message = pattern.is_a?(Regexp) ? pattern.inspect : pattern
+      raise Errno::ENOENT.new(message)
+    end
+
+    results.join
+  end
+
+  # Public: Extract file(s) from archive to destination path and optionally
+  # cleanup extracted files after yielding a block if it is provided.
+  #
+  # archive_path     - Pathname or String path to archive.
+  # destination_path - Pathname or String destination path for files.
+  # pattern          - String relative file path or Regexp pattern for
+  #                    selecting multiple files.
+  #
+  # Returns Pathname or String destination_path (or NilClass if block given).
+  def extract_from_archive(archive_path, destination_path, pattern=/.*/, &block)
+    read_from_archive(archive_path, pattern) do |tarfile|
+      destination_file = File.join(destination_path, tarfile.full_name)
+
+      if tarfile.directory?
+        FileUtils.mkdir_p(destination_file)
+      else
+        destination_directory = File.dirname(destination_file)
+        FileUtils.mkdir_p(destination_directory) unless File.directory?(destination_directory)
+        File.open(destination_file, "wb") do |f|
+          f.write(tarfile.read)
+        end
+      end
+    end
+
+    if block_given? && File.exist?(destination_path)
+      yield
+      FileUtils.rm_rf(destination_path, :secure => true)
+      return nil
+    else
+      return destination_path
+    end
+  end
+end

data/tardotgz.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+
+Gem::Specification.new do |spec|
+  spec.name          = "tardotgz"
+  spec.version       = "1.0.2"
+  spec.platform      = Gem::Platform::RUBY
+  spec.date          = "2015-02-22"
+  spec.summary       = "Archive utility module"
+  spec.description   = "Methods for creating, reading, and extracting gzipped tarballs."
+  spec.authors       = ["Jonathan Hoyt"]
+  spec.email         = "jonmagic@gmail.com"
+  spec.files         = ["lib/tardotgz.rb"]
+  spec.homepage      = "https://github.com/jonmagic/tardotgz"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split("\n")
+  spec.test_files    = `git ls-files -- {test}/*`.split("\n")
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler",  "~> 1.6"
+  spec.add_development_dependency "rake",     "~> 10.4"
+  spec.add_development_dependency "minitest", "~> 5.5"
+end

data/test/lib/tardotgz_test.rb

@@ -0,0 +1,127 @@
+require_relative "../test_helper"
+
+class TardotgzTest < Minitest::Test
+  include Tardotgz
+
+  def test_that_constant_is_defined
+    assert_equal "constant", defined?(Tardotgz)
+  end
+
+  def test_that_it_is_a_module
+    assert_equal Module, Tardotgz.class
+  end
+
+  def test_create_archive_creates_archive
+    source_path = path_helper("lib")
+    archive_path = path_helper("lib.tar.gz")
+    assert_equal archive_path, create_archive(source_path, archive_path)
+
+    assert File.exist?(archive_path)
+    File.delete(archive_path)
+  end
+
+  def test_create_archive_raises_error_if_source_path_is_not_readable
+    source_path = path_helper("foobarbaz")
+    archive_path = path_helper("lib.tar.gz")
+
+    assert_raises(Errno::ENOENT) do
+      create_archive(source_path, archive_path)
+    end
+  end
+
+  def test_create_archive_raises_error_if_archive_path_is_not_writable
+    source_path = path_helper("lib")
+    archive_path = "/foo.tar.gz"
+
+    assert_raises(Errno::EACCES) do
+      create_archive(source_path, archive_path)
+    end
+  end
+
+  def test_read_from_archive_returns_contents_of_file_matching_pattern_string
+    archive_path = path_helper("test/fixtures/archive.tar.gz")
+    pattern      = "testing1.md"
+
+    assert_equal "hello world\n", read_from_archive(archive_path, pattern)
+  end
+
+  def test_read_from_archive_returns_contents_of_files_matching_pattern_regexp
+    archive_path     = path_helper("test/fixtures/archive.tar.gz")
+    pattern          = /testing\d\.md/
+
+    assert_equal "hello world\nfoobarbaz\n", read_from_archive(archive_path, pattern)
+  end
+
+  def test_read_from_archive_yields_block_for_each_file_matching_pattern
+    archive_path     = path_helper("test/fixtures/archive.tar.gz")
+    pattern          = /testing\d\.md/
+    expected_results = [
+      "hello world\n",
+      "foobarbaz\n"
+    ]
+
+    result = read_from_archive(archive_path, pattern) do |tarfile|
+      assert expected_results.include?(tarfile.read)
+    end
+
+    assert_nil result
+  end
+
+  def test_read_from_archive_raises_error_if_archive_does_not_exist
+    archive_path = path_helper("foobarbaz.tar.gz")
+
+    assert_raises(Errno::ENOENT) do
+      read_from_archive(archive_path, "foo")
+    end
+  end
+
+  def test_read_from_archive_raises_error_if_pattern_does_not_match_any_files
+    archive_path = path_helper("test/fixtures/archive.tar.gz")
+
+    assert_raises(Errno::ENOENT) do
+      read_from_archive(archive_path, "foobarbaz")
+    end
+
+    assert_raises(Errno::ENOENT) do
+      read_from_archive(archive_path, /drunken\/noodle/)
+    end
+  end
+
+  def test_extract_from_archive_writes_archive_contents_for_string_pattern_to_disk
+    archive_path     = path_helper("test/fixtures/archive.tar.gz")
+    destination_path = path_helper(".tarball-extract-tmp")
+    pattern          = "testing1.md"
+
+    assert_equal destination_path, extract_from_archive(archive_path, destination_path, pattern)
+    assert File.exist?(destination_path.join("testing1.md"))
+
+    FileUtils.rm_rf(destination_path, :secure => true)
+  end
+
+  def test_extract_from_archive_writes_archive_contents_for_regexp_pattern_to_disk
+    archive_path     = path_helper("test/fixtures/archive.tar.gz")
+    destination_path = path_helper(".tarball-extract-tmp")
+    pattern          = /testing\d\.md/
+
+    assert_equal destination_path, extract_from_archive(archive_path, destination_path, pattern)
+    assert File.exist?(destination_path.join("testing1.md"))
+    assert File.exist?(destination_path.join("testing2.md"))
+
+    FileUtils.rm_rf(destination_path, :secure => true)
+  end
+
+  def test_extract_from_archive_accepts_a_block_and_cleans_up_after_yield
+    archive_path     = path_helper("test/fixtures/archive.tar.gz")
+    destination_path = path_helper(".tarball-extract-tmp")
+    pattern          = /testing\d\.md/
+
+    result = extract_from_archive(archive_path, destination_path, pattern) do
+      assert File.exist?(destination_path.join("testing1.md"))
+      assert File.exist?(destination_path.join("testing2.md"))
+    end
+
+    assert_nil result
+    refute File.exist?(destination_path)
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
+require "tardotgz"
+require "minitest/autorun"
+require "pathname"
+
+def path_helper(path_relative_to_project_root)
+  project_root = File.expand_path("../", File.dirname(__FILE__))
+  Pathname(project_root).join(path_relative_to_project_root)
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: tardotgz
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+platform: ruby
+authors:
+- Jonathan Hoyt
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.5'
+description: Methods for creating, reading, and extracting gzipped tarballs.
+email: jonmagic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- Rakefile
+- lib/tardotgz.rb
+- tardotgz.gemspec
+- test/fixtures/archive.tar.gz
+- test/lib/tardotgz_test.rb
+- test/test_helper.rb
+homepage: https://github.com/jonmagic/tardotgz
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Archive utility module
+test_files: []