and_feathers 0.0.1 → 1.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1223a216ba02082494665468136a5511c39a9f1a
-  data.tar.gz: ab24c8bbac7301824b242bbb875c7ff88b3b60f4
+  metadata.gz: c8677ebc7f56d9f906f50385f52023ac81ba58bd
+  data.tar.gz: c480d1890de2bc3d78f2d7da5daf317300113be0
 SHA512:
-  metadata.gz: ce15a3c45c91982cad44943259acd6575b49f28e639bfec316a307ab973434d61b50088604898f6ad0b618b42745c54cd7ac373185d2cf4b4c0bc27d774e883c
-  data.tar.gz: 3db4aa09d56d1d9829909d89bc5e246f2f38eeb112f4ed62643160319ac83375dda49a395ba3d7ee23563a2fffad723098837f6fb778d46a23396782c33d1f5a
+  metadata.gz: f9fb0a23273a125b5a519d11c3f8a5a00cde68e7a33afbf0c5159c8d2b10954b159c42fc9de5212f5a8d4ff97d0a1fec8d463910f1960f9fd29503465b6614b3
+  data.tar.gz: 9e541a6708157de758811e543cbc6bef2cdd25dea3dad6aac1c0243f0f288b62834eb702d1672633ef7788a53718826da671c09753080422a9dc803675fd4a43

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+.ruby-version

data/.rspec

@@ -1,4 +1,4 @@
 -I spec
 -I lib
 --color
---order random
+-r byebug

data/Gemfile

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

data/README.md

@@ -1,14 +1,10 @@
 # AndFeathers
 
-Declaratively build in-memory gzipped tarballs.
+Declaratively and iteratively build in-memory archive structures.
 
 ## Installation
 
-Either run:
-
-    $ gem install and_feathers
-
-Or, if you're using Bundler, add this line to your application's Gemfile:
+Add this line to your application's Gemfile:
 
     gem 'and_feathers'
 
@@ -16,15 +12,28 @@ And then execute:
 
     $ bundle
 
+Or install it yourself as:
+
+    $ gem install and_feathers
+
 ## Usage
 
-Suppose you want to create the equivalent of a Chef cookbook artifact created using knife:
+The examples below focus on specifying an archive's structure using `and_feathers`. See:
+
+* [`and_feathers-gzipped_tarball`](https://github.com/bcobb/and_feathers-gzipped_tarball) for notes on writing a `.tgz` file to disk
+* [`and_feathers-zip`](https://github.com/bcobb/and_feathers-zip) for notes on writing a `.zip` file to disk
+
+Once you're "inside" `and_feathers`, either because you've called `AndFeathers.build` or `AndFeathers.from_path`, the two main methods you'll call on block parameters are `file` and `dir`. These, as you might suspect, create file and directory entries, respectively.
+
+The examples below show how you might use these two methods to build up directory structures.
+
+### Specify each directory and file individually
 
 ```ruby
 require 'and_feathers'
 require 'json'
 
-tarball = AndFeathers.build('redis') do |redis|
+archive = AndFeathers.build('redis') do |redis|
   redis.file('README.md') { "README content" }
   redis.file('metadata.json') { JSON.dump({}) }
   redis.file('metadata.rb') { "# metadata.rb content" }
@@ -32,13 +41,50 @@ tarball = AndFeathers.build('redis') do |redis|
     attributes.file('default.rb') { '# default.rb content' }
   end
   redis.dir('recipes') do |recipes|
-    attributes.file('default.rb') { '# default.rb content' }
+    recipes.file('default.rb') { '# default.rb content' }
   end
   redis.dir('templates') do |templates|
     templates.dir('default')
   end
 end
+```
+
+### Specify directories and files by their paths
 
-tarball.to_io # a gzipped, tarball StringIO
+```ruby
+require 'and_feathers'
+
+archive = AndFeathers.build('rails_app') do |app|
+  app.file('README.md') { "README content" }
+  app.file('config/routes.rb') do
+    "root to: 'public#home'"
+  end
+  app.dir('app/controllers') do |controllers|
+    controllers.file('application_controller.rb') do
+      "class ApplicationController < ActionController:Base\nend"
+    end
+    controllers.file('public_controller.rb') do
+      "class PublicController < ActionController:Base\nend"
+    end
+  end
+  app.file('app/views/public/home.html.erb')
+end
 ```
 
+### Load an existing directory as an Archive
+
+In the example below, we load the fixture directory at [`spec/fixtures/archiveme`](/spec/fixtures/archiveme), and then use `and_feathers` to perform surgery on the in-memory archive. In particular, we add a `test` directory and file to its archive, and update its `lib` directory a couple of times.
+
+```ruby
+require 'and_feathers'
+
+archive = AndFeathers.from_path('spec/fixtures/archiveme')
+archive.file('test/basic_test.rb') { '# TODO: tests' }
+archive.file('lib/archiveme/version.rb') do
+  "module Archiveme\n  VERSION = '1.0.0'\nend"
+end
+archive.file('lib/archiveme.rb') do
+  # The Archiveme fixture is a class, but we'll change it to a module
+  "module Archiveme\nend"
+end
+```

data/and_feathers.gemspec

@@ -8,7 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = AndFeathers::VERSION
   spec.authors       = ["Brian Cobb"]
   spec.email         = ["bcobb@uwalumni.com"]
-  spec.summary       = %q{Declaratively build GZipped Tarballs in memory}
+  spec.description   = %q{Declaratively and iteratively build archive structures which easily serialize to on-disk formats such as zip and tgz.}
+  spec.summary       = %q{In-memory archive structures}
   spec.homepage      = "http://github.com/bcobb/and_feathers"
   spec.license       = "MIT"
 

data/lib/and_feathers/archive.rb

@@ -0,0 +1,99 @@
+require 'and_feathers/file'
+require 'and_feathers/directory'
+require 'and_feathers/sugar'
+
+module AndFeathers
+  #
+  # The parent class of a given directory tree. It knows whether or not the
+  # archive's contents should be extracted into its own directory or into its
+  # containing directory.
+  #
+  # An +Archive+ exposes the same sugary interface exposed by a +Directory+,
+  # but it is implemented so that adding files and directories directly to the
+  # +Archive+ is not destructive. In fact, whenever a file or directory is
+  # added to an +Archive+, the +Archive+ creates a new top-level directory, and
+  # delegates the change to it. That way, when it's time to enumerate the
+  # entries in the +Archive+, we can take the union of all of these top-level
+  # directories and enumerate _its_ entries. Thus, the only possibility for
+  # loss is if two changes modify the same file, in which case we take the
+  # latest file to be the authoritative file.
+  #
+  class Archive
+    include Sugar
+    include Enumerable
+
+    #
+    # Creates a new +Archive+
+    #
+    # @param extract_to [String] the path under which the +Archive+ should be
+    #   extracted
+    # @param extraction_mode [Fixnum] the mode of the +Archive+'s base directory
+    #
+    def initialize(extract_to = '.', extraction_mode = 16877)
+      @initial_version = Directory.new(extract_to, extraction_mode)
+      @versions = [@initial_version]
+      @extract_to = extract_to
+      @extraction_mode = extraction_mode
+    end
+
+    #
+    # Adds a +Directory+ to the top level of the +Archive+
+    #
+    # @param directory [Directory]
+    #
+    def add_directory(directory)
+      @versions << Directory.new(@extract_to, @extraction_mode).tap do |parent|
+        parent.add_directory(directory)
+      end
+    end
+
+    #
+    # Adds a +File+ to the top level of the +Archive+
+    #
+    # @param file [File]
+    #
+    def add_file(file)
+      @initial_version.file(file.name, file.mode, &file.content)
+    end
+
+    #
+    # Iterates depth-first through the +Archive+'s entries
+    #
+    # @yieldparam entry [Directory, File]
+    #
+    def each(&block)
+      @versions.reduce(&:|).each(&block)
+    end
+
+    #
+    # Returns this +Archive+ as a package of the given +package_type+
+    #
+    # @example
+    #   require 'and_feathers/gzipped_tarball'
+    #
+    #   format = AndFeathers::GzippedTarball
+    #   AndFeathers::Archive.new('test', 16877).to_io(format)
+    #
+    # @see https://github.com/bcobb/and_feathers-gzipped_tarball
+    # @see https://github.com/bcobb/and_feathers-zip
+    #
+    # @param package_type [.open,#add_file,#add_directory]
+    #
+    # @return [StringIO]
+    #
+    def to_io(package_type)
+      package_type.open do |package|
+        package.add_directory(@initial_version)
+
+        each do |child|
+          case child
+          when File
+            package.add_file(child)
+          when Directory
+            package.add_directory(child)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/and_feathers/directory.rb

@@ -0,0 +1,155 @@
+require 'and_feathers/sugar'
+
+module AndFeathers
+  #
+  # Represents a Directory
+  #
+  class Directory
+    include Sugar
+    include Enumerable
+
+    attr_reader :name, :mode
+    attr_writer :parent
+
+    #
+    # @!attribute [r] name
+    #   @return [String] the directory name
+    #
+    # @!attribute [r] mode
+    #   @return [Fixnum] the directory mode
+    #
+    # @!attribute [rw] parent
+    #   @return [Directory] the directory's parent
+    #
+
+    #
+    # Creates a new +Directory+
+    #
+    # @param name [String] the directory name
+    # @param mode [Fixnum] the directory mode
+    #
+    def initialize(name = '.', mode = 16877)
+      @name = name
+      @mode = mode
+      @parent = nil
+      @files = {}
+      @directories = {}
+    end
+
+    #
+    # This +Directory+'s path
+    #
+    # @return [String]
+    #
+    def path
+      if @parent
+        ::File.join(@parent.path, name)
+      else
+        if name != '.'
+          ::File.join('.', name)
+        else
+          name
+        end
+      end
+    end
+
+    #
+    # Determines this +Directory+'s path relative to the given path.
+    #
+    # @return [String]
+    #
+    def path_from(relative_path)
+      path.sub(/^#{Regexp.escape(relative_path)}\/?/, '')
+    end
+
+    #
+    # Computes the union of this +Directory+ with another +Directory+. If the
+    # two directories have a file path in common, the file in the +other+
+    # +Directory+ takes precedence. If the two directories have a sub-directory
+    # path in common, the union's sub-directory path will be the union of those
+    # two sub-directories.
+    #
+    # @raise [ArgumentError] if the +other+ parameter is not a +Directory+
+    #
+    # @param other [Directory]
+    #
+    # @return [Directory]
+    #
+    def |(other)
+      if !other.is_a?(Directory)
+        raise ArgumentError, "#{other} is not a Directory"
+      end
+
+      self.dup.tap do |directory|
+        other.files.each do |file|
+          directory.add_file(file.dup)
+        end
+
+        other.directories.each do |new_directory|
+          existing_directory = @directories[new_directory.name]
+
+          if existing_directory.nil?
+            directory.add_directory(new_directory.dup)
+          else
+            directory.add_directory(new_directory.dup | existing_directory.dup)
+          end
+        end
+      end
+    end
+
+    #
+    # The +File+ entries which exist in this +Directory+
+    #
+    # @return [Array<File>]
+    #
+    def files
+      @files.values
+    end
+
+    #
+    # The +Directory+ entries which exist in this +Directory+
+    #
+    # @return [Array<Directory>]
+    #
+    def directories
+      @directories.values
+    end
+
+    #
+    # Iterates through this +Directory+'s children depth-first
+    #
+    # @yieldparam child [File, Directory]
+    #
+    def each(&block)
+      files.each(&block)
+
+      directories.each do |subdirectory|
+        block.call(subdirectory)
+
+        subdirectory.each(&block)
+      end
+    end
+
+    #
+    # Sets the given +directory+'s parent to this +Directory+, and adds it as a
+    # child.
+    #
+    # @param directory [Directory]
+    #
+    def add_directory(directory)
+      @directories[directory.name] = directory
+      directory.parent = self
+    end
+
+    #
+    # Sets the given +file+'s parent to this +Directory+, and adds it as a
+    # child.
+    #
+    # @param file [File]
+    #
+    def add_file(file)
+      @files[file.name] = file
+      file.parent = self
+    end
+  end
+end

data/lib/and_feathers/file.rb

@@ -0,0 +1,66 @@
+module AndFeathers
+  #
+  # Represents a File inside the archive
+  #
+  class File
+    attr_reader :name, :mode, :content
+    attr_writer :parent
+
+    #
+    # @!attribute [r] name
+    #   @return [String] the file's name
+    #
+    # @!attribute [r] mode
+    #   @return [Fixnum] the file's mode
+    #
+    # @!attribute [r] content
+    #   @return [Fixnum] a block which returns the file's content
+    #
+    # @!attribute [rw] parent
+    #   @return [Directory] the file's parent
+    #
+
+    #
+    # Creates a new +File+
+    #
+    # @param name [String] the file name
+    # @param mode [Fixnum] the file mode
+    # @param content [Proc] a block which returns the file contents
+    #
+    def initialize(name, mode, content)
+      @name = name
+      @mode = mode
+      @content = content
+      @parent = nil
+    end
+
+    #
+    # This +File+'s path
+    #
+    # @return [String]
+    #
+    def path
+      if @parent
+        ::File.join(@parent.path, name)
+      else
+        ::File.join('.', name)
+      end
+    end
+
+    #
+    # Determines this +File+'s path relative to the given path.
+    #
+    # @return [String]
+    #
+    def path_from(relative_path)
+      path.sub(/^#{Regexp.escape(relative_path)}\/?/, '')
+    end
+
+    #
+    # This +File+'s contents
+    #
+    def read
+      @content.call
+    end
+  end
+end

data/lib/and_feathers/sugar.rb

@@ -0,0 +1,105 @@
+module AndFeathers
+  #
+  # A module which provides convenience methods for defining a directory/file
+  # structure
+  #
+  module Sugar
+    #
+    # Add a +Directory+ named +name+ to this entity's list of children. The
+    # +name+ may simply be the name of the directory, or may be a path to the
+    # directory.
+    #
+    # In the case of the latter, +dir+ will create the +Directory+ tree
+    # specified by the path. The block parameter yielded in this case will be
+    # the innermost directory.
+    #
+    # @example
+    #   archive = Directory.new
+    #   archive.dir('app') do |app|
+    #     app.name == 'app'
+    #     app.path == './app'
+    #   end
+    #
+    # @example
+    #   archive.dir('app/controllers/concerns') do |concerns|
+    #     concerns.name == 'concerns'
+    #     concerns.path == './app/controllers/concerns'
+    #   end
+    #
+    # @param name [String] the directory name
+    # @param mode [Fixnum] the directory mode
+    #
+    # @yieldparam directory [AndFeathers::Directory] the newly-created
+    #   +Directory+
+    #
+    def dir(name, mode = 16877, &block)
+      name_parts = name.split(::File::SEPARATOR)
+
+      innermost_child_name = name_parts.pop
+
+      if name_parts.empty?
+        Directory.new(name, mode).tap do |directory|
+          add_directory(directory)
+
+          block.call(directory) if block
+        end
+      else
+        innermost_parent = name_parts.reduce(self) do |parent, child_name|
+          parent.dir(child_name)
+        end
+
+        innermost_parent.dir(innermost_child_name, &block)
+      end
+    end
+
+    #
+    # The default file content block, which returns an empty string
+    #
+    NO_CONTENT = Proc.new { "" }
+
+    #
+    # Add a +File+ named +name+ to this entity's list of children. The +name+
+    # may simply be the name of the file or may be a path to the file.
+    #
+    # In the case of the latter, +file+ will create the +Directory+ tree
+    # which contains the +File+ specified by the path.
+    #
+    # Either way, the +File+'s contents will be set to the result of the
+    # given block, or to a blank string if no block is given
+    #
+    # @example
+    #   archive = Directory.new
+    #   archive.file('README') do
+    #     "Cool"
+    #   end
+    #
+    # @example
+    #   archive = Directory.new
+    #   archive.file('app/models/user.rb') do
+    #     "class User < ActiveRecord::Base\nend"
+    #   end
+    #
+    # @param name [String] the file name
+    # @param mode [Fixnum] the file mode
+    #
+    # @yieldreturn [String] the file contents
+    #
+    def file(name, mode = 33188, &content)
+      content ||= NO_CONTENT
+
+      name_parts = name.split(::File::SEPARATOR)
+
+      file_name = name_parts.pop
+
+      if name_parts.empty?
+        File.new(name, mode, content).tap do |file|
+          add_file(file)
+        end
+      else
+        dir(name_parts.join(::File::SEPARATOR)) do |parent|
+          parent.file(file_name, mode, &content)
+        end
+      end
+    end
+  end
+end

data/lib/and_feathers/version.rb

@@ -1,3 +1,8 @@
 module AndFeathers
-  VERSION = "0.0.1"
+  #
+  # AndFeathers strives to adhere to semantic versioning. Version 1.0.0
+  # introduces the change to a configurable output format, which breaks the
+  # interface of the initial release.
+  #
+  VERSION = "1.0.0.pre"
 end

data/lib/and_feathers.rb

@@ -1,6 +1,4 @@
-require 'and_feathers/tarball/file'
-require 'and_feathers/tarball/directory'
-require 'and_feathers/tarball'
+require 'and_feathers/archive'
 require 'and_feathers/version'
 
 #
@@ -8,29 +6,70 @@ require 'and_feathers/version'
 #
 module AndFeathers
   #
-  # Builds a new +Tarball+. If +base+ is not given, the tarball's contents
+  # Builds a new archive. If +base+ is not given, the archives's contents
   # would be extracted to intermingle with whichever directory contains the
-  # tarball. If +base+ is given, the tarball's contents will live inside a
-  # directory with that name. This is just a convenient way to have a +dir+
-  # call wrap the tarball's contents
+  # archive. If +base+ is given, the archive's contents will live inside a
+  # directory with that name.
   #
-  # @param base [String] name of the base directory containing the tarball's
+  # @param extract_to [String] name of the base directory containing the archive's
   #   contents
-  # @param base_mode [Fixnum] the mode of the base directory
+  # @param extraction_mode [Fixnum] the mode of the base directory
   #
-  # @yieldparam tarball [Tarball]
+  # @yieldparam archive [Archive]
   #
-  def self.build(base = nil, base_mode = 16877, &block)
-    if base && base_mode
-      Tarball.new.tap do |tarball|
-        tarball.dir(base, base_mode) do |dir|
-          block.call(dir)
-        end
+  def self.build(extract_to = nil, extraction_mode = 16877, &block)
+    extract_to ||= '.'
+
+    Archive.new(extract_to, extraction_mode).tap do |archive|
+      block.call(archive)
+    end
+  end
+
+  #
+  # Builds a new archive from the directory at the given +path+. The
+  # innermost directory is taken to be the parent folder of the archive's
+  # contents.
+  #
+  # @param path [String] path to the directory to archive
+  #
+  # @yieldparam archive [Archive] the loaded archive
+  #
+  def self.from_path(path, &block)
+    if !::File.exists?(path)
+      raise ArgumentError, "#{path} does not exist"
+    end
+
+    directories, files = ::Dir[::File.join(path, '**/*')].partition do |path|
+      ::File.directory?(path)
+    end
+
+    full_path = ::File.expand_path(path)
+    extract_to = full_path.split(::File::SEPARATOR).last
+    extraction_mode = ::File.stat(full_path).mode
+
+    Archive.new(extract_to, extraction_mode).tap do |archive|
+      directories.map do |directory|
+        [
+          directory.sub(/^#{Regexp.escape(path)}\/?/, ''),
+          ::File.stat(directory).mode
+        ]
+      end.each do |directory, mode|
+        archive.dir(directory, mode)
       end
-    else
-      Tarball.new.tap do |tarball|
-        block.call(tarball)
+
+      files.each do |file|
+        mode = ::File.stat(file).mode
+
+        ::File.open(file, 'rb') do |io|
+          content = io.read
+
+          archive.file(file.sub(/^#{Regexp.escape(path)}\/?/, ''), mode) do
+            content
+          end
+        end
       end
+
+      block.call(archive) if block
     end
   end
 end