music_ids 0.3.4 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 01d4df7373cff1ee3e167e3d95e762b2df104885
-  data.tar.gz: 7b0240d4b59fc374758094344fc16609407a6824
+  metadata.gz: 86e0063188644c2b834ba47d11edebc8de761c37
+  data.tar.gz: 47738cdae0a47c725ea4eadb9cadb723aeb5b735
 SHA512:
-  metadata.gz: 3c6ba9a0f85c9c9b4f719e00bc48a3fc66b67cd831f6147a1b41b7052d9fc5de8b08dc9873bfec5a8065b233b6a55b78a40114898f902268f9d119b66f6ca8ee
-  data.tar.gz: a0c4686300285053b14b86d33343c1c3d86dfd9f92c4c1aa4c4d630782e75408f9328955920835a0e67faae01088222cb71c04ece05eb1ae4b3f583989b0e46b
+  metadata.gz: 5ea07f4aac3e25370b947e51cbc531a5a05702e6ab767cd5166770741f3e85bb70df9c35ea292dd69e6708f636c8b76124dc1dbf8e47d94a25ecb7fb27d880ab
+  data.tar.gz: 0a7fc56bb2266614b103e5ee5ec04fa6f34b80415b1f3fbd6a0c3deb3f66c1c69d5096e5a5f2a27a606072145354a7907fc243c5c693c759e23152b05ad181f5

data/README.md

@@ -90,6 +90,74 @@ JSON.generate({isrc: isrc, grid: grid})
 #=> "{\"isrc\":\"FRZ039800212\",\"grid\":\"A12425GABC1234002M\"}"
 ```
 
+Problems with your ID will raise an ArgumentError on parsing
+
+```ruby
+require 'music_ids'
+
+begin
+  isrc = MusicIds::ISRC.parse('FRZ03')
+rescue ArgumentError => e
+  e.message
+end
+#=> "'FRZ03' is not the right length to be a MusicIds::ISRC"
+
+begin
+  grid = MusicIds::GRid.parse('A12425G')
+rescue ArgumentError => e
+  e.message
+end
+#=> "'A12425G' is not the right length to be a MusicIds::GRid"
+```
+
+If you have to sometimes deal with bad metadata, then you may want a more
+forgiving approach. Enter 'relaxed' parsing. You can pass `relaxed: true` as an
+options hash to `.parse`, or you can call `.relaxed` directly. A 'bad' instance
+returned by relaxed mode parsing reports that it's not ok with `#ok?` and won't
+return any components, and will only return the input string it was passed and
+not the full or prefixed versions you can get for a well-formed ISRC.
+
+```ruby
+require 'music_ids'
+
+bad_isrc = MusicIds::ISRC.parse('bad', relaxed: true)
+bad_isrc.ok?           #=> false
+bad_isrc.to_s          #=> 'bad'
+bad_isrc.country       #=> nil
+bad_isrc.as(:data)     #=> 'bad'
+bad_isrc.as(:full)     #=> 'bad'
+bad_isrc.as(:prefixed) #=> 'bad'
+
+other_bad_isrc = MusicIds::ISRC.relaxed('bad')
+other_bad_isrc.ok?     #=> false
+other_bad_isrc.to_s    #=> 'bad'
+
+bad_grid = MusicIds::GRid.parse('bad', relaxed: true)
+bad_grid.ok?           #=> false
+bad_grid.to_s          #=> 'bad'
+bad_grid.scheme        #=> nil
+bad_grid.as(:data)     #=> 'bad'
+bad_grid.as(:full)     #=> 'bad'
+bad_grid.as(:prefixed) #=> 'bad'
+
+other_bad_grid = MusicIds::GRid.relaxed('bad')
+other_bad_grid.ok?     #=> false
+other_bad_grid.to_s    #=> 'bad'
+
+MusicIds::ISRC.relaxed(nil) #=> nil
+MusicIds::GRid.relaxed(nil) #=> nil
+
+# Of course, parsing valid IDs in relaxed mode works just fine:
+MusicIds::ISRC.relaxed('FRZ039800212').ok?       #=> true
+MusicIds::GRid.relaxed('A12425GABC1234002M').ok? #=> true
+
+# And strict parsed instances can tell you they're okay
+MusicIds::ISRC.parse('FRZ039800212').ok?         #=> true
+MusicIds::GRid.parse('A12425GABC1234002M').ok?   #=> true
+```
+
+For more details, see the [RDoc](http://www.rubydoc.info/gems/music_ids).
+
 ## Development
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/music_ids/id.rb

@@ -8,7 +8,13 @@ module MusicIds
       # @option opts [true, false] :relaxed (false) Whether to parse in relaxed mode
       # @return [ISRC] the ISRC instance
       def parse(input, opts = {})
-        opts[:relaxed] ? parse_relaxed(input) : parse_strict(input)
+        opts[:relaxed] ? relaxed(input) : parse_strict(input)
+      end
+
+      def relaxed(input)
+        parse_string(input) { |input|
+          new(input, ok: false) unless input.nil?
+        }
       end
 
       private
@@ -21,17 +27,12 @@ module MusicIds
 
       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)
+          raise ArgumentError, "'#{input}' is not the right length to be a #{self.name}"
         }
       end
 
       def parse_string(input)
+        return yield(input) if input.nil?
         normalised = input.to_s.upcase
         if match = well_formed_id_matcher.match(normalised)
           new(match[1].gsub('-', ''))

data/lib/music_ids/version.rb

@@ -1,3 +1,3 @@
 module MusicIds
-  VERSION = "0.3.4"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: music_ids
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Patterson