music_ids 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0dcfa17ed18001f410a21d829f1b76e908d4434e
-  data.tar.gz: cc4b1fb8380914370cab6d9de1b1748f70ee4299
+  metadata.gz: ab2b1cbddfb673d888c9dbf7f493cf87b4536c99
+  data.tar.gz: 7a3eb549ec25b0cce0af4424e7f981d237b9eb8f
 SHA512:
-  metadata.gz: e1a729e07cea652ccacf911a0712b6b2a5c1696661ada9c65ebff2150edda6ab4a4bd461cfc9065e32f03bac7681f5ab968c72e206211c3095d471e1314e3e9d
-  data.tar.gz: eafd21cf4c04b24c2fd9980343cc6d15bfbd9962836a1ebaa2560c07d6d393bbf8e8850cb87f14bf2c972ada9013e9d5fe981037033e7ee147aa43dec6de2403
+  metadata.gz: b955c505b78a891e7ca4fc2f03d9baddb7506e0c6faf97af297b17ec5b5594184ea41e587b24bf5cbabcad2a0a24a85be1ef1cd3129e9fc1a059dea3dcd10e66
+  data.tar.gz: eb5119e0309675bd2abf35eb71297f25e65f7ea95a87fa8387f91d745c6a48a73b377b938ac26b80fbcac5eb017a0e45ff3c61a3b4363bc3674bcd01c30b11b9

data/lib/music_ids/grid.rb

@@ -1,3 +1,5 @@
+require 'music_ids/id'
+
 module MusicIds
   # The GRid class represents a Global Release Identifier, and
   # provides simple methods to parse and re-present them.
@@ -8,7 +10,7 @@ module MusicIds
   # often used as key identifiers in the delivery and reporting of digital
   # music products.
   #
-  # You can get more details from 
+  # You can get more details from
   # https://en.wikipedia.org/wiki/Global_Release_Identifier and
   # http://www.ifpi.org/grid.php
   #
@@ -33,112 +35,51 @@ module MusicIds
   # instance that will return <tt>false</tt> from <tt>#ok?</tt> and will return
   # nil from all the component methods like <tt>#issuer</tt>
   class GRid
-    # See http://www.ifpi.org/downloads/GRid_Standard_v2_1.pdf §5
-    WELL_FORMED_INPUT = /\AA1-?[A-Z0-9]{5}-?[A-Z0-9]{10}-?[A-Z0-9]\Z/
-
-    class << self
-      # Parse a GRid string into a GRid instance
-      #
-      # @param input [String] The input GRid string to parse
-      # @param opts [Hash] Parsing options
-      # @option opts [true, false] :relaxed (false) Whether to parse in relaxed mode
-      # @return [GRid] the grid instance
-      def parse(input, opts = {})
-        input = input.to_s.upcase
-        opts[:relaxed] ? parse_relaxed(input) : parse_strict(input)
-      end
-
-      private
-
-      def parse_strict(input)
-        if WELL_FORMED_INPUT.match(input)
-          new(input.gsub('-', ''))
-        else
-          raise ArgumentError, "'#{input}' is not the right length to be a 12- or 15-character ISRC"
-        end
-      end
-
-      def parse_relaxed(input)
-        if WELL_FORMED_INPUT.match(input)
-          new(input.gsub('-', ''))
-        else
-          new(input, ok: false)
-        end
-      end
-    end
+    include Id
 
-    # @api private
-    # @param grid_string [String] The GRid string
-    # @param opts [Hash]
-    # @option opts [true, false] :ok (true) Whether the GRid is well-formed or not
-    def initialize(grid_string, opts = {ok: true})
-      @grid_string = grid_string.dup.freeze
-      @ok = opts[:ok] ? true : false
+    # See http://www.ifpi.org/downloads/GRid_Standard_v2_1.pdf §5
+    def self.id_blocks
+      ['A1', '[A-Z0-9]{5}', '[A-Z0-9]{10}', '[A-Z0-9]']
     end
 
-    # Is this a well-formed GRid?
-    # @return [true,false]
-    def ok?
-      @ok
+    # The prefix to use for generating a prefixed string representation of the GRID
+    # (see http://www.ifpi.org/downloads/GRid_Standard_v2_1.pdf §6
+    def self.prefix
+      @prefix ||= 'GRID'.freeze
     end
 
     # Return the GRid's two-letter scheme identifier
     # @return [String]
     def scheme
-      return unless ok?
-      @scheme ||= @grid_string[0,2].freeze
+      fetch(:@scheme) { |grid_string| grid_string[0,2] }
     end
 
     # Return the GRid's 5-character issuer code
     # @return [String]
     def issuer
-      return unless ok?
-      @issuer ||= @grid_string[2,5].freeze
+      fetch(:@issuer) { |grid_string| grid_string[2,5] }
     end
 
     # Return the GRid's 10-character release number.
     # @return [String]
     def release
-      return unless ok?
-      @release ||= @grid_string[7,10].freeze
+      fetch(:@release) { |grid_string| grid_string[7,10] }
     end
 
     # Return the GRid's check character.
     # @return [String]
     def check
-      return unless ok?
-      @check ||= @grid_string[17,1].freeze
-    end
-
-    # return the GRid as a normalised 18-character string
-    # @reuturn [String]
-    def to_s
-      @grid_string.dup
+      fetch(:@check) { |grid_string| grid_string[17,1] }
     end
 
     def to_grid
       self
     end
 
-    def ==(other)
-      to_s == other.to_s
-    end
-
-    # Returns the GRid as a string, either the 18-character normalised string
-    # (:data) or the 21-character display string (:full). Note that a
-    # badly-formed GRid will simply return the original string whichever format
-    # you ask for.
-    # @param format [:data, :full] the output format to use
+    # Generate the hyphen-separated full display GRid string
     # @return [String]
-    def as(format)
-      case format
-      when :data
-        to_s
-      when :full
-        ok? ? "#{scheme}-#{issuer}-#{release}-#{check}" : to_s
-      else
-        raise ArgumentError, "format must be one of [:data, :full], but it was #{format.inspect}"
-      end
+    def as_full
+      "#{scheme}-#{issuer}-#{release}-#{check}"
     end
   end
 end

data/lib/music_ids/id.rb

@@ -0,0 +1,105 @@
+module MusicIds
+  module Id
+    module ClassMethods
+      # Parse an identifier string into an instance
+      #
+      # @param input [String] The input identifier string to parse
+      # @param opts [Hash] Parsing options
+      # @option opts [true, false] :relaxed (false) Whether to parse in relaxed mode
+      # @return [ISRC] the ISRC instance
+      def parse(input, opts = {})
+        input = input.to_s.upcase
+        opts[:relaxed] ? parse_relaxed(input) : parse_strict(input)
+      end
+
+      private
+
+      def well_formed_id_matcher
+        @matcher ||= begin
+          Regexp.compile("\\A(?:#{prefix}:)?(#{id_blocks.join('-')}|#{id_blocks.join('')})\\Z")
+        end
+      end
+
+      def parse_strict(input)
+        parse_string(input) { |input|
+          raise ArgumentError, "'#{input}' is not the right length to be a #{self.class}"
+        }
+      end
+
+      def parse_relaxed(input)
+        parse_string(input) { |input|
+          new(input, ok: false)
+        }
+      end
+
+      def parse_string(input)
+        if match = well_formed_id_matcher.match(input)
+          new(match[1].gsub('-', ''))
+        else
+          yield(input)
+        end
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # @api private
+    # @param isrc_string [String] The ISRC string
+    # @param opts [Hash]
+    # @option opts [true, false] :ok (true) Whether the ISRC is well-formed or not
+    def initialize(id_string, opts = {ok: true})
+      @id_string = id_string.dup.freeze
+      @ok = opts[:ok] ? true : false
+    end
+
+    # Is this a well-formed ID?
+    # @return [true,false]
+    def ok?
+      @ok
+    end
+
+    # return the ID as a normalised string
+    # @return [String]
+    def to_s
+      @id_string.dup
+    end
+
+    def ==(other)
+      to_s == other.to_s
+    end
+
+    # Returns the ID as a string, either as the normalised canonical string
+    # (:data) or the format specified for 'full' display (:full). Note that a
+    # badly-formed ID will simply return the original string whichever format
+    # you ask for.
+    # @param format [:data, :full, :prefixed] the output format to use
+    # @return [String]
+    def as(format)
+      case format
+      when :data
+        to_s
+      when :full
+        ok? ? as_full : to_s
+      when :prefixed
+        "#{prefix}:#{as_full}"
+      else
+        raise ArgumentError, "format must be one of [:data, :full, :prefixed], but it was #{format.inspect}"
+      end
+    end
+
+    # Return the prefix for the identifier
+    def prefix
+      self.class.prefix
+    end
+
+    private
+
+    def fetch(ivar)
+      return unless ok?
+      return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+      instance_variable_set(ivar, yield(@id_string).freeze)
+    end
+  end
+end

data/lib/music_ids/isrc.rb

@@ -1,3 +1,5 @@
+require 'music_ids/id'
+
 module MusicIds
   # The ISRC class represents an International Standard Recording Code, and
   # provides simple methods to parse and re-present them.
@@ -43,116 +45,54 @@ module MusicIds
   # instance that will return <tt>false</tt> from <tt>#ok?</tt> and will return
   # nil from all the component methods like <tt>#registrant</tt>
   class ISRC
-    # See http://www.ifpi.org/content/library/isrc_handbook.pdf §3.5
-    WELL_FORMED_INPUT = /\A[A-Z]{2}-?[A-Z0-9]{3}-?[0-9]{2}-?[0-9]{5}\Z/
-
-    class << self
-      # Parse an ISRC string into an ISRC instance
-      #
-      # @param input [String] The input ISRC string to parse
-      # @param opts [Hash] Parsing options
-      # @option opts [true, false] :relaxed (false) Whether to parse in relaxed mode
-      # @return [ISRC] the ISRC instance
-      def parse(input, opts = {})
-        input = input.to_s.upcase
-        opts[:relaxed] ? parse_relaxed(input) : parse_strict(input)
-      end
-
-      private
-
-      def parse_strict(input)
-        if WELL_FORMED_INPUT.match(input)
-          new(input.gsub('-', ''))
-        else
-          raise ArgumentError, "'#{input}' is not the right length to be a 12- or 15-character ISRC"
-        end
-      end
-
-      def parse_relaxed(input)
-        if WELL_FORMED_INPUT.match(input)
-          new(input.gsub('-', ''))
-        else
-          new(input, ok: false)
-        end
-      end
-    end
+    include Id
 
-    # @api private
-    # @param isrc_string [String] The ISRC string
-    # @param opts [Hash]
-    # @option opts [true, false] :ok (true) Whether the ISRC is well-formed or not
-    def initialize(isrc_string, opts = {ok: true})
-      @isrc_string = isrc_string.dup.freeze
-      @ok = opts[:ok] ? true : false
+    # See http://www.ifpi.org/content/library/isrc_handbook.pdf §3.5
+    def self.id_blocks
+      ['[A-Z]{2}', '[A-Z0-9]{3}', '[0-9]{2}', '[0-9]{5}']
     end
 
-    # Is this a well-formed ISRC?
-    # @return [true,false]
-    def ok?
-      @ok
+    # The prefix to use for generating a prefixed string representation of the ISRC
+    # (see http://www.ifpi.org/downloads/GRid_Handbook_V2_0_final.pdf §9.2 / §9.3
+    def self.prefix
+      @prefix ||= 'ISRC'.freeze
     end
 
     # Return the ISRC's two-letter country code
     # @return [String]
     def country
-      return unless ok?
-      @country ||= @isrc_string[0,2].freeze
+      fetch(:@country) { |isrc_string| isrc_string[0,2] }
     end
 
     # Return the ISRC's three-character registrant code
     # @return [String]
     def registrant
-      return unless ok?
-      @registrant ||= @isrc_string[2,3].freeze
+      fetch(:@registrant) { |isrc_string| isrc_string[2,3] }
     end
 
     # Return the ISRC's two-digit year.
     #
     # Note that year > 40 is a 19YY year, and 00 to 39 are 20YY years
-    # see http://www.ifpi.org/content/library/isrc_handbook.pdf section 4.8
+    # see http://www.ifpi.org/content/library/isrc_handbook.pdf §4.8
     # @return [String]
     def year
-      return unless ok?
-      @year ||= @isrc_string[5,2].freeze
+      fetch(:@year) { |isrc_string| isrc_string[5,2] }
     end
 
     # Return the ISRC's five-character designation code.
-    #
     # @return [String]
     def designation
-      return unless ok?
-      @designation ||= @isrc_string[7,5].freeze
-    end
-
-    # return the ISRC as a normalised 12-character string
-    # @reuturn [String]
-    def to_s
-      @isrc_string.dup
+      fetch(:@designation) { |isrc_string| isrc_string[7,5] }
     end
 
     def to_isrc
       self
     end
 
-    def ==(other)
-      to_s == other.to_s
-    end
-
-    # Returns the ISRC as a string, either the 12-character normalised string
-    # (:data) or the 15-character display string (:full). Note that a
-    # badly-formed ISRC will simply return the original string whichever format
-    # you ask for.
-    # @param format [:data, :full] the output format to use
+    # Generate the hyphen-separated full display ISRC string
     # @return [String]
-    def as(format)
-      case format
-      when :data
-        to_s
-      when :full
-        ok? ? "#{country}-#{registrant}-#{year}-#{designation}" : to_s
-      else
-        raise ArgumentError, "format must be one of [:data, :full], but it was #{format.inspect}"
-      end
+    def as_full
+      "#{country}-#{registrant}-#{year}-#{designation}"
     end
   end
 end

data/lib/music_ids/version.rb

@@ -1,3 +1,3 @@
 module MusicIds
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: music_ids
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Matt Patterson
@@ -89,6 +89,7 @@ files:
 - bin/setup
 - lib/music_ids.rb
 - lib/music_ids/grid.rb
+- lib/music_ids/id.rb
 - lib/music_ids/isrc.rb
 - lib/music_ids/version.rb
 - music_ids.gemspec