gabe-uuid 0.3

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Gabriel Boyer
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,13 @@
+UUID
+====
+
+A simple library for generating/using Universally Unique Identifiers, as defined
+in RFC 4122 (http://www.ietf.org/rfc/rfc4122.txt).
+
+This library generates version 4 UUIDs, which are based on random bytes read from
+SecureRandom (included for Ruby <1.8.7).
+
+Author
+------
+
+Gabriel Boyer (gboyer@gmail.com)

data/Rakefile

@@ -0,0 +1,30 @@
+require "rake/gempackagetask"
+require "spec/rake/spectask"
+
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("spec") do |task|
+  task.spec_opts = ["--format", "specdoc", "--colour"]
+  task.spec_files = ["spec/**/*_spec.rb"]
+end
+
+spec = Gem::Specification.new do |s|
+  s.name         = 'uuid'
+  s.version      = '0.3'
+  s.platform     = Gem::Platform::RUBY
+  s.author       = 'Gabriel Boyer'
+  s.email        = 'gboyer@gmail.com'
+  s.homepage     = 'http://github.com/gabe/uuid/'
+  s.summary      = 'Simple UUID implementation'
+  s.description  = 'Simple UUID implementation, as per RFC 4122'
+  s.require_path = "lib"
+  s.files        = %w[ LICENSE README.markdown Rakefile
+	                     spec/spec_helper.rb spec/uuid_spec.rb
+	                     lib/uuid.rb lib/compat/securerandom.rb ]
+  s.required_ruby_version = ">= 1.8.6"
+end
+ 
+Rake::GemPackageTask.new(spec) do |package|
+  package.gem_spec = spec
+end

data/lib/compat/securerandom.rb

@@ -0,0 +1,182 @@
+# = Secure random number generator interface.
+#
+# This library is an interface for secure random number generator which is
+# suitable for generating session key in HTTP cookies, etc.
+#
+# It supports following secure random number generators.
+#
+# * openssl
+# * /dev/urandom
+# * Win32
+#
+# == Example
+#
+# # random hexadecimal string.
+# p SecureRandom.hex(10) #=> "52750b30ffbc7de3b362"
+# p SecureRandom.hex(10) #=> "92b15d6c8dc4beb5f559"
+# p SecureRandom.hex(11) #=> "6aca1b5c58e4863e6b81b8"
+# p SecureRandom.hex(12) #=> "94b2fff3e7fd9b9c391a2306"
+# p SecureRandom.hex(13) #=> "39b290146bea6ce975c37cfc23"
+# ...
+#
+# # random base64 string.
+# p SecureRandom.base64(10) #=> "EcmTPZwWRAozdA=="
+# p SecureRandom.base64(10) #=> "9b0nsevdwNuM/w=="
+# p SecureRandom.base64(10) #=> "KO1nIU+p9DKxGg=="
+# p SecureRandom.base64(11) #=> "l7XEiFja+8EKEtY="
+# p SecureRandom.base64(12) #=> "7kJSM/MzBJI+75j8"
+# p SecureRandom.base64(13) #=> "vKLJ0tXBHqQOuIcSIg=="
+# ...
+#
+# # random binary string.
+# p SecureRandom.random_bytes(10) #=> "\016\t{\370g\310pbr\301"
+# p SecureRandom.random_bytes(10) #=> "\323U\030TO\234\357\020\a\337"
+# ...
+
+begin
+  require 'openssl'
+rescue LoadError
+end
+
+module SecureRandom
+  # SecureRandom.random_bytes generates a random binary string.
+  #
+  # The argument n specifies the length of the result string.
+  #
+  # If n is not specified, 16 is assumed.
+  # It may be larger in future.
+  #
+  # If secure random number generator is not available,
+  # NotImplementedError is raised.
+  def self.random_bytes(n=nil)
+    n ||= 16
+
+    if defined? OpenSSL::Random
+      return OpenSSL::Random.random_bytes(n)
+    end
+
+    if !defined?(@has_urandom) || @has_urandom
+      flags = File::RDONLY
+      flags |= File::NONBLOCK if defined? File::NONBLOCK
+      flags |= File::NOCTTY if defined? File::NOCTTY
+      flags |= File::NOFOLLOW if defined? File::NOFOLLOW
+      begin
+        File.open("/dev/urandom", flags) {|f|
+          unless f.stat.chardev?
+            raise Errno::ENOENT
+          end
+          @has_urandom = true
+          ret = f.readpartial(n)
+          if ret.length != n
+            raise NotImplementedError, "Unexpected partial read from random device"
+          end
+          return ret
+        }
+      rescue Errno::ENOENT
+        @has_urandom = false
+      end
+    end
+
+    if !defined?(@has_win32)
+      begin
+        require 'Win32API'
+
+        crypt_acquire_context = Win32API.new("advapi32", "CryptAcquireContext", 'PPPII', 'L')
+        @crypt_gen_random = Win32API.new("advapi32", "CryptGenRandom", 'LIP', 'L')
+
+        hProvStr = " " * 4
+        prov_rsa_full = 1
+        crypt_verifycontext = 0xF0000000
+
+        if crypt_acquire_context.call(hProvStr, nil, nil, prov_rsa_full, crypt_verifycontext) == 0
+          raise SystemCallError, "CryptAcquireContext failed: #{lastWin32ErrorMessage}"
+        end
+        @hProv, = hProvStr.unpack('L')
+
+        @has_win32 = true
+      rescue LoadError
+        @has_win32 = false
+      end
+    end
+    if @has_win32
+      bytes = " " * n
+      if @crypt_gen_random.call(@hProv, bytes.size, bytes) == 0
+        raise SystemCallError, "CryptGenRandom failed: #{lastWin32ErrorMessage}"
+      end
+      return bytes
+    end
+
+    raise NotImplementedError, "No random device"
+  end
+
+  # SecureRandom.hex generates a random hex string.
+  #
+  # The argument n specifies the length of the random length.
+  # The length of the result string is twice of n.
+  #
+  # If n is not specified, 16 is assumed.
+  # It may be larger in future.
+  #
+  # If secure random number generator is not available,
+  # NotImplementedError is raised.
+  def self.hex(n=nil)
+    random_bytes(n).unpack("H*")[0]
+  end
+
+  # SecureRandom.base64 generates a random base64 string.
+  #
+  # The argument n specifies the length of the random length.
+  # The length of the result string is about 4/3 of n.
+  #
+  # If n is not specified, 16 is assumed.
+  # It may be larger in future.
+  #
+  # If secure random number generator is not available,
+  # NotImplementedError is raised.
+  def self.base64(n=nil)
+    [random_bytes(n)].pack("m*").delete("\n")
+  end
+
+  # SecureRandom.random_number generates a random number.
+  #
+  # If an positive integer is given as n,
+  # SecureRandom.random_number returns an integer:
+  # 0 <= SecureRandom.random_number(n) < n.
+  #
+  # If 0 is given or an argument is not given,
+  # SecureRandom.random_number returns an float:
+  # 0.0 <= SecureRandom.random_number() < 1.0.
+  def self.random_number(n=0)
+    if 0 < n
+      hex = n.to_s(16)
+      hex = '0' + hex if (hex.length & 1) == 1
+      bin = [hex].pack("H*")
+      mask = bin[0].ord
+      mask |= mask >> 1
+      mask |= mask >> 2
+      mask |= mask >> 4
+      begin
+        rnd = SecureRandom.random_bytes(bin.length)
+        rnd[0] = (rnd[0].ord & mask).chr
+      end until rnd < bin
+      rnd.unpack("H*")[0].hex
+    else
+      # assumption: Float::MANT_DIG <= 64
+      i64 = SecureRandom.random_bytes(8).unpack("Q")[0]
+      Math.ldexp(i64 >> (64-Float::MANT_DIG), -Float::MANT_DIG)
+    end
+  end
+
+  # Following code is based on David Garamond's GUID library for Ruby.
+  def self.lastWin32ErrorMessage # :nodoc:
+    get_last_error = Win32API.new("kernel32", "GetLastError", '', 'L')
+    format_message = Win32API.new("kernel32", "FormatMessageA", 'LPLLPLPPPPPPPP', 'L')
+    format_message_ignore_inserts = 0x00000200
+    format_message_from_system    = 0x00001000
+
+    code = get_last_error.call
+    msg = "\0" * 1024
+    len = format_message.call(format_message_ignore_inserts + format_message_from_system, 0, code, 0, msg, 1024, nil, nil, nil, nil, nil, nil, nil, nil)
+    msg[0, len].tr("\r", '').chomp
+  end
+end

data/lib/uuid.rb

@@ -0,0 +1,128 @@
+begin
+  require 'securerandom'
+rescue LoadError
+  require File.join(File.dirname(__FILE__), 'compat', 'securerandom')
+end
+
+class UUID
+  def initialize(value = nil)
+    @value = Integer(value)
+    unless (@value >= 0) && (@value < (1 << 128))
+      raise RangeError, "#{value} (Integer value #{@value}) is out of range (need unsigned 128-bit value)"
+    end
+  end
+  
+  def ==(other)
+    eql?(other)
+  end
+  
+  def clock_seq
+    ((clock_seq_hi_variant & 0x3f) << 8) | clock_seq_low
+  end
+  
+  def clock_seq_hi_variant
+    (to_i >> 56) & 0xff
+  end
+  
+  def clock_seq_low
+    (to_i >> 48) & 0xff
+  end
+  
+  def eql?(other)
+    other.is_a?(self.class) && (other.to_i == to_i)
+  end
+  
+  def hash
+    to_i.hash
+  end
+  
+  def hex
+    '%032x' % to_i
+  end
+  
+  def inspect
+    to_s
+  end
+  
+  def node
+    to_i & 0xffffffffffff
+  end
+  
+  def time
+    ((time_hi_version & 0x0fff) << 48) | (time_mid << 32) | time_low
+  end
+  
+  def time_hi_version
+    (to_i >> 64) & 0xffff
+  end
+  
+  def time_low
+    (to_i >> 96)
+  end
+  
+  def time_mid
+    (to_i >> 80) & 0xffff
+  end
+  
+  def to_i
+    @value
+  end
+  
+  def to_s
+    h = hex
+    '%s-%s-%s-%s-%s' % [h[0...8], h[8...12], h[12...16], h[16...20], h[20...32]]
+  end
+  
+  def urn
+    "urn:uuid:#{self}"
+  end
+  
+  RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, RESERVED_FUTURE = [
+    'reserved for NCS compatibility',
+    'specified in RFC 4122',
+    'reserved for Microsoft compatibility',
+    'reserved for future definition'
+  ]
+  
+  def variant
+    case 0
+    when to_i & (0x8000 << 48)
+      RESERVED_NCS
+    when to_i & (0x4000 << 48)
+      RFC_4122
+    when to_i & (0x2000 << 48)
+      RESERVED_MICROSOFT
+    else
+      RESERVED_FUTURE
+    end
+  end
+  
+  def version
+    (variant == RFC_4122) ? ((to_i >> 76) & 0xf) : nil
+  end
+  
+  class << self
+    def parse(uuid)
+      str = uuid.to_s
+      unless str =~ /^(urn:uuid:)?[0-9a-fA-F]{8}((-)?[0-9a-fA-F]{4}){3}(-)?[0-9a-fA-F]{12}$/
+        raise ArgumentError, "#{str} is not a recognized UUID representation"
+      end
+      new bytes_to_i(str.gsub(/(^urn:uuid:|-)/, '').downcase.unpack('a2' * 16).collect { |x| x.to_i(16) }.pack('C*'))
+    end
+    
+    def uuid4
+      bytes = SecureRandom.random_bytes(16)
+      bytes[6] = (bytes[6] & 0x0f) | 0x40
+      bytes[8] = (bytes[8] & 0x3f) | 0x80
+      new bytes_to_i(bytes)
+    end
+    
+    private
+    
+    def bytes_to_i(bytes)
+      bytes.unpack('C*').inject { |value, i| value * 256 | i }
+    end
+  end
+end
+
+UUID::Nil = UUID.new(0)

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'rubygems'
+require 'spec'
+require 'uuid'

data/spec/uuid_spec.rb

@@ -0,0 +1,87 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe UUID, '.uuid4' do
+  it 'generates a new UUID' do
+    UUID.uuid4.should be_a_kind_of(UUID)
+    UUID.uuid4.should_not == UUID.new
+  end
+  
+  it 'generates version 4 UUIDs' do
+    UUID.uuid4.to_s.should =~ /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/
+    UUID.uuid4.version.should == 4
+  end
+  
+  it 'generates UUIDs of the RFC 4122 variant' do
+    UUID.uuid4.variant.should == UUID::RFC_4122
+  end
+end
+
+describe UUID, '.parse' do
+  it 'creates a UUID from a valid string representation when passed one' do
+    id = UUID.uuid4
+    [id.to_s, id.hex, id.urn].each do |s|
+      UUID.parse(s).should == id
+    end
+    UUID.parse(UUID::Nil.to_s).should == UUID::Nil
+  end
+  
+  it 'raises an ArgumentError when passed a string it cannot parse into a UUID' do
+    lambda { UUID.parse '<garbage>' }.should raise_error(ArgumentError)
+  end
+end
+
+describe UUID, '#initialize' do
+  it 'creates a UUID from an Integer when passed one that is within range for a UUID' do
+    id = UUID.uuid4
+    UUID.new(id.to_i).should == id
+    UUID.new(0).should == UUID::Nil
+  end
+
+  it 'raises an ArgumentError when passed a parameter that cannot be coerced into an Integer' do
+    lambda { UUID.new '<garbage>' }.should raise_error(ArgumentError)
+  end
+
+  it 'raises a RangeError when passed an Integer that is out of range for a UUID' do
+    lambda { UUID.new -1 }.should raise_error(RangeError)
+    lambda { UUID.new(1 << 128) }.should raise_error(RangeError)
+  end
+end
+
+describe UUID, '#to_i' do
+  it 'returns an unsigned integer representation of the UUID' do
+    i = UUID.uuid4.to_i
+    i.should be_a_kind_of(Integer)
+    i.should >= 0
+    i.should < (1 << 128)
+  end
+end
+
+delimited_hex_format = /[0-9a-fA-F]{8}(-[0-9a-fA-F]{4}){3}-[0-9a-fA-F]{12}/
+
+describe UUID, '#to_s' do
+  it 'returns a UUID string in delimited hex format (i.e., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)' do
+    UUID.new.to_s.should =~ /^#{delimited_hex_format}$/
+  end
+end
+
+describe UUID, '#hex' do
+  it 'returns a UUID string in undelimited hex format (i.e., xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx)' do
+    UUID.new.hex.should =~ /^[0-9a-fA-F]{8}([0-9a-fA-F]{4}){3}[0-9a-fA-F]{12}$/
+  end
+end
+
+describe UUID, '#urn' do
+  it 'returns a UUID string in delimited hex format with a urn prefix (i.e., urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)' do
+    UUID.new.urn.should =~ /^urn:uuid:#{delimited_hex_format}$/
+  end
+end
+
+describe 'UUID::Nil' do
+  it 'has a string representation (#to_s) of 00000000-0000-0000-0000-000000000000' do
+    UUID::Nil.to_s.should == '00000000-0000-0000-0000-000000000000'
+  end
+  
+  it 'has an integer value (#to_i) of 0' do
+    UUID::Nil.to_i.should == 0
+  end
+end

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification 
+name: gabe-uuid
+version: !ruby/object:Gem::Version 
+  version: "0.3"
+platform: ruby
+authors: 
+- Gabriel Boyer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-13 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Simple UUID implementation, as per RFC 4122
+email: gboyer@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.markdown
+- Rakefile
+- spec/spec_helper.rb
+- spec/uuid_spec.rb
+- lib/uuid.rb
+- lib/compat/securerandom.rb
+has_rdoc: false
+homepage: http://github.com/gabe/uuid/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Simple UUID implementation
+test_files: []
+