id3 0.5.0 → 1.0.0.pre4

data/lib/helpers/hash_extensions.rb

@@ -0,0 +1,20 @@
+#
+# EXTENSIONS to Class Hash
+#
+
+# include Hash#inverse from Facets of Ruby or from our helper
+# then Monkey-Patch the Hash#invert method:
+
+require 'helpers/invert_hash'
+
+class Hash
+  # original Hash#invert is still available as Hash#old_invert
+  alias old_invert invert
+  
+  # monkey-patching Hash#invert method - it's backwards compatible, but preserves duplicate values in the hash
+  def invert
+    self.inverse
+  end
+end
+
+

data/lib/helpers/hexdump.rb

@@ -0,0 +1,136 @@
+# ==============================================================================
+# EXTENDING CLASS STRING
+# ==============================================================================
+# --
+# (C) Copyright 2004 by Tilo Sloboda <tools@unixgods.org>
+#
+# License:
+#         Freely available under the terms of the OpenSource "Artistic License"
+#         in combination with the Addendum A (below)
+#
+#         In case you did not get a copy of the license along with the software,
+#         it is also available at:   http://www.unixgods.org/~tilo/artistic-license.html
+#
+# Addendum A:
+#         THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU!
+#         SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+#         REPAIR OR CORRECTION.
+#
+#         IN NO EVENT WILL THE COPYRIGHT HOLDERS  BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
+#         SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
+#         TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+#         INACCURATE OR USELESS OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+#         TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDERS OR OTHER PARTY HAS BEEN
+#         ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+#++
+
+# this is written for Ruby version < 1.9 - unfortunately they changed the I/O and String classes significantly.
+# have to fix this up for newer Ruby versions.
+
+if RUBY_VERSION >= "1.9.0"
+  ZEROBYTE = "\x00".force_encoding(Encoding::BINARY)  unless defined? ZEROBYTE
+
+else # older Ruby versions:
+  
+  class String
+    alias bytesize size
+
+    def getbyte(x)   # when accessing a string and selecting x-th byte to do calculations , as defined in Ruby 1.9                                         
+      self[x]  # returns an integer                                                                                                                        
+    end
+  end
+
+  ZEROBYTE = "\0"  unless defined? ZEROBYTE
+end      
+
+
+class String
+  #
+  # prints out a good'ol hexdump of the data contained in the string
+  #
+  # parameters:     sparse:   true / false     do we want to print multiple lines with zero values?
+
+  def hexdump(sparse = false)
+
+    selfsize = self.bytesize
+
+     first = true
+
+     print "\n index       0 1 2 3  4 5 6 7  8 9 A B  C D E F\n\n"
+
+     lines,rest = selfsize.divmod(16)
+     address = 0; i = 0    # we count them independently for future extension.
+
+     while lines > 0
+        str = self[i..i+15]
+        
+        # we don't print lines with all zeroes, unless it's the last line
+
+        if str == ZEROBYTE * 16     # if the 16 bytes are all zero
+        
+          if (!sparse) || (sparse &&  lines == 1 && rest == 0)
+             str.tr!("\000-\037\177-\377",'.')
+
+             printf( "%08x    %8s %8s %8s %8s    %s\n", 
+                address, self[i..i+3].unpack('H8').first, self[i+4..i+7].unpack('H8').first,
+                self[i+8..i+11].unpack('H8').first, self[i+12..i+15].unpack('H8').first, str)
+          else
+                print "  ....      00 .. 00 00 .. 00 00 .. 00 00 .. 00    ................\n" if first
+                first = false
+	  end
+
+        else  # print string which is not all zeros
+
+          str.tr!("\000-\037\177-\377",'.')
+
+          printf( "%08x    %8s %8s %8s %8s    %s\n", 
+                address, self[i..i+3].unpack('H8').first, self[i+4..i+7].unpack('H8').first,
+                self[i+8..i+11].unpack('H8').first, self[i+12..i+15].unpack('H8').first, str)
+          first = true
+	end
+        i += 16; address += 16; lines -= 1
+     end
+     
+     # now do the remaining bytes, which don't fit a full line..
+     # yikes - this is truly ugly!  REWRITE THIS!!
+
+     if rest > 0
+        chunks2,rest2 = rest.divmod(4)     
+        j = i; k = 0
+        if (i < selfsize)
+           printf( "%08x    ", address)
+           while (i < selfsize)
+                printf "%02x", self.getbyte(i)
+                i += 1; k += 1
+                print  " " if ((i % 4) == 0)
+           end
+           for i in (k..15)
+                  print "  "
+           end
+           str = self[j..selfsize]
+           str.tr!("\000-\037\177-\377",'.')
+           print " " * (4 - chunks2+1)
+           printf("  %s\n", str)
+        end
+     end
+  end
+
+end
+
+
+
+__END__
+
+
+# you would use it like this:
+
+require './hexdump'
+
+s =  "some random long string"
+
+t =  s + ZEROBYTE*80  + s + ZEROBYTE*64 + s + "bla bla bla!"
+t.hexdump(true)    # surpress consecutive lines with zero values
+t.hexdump          # same as t.hexdump(false)
+
+
+

data/lib/helpers/invert_hash.rb

@@ -0,0 +1,128 @@
+# ==============================================================================
+# EXTENDING CLASS HASH
+# ==============================================================================
+#--
+# (C) Copyright 2004 by Tilo Sloboda <tools@unixgods.org>
+#
+# updated:  Time-stamp: <Mon, 24 Oct 2011, 23:03:29 PDT  tilo>
+#
+# License:
+#         Freely available under the terms of the OpenSource "Artistic License"
+#         in combination with the Addendum A (below)
+#
+#         In case you did not get a copy of the license along with the software,
+#         it is also available at:   http://www.unixgods.org/~tilo/artistic-license.html
+#
+# Addendum A:
+#         THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU!
+#         SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+#         REPAIR OR CORRECTION.
+#
+#         IN NO EVENT WILL THE COPYRIGHT HOLDERS  BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
+#         SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY
+#         TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
+#         INACCURATE OR USELESS OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
+#         TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDERS OR OTHER PARTY HAS BEEN
+#         ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+#++
+# ==============================================================================
+
+# Project Homepage:  http://www.unixgods.org/~tilo/Ruby/invert_hash.html
+#
+# This also appears in the "Facets of Ruby" library, and is mentioned in the O'Reilly Ruby Cookbook 
+#
+# Ruby's Hash.invert method can't handle the common case that two or more hash entries have the same value.
+#
+#  hash.invert.invert == h    # => ?       # is not generally true for Ruby's standard Hash#invert method
+#
+#  hash.inverse.inverse == h  # => true    # is true, even if the hash has duplicate values
+#
+# If you have a Math background, you would expect that performing an "invert" operation twice would result in the original hash.
+#
+# The Hash#inverse method provides this.
+#
+#
+# If you want to permanently overload Ruby's original invert method, you may want to do this:
+#
+#  class Hash
+#    alias old_invert invert   # old Hash#invert is still accessible as Hash#old_invert
+#    
+#    def invert
+#      self.inverse            # Hash#invert is not using inverse method
+#    end
+#  end
+
+class Hash
+  
+  # Returns a new hash, using given hash's values as keys and using keys as values.
+  # If the input hash has duplicate values, the resulting hash will contain arrays as values.
+  # If you perform inverse twice, the output is identical to the original hash.
+  # e.g. no data is lost.
+  #  
+  #  hash = { 'zero' => 0 , 'one' => 1, 'two' => 2, 'three' => 3 ,   # English numbers
+  #           'null' => 0, 'eins' => 1, 'zwei' => 2 , 'drei' => 3 }  # German numbers
+  #  
+  #  # Hash#inverse keeps track of duplicates, and preserves the input data
+  #  
+  #  hash.inverse          # => { 0=>["null", "zero"], 1=>["eins", "one"], 2=>["zwei", "two"], 3=>["drei", "three"] }
+  #  
+  #  hash.inverse.inverse  # => { "null"=>0, "zero"=>0, "eins"=>1, "one"=>1, "zwei"=>2, "two"=>2, "drei"=>3, "three"=>3 }
+  #  
+  #  hash.inverse.inverse == hash  # => true   # works as you'd expect
+  #  
+  #  # In Comparison:
+  #  # 
+  #  # the standard Hash#invert loses data when dupclicate values are present
+  #  
+  #  hash.invert           # => { 0=>"null", 1=>"eins", 2=>"zwei", 3=>"drei" }
+  #  hash.invert.invert    # => { "null"=>0, "eins"=>1, "zwei"=>2, "drei"=>3 }   # data is lost
+  #  
+  #  hash.invert.invert == hash   # => false   # oops, data was lost!
+  #   
+
+  def inverse
+    i = Hash.new
+    self.each_pair{ |k,v|
+      if (v.class == Array)
+        v.each{ |x|
+          if i.has_key?(x)
+            i[x] = [k,i[x]].flatten
+          else
+            i[x] = k
+          end
+        }
+      else
+        if i.has_key?(v)
+		   i[v] = [k,i[v]].flatten
+        else
+          i[v] = k
+        end
+      end
+    }
+    return i
+  end
+  
+end
+
+
+#--
+# 
+# require 'active_support'
+# 
+# class Hash
+# 
+#   def inverse
+#     i = ActiveSupport::OrderedHash.new
+#     self.each_pair{ |k,v|
+#       if (v.class == Array)
+#         v.each{ |x|
+#           i[x] = i.has_key?(x) ? [i[x],k].flatten : k
+#         }
+#       else
+#         i[v] = i.has_key?(v) ? [i[v],k].flatten : k
+#       end
+#     }
+#     return i
+#   end
+# 
+# end

data/lib/helpers/recursive_helper.rb

@@ -0,0 +1,39 @@
+# module ID3
+#  module Helpers
+
+    # ------------------------------------------------------------------------------
+    # recursiveDirectoryDescend
+    #      do action for files matching regexp
+    #
+    #      could be extended to array of (regexp,action) pairs
+    #
+    def recursive_dir_descend(dir,regexp,action)
+     # print "dir : #{dir}\n"
+
+      olddir = Dir.pwd
+      dirp = Dir.open(dir)
+      Dir.chdir(dir)
+      pwd = Dir.pwd
+      @dirN += 1
+
+      for file in dirp
+        file.chomp
+        next if file =~ /^\.\.?$/
+        filename = "#{pwd}/#{file}"
+
+        if File::directory?(filename)
+           recursive_dir_descend(filename,regexp,action)
+        else
+           @fileN += 1
+           if file =~ regexp
+               # evaluate action
+               eval action
+           end
+        end
+      end
+      Dir.chdir(olddir)
+    end
+    # ------------------------------------------------------------------------------
+
+#  end
+# end

data/lib/helpers/restricted_ordered_hash.rb

@@ -0,0 +1,88 @@
+require 'id3/frame_array'
+
+# ==============================================================================
+# Class RestrictedOrderedHash
+#    this is a helper Class for ID3::Frame
+#
+#    this is a helper Class for GenericTag
+#
+#    this is from 2002 .. new Ruby Versions now have "OrderedHash" .. but I'll keep this class for now.
+
+class RestrictedOrderedHash < ActiveSupport::OrderedHash
+
+  attr_accessor :locked
+  
+  def lock
+    @locked = true
+  end
+  
+  def initialize 
+    @locked = false
+    super
+  end
+  
+ alias old_store []=
+
+  def []= (key,val)
+    if self[key]
+      #            self.old_store(key,val)    # this would overwrite the old_value if a key already exists (duplicate ID3-Frames)
+      
+      # strictly speaking, we only need this for the ID3v2 Tag class Tag2:
+      if self[key].class != ID3::FrameArray   # Make this ID3::FrameArray < Array
+        old_value = self[key]
+        new_value = ID3::FrameArray.new
+        new_value << old_value           # make old_value a FrameArray
+        self.old_store(key, new_value  )
+      end
+      self[key] << val
+      
+    else
+      if @locked
+        # we're not allowed to add new keys!
+        raise ArgumentError, "You can not add new keys! The ID3-frame #{@name} has fixed entries!\n" +
+          "               valid key are: " + self.keys.join(",") +"\n"
+      else 
+        self.old_store(key,val)
+      end
+    end
+  end
+  
+  # users can not delete entries from a locked hash..
+  
+  alias old_delete delete
+  
+  def delete(key)
+    if !@locked
+      old_delete(key)
+    end
+  end
+end
+
+
+# ==============================================================================
+# Class RestrictedOrderedHashWithMultipleValues
+#    this is a helper Class for ID3::Frame
+# 
+# same as the parent class, but if a key is already present, it stores multiple values as an Array of values
+
+# class RestrictedOrderedHashWithMultipleValues < RestrictedOrderedHash
+#   alias old_store2 []=
+
+#   # if key already in Hash, then replace value with [ old_value ] and append new value to it.
+#   def []= (key,val)
+
+#     puts "Key: #{key} , Val: #{val} , Class: #{self[key].class}"
+
+#     if self[key]
+#       if self[key].class == ID3::Frame
+#         old_value = self[key]
+#         self[key] = [ old_value ]
+#       end
+#       self[key] << value
+#     else
+#       self.old_store2(key,val)
+#     end
+#   end
+
+# end
+

data/lib/helpers/ruby_1.8_1.9_compatibility.rb

@@ -0,0 +1,62 @@
+# ==============================================================================
+# Loading Libraries and Stuff needed for Ruby 1.9 vs 1.8 Compatibility
+# ==============================================================================
+# the idea here is to define a couple of go-between methods for different classes
+# which are differently defined depending on which Ruby version it is -- thereby
+# abstracting from the particular Ruby version's API of those classes
+
+if RUBY_VERSION >= "1.9.0"
+  require "digest/md5"
+  require "digest/sha1"
+  include Digest
+  
+  require 'fileutils'        # replaces ftools
+  include FileUtils::Verbose
+  
+  class File
+    def read_bytes(n)  # returns a string containing bytes
+      #      self.read(n)
+      #      self.sysread(n)
+      self.bytes.take(n)
+    end
+    def write_bytes(bytes)
+      self.syswrite(bytes)
+    end
+    def get_byte
+      self.getbyte     # returns a number 0..255
+    end
+  end
+  
+  ZEROBYTE = "\x00".force_encoding(Encoding::BINARY) unless defined? ZEROBYTE
+  
+else # older Ruby versions:
+  require 'rubygems'
+  
+  require "md5"
+  require "sha1"
+  
+  require 'ftools'
+  def move(a,b)
+    File.move(a,b)
+  end
+  
+  class String
+    def getbyte(x)   # when accessing a string and selecting x-th byte to do calculations , as defined in Ruby 1.9
+      self[x]  # returns an integer
+    end
+  end
+  
+  class File
+    def read_bytes(n)
+      self.read(n)   # should use sysread here as well?
+    end
+    def write_bytes(bytes)
+      self.write(bytes)   # should use syswrite here as well?
+    end
+    def get_byte     # in older Ruby versions <1.9 getc returned a byte, e.g. a number 0..255
+      self.getc   # returns a number 0..255
+    end
+  end
+  
+  ZEROBYTE = "\0" unless defined? ZEROBYTE
+end