id3lib-ruby 0.1.0 → 0.2.0

data/CHANGES

@@ -1,14 +1,16 @@
-= id3lib-ruby Changes
-
-=== Before release
-
-* New: Everything.
-* Get rid of ID3::Frame and use normal Hash instead.
-* Clean up ID3::Frames and Fields -> replace them with an ID3::Info module.
-* How to set ID3 genre?
-* Replace Accessors.add with normal function definitions
-* Document library with RDOC.
-* Add more frame accessor methods (maybe there are now too much?).
-* Added reading and writing of UTF-16 frames. Works only with ID3v2.
-* Renamed extension ID3Lib to ID3Lib::API and module ID3 to ID3Lib.
-* Finish and test gem specification.
+= id3lib-ruby changes
+
+=== 0.2.0 (r21)
+
+* Overhauled direct access methods
+  * Remove frames by setting them to nil, e.g. tag.title = nil
+  * Removed methods for rarely used frames.
+  * All methods use strings now, no special cases like track anymore.
+  * Explicit call of to_s in set_frame_text.
+* More unit tests
+* Added method invalid_frames which is useful to detect invalid frame
+  data before calling update!.
+
+=== 0.1.0 (r19)
+
+* First release :)

data/Rakefile

@@ -10,7 +10,7 @@ require 'rake/testtask'
 require 'rake/rdoctask'
 
 
-PKG_VERSION = '0.1.0'
+PKG_VERSION = '0.2.0'
 
 PKG_FILES = FileList[
   'lib/**/*.rb',

data/TODO

@@ -1,9 +1,5 @@
-= id3lib-ruby To Do List
+= id3lib-ruby to-do list
 
-* Overhaul direct access methods
-  * Implement removing frames. tag.title = nil ?
-  * Remove methods for rarely used frames.
-  * Use strings in all methods - get rid of exceptions.
-* Add method to check if frames and fields are valid.
 * Create Windows binary gem (id3lib.dll included).
+* Evaluate a more object-oriented way to handle frames, instead of hashes.
 * Add UTF-8 support if id3lib can handle it.

data/lib/id3lib.rb

@@ -213,7 +213,9 @@ module ID3Lib
     #
     def set_frame_text(id, text)
       remove_frame(id)
-      self << { :id => id, :text => text }
+      if text
+        self << { :id => id, :text => text.to_s }
+      end
     end
 
     #
@@ -227,6 +229,9 @@ module ID3Lib
     # Updates the tag. This change can't be undone. _writetype_ specifies
     # which tag type to write and defaults to _readtype_ (see #new).
     #
+    # Invalid frames or frame data is ignored. Use #invalid_frames before
+    # update! if you want to know if you have invalid data.
+    #
     # Returns a number corresponding to the written tag type(s) or nil if
     # the update failed.
     #
@@ -278,6 +283,34 @@ module ID3Lib
       @tag.has_tag_type(type)
     end
 
+    #
+    # Returns an Array of invalid frames and fields. If a frame ID is
+    # invalid, it alone is in the resulting array. If a frame ID is valid
+    # but has invalid fields, the frame ID and the invalid field IDs are
+    # included.
+    #
+    #    tag.invalid_frames
+    #    #=> [ [:TITS], [:TALB, :invalid] ]
+    #
+    def invalid_frames
+      invalid = []
+      each do |frame|
+        if not info = Info.frame(frame[:id])
+          # Frame ID doesn't exist.
+          invalid << [frame[:id]]
+          next
+        end
+        # Frame ID is ok, but are all fields ok?
+        invalid_fields = frame.keys.reject { |id|
+          info[FIELDS].include?(id) or id == :id
+        }
+        if not invalid_fields.empty?
+          invalid << [frame[:id], *invalid_fields]
+        end
+      end
+      invalid.empty? ? nil : invalid
+    end
+
     private
 
     def read_frames
@@ -342,7 +375,7 @@ module ID3Lib
     def self.field(libframe, id)
       libframe.field(Info.field(id)[NUM])
     end
-            
+
   end
 
 

data/lib/id3lib/accessors.rb

@@ -4,16 +4,14 @@ module ID3Lib
   #
   # The Accessors module defines accessor methods for ID3 text frames.
   #
-  # Have a look at the source code to see the ID3 frame ID behind an accessor.
-  #
   # === Most used accessors
   #
-  # Here's a list of the probably most used accessors:
+  # Here's a list of the most used accessors:
   #
   # * #title
   # * #performer or #artist
   # * #album
-  # * #genre
+  # * #genre or #content_type
   # * #year
   # * #track
   # * #part_of_set or #disc
@@ -21,22 +19,6 @@ module ID3Lib
   # * #composer
   # * #bpm
   #
-  # === Automatic conversion
-  #
-  # Some accessors automatically convert the raw text to a more
-  # suitable type (when reading) and back (when writing). For example,
-  # the track information is converted to an array of one or two items.
-  #
-  #    tag.track    #=> [1,12]
-  #
-  # and the year is an integer.
-  #
-  #    tag.year     #=> 2005
-  #
-  # Use the Tag#frame_text method to get the raw text.
-  #
-  #    tag.frame_text(:TRCK)  #=> "1/12"
-  #
   module Accessors
 
     def title()       frame_text(:TIT2) end
@@ -44,103 +26,60 @@ module ID3Lib
 
     def performer()       frame_text(:TPE1) end
     def performer=(v) set_frame_text(:TPE1, v) end
-    alias_method :artist, :performer
-    alias_method :artist=, :performer=
+    alias artist  performer
+    alias artist= performer=
 
     def album()       frame_text(:TALB) end
     def album=(v) set_frame_text(:TALB, v) end
 
-    def comment()       frame_text(:COMM) end
-    def comment=(v) set_frame_text(:COMM, v) end
-
     def genre()       frame_text(:TCON) end
     def genre=(v) set_frame_text(:TCON, v) end
-    alias_method :content_type, :genre
-    alias_method :content_type=, :genre=
-
-    def bpm()       frame_text(:TBPM) end
-    def bpm=(v) set_frame_text(:TBPM, v.to_s) end
-
-    def composer()       frame_text(:TCOM) end
-    def composer=(v) set_frame_text(:TCOM, v) end
-
-    def copyright()       frame_text(:TCOP) end
-    def copyright=(v) set_frame_text(:TCOP, v) end
+    alias content_type  genre
+    alias content_type= genre=
 
-    def date()       frame_text(:TDAT) end
-    def date=(v) set_frame_text(:TDAT, v) end
+    def year() frame_text(:TYER) end
+    def year=(v) set_frame_text(:TYER, v) end
 
-    def encoding_time()       frame_text(:TDEN) end
-    def encoding_time=(v) set_frame_text(:TDEN, v) end
+    def track() frame_text(:TRCK) end
+    def track=(v) set_frame_text(:TRCK, v) end
 
-    def playlist_delay()       frame_text(:TDLY) end
-    def playlist_delay=(v) set_frame_text(:TDLY, v) end
+    def part_of_set() frame_text(:TPOS) end
+    def part_of_set=(v) set_frame_text(:TPOS, v) end
+    alias disc  part_of_set
+    alias disc= part_of_set=
 
-    def original_release_time()       frame_text(:TDOR) end
-    def original_release_time=(v) set_frame_text(:TDOR, v) end
-
-    def recording_time()       frame_text(:TDRC) end
-    def recording_time=(v) set_frame_text(:TDRC, v) end
+    def comment()       frame_text(:COMM) end
+    def comment=(v) set_frame_text(:COMM, v) end
 
-    def release_time()       frame_text(:TDRL) end
-    def release_time=(v) set_frame_text(:TDRL, v) end
+    # Returns an array of comment frames.
+    def comment_frames() select{ |f| f[:id] == :COMM } end
 
-    def tagging_time()       frame_text(:TDTG) end
-    def tagging_time=(v) set_frame_text(:TDTG, v) end
+    def composer()       frame_text(:TCOM) end
+    def composer=(v) set_frame_text(:TCOM, v) end
 
-    def involved_people()       frame_text(:TIPL) end
-    def involved_people=(v) set_frame_text(:TIPL, v) end
+    def grouping()       frame_text(:TIT1) end
+    def grouping=(v) set_frame_text(:TIT1, v) end
 
-    def encoded_by()       frame_text(:TENC) end
-    def encoded_by=(v) set_frame_text(:TENC, v) end
+    def bpm()       frame_text(:TBPM) end
+    def bpm=(v) set_frame_text(:TBPM, v.to_s) end
 
-    def lyricist()       frame_text(:TEXT) end
-    def lyricist=(v) set_frame_text(:TEXT, v) end
+    def subtitle()       frame_text(:TIT3) end
+    def subtitle=(v) set_frame_text(:TIT3, v) end
 
-    def file_type()       frame_text(:TFLT) end
-    def file_type=(v) set_frame_text(:TFLT, v) end
+    def date()       frame_text(:TDAT) end
+    def date=(v) set_frame_text(:TDAT, v) end
 
     def time()       frame_text(:TIME) end
     def time=(v) set_frame_text(:TIME, v) end
 
-    def content_group()       frame_text(:TIT1) end
-    def content_group=(v) set_frame_text(:TIT1, v) end
-
-    def subtitle()       frame_text(:TIT3) end
-    def subtitle=(v) set_frame_text(:TIT3, v) end
-
-    def initial_key()       frame_text(:TKEY) end
-    def initial_key=(v) set_frame_text(:TKEY, v) end
-
     def language()       frame_text(:TLAN) end
     def language=(v) set_frame_text(:TLAN, v) end
 
-    def audio_length()       frame_text(:TLEN) end
-    def audio_length=(v) set_frame_text(:TLEN, v) end
-
-    def musician_credits()       frame_text(:TMCL) end
-    def musician_credits=(v) set_frame_text(:TMCL, v) end
-
-    def media_type()       frame_text(:TMED) end
-    def media_type=(v) set_frame_text(:TMED, v) end
-
-    def mood()       frame_text(:TMOO) end
-    def mood=(v) set_frame_text(:TMOO, v) end
-
-    def original_title()       frame_text(:TOAL) end
-    def original_title=(v) set_frame_text(:TOAL, v) end
-
-    def original_filename()       frame_text(:TOFN) end
-    def original_filename=(v) set_frame_text(:TOFN, v) end
-
-    def original_lyricist()       frame_text(:TOLY) end
-    def original_lyricist=(v) set_frame_text(:TOLY, v) end
-
-    def original_performer()       frame_text(:TOPE) end
-    def original_performer=(v) set_frame_text(:TOPE, v) end
+    def lyrics()       frame_text(:USLT) end
+    def lyrics=(v) set_frame_text(:USLT, v) end
 
-    def file_owner()       frame_text(:TOWN) end
-    def file_owner=(v) set_frame_text(:TOWN, v) end
+    def lyricist()       frame_text(:TEXT) end
+    def lyricist=(v) set_frame_text(:TEXT, v) end
 
     def band()       frame_text(:TPE2) end
     def band=(v) set_frame_text(:TPE2, v) end
@@ -148,112 +87,16 @@ module ID3Lib
     def conductor()       frame_text(:TPE3) end
     def conductor=(v) set_frame_text(:TPE3, v) end
 
-    def produced_notice()       frame_text(:TPRO) end
-    def produced_notice=(v) set_frame_text(:TPRO, v) end
+    def interpreted_by()       frame_text(:TPE4) end
+    def interpreted_by=(v) set_frame_text(:TPE4, v) end
+    alias remixed_by  interpreted_by
+    alias remixed_by= interpreted_by=
 
     def publisher()       frame_text(:TPUB) end
     def publisher=(v) set_frame_text(:TPUB, v) end
 
-    def internet_radio_station()       frame_text(:TRSN) end
-    def internet_radio_station=(v) set_frame_text(:TRSN, v) end
-
-    def internet_radio_owner()       frame_text(:TRSO) end
-    def internet_radio_owner=(v) set_frame_text(:TRSO, v) end
-
-    def album_sort_order()       frame_text(:TSOA) end
-    def album_sort_order=(v) set_frame_text(:TSOA, v) end
-
-    def performer_sort_order()       frame_text(:TSOP) end
-    def performer_sort_order=(v) set_frame_text(:TSOP, v) end
-
-    def title_sort_order()       frame_text(:TSOT) end
-    def title_sort_order=(v) set_frame_text(:TSOT, v) end
-
-    def isrc()       frame_text(:TSRC) end
-    def isrc=(v) set_frame_text(:TSRC, v) end
-
-    def encoder_settings()       frame_text(:TSSE) end
-    def encoder_settings=(v) set_frame_text(:TSSE, v) end
-
-    def set_subtitle()       frame_text(:TSST) end
-    def set_subtitle=(v) set_frame_text(:TSST, v) end
-
-    def terms_of_use()       frame_text(:TPE2) end
-    def terms_of_use=(v) set_frame_text(:TPE2, v) end
-
-    def commercial_url()       frame_text(:WCOM) end
-    def commercial_url=(v) set_frame_text(:WCOM, v) end
-
-    def copyright_url()       frame_text(:WCOP) end
-    def copyright_url=(v) set_frame_text(:WCOP, v) end
-
-    def audio_file_url()       frame_text(:WOAF) end
-    def audio_file_url=(v) set_frame_text(:WOAF, v) end
-
-    def performer_url()       frame_text(:WOAR) end
-    def performer_url=(v) set_frame_text(:WOAR, v) end
-
-    def audio_source_url()       frame_text(:WOAS) end
-    def audio_source_url=(v) set_frame_text(:WOAS, v) end
-
-    def internet_radio_url()       frame_text(:WORS) end
-    def internet_radio_url=(v) set_frame_text(:WORS, v) end
-
-    def payment_url()       frame_text(:WPAY) end
-    def payment_url=(v) set_frame_text(:WPAY, v) end
-
-    def publisher_url()       frame_text(:WPUB) end
-    def publisher_url=(v) set_frame_text(:WPUB, v) end
-
-    # Returns an array of comment frames.
-    def comment_frames() select{ |f| f[:id] == :COMM } end
-
-    #
-    # Returns an array of one or two numbers.
-    #
-    #    tag.track                #=> [3,11]
-    #    tag.frame_text(:TRCK)    #=> "3/11"
-    #
-    #    tag_2.track              #=> [5]
-    #    tag_2.frame_text(:TRCK)  #=> "5"
-    #
-    def track() frame_text(:TRCK).split('/').collect{ |s| s.to_i } end
-
-    #
-    # Assign either an array or a string.
-    #
-    #    tag.track = [4,11]
-    #    tag.track = [5]
-    #    tag.track = "4/11"
-    #
-    def track=(v) set_frame_text(:TRCK, (v.join('/') rescue v.to_s)) end
-
-    #
-    # Returns an array of one or two numbers like #track.
-    #
-    def part_of_set() frame_text(:TPOS).split('/').collect{ |s| s.to_i } end
-    alias_method :disc, :part_of_set
-
-    #
-    # Assign either an array or a string like #track=.
-    #
-    def part_of_set=(v) set_frame_text(:TPOS, (v.join('/') rescue v.to_s)) end
-    alias_method :disc=, :part_of_set=
-
-    #
-    # Returns a number.
-    #
-    #    tag.year   #=> 2004
-    #
-    def year() frame_text(:TYER).to_i end
-
-    #
-    # Assign a number or a string.
-    #
-    #    tag.year = 2005
-    #    tag.year = "2005"
-    #
-    def year=(v) set_frame_text(:TYER, v.to_s) end
+    def encoded_by()       frame_text(:TENC) end
+    def encoded_by=(v) set_frame_text(:TENC, v) end
 
   end
 

data/test/test_reading.rb

@@ -25,8 +25,8 @@ class TestReading < Test::Unit::TestCase
     assert_equal 'Dummy Artist',  @tag.artist
     assert_equal 'Dummy Artist',  @tag.performer
     assert_equal 'Dummy Album',   @tag.album
-    assert_equal [1,10],          @tag.track
-    assert_equal 2000,            @tag.year
+    assert_equal '1/10',          @tag.track
+    assert_equal '2000',          @tag.year
     assert_equal 'Dummy Comment', @tag.comment
     assert_equal 'Pop',           @tag.genre
   end
@@ -53,4 +53,18 @@ class TestReading < Test::Unit::TestCase
     assert_equal 2038, @tag.size
   end
 
+  def test_invalid_frames
+    assert_nil @tag.invalid_frames
+
+    @tag << { :id => :TITS }
+    assert_equal [[:TITS]], @tag.invalid_frames
+
+    @tag << { :id => :TALB, :invalid => 'text' }
+    assert_equal [[:TITS], [:TALB, :invalid]], @tag.invalid_frames
+
+    @tag << { :id => :APIC, :text => 'invalid' }
+    assert_equal [[:TITS], [:TALB, :invalid], [:APIC, :text]],
+      @tag.invalid_frames
+  end
+
 end

data/test/test_writing.rb

@@ -53,58 +53,43 @@ class TestWriting < Test::Unit::TestCase
     assert_equal genre_id, @tag.genre
   end
 
-  # The track can be set in various ways. Test them all :)
   def test_track
-    @tag.track = 1
-    assert_equal [1], @tag.track
-    @tag.update!
-    assert_equal [1], @tag.track
-    reload!
-    assert_equal [1], @tag.track
-    
-    @tag.track = [2]
-    assert_equal [2], @tag.track
-    @tag.update!
-    assert_equal [2], @tag.track
-    reload!
-    assert_equal [2], @tag.track
-    
-    @tag.track = [3,10]
-    assert_equal [3,10], @tag.track
-    @tag.update!
-    assert_equal [3,10], @tag.track
-    reload!
-    assert_equal [3,10], @tag.track
-    
     @tag.track = '4'
-    assert_equal [4], @tag.track
+    assert_equal '4', @tag.track
     @tag.update!
-    assert_equal [4], @tag.track
+    assert_equal '4', @tag.track
     reload!
-    assert_equal [4], @tag.track
-    
+    assert_equal '4', @tag.track
+
     @tag.track = '5/12'
-    assert_equal [5,12], @tag.track
+    assert_equal '5/12', @tag.track
+    @tag.update!
+    assert_equal '5/12', @tag.track
+    reload!
+    assert_equal '5/12', @tag.track
+
+    @tag.track = 6
+    assert_equal '6', @tag.track
     @tag.update!
-    assert_equal [5,12], @tag.track
+    assert_equal '6', @tag.track
     reload!
-    assert_equal [5,12], @tag.track
+    assert_equal '6', @tag.track
   end
   
   def test_year
-    @tag.year = 2001
-    assert_equal 2001, @tag.year
+    @tag.year = '2001'
+    assert_equal '2001', @tag.year
     @tag.update!
-    assert_equal 2001, @tag.year
+    assert_equal '2001', @tag.year
     reload!
-    assert_equal 2001, @tag.year
-    
-    @tag.year = '2002'
-    assert_equal 2002, @tag.year
+    assert_equal '2001', @tag.year
+
+    @tag.year = 2002
+    assert_equal '2002', @tag.year
     @tag.update!
-    assert_equal 2002, @tag.year
+    assert_equal '2002', @tag.year
     reload!
-    assert_equal 2002, @tag.year
+    assert_equal '2002', @tag.year
   end
 
   def test_comments
@@ -151,6 +136,11 @@ class TestWriting < Test::Unit::TestCase
     assert_nil @tag.frame(:TIT2)
   end
   
+  def test_remove_frame_with_direct_access
+    @tag.title = nil
+    assert_nil @tag.frame(:TIT2)
+  end
+  
   def test_wrong_frame
     l = @tag.length
     @tag << {:id => :WRONG, :text => "Test"}
@@ -210,5 +200,38 @@ class TestWriting < Test::Unit::TestCase
     @tag.performer = "Nobody"
     assert_equal nil, @tag.update!
   end
-  
+
+  def test_accessors
+    accessors = %w[
+      title performer album genre year track part_of_set comment composer
+      grouping bpm subtitle date time language lyrics lyricist band
+      conductor interpreted_by publisher encoded_by
+    ]
+    do_tests_for_accessors(accessors)
+  end
+
+  def test_accessor_aliases
+    aliases = %w[ artist content_type disc remixed_by ]
+    do_tests_for_accessors(aliases)
+  end
+
+  def do_tests_for_accessors(accessors)
+    accessors.each do |m|
+      @tag.send("#{m}=", "#{m} test")
+      assert_equal "#{m} test", @tag.send(m)
+    end
+
+    @tag.update!
+
+    accessors.each do |m|
+      assert_equal "#{m} test", @tag.send(m)
+    end
+
+    reload!
+
+    accessors.each do |m|
+      assert_equal "#{m} test", @tag.send(m)
+    end
+  end
+
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: id3lib-ruby
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2006-04-24 00:00:00 +02:00
+  version: 0.2.0
+date: 2006-05-07 00:00:00 +02:00
 summary: id3lib-ruby provides a Ruby interface to the id3lib C++ library for easily editing ID3 tags (v1 and v2) like with pyid3lib.
 require_paths: 
   - lib