music_ids 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d75caff64b4e4891c3f7ec2f74cd69565326ad32
-  data.tar.gz: ce0f8a0238c334c6f9fae24e73d2a4e56c0047d9
+  metadata.gz: 0dcfa17ed18001f410a21d829f1b76e908d4434e
+  data.tar.gz: cc4b1fb8380914370cab6d9de1b1748f70ee4299
 SHA512:
-  metadata.gz: 8c011793f6cc32c44a74add1a360e30c6b1c44791c145500ac1ac75b154a7d0dfed11e852d118035f55a564d6813ee9ad9c22a071da9c7bcf41998d03fa27f30
-  data.tar.gz: 5ba4a46d7e81136e56299c0f6e1247735f133108527587305d55c8f492dbbb39e09e443a197e1e819001f775bba22500cef8ddadded324ca30c2bb8228cba4fd
+  metadata.gz: e1a729e07cea652ccacf911a0712b6b2a5c1696661ada9c65ebff2150edda6ab4a4bd461cfc9065e32f03bac7681f5ab968c72e206211c3095d471e1314e3e9d
+  data.tar.gz: eafd21cf4c04b24c2fd9980343cc6d15bfbd9962836a1ebaa2560c07d6d393bbf8e8850cb87f14bf2c972ada9013e9d5fe981037033e7ee147aa43dec6de2403

data/README.md

@@ -1,5 +1,7 @@
 # MusicIds
 
+[![Build Status](https://travis-ci.org/tape-tv/music_ids.svg)](https://travis-ci.org/tape-tv/music_ids)[![Code Climate](https://codeclimate.com/github/tape-tv/music_ids/badges/gpa.svg)](https://codeclimate.com/github/tape-tv/music_ids)[![Test Coverage](https://codeclimate.com/github/tape-tv/music_ids/badges/coverage.svg)](https://codeclimate.com/github/tape-tv/music_ids/coverage)[![Gem Version](https://badge.fury.io/rb/music_ids.svg)](http://badge.fury.io/rb/music_ids) [RDoc](http://www.rubydoc.info/gems/music_ids)
+
 `music_ids` contains classes that represent some of the main ID formats in use in the music industry for identifying individual pieces of recorded music.
 
 There are often several ways that these IDs can be written, so the classes provide standard APIs to parse and normalise ID strings, as well as to break them into their components.

data/lib/music_ids/grid.rb

@@ -0,0 +1,144 @@
+module MusicIds
+  # The GRid class represents a Global Release Identifier, and
+  # provides simple methods to parse and re-present them.
+  #
+  # == What is a GRid?
+  # GRid's are unique identifiers for Releases of recorded music, as distinct
+  # from different Products (See the GRid Handbook for more details). They're
+  # often used as key identifiers in the delivery and reporting of digital
+  # music products.
+  #
+  # You can get more details from 
+  # https://en.wikipedia.org/wiki/Global_Release_Identifier and
+  # http://www.ifpi.org/grid.php
+  #
+  # == Well-formedness and validity
+  # GRid's are supposed to be able to be looked up in a global database, so we
+  # need to draw a distinction between *valid* GRid's, which are GRid's we have
+  # looked up and verified in that database, and well-formed GRid's, which are
+  # just strings that match the requirements above.
+  #
+  # Checking or enforcing validity is beyond the scope of this class.
+  # Well-formedness, on the other hand, is easy to check and enforce.
+  #
+  # While you don't want to be emitting badly-formed GRid's, if you handle
+  # GRid's from elsewhere you may well run across bad metadata that you need to
+  # preserve, but probably want to be aware of the fact that it's bad.
+  #
+  # To help with that there are two parsing modes, strict (the default), and
+  # relaxed.
+  #
+  # In strict parsing mode, <tt>GRid.parse</tt> will raise an error if passed a
+  # badly-formed GRid string. In relaxed mode, it will return an <tt>GRid</tt>
+  # 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
+
+    # @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
+    end
+
+    # Is this a well-formed GRid?
+    # @return [true,false]
+    def ok?
+      @ok
+    end
+
+    # Return the GRid's two-letter scheme identifier
+    # @return [String]
+    def scheme
+      return unless ok?
+      @scheme ||= @grid_string[0,2].freeze
+    end
+
+    # Return the GRid's 5-character issuer code
+    # @return [String]
+    def issuer
+      return unless ok?
+      @issuer ||= @grid_string[2,5].freeze
+    end
+
+    # Return the GRid's 10-character release number.
+    # @return [String]
+    def release
+      return unless ok?
+      @release ||= @grid_string[7,10].freeze
+    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
+    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
+    # @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
+    end
+  end
+end

data/lib/music_ids/isrc.rb

@@ -139,7 +139,9 @@ module MusicIds
     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
+    # (: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
     # @return [String]
     def as(format)

data/lib/music_ids/version.rb

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

data/lib/music_ids.rb

@@ -1,5 +1,6 @@
-require "music_ids/version"
+require 'music_ids/version'
+require 'music_ids/isrc'
+require 'music_ids/grid'
 
 module MusicIds
-  # Your code goes here...
 end

metadata

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