urn 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f729f3390ecec4c9843f007a1be16632ca7b1516
-  data.tar.gz: b85858036290b073d73ddca76076f59fe4e9476e
+  metadata.gz: 8943094c2abdbd829f57606ac2f651ac1f16944a
+  data.tar.gz: 2e7adb38f071f23aa5325509ed77c87dc67c2abd
 SHA512:
-  metadata.gz: 69b2624baef7186d9c1f4beea2fe468a01eb3c85134647a8b30761b46d3ce51a27bf2fa8d054744ff206a76010361a3b5eb39e6ba9e2551ef8d442da6aed82cc
-  data.tar.gz: 3ace937ef1827b479377959d3bba1b7ebf87ff31690b18ad359571a4d59c15c73e3a2edfc09f69690ec548b47fa0458cf0e84c7ecefc54e09e9e166e7cbf5e85
+  metadata.gz: f19abc0d935c0e06f933dac8e3aba375c2f841072cdde554539216d2d8b544102934f5df025dcc7276fb5fb389ba5f50cd1310212227ada8ed0ea33c0ae7b729
+  data.tar.gz: 9a829c8512031bee7061ff5b7a521c66de6026dfa866dd43ce88937aaed832e00d6e7c14b385a262d285ff4d00971b7f89832cba56be1d772060d8e1f90da24e

data/CHANGELOG.md

@@ -2,6 +2,52 @@
 All notable changes to this project will be documented in this file. This
 project adheres to [Semantic Versioning](http://semver.org/).
 
+## [2.0.0] - 2016-03-22
+### Changed
+- Only return `URN` instances for valid `URN`s at creation. Raise `URN::InvalidURNError` otherwise.
+- `#normalize` returns a normalized `URN` object instead of its `String` representation. You can get the normalized `String` representation with `.normalize.to_s`
+- Do not allow hexadecimal numbers from 0 to 20 and from 7F to FF. See [RFC2141](https://www.ietf.org/rfc/rfc2141.txt) section "2.4 Excluded characters".
+
+### Added
+- Shortcut method (`URN()`) at creation:
+```ruby
+urn = URN('URN:Name:Spec')
+#=> #<URN:0x007fd97a835558 @urn="URN:Name:Spec">
+```
+- `REGEX` into the API documentation
+- `#nid` returns the namespace identifier part.
+```ruby
+URN('URN:Name:Spec').nid
+#=> "Name"
+```
+- `#nss` returns the namespace specific string part.
+```ruby
+URN('URN:Name:Spec').nss
+#=> "Spec"
+```
+- `#to_s` returns the `String` representation.
+```ruby
+URN('URN:Name:Spec').to_s
+#=> "URN:Name:Spec"
+```
+- `#===(other)` returns true if the URN objects are equivalent. This method normalizes both URNs before doing the comparison, and allows comparison against Strings.
+- `#==(other)` returns true if the URN objects are equivalent. This method normalizes both URNs before doing the comparison.
+- `#eql?(other)` returns true if the URN objects are equal. This method does NOT normalize either URN before doing the comparison.
+- `.extract(str)` attempts to parse and merge a set of URNs. If no `block` is given, then returns the result as an `Array`. Else it calls `block` for each element in result and returns `nil`.
+- URN initialization accepts a `URN` as argument:
+```ruby
+URN(URN('urn:foo:bar'))
+#=> #<URN:0x007f85040434c8 @urn="urn:foo:bar">
+```
+
+### Removed
+- `#valid?`. Validity check is now at object creation time, therefore all instances of `URN` are valid.
+
+
+## [1.0.0] - 2016-03-09
+### Changed
+- The library is now [RFC2141](https://www.ietf.org/rfc/rfc2141.txt) compliant.
+
 ## [0.1.3] - 2016-03-07
 ### Fixed
 - Explicitly require CGI standard library
@@ -18,6 +64,8 @@ project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - First version with basic implementation.
 
+[2.0.0]: https://github.com/altmetric/urn/releases/tag/v2.0.0
+[1.0.0]: https://github.com/altmetric/urn/releases/tag/v1.0.0
 [0.1.3]: https://github.com/altmetric/urn/releases/tag/v0.1.3
 [0.1.2]: https://github.com/altmetric/urn/releases/tag/v0.1.2
 [0.1.1]: https://github.com/altmetric/urn/releases/tag/v0.1.1

data/README.md

@@ -1,8 +1,9 @@
 # URN [![Build Status](https://travis-ci.org/altmetric/urn.svg?branch=master)](https://travis-ci.org/altmetric/urn)
 
-Ruby library to validate and normalize URNs.
+Ruby library to validate and normalize URNs according to [RFC 2141](https://www.ietf.org/rfc/rfc2141.txt).
+
+[![Gem Version](https://badge.fury.io/rb/urn.svg)](https://badge.fury.io/rb/urn)  
 
-**Current version:** 0.1.3  
 **Supported Ruby versions:** 1.8.7, 1.9.2, 1.9.3, 2.0, 2.1, 2.2, 2.3
 
 ## Installation
@@ -10,7 +11,7 @@ Ruby library to validate and normalize URNs.
 Add this line to your application's `Gemfile`:
 
 ```ruby
-gem 'urn', '~> 0.1'
+gem 'urn', '~> 2.0'
 ```
 
 And then execute:
@@ -19,62 +20,127 @@ And then execute:
 
 Or install it yourself as:
 
-    $ gem install urn -v '~> 0.1'
+    $ gem install urn -v '~> 2.0'
 
 ## Usage
 
 ```ruby
-urn = URN.new('URN:NameSpace:Identifier')
+urn = URN('URN:NameSpace:Identifier')
 #=> #<URN:0x007fd97a835558 @urn="URN:NameSpace:Identifier">
 
-urn.valid?
-#=> true
+urn = URN.new('URN:NameSpace:Identifier')
+#=> #<URN:0x007fd97a835558 @urn="URN:NameSpace:Identifier">
 
 urn.normalize
 #=> "urn:namespace:Identifier"
+
+urn = URN('123')
+#=> URN::InvalidURNError: bad URN(is not URN?): 123
 ```
 
 ## API Documentation
 
 ### `URN::PATTERN`
-
 ```ruby
 text.match(/\?urn=(#{URN::PATTERN})/)
 ```
+Return a `String` of an unanchored regular expression suitable for matching URNs.
 
-Return a `String` of an unanchored regular expression suitable for matching
-URNs.
-
-### `URN.new`
+### `URN::REGEX`
+```ruby
+URN::REGEX
+#=> /\A(?i:urn:(?!urn:)[a-z0-9][a-z0-9-]{1,31}:(?:[a-z0-9()+,-.:=@;$_!*']|%[0-9a-f]{2})+)\z/
+```
+Return a `Regexp` object with the anchored regular expression suitable to match a URN.
 
+### `URN()` or `URN.new`
 ```ruby
+urn = URN('urn:nid:nss')
+#=> #<URN:0xdecafbad @urn="urn:nid:nss">
+
 urn = URN.new('urn:nid:nss')
 #=> #<URN:0xdecafbad @urn="urn:nid:nss">
+
+urn = URN('1234')
+#=> URN::InvalidURNError: bad URN(is not URN?): 1234
 ```
+Return a new `URN` instance when the given string is valid according to [RFC 2141](https://www.ietf.org/rfc/rfc2141.txt). Otherwise, it raises an `URN::InvalidURNError`
 
-Return a new `URN` instance with the given string.
+### `URN#normalize`
+```ruby
+URN('URN:FOO:BAR').normalize
+#=> #<URN:0x007fb9a3096848 @urn="urn:foo:BAR">
+```
+Return the normalized `URN` object, normalizing the case
+of the `urn` token and namespace identifier. Call `#to_s` after `#normalize` if you want the normalized `String` representation.
 
-### `URN#valid?`
+### `URN#nid`
+```ruby
+URN('urn:nid:nss').nid
+#=> "nid"
+```
+Return the namespace identifier part.
 
+### `URN#nss`
 ```ruby
-URN.new('foo').valid?
-#=> false
+URN('urn:nid:nss').nss
+#=> "nss"
+```
+Return the namespace specific string part.
+
+### `URN#to_s`
+```ruby
+URN('urn:Nid:Nss').to_s
+#=> "urn:Nid:Nss"
+```
+Return the `String` representation.
+
+### `#===(other)`
+```ruby
+URN('urn:name:spec') === 'URN:Name:spec'
+#=> true
 
-URN.new('urn:foo:bar').valid?
+URN('urn:name:spec') === URN('URN:Name:spec')
 #=> true
 ```
+Return true if the URN objects are equivalent. This method normalizes both URNs before doing the comparison, and allows comparison against Strings.
 
-Returns true if the `URN` is valid according to [RFC 2141](https://www.ietf.org/rfc/rfc2141.txt).
+### `#==(other)`
+```ruby
+URN('urn:name:spec') == 'URN:Name:spec'
+#=> false
 
-### `URN#normalize`
+URN('urn:name:spec') == URN('URN:Name:spec')
+#=> true
+```
+Returns true if the URN objects are equivalent. This method normalizes both URNs before doing the comparison.
 
+### `#eql?(other)`
 ```ruby
-URN.new('URN:FOO:BAR').normalize
-#=> "urn:foo:BAR"
+URN('urn:name:spec').eql?('urn:name:spec')
+#=> false
+
+URN('urn:name:spec').eql?(URN('urn:NAME:spec'))
+#=> false
+
+URN('urn:name:spec').eql?(URN('urn:name:spec'))
+#=> true
 ```
+Returns true if the URN objects are equal. This method does NOT normalize either URN before doing the comparison.
 
-Return a normalized `String` representation of the `URN`, normalizing the case
-of the `urn` token and namespace identifier.
+### `.extract(str)`
+```ruby
+URN.extract('text urn:1234:abc more text URN:foo:bar%23.\\')
+#=> ['urn:1234:abc', 'URN:foo:bar%23.']
+
+normalized_urns = []
+#=> []
+URN.extract('text urn:1234:abc more text URN:foo:bar%23.\\') { |urn| normalized_urns << URN(urn).normalize.to_s }
+#=> nil
+normalized_urns
+#=> ['urn:1234:abc', 'URN:foo:bar%23.']
+```
+Extracts URNs from a string. If block given, iterates through all matched URNs. Returns nil if block given or array with matches.
 
 ## Contributing
 

data/lib/urn.rb

@@ -1,26 +1,63 @@
+def URN(urn)
+  URN.new(urn)
+end
+
 class URN
+  InvalidURNError = Class.new(StandardError)
+
   PATTERN = %{(?i:urn:(?!urn:)[a-z0-9][a-z0-9\-]{1,31}:} +
-            %{(?:[a-z0-9()+,-.:=@;$_!*']|%[0-9a-f]{2})+)}.freeze
+            %{(?:[a-z0-9()+,-.:=@;$_!*']|%(?:2[1-9a-f]|[3-6][0-9a-f]|7[0-9a-e]))+)}.freeze
   REGEX = /\A#{PATTERN}\z/
 
-  attr_reader :urn
+  attr_reader :urn, :nid, :nss
   private :urn
 
-  def initialize(urn)
-    @urn = urn
+  def self.extract(str, &blk)
+    str.scan(/#{PATTERN}/, &blk)
   end
 
-  def valid?
-    !(urn =~ REGEX).nil?
+  def initialize(urn)
+    urn = urn.to_s
+    fail InvalidURNError, "bad URN(is not URN?): #{urn}" if urn !~ REGEX
+
+    @urn = urn
+    _scheme, @nid, @nss = urn.split(':', 3)
   end
 
   def normalize
-    return unless valid?
-
-    _scheme, nid, nss = urn.split(':', 3)
     normalized_nid = nid.downcase
     normalized_nss = nss.gsub(/%([0-9a-f]{2})/i) { |hex| hex.downcase }
 
-    "urn:#{normalized_nid}:#{normalized_nss}"
+    URN.new("urn:#{normalized_nid}:#{normalized_nss}")
+  end
+
+  def to_s
+    urn
+  end
+
+  def ===(other)
+    if other.respond_to?(:normalize)
+      urn_string = other.normalize.to_s
+    else
+      begin
+        urn_string = URN.new(other).normalize.to_s
+      rescue URN::InvalidURNError
+        return false
+      end
+    end
+
+    normalize.to_s == urn_string
+  end
+
+  def ==(other)
+    return false unless other.is_a?(URN)
+
+    normalize.to_s == other.normalize.to_s
+  end
+
+  def eql?(other)
+    return false unless other.is_a?(URN)
+
+    to_s == other.to_s
   end
 end

data/spec/urn_spec.rb

@@ -2,65 +2,168 @@
 require 'urn'
 
 RSpec.describe URN do
-  describe '#valid?' do
-    it 'returns true if it is valid' do
-      expect(described_class.new('urn:namespace:specificstring')).to be_valid
+  describe 'URN' do
+    it 'returns a URN if it is valid' do
+      expect(URN('urn:namespace:specificstring')).to be_kind_of(described_class)
     end
 
-    it 'returns true if namespace includes urn' do
-      expect(described_class.new('urn:urnnamespace:specificstring')).to be_valid
+    it 'raise InvalidURNError if it is not valid' do
+      expect { URN('urn:urn:1234') }.to raise_error(described_class::InvalidURNError, 'bad URN(is not URN?): urn:urn:1234')
     end
 
-    it 'returns false if it does not start with urn' do
-      expect(described_class.new('not-urn:namespace:specificstring')).not_to be_valid
+    it 'returns the same URN if the argument is a URN' do
+      urn = URN.new('urn:foo:bar')
+
+      expect(URN(urn).to_s).to eq('urn:foo:bar')
+    end
+  end
+
+  describe '#initialize' do
+    it 'returns the same URN if the argument is a URN' do
+      urn = URN.new('urn:foo:bar')
+
+      expect(URN.new(urn).to_s).to eq('urn:foo:bar')
+    end
+
+    it 'returns a URN if it is valid' do
+      expect(described_class.new('urn:namespace:specificstring')).to be_kind_of(described_class)
     end
 
-    it 'returns false if namespace is urn' do
-      expect(described_class.new('urn:urn:specificstring')).not_to be_valid
+    it 'raise InvalidURNError if it is not valid' do
+      expect { described_class.new('urn:urn:1234') }.to raise_error(described_class::InvalidURNError, 'bad URN(is not URN?): urn:urn:1234')
     end
 
-    it 'returns false if namespace is URN' do
-      expect(described_class.new('urn:URN:specificstring')).not_to be_valid
+    it 'returns a URN if namespace includes urn' do
+      expect(described_class.new('urn:urnnamespace:specificstring')).to be_kind_of(described_class)
+    end
+
+    it 'raises an error if it does not start with urn' do
+      expect { described_class.new('not-urn:namespace:specificstring') }.to raise_error(described_class::InvalidURNError)
+    end
+
+    it 'raises an error if namespace is urn' do
+      expect { described_class.new('urn:urn:specificstring') }.to raise_error(described_class::InvalidURNError)
+    end
+
+    it 'raises an error if namespace is URN' do
+      expect { described_class.new('urn:URN:specificstring') }.to raise_error(described_class::InvalidURNError)
     end
 
     it 'returns true if the namespace identifier is 32 characters long' do
       nid = 'a' * 32
 
-      expect(described_class.new("urn:#{nid}:bar")).to be_valid
+      expect(described_class.new("urn:#{nid}:bar")).to be_kind_of(described_class)
     end
 
-    it 'returns false if the namespace identifier begins with a hyphen' do
-      expect(described_class.new('urn:-foo:bar')).not_to be_valid
+    it 'raises an error if the namespace identifier begins with a hyphen' do
+      expect { described_class.new('urn:-foo:bar') }.to raise_error(described_class::InvalidURNError)
     end
 
-    it 'returns false if the namespace specific string has invalid escaping' do
-      expect(described_class.new('urn:foo:bar%2')).not_to be_valid
+    it 'raises an error if the namespace specific string has invalid escaping' do
+      expect { described_class.new('urn:foo:bar%2') }.to raise_error(described_class::InvalidURNError)
     end
 
-    it 'returns false if the namespace specific string has reserved characters' do
-      expect(described_class.new('urn:foo:café')).not_to be_valid
+    it 'raises an error if the namespace specific string has reserved characters' do
+      expect { described_class.new('urn:foo:café') }.to raise_error(described_class::InvalidURNError)
     end
-  end
 
-  describe '#normalize' do
-    it 'returns nil if it is not valid' do
-      expect(described_class.new('urn:').normalize).to be_nil
+    it 'raises an error if the namespace specific string has a not allowed hexadecimal value' do
+      expect { described_class.new('urn:foo:abc%10') }.to raise_error(described_class::InvalidURNError)
     end
+  end
 
+  describe '#normalize' do
     it 'lowercases the leading "urn:" token' do
-      expect(described_class.new('URN:foo:123').normalize).to eq('urn:foo:123')
+      expect(described_class.new('URN:foo:123').normalize.to_s).to eq('urn:foo:123')
     end
 
     it 'lowercases the namespace identifier' do
-      expect(described_class.new('urn:FOO:123').normalize).to eq('urn:foo:123')
+      expect(described_class.new('urn:FOO:123').normalize.to_s).to eq('urn:foo:123')
     end
 
     it 'lowercases %-escaping in the namespace specific string' do
-      expect(described_class.new('urn:foo:123%2C456').normalize).to eq('urn:foo:123%2c456')
+      expect(described_class.new('urn:foo:123%2C456').normalize.to_s).to eq('urn:foo:123%2c456')
     end
 
     it 'does not lowercase other characters in the namespace specific string' do
-      expect(described_class.new('urn:foo:BA%2CR').normalize).to eq('urn:foo:BA%2cR')
+      expect(described_class.new('urn:foo:BA%2CR').normalize.to_s).to eq('urn:foo:BA%2cR')
+    end
+  end
+
+  describe '#nid' do
+    it 'returns the namespace identifier' do
+      expect(described_class.new('urn:namespace:specificstring').nid).to eq('namespace')
+    end
+  end
+
+  describe '#nss' do
+    it 'returns the namespace specific string' do
+      expect(described_class.new('urn:namespace:specificstring').nss).to eq('specificstring')
+    end
+  end
+
+  describe '#to_s' do
+    it 'returns the string representation of the URN' do
+      expect(described_class.new('urn:Name:Spec').to_s).to eq('urn:Name:Spec')
+    end
+  end
+
+  describe '#===' do
+    it 'returns true if the string is an equivalent valid URN' do
+      expect(described_class.new('urn:name:spec') === 'URN:Name:spec').to be(true)
+    end
+
+    it 'returns true if the normalized object of the other class is equal' do
+      expect(described_class.new('urn:name:spec') === URI('urn:name:spec')).to be(true)
+    end
+
+    it 'returns true if the URN object is an equivalent valid URN' do
+      expect(described_class.new('urn:name:spec') === described_class.new('URN:Name:spec')).to be(true)
+    end
+
+    it 'returns false if the URN is not equivalent' do
+      expect(described_class.new('urn:name:spec') === described_class.new('URN:Name:SPEC')).to be(false)
+    end
+
+    it 'return false if the URN is not valid' do
+      expect(described_class.new('urn:name:spec') === 'urn:urn:urn').to be(false)
+    end
+  end
+
+  describe '#==' do
+    it 'returns true if the URN object is an equivalent valid URN' do
+      expect(described_class.new('urn:name:spec')).to eq(described_class.new('URN:Name:spec'))
+    end
+
+    it 'returns false if the argument is not a URN object' do
+      expect(described_class.new('urn:name:spec')).not_to eq('urn:name:spec')
+    end
+  end
+
+  describe '#eql?' do
+    it 'returns true if both URNs are equal' do
+      expect(described_class.new('urn:Name:Spec')).to eql(described_class.new('urn:Name:Spec'))
+    end
+
+    it 'returns false if the URNs are not equal' do
+      expect(described_class.new('urn:name:spec')).not_to eql(described_class.new('urn:Name:spec'))
+    end
+  end
+
+  describe '.extract' do
+    it 'extracts the URNs from a string' do
+      str = 'En un pueblo italiano urn:1234:abc al pie de la montaña URN:foo:bar%23.\\'
+
+      expect(URN.extract(str)).to contain_exactly('urn:1234:abc', 'URN:foo:bar%23.')
+    end
+
+    it 'extracts the URNs from a string using a block' do
+      str = 'Llum, foc, destrucció. urn:foo:%10 El món pot ser només una runa, URN:FOO:BA%2cR això no ho consentirem.'
+
+      normalized_urns = []
+      URN.extract(str) { |urn| normalized_urns << URN(urn).normalize.to_s }
+
+      expect(normalized_urns).to contain_exactly('urn:foo:BA%2cR')
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: urn
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Ana Castro
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-09 00:00:00.000000000 Z
+date: 2016-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler