Global Names UUID

DOI Gem Version Continuous Integration Status Coverage Status CodeClimate Dependency Status

Gem gn_uuid creates UUID version 5 out of scientific name string. It uses globalnames.org domain for DNS namespace. There is a 1:1 relationship between the string and the corresponding UUID, so it allows globally connect data about a name string originated from independent sources without a need to negotiate identifiers. You can find more information about UUID v5 from the original RFC4122 document.

Installation

Add this line to your application's Gemfile:

gem 'gn_uuid'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gn_uuid

Usage

GnUUID.uuid(string, guid = true)

Parameter Type Description
str String Scientific Name String
guid Boolean true returns a String guid, false -- UUID object; default true
require "gn_uuid"

uuid = GnUUID.uuid("Homo sapiens")
# output: 16f235a0-e4a3-529c-9b83-bd15fe722110

If you plan to convert uuid into its other formats use

uuid = GnUUID.uuid("Homo sapiens", false)
# output: urn:uuid:b33e4b19-2399-56c8-9dd3-eff79f221d2f

# as a 'stanard guid'
uuid.to_s
# output: b33e4b19-2399-56c8-9dd3-eff79f221d2f

# as an decimal integer
uuid.to_i
# output: 30500639462008600581628158843502600464

# as an URI
uuid.to_uri
uuid.inspect (alias_method for to_uri)
# output: urn:uuid:b33e4b19-2399-56c8-9dd3-eff79f221d2f


# as a 16-bytes string
uuid.bytes
# output: "\x16\xF25\xA0\xE4\xA3R\x9C\x9B\x83\xBD\x15\xFEr!\x10"

# return UUID version
uuid.version
# output: 5

Please note that the internal GnUUID::UUID does not have to be of the version 5, but GnUUID.uuid generates only version 5 UUIDs

GnUUID.parse(uuid)

Takes a uuid string like "b33e4b19-2399-56c8-9dd3-eff79f221d2f" and returns an instance of GnUUID::UUID class. It can parse any UUID, not only version 5

uuid = GnUUID.parse("b33e4b19-2399-56c8-9dd3-eff79f221d2f")
uuid.inspect
# output: urn:uuid:b33e4b19-2399-56c8-9dd3-eff79f221d2f

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

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

Acknowledgement

This gem heavily borrowed ideas and code from Urabe Shyouhei's ruby-uuid gem

The gem is available as open source under the terms of the MIT License.

Author -- Dmitry Mozzherin

Copyright (c) 2015 Marine Biological Laboratory.