discid 1.0.0.a1 → 1.0.0.rc1

data/.yardopts

@@ -1 +1 @@
---no-private --markup markdown
+--no-private --markup markdown --markup-provider kramdown - CHANGES

data/CHANGES

@@ -1,42 +1,45 @@
-= Changelog
-== 1.0.0.a1 (2013-04-22)
+# Changelog
+
+## 1.0.0
+* Support libdiscid versions 0.1.0 through 0.5.0
+* Compatible with JRuby
+
+## 1.0.0.a1 (2013-04-22)
 * Use FFI instead of C module
 * Completely overhauled API
 * Full support for MCN, ISRC and libdiscid feature detection
 * Renamed from mb-discid to just discid
 
-== 0.2.0 (2013-02-17)
+## 0.2.0 (2013-02-17)
 * Support for MCN and ISRC (requires libdiscid >= 0.3)
 
-== 0.1.5 (2011-07-02)
+## 0.1.5 (2011-07-02)
 * Added binding for get_webservice_url()
 * Add lib path detection, allows out-of-the-box install when your
   libdiscid is in /usr/local (Matt Patterson)
 
-== 0.1.4 (2009-11-19)
-* Fixed calling +read+ method without argument
+## 0.1.4 (2009-11-19)
+* Fixed calling read method without argument
 
-== 0.1.3 (2009-11-19)
-* Added singleton method +sectors_to_seconds+ to convert sectors into seconds
-* Added method +seconds+ to retrieve disc length in seconds
-* Added method +track_info+ for accessing more detailed information about tracks
+## 0.1.3 (2009-11-19)
+* Added singleton method sectors_to_seconds to convert sectors into seconds
+* Added method seconds to retrieve disc length in seconds
+* Added method track_info for accessing more detailed information about tracks
 * Fixed building with Ruby 1.9 (Mihaly Csomay)
 
-== 0.1.2 (2007-07-04)
-* Support the method +put+ to set the TOC information directly instead of
+## 0.1.2 (2007-07-04)
+* Support the method put to set the TOC information directly instead of
   reading it from a device.
-* Fixed possible core dump if +read+ was called twice and failed the
+* Fixed possible core dump if read was called twice and failed the
   second time.
 * New to_s method (returns string representation of the ID itself).
 * Complete RDoc documentation.
 
-== 0.1.1 (2007-06-03)
+## 0.1.1 (2007-06-03)
 * Minor changes to source to support MS compiler
 * Provide Win32 binary gem
 * Changed require of library to "require 'mb-discid'" (was "require 'DiscID'"
   before, which was likely to cause problems)
 
-== 0.1.0 (2007-06-02)
+## 0.1.0 (2007-06-02)
 * Initial release
-
-$Id$

data/README.md

@@ -8,7 +8,7 @@ the library can extract the MCN/UPC/EAN and the ISRCs from disc.
 ## Requirements
 * Ruby >= 1.8.6
 * Ruby-FFI
-* libdiscid >= 0.2.2
+* libdiscid >= 0.1.0
 
 ## Installation
 Before installing ruby-discid make sure you have libdiscid installed. See
@@ -23,6 +23,7 @@ Or install it from the source tarball:
     rake install
  
 ## Usage
+
 ### Read only the TOC
 
     require 'discid'
@@ -52,5 +53,16 @@ Or install it from the source tarball:
       puts "  ISRC  : %s" % track.isrc
     end
 
-See the documentation of {DiscId} or the files in the `examples` directory for
-more usage information.
+See the [API documentation](http://rubydoc.info/github/phw/ruby-discid/master/frames)
+of {DiscId} or the files in the `examples` directory for more usage information.
+
+## Contribute
+The source code for ruby-discid is available on
+[GitHub](https://github.com/phw/ruby-discid).
+
+Please report any issues on the
+[issue tracker](https://github.com/phw/ruby-discid/issues).
+
+## License
+ruby-discid is released under the GNU Lesser General Public License Version 3.
+See LICENSE.txt for details.

data/discid.gemspec

@@ -11,7 +11,8 @@ Gem::Specification.new do |spec|
   spec.description   = %q{ruby-discid provides Ruby bindings for the MusicBrainz DiscID library libdiscid. It allows calculating DiscIDs (MusicBrainz and freedb) for Audio CDs. Additionally the library can extract the MCN/UPC/EAN and the ISRCs from disc.}
   spec.summary       = %q{Ruby bindings for libdiscid}
   spec.homepage      = "https://github.com/phw/ruby-discid"
-  spec.license       = "LGPL3"
+  spec.license       = "LGPL-3"
+  spec.post_install_message = %q{Please make sure you have libdiscid (http://musicbrainz.org/doc/libdiscid) installed.}
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -23,5 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "yard"
-  spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency "kramdown"
 end

data/examples/discid.rb

@@ -41,10 +41,11 @@ First track : #{disc.first_track_num}
 Last track  : #{disc.last_track_num}
 Total length: #{disc.seconds} seconds
 Sectors     : #{disc.sectors}
-MCN         : #{disc.mcn}
-
 EOF
 
+puts "MCN         : #{disc.mcn}" if DiscId.has_feature?(:mcn)
+puts
+
 # Print information about individual tracks:
 disc.tracks do |track|
   puts "Track ##{track.number}"
@@ -54,10 +55,9 @@ disc.tracks do |track|
       [track.start_time / 60, track.start_time % 60, track.start_sector]
   puts "  End   : %02d:%02d (sector %i)" %
       [track.end_time / 60, track.end_time % 60, track.end_sector]
-  puts "  ISRC  : %s" % track.isrc
+  puts "  ISRC  : %s" % track.isrc if DiscId.has_feature?(:isrc)
 end
 
 # Print a submission URL that can be used to submit
 # the disc ID to MusicBrainz.org.
 puts "\nSubmit via #{disc.submission_url}"
-#puts "\nWebservice #{disc.webservice_url}"

data/lib/discid.rb

@@ -20,6 +20,50 @@ require 'discid/version'
 # The DiscId module allows calculating DiscIDs (MusicBrainz and freedb)
 # for Audio CDs. Additionally the library can extract the MCN/UPC/EAN and
 # the ISRCs from disc.
+#
+# The main interface for using this module are the {read} and {put}
+# methods which both return an instance of {Disc}. {read} allows you to
+# read the data from an actual CD drive while {put} allows you to
+# calculate the DiscID for a previously read CD TOC.
+#
+# Depending on the version of libdiscid and the operating system used
+# additional features like reading the MCN or ISRCs from the disc
+# might be available. You can check for supported features with {has_feature?}.
+#
+# @see http://musicbrainz.org/doc/libdiscid#Feature_Matrix
+#
+# @example Read the TOC, MCN and ISRCs
+#     require 'discid'
+# 
+#     device = "/dev/cdrom"
+#     disc = DiscId.read(device, :mcn, :isrc)
+# 
+#     # Print information about the disc:
+#     puts "DiscID      : #{disc.id}"
+#     puts "FreeDB ID   : #{disc.freedb_id}"
+#     puts "Total length: #{disc.seconds} seconds"
+#     puts "MCN         : #{disc.mcn}"
+#
+#     # Print information about individual tracks:
+#     disc.tracks do |track|
+#       puts "Track ##{track.number}"
+#       puts "  Length: %02d:%02d (%i sectors)" %
+#           [track.seconds / 60, track.seconds % 60, track.sectors]
+#       puts "  ISRC  : %s" % track.isrc
+#     end
+#
+# @example Get the DiscID for an existing TOC
+#     require 'discid'
+#
+#     first_track = 1
+#     sectors = 82255
+#     offsets = [150, 16157, 35932, 57527]
+#     disc = DiscId.put(first_track, sectors, offsets)
+#     puts disc.id # Output: E5VLOkhodzhvsMlK8LSNVioYOgY-
+#
+# @example Check for supported MCN feature
+#     disc = DiscId.read(nil, :mcn)
+#     puts "MCN: #{disc.mcn}" if DiscId.has_feature?(:mcn)
 module DiscId
 
   # Read the disc in the given CD-ROM/DVD-ROM drive extracting only the
@@ -39,14 +83,20 @@ module DiscId
   # @example Read the TOC, MCN and ISRCs:
   #     disc = DiscId.read(device, :mcn, :isrc)
   #
+  # @note libdiscid >= 0.5.0 is required for the feature selection to work.
+  #       Older versions will allways read MCN and ISRCs when supported. See
+  #       {http://musicbrainz.org/doc/libdiscid#Feature_Matrix} for a list of
+  #       supported features by version and platform.
+  #
   # @raise [TypeError] `device` can not be converted to a String.
   # @raise [Exception] Error reading from `device`. `Exception#message` contains
   #    error details.
-  # @param device [String] The device identifier.
-  # @param *features [:mcn, :isrc] List of features to use.
+  # @param device [String] The device identifier. If set to `nil` {default_device}
+  #     will be used.
+  # @param features [:mcn, :isrc] List of features to use.
   #     `:read` is always implied.
   # @return [Disc]
-  def self.read(device, *features)
+  def self.read(device = nil, *features)
     disc = Disc.new
     disc.read device, *features
     return disc
@@ -79,12 +129,31 @@ module DiscId
 
   # Check if a certain feature is implemented on the current platform.
   #
+  # You can obtain a list of supported features with {feature_list}.
+  #
+  # @note libdiscid >= 0.5.0 required. Older versions will return `true`
+  #     for `:read` and `false` for anything else.
+  #
   # @param feature [:read, :mcn, :isrc]
   # @return [Boolean] True if the feature is implemented and false if not.
   def self.has_feature?(feature)
     feature = feature.to_sym if feature.respond_to? :to_sym
-    result = Lib.has_feature feature if Lib::Features.symbols.include? feature
-    return result == 1
+    return self.feature_list.include? feature
+  end
+
+  # A list of features supported by the current platform.
+  # 
+  # Currently the following features are available:
+  # 
+  # * :read
+  # * :mcn
+  # * :isrc
+  #
+  # @note libdiscid >= 0.5.0 required. Older versions will return only [:read].
+  #
+  # @return [Array<Symbol>]
+  def self.feature_list
+    return Lib::Features.symbols.select {|f| Lib.has_feature(f) == 1}
   end
 
   # Converts sectors to seconds.

data/lib/discid/disc.rb

@@ -36,7 +36,7 @@ module DiscId
     # @private
     def read(device, *features)
       @read = false
-      device = self.class.default_device if device.nil?
+      device = DiscId.default_device if device.nil?
       
       if not device.respond_to? :to_s
         raise TypeError, 'wrong argument type (expected String)'
@@ -123,7 +123,11 @@ module DiscId
     #
     # Requires libdiscid >= 0.5. If not supported this method will always
     # return `nil`.
-    # 
+    #
+    # @note libdiscid >= 0.3.0 required. Older versions will always return nil.
+    #     Not available on all platforms, see
+    #     {http://musicbrainz.org/doc/libdiscid#Feature_Matrix}.
+    #
     # @return [String] MCN or `nil` if no ID was yet read. 
     def mcn
       return nil unless @read

data/lib/discid/lib.rb

@@ -18,7 +18,8 @@ require "ffi"
 module DiscId
 
   # This module encapsulates the C interface for libdiscid using FFI.
-  # The Lib module is intended for internal use only and should be considered private.
+  # The Lib module is intended for internal use only and should be
+  # considered private.
   #
   # @private
   module Lib
@@ -29,8 +30,15 @@ module DiscId
 
     attach_function :free, :discid_free, [:pointer], :void
   
-    # TODO: Handle old discid_read
-    attach_function :read, :discid_read_sparse, [:pointer, :string, :uint], :int
+    begin
+      attach_function :read, :discid_read_sparse, [:pointer, :string, :uint], :int
+    rescue FFI::NotFoundError
+      attach_function :legacy_read, :discid_read, [:pointer, :string], :int
+      
+      def self.read(handle, device, features)
+        legacy_read(handle, device)
+      end
+    end
 
     attach_function :put, :discid_put, [:pointer, :int, :int, :pointer], :int
 
@@ -54,27 +62,52 @@ module DiscId
 
     attach_function :get_track_length, :discid_get_track_length, [:pointer, :int], :int
 
-    attach_function :get_mcn, :discid_get_mcn, [:pointer], :string
+    begin
+      attach_function :get_mcn, :discid_get_mcn, [:pointer], :string
+    rescue FFI::NotFoundError
+      def self.get_mcn(handle)
+        return nil
+      end
+    end
 
-    attach_function :get_track_isrc, :discid_get_track_isrc, [:pointer, :int], :string
+    begin
+      attach_function :get_track_isrc, :discid_get_track_isrc, [:pointer, :int], :string
+    rescue FFI::NotFoundError
+      def self.get_track_isrc(handle, track)
+        return nil
+      end
+    end
 
     Features = enum(:feature, [:read, 1 << 0,
                                :mcn, 1 << 1,
                                :isrc, 1 << 2])
 
-    attach_function :has_feature, :discid_has_feature, [:feature], :int
+    begin
+      attach_function :has_feature, :discid_has_feature, [:feature], :int
+    rescue FFI::NotFoundError
+      def self.has_feature(feature)
+        return feature.to_sym == :read ? 1 : 0
+      end
+    end
 
     #attach_function :get_feature_list, :discid_get_feature_list, [:pointer], :void
     
-    attach_function :get_version_string, :discid_get_version_string, [], :string
-    
+    begin
+      attach_function :get_version_string, :discid_get_version_string, [], :string
+    rescue FFI::NotFoundError
+      def self.get_version_string
+        return "libdiscid < 0.4.0"
+      end
+    end
+
     def self.features_to_int(features)
       feature_flag = 0
       features.each do |feature|
         if feature.respond_to? :to_sym
           feature = feature.to_sym
           feature_flag |= self::Features[feature] if
-            self::Features.symbols.include?(feature)
+            self::Features.symbols.include?(feature) and
+            self.has_feature(feature)
         end
       end
 

data/lib/discid/track_info.rb

@@ -55,7 +55,11 @@ module DiscId
     # @return [Integer]
     attr_reader :start_sector
     
-    # ISRC number of the trac
+    # ISRC number of the track.
+    #
+    # @note libdiscid >= 0.3.0 required. Older versions will always return nil.
+    #     Not available on all platforms, see
+    #     {http://musicbrainz.org/doc/libdiscid#Feature_Matrix}.
     #
     # @return [String]
     attr_reader :isrc

data/lib/discid/version.rb

@@ -15,5 +15,5 @@
 
 
 module DiscId
-  VERSION = "1.0.0.a1"
+  VERSION = "1.0.0.rc1"
 end

data/test/test_discid.rb

@@ -159,4 +159,9 @@ class TestDiscID < Test::Unit::TestCase
            "Feature 'notafeature' should not be supported")
   end
   
+  def test_feature_list_must_contain_read
+    assert(DiscId.feature_list.include?(:read),
+           "Feature :read should be supported")
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: discid
 version: !ruby/object:Gem::Version
-  version: 1.0.0.a1
+  version: 1.0.0.rc1
   prerelease: 6
 platform: ruby
 authors:
@@ -76,7 +76,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: kramdown
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -119,8 +119,9 @@ files:
 - test/test_discid.rb
 homepage: https://github.com/phw/ruby-discid
 licenses:
-- LGPL3
-post_install_message: 
+- LGPL-3
+post_install_message: Please make sure you have libdiscid (http://musicbrainz.org/doc/libdiscid)
+  installed.
 rdoc_options: []
 require_paths:
 - lib