grizzled-ruby 0.1.0 → 0.1.1

data/lib/grizzled/dir.rb

@@ -1,3 +1,6 @@
+# Miscellaneous additional directory-related modules and classes.
+#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -30,13 +33,8 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
-# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
-#
-# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
-# Copyright:: Copyright (c) 2011 Brian M. Clapper
-# License:: BSD License
 class Dir
 
   # Adds a +walk+ method to the standard Ruby +Dir+ class. +walk+ walks a
@@ -61,7 +59,7 @@ module Grizzled
   # Useful directory-related methods.
   class Directory
 
-    # Walk a directory tree, starting at _dirname_, invoking the supplied
+    # Walk a directory tree, starting at +dirname+, invoking the supplied
     # block on each directory. The block is passed a +Dir+ object. The
     # directory is walked top-down, not depth-first. To terminate the
     # traversal, the block should return +false+. Anything else (including

data/lib/grizzled/fileutil/includer.rb

@@ -1,8 +1,7 @@
 # Provides a file inclusion preprocessor. See the documentation for
 # the Grizzled::FileUtil::Includer class for complete details.
 #
-# ---
-#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -35,7 +34,7 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
 require 'open-uri'
 require 'uri'

data/lib/grizzled/fileutil/ziputil.rb

@@ -0,0 +1,296 @@
+# Provides convenient, simple front-end functions for the 'rubyzip' gem.
+# NOTE: To use this module, you _must_ have the 'rubyzip' gem installed.
+#
+#--
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+require 'open-uri'
+require 'uri'
+require 'pathname'
+require 'rubygems'
+require 'zip/zip'
+require 'fileutils'
+
+module Grizzled
+
+  module FileUtil
+
+    # Namespace module, containing contains some simplified, front-end
+    # "zip" and "unzip" utility wrappers for the +rubyzip+ gem. This
+    # module requires the +rubyzip+ gem to be present.
+    module ZipUtil
+
+      # +ZipMixin+ provides convenient front-end methods for zipping files;
+      # it uses the 'rubyzip' gem under the covers, so you must have
+      # 'rubyzip' installed to use this class. Mixing this module into your
+      # class mixes in methods that will allow you to zip up files. Related
+      # modules and classes:
+      #
+      # [Grizzled::FileUtil::Zipper]     A class that includes this module
+      #                                  and can be instantiated by itself.
+      # [Grizzled::FileUtil::UnzipMixin] A module mixin for unzipping zip files.
+      # [Grizzled::FileUtil::Unzipper]   A class that includes `UnzipMixin'
+      #                                  and can be instantiated by itself.
+      module ZipMixin
+
+        # Create a zip file from the contents of a directory.
+        #
+        # Parameters:
+        #
+        # [+zip_file+]  The zip file to open. The file is created if it doesn't
+        #               already exists.
+        # [+directory+] The directory whose contents are to be included in
+        #               the file.
+        # [+options+]   Options hash, as described below.
+        # [+&select+]   If a block (+select+) is given, then +zip+ passes each
+        #               file or directory to the block and only adds the entry
+        #               to the zip file if the block returns +true+. If no
+        #               block is given, then all files and directories are
+        #               added (subject also to the +:recursive+ option, below).
+        #
+        # Options:
+        #
+        # [+:recursive+]   If +false+, only zip the files in the directory; if
+        #                  +true+ (the default), recursively zip the entire
+        #                  directory.
+        # [+:dir_at_top+]  If +false+, don't include zip the directory itself
+        #                  (i.e., the top-level files will be at the top level
+        #                  of the zip file). If +true+ (the default), the
+        #                  the directory itself (the basename) will be the
+        #                  top-level element of the zip file.
+        # [+:recreate]     If +true+, remove the zip file if it exists already,
+        #                  so it's recreated from scratch. If +false+ (the 
+        #                  default), don't recreate the zip file if it doesn't
+        #                  exist; instead, update the existing file.
+        #
+        # Returns:
+        #
+        # The +zip_file+ argument, for convenience.
+        #
+        # Example:
+        #
+        #    require 'grizzled/fileutil/ziputil'
+        #    import 'tmpdir'
+        #
+        #    include Grizzled::FileUtil::ZipUtil::ZipMixin
+        #
+        #    Dir.mktmpdir do |d|
+        #      zip zipfile_path, d
+        #    end
+        def zip(zip_file, directory, options = {}, &select)
+          recurse = options.fetch(:recursive, true)
+          dir_at_top = options.fetch(:dir_at_top, true)
+          recreate = options.fetch(:recreate, true)
+
+          if dir_at_top
+            abs_dir = File.expand_path(directory)
+            entry_dir = File.basename(abs_dir)
+            chdir_to = File.dirname(abs_dir)
+            glob = File.join(entry_dir, '**', '*').to_s
+          else
+            chdir_to = directory
+            entry_dir = '.'
+            glob = File.join('**', '*').to_s
+          end
+
+          # Remove the existing zip file, if asked to do so.
+          FileUtils::rm_f zip_file if recreate
+
+          # Open the zip file. Then, CD to the appropriate directory
+          # and pack it up.
+          zip = Zip::ZipFile.open(zip_file, Zip::ZipFile::CREATE)
+          FileUtils::cd chdir_to do |d|
+            Dir[glob].each do |path|
+
+              # If the caller supplied a block, only add the file if the block
+              # says we can.
+              add = block_given? ? select.call(path) : true
+              if add
+                if File.directory? path
+                  zip.mkdir path if recurse
+                else
+                  zip.add(path, path) if (File.dirname(path) == '.') or recurse
+                end
+              end
+            end
+            zip.close
+          end
+          zip_file
+        end
+      end # module ZipMixin
+
+      # +UnzipMixin+ provides convenient front-end methods for unzipping
+      # files; it uses the 'rubyzip' gem under the covers, so you must have
+      # 'rubyzip' installed to use this class. Mixing this module into your
+      # class mixes in methods that will allow you to unzip zip files.
+      # Related modules and classes:
+      #
+      # [Grizzled::FileUtil::Zipper]    A class that includes this module
+      #                                 and can be instantiated by itself.
+      # [Grizzled::FileUtil::ZipMixin]  A module mixin for zipping zip files.
+      # [Grizzled::FileUtil::Unzipper]  A class that includes `UnzipMixin'
+      #                                 and can be instantiated by itself.
+      module UnzipMixin
+        # Unzips a zip file into a directory.
+        #
+        # Parameters:
+        #
+        # [+zip_file+]  The zip file to unzip.
+        # [+directory+] The directory into which to unzip the file. The
+        #               directory is created if it doesn't already exist.
+        # [+options+]   Options hash, as described below.
+        # [+&select+]   If a block (+select+) is given, then +unzip+ passes each
+        #               zip file entry name to the block and only unzips the
+        #               entry if the block returns +true+. If no block is
+        #               given, then everything is unzipped (subject also to
+        #               the +:recursive+ option, below).
+        #
+        # Options:
+        #
+        # [+:recursive+]  If +false+, only extract the top-level files from
+        #                 the zip file. If +true+ (the default),
+        #                 recursively extract everything.
+        # [+:overwrite+]  If +false+ (the default), do not overwrite existing
+        #                 files in the directory. If +true+, overwrite
+        #                 any existing files in the directory with extracted
+        #                 zip files whose names match.
+        #
+        # Example:
+        #
+        #    import 'grizzled/fileutil/ziputil'
+        #    import 'tmpdir'
+        #
+        #    include Grizzled::FileUtil::ZipUtil
+        #
+        #    Dir.mktmpdir do |d|
+        #      unzip zipfile_path, d
+        #      # muck with unpacked contents
+        #    end
+
+        def unzip(zip_file, directory, options = {}, &select)
+          overwrite = options.fetch(:overwrite, false)
+          recurse = options.fetch(:recursive, true)
+
+          zip = Zip::ZipFile.open(zip_file)
+          Zip::ZipFile.foreach(zip_file) do |entry|
+            file_path = File.join(directory, entry.to_s)
+            parent_dir = File.dirname file_path
+            if recurse or (parent_dir == '.') or (parent_dir == '')
+              # If the caller supplied a block, only extract the file if
+              # the block says we can.
+              extract = block_given? ? select.call(path) : true
+              if extract
+                if parent_dir != ''
+                  if not File.exists? parent_dir
+                    FileUtils::mkdir_p parent_dir
+                  end
+                end
+              end
+            end
+            zip.extract(entry, file_path)
+          end
+        end
+
+        # Call a given block with the list of entries in a zip file, without
+        # extracting them.
+        #
+        # Parameters:
+        #
+        # [+zip_file+]  The zip file to unzip.
+        # [+block+]     Block to execute on each entry. If omitted, an
+        #               Enumerator is returned. The block receives a string
+        #               representing the path of the item in the file.
+        def zip_file_entries(zip_file, &block)
+          if not block_given?
+            a = []
+          end
+
+          Zip::ZipFile.foreach(zip_file) do |entry|
+            if block_given?
+              block.call(entry.to_s)
+            else
+              a << entry.to_s
+            end
+          end
+
+          if not block_given?
+            return a.each
+          end
+        end
+      end # module UnzipMixin
+
+      # +Zipper+ is a class version of +ZipMixin+ and is useful when you
+      # don't want to mix the methods directly into your class or module.
+      # It provides the methods of +ZipMixin+ as class methods.
+      #
+      # Example:
+      #
+      #    require 'grizzled/fileutil/ziputil'
+      #    import 'tmpdir'
+      #
+      #    include Grizzled::FileUtil::ZipUtil
+      #
+      #    Dir.mktmpdir do |d|
+      #      Zipper.zip zipfile_path, d
+      #    end
+      class Zipper
+        class << self
+          include Grizzled::FileUtil::ZipUtil::ZipMixin
+        end
+      end
+
+      # +Unzipper+ is a class version of +UnzipMixin+ and is useful when
+      # you don't want to mix the methods directly into your class or
+      # module. It provides the methods of +UnzipMixin+ as class methods.
+      #
+      #    import 'grizzled/fileutil/ziputil'
+      #    import 'tmpdir'
+      #
+      #    include Grizzled::FileUtil::ZipUtil
+      #
+      #    Dir.mktmpdir do |d|
+      #      Unzipper.unzip zipfile_path, d
+      #      # muck with unpacked contents
+      #    end
+      class Unzipper
+        class << self
+          include Grizzled::FileUtil::ZipUtil::UnzipMixin
+        end
+      end
+
+    end # module ZipUtil
+  end # module File
+end # module Grizzled
+

data/lib/grizzled/fileutil.rb

@@ -0,0 +1,139 @@
+# Miscellaneous additional Ruby file utility modules and classes.
+#
+#--
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#++
+
+module Grizzled
+
+  # This module and its submodules contain various file-related utility
+  # methods.
+  module FileUtil
+
+    # Exception thrown for a bad directory tree value.
+    class BadDirectoryTreeValue < StandardError
+      def initialize(key, value)
+        super("Directory tree key '#{key}' has unsupported value '#{value}' " +
+              "of type #{value.class}. Values must be hashes or strings.")
+      end
+    end
+
+    # Exception thrown for bad directory tree key.
+    class BadDirectoryTreeKey < StandardError; end
+
+    # Create a file/directory hierarchy. The hash table specifies the
+    # entries, using the following rules.
+    #
+    # - A hash entry whose value is another hash table is taken to
+    #   be a directory and will be recursively created.
+    # - A hash entry with a String value is a file, whose contents are the
+    #   string.
+    # - A hash entry with an Enumerable value is a file, whose contents are
+    #   the enumerable values, rendered as strings.
+    # - Anything else is an error.
+    #
+    # For instance, this hash:
+    #
+    #    tree = {"foo" =>
+    #              {"bar"   => {"a" => "File a's contents",
+    #                           "b" => "File b's contents"},
+    #               "baz"   => {"c" => "Blah blah blah"},
+    #               "xyzzy" => "Yadda yadda yadda"}}
+    #
+    # results in this directory tree:
+    #
+    #     foo/
+    #         bar/
+    #             a   # File a's contents
+    #             b   # File a's contents
+    #
+    #         baz/
+    #             c   # Blah blah blah
+    #
+    #         xyzzy   # Yadda yadda yadda
+    #
+    # The keys should be simple file names, with no file separators (i.e.,
+    # no parent directories).
+    #
+    # Parameters:
+    #
+    # [+directory+] The starting directory, which is created if it does not
+    #               exist.
+    # [+tree+]      The entry tree, as described above
+    #
+    # Returns:
+    #
+    # A +Dir+ object for +directory+, for convenience.
+    def make_directory_tree(directory, tree)
+
+      require 'fileutils'
+
+      if File.exists? directory
+        if not File.directory? directory
+          raise BadDirectoryTreeKey.new("Directory '#{directory}' already " +
+                                        "exists and isn't a directory.")
+        end
+      else
+        Dir.mkdir directory
+      end
+
+      FileUtils.cd directory do
+        tree.each do |entry, contents|
+          if entry.include? File::SEPARATOR
+            raise BadDirectoryTreeKey.new("File tree key '#{key}' contains " +
+                                          "illegal file separator character.");
+          end
+
+          # Must test Hash first, because Hash is Enumerable.
+
+          if contents.kind_of? Hash
+            # This is a directory
+            make_directory_tree(entry, contents)
+
+          elsif contents.kind_of? Enumerable
+            f = File.open(File.join(entry), 'w')
+            contents.each {|thing| f.write(thing.to_s)}
+            f.close
+
+          else
+            raise BadDirectoryTreeValue.new(entry, contents)
+          end
+        end
+      end
+
+      return Dir.new(directory)
+    end
+
+  end # Module FileUtil
+end # module Grizzled

data/lib/grizzled/forwarder.rb

@@ -1,8 +1,7 @@
 # Provides a module which, when mixed in, can be used to forward all
 # missing methods to another object.
 #
-# ---
-#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -35,7 +34,7 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
 module Grizzled
 

data/lib/grizzled/stack.rb

@@ -1,8 +1,7 @@
 # Provides a simple stack implementation. See the Grizzled::Stack class
 # for complete details.
 #
-# ---
-#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -35,13 +34,8 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
-# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
-#
-# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
-# Copyright:: Copyright (c) 2011 Brian M. Clapper
-# License:: BSD License
 module Grizzled
 
   # Thrown for un-safe stacks if the stack

data/lib/grizzled/string/template.rb

@@ -3,8 +3,7 @@
 # module, the Grizzled::String::UnixShellStringTemplate class and the
 # Grizzled::String::WindowsCmdStringTemplate class for complete details.
 #
-# ---
-#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -37,13 +36,8 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
-# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
-#
-# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
-# Copyright:: Copyright (c) 2011 Brian M. Clapper
-# License:: BSD License
 module Grizzled
 
   module String

data/lib/grizzled/unix.rb

@@ -1,3 +1,6 @@
+# Miscellaneous Unix-related modules and classes
+#
+#--
 # This software is released under a BSD license, adapted from
 # http://opensource.org/licenses/bsd-license.php
 #
@@ -30,13 +33,8 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# ---------------------------------------------------------------------------
+#++
 
-# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
-#
-# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
-# Copyright:: Copyright (c) 2011 Brian M. Clapper
-# License:: BSD License
 module Grizzled
 
   # Unix-related OS things.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: grizzled-ruby
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: 
   segments: 
   - 0
   - 1
-  - 0
-  version: 0.1.0
+  - 1
+  version: 0.1.1
 platform: ruby
 authors: 
 - Brian M. Clapper
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-12 00:00:00 -05:00
+date: 2011-03-18 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -30,8 +30,10 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/grizzled/fileutil.rb
 - lib/grizzled/stack.rb
 - lib/grizzled/fileutil/includer.rb
+- lib/grizzled/fileutil/ziputil.rb
 - lib/grizzled/dir.rb
 - lib/grizzled/forwarder.rb
 - lib/grizzled/string/template.rb