URN

Ruby library to validate and normalize URNs according to RFC 2141.

Supported Ruby versions: >= 2.3

Installation

Add this line to your application's Gemfile:

gem 'urn', '~> 2.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install urn -v '~> 2.0'

Usage

urn = URN('URN:NameSpace:Identifier')
#=> #<URN:0x007fd97a835558 @urn="URN:NameSpace:Identifier">

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

text.match(/\?urn=(#{URN::PATTERN})/)

Return a String of an unanchored regular expression suitable for matching URNs.

URN::REGEX

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

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. Otherwise, it raises an URN::InvalidURNError

URN#normalize

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#nid

URN('urn:nid:nss').nid
#=> "nid"

Return the namespace identifier part.

URN#nss

URN('urn:nid:nss').nss
#=> "nss"

Return the namespace specific string part.

URN#to_s

URN('urn:Nid:Nss').to_s
#=> "urn:Nid:Nss"

Return the String representation.

#===(other)

URN('urn:name:spec') === 'URN:Name:spec'
#=> true

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.

#==(other)

URN('urn:name:spec') == 'URN:Name:spec'
#=> false

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)

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.

.extract(str)

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

Bug reports and pull requests are welcome on GitHub at https://github.com/altmetric/urn.

License

Copyright © 2016-2024 Altmetric LLP

Distributed under the MIT License.