uuid-ncname 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fc4b7e3db6125831483cce9cc94ff07241e7087163160d74b5b68bfada42745
-  data.tar.gz: b82352826f8c74f755df56e07c77af3d807cb886e2c8e72807c2bc38ef5cce88
+  metadata.gz: 709119ee194cd0d230580aa34906af6ffcf2ff1d271ec431396d5ab8395a150b
+  data.tar.gz: e21a0cdd45a3d905c85d20469b63f0978a154bd8e7e791b2780b575c8e8a994f
 SHA512:
-  metadata.gz: d8def5dba926479acf58efbb8f6c227fdb34b2b3ee375b027a189a318089114b981430d77b2cb855d1c67d42984fdd0a75c406287aa699c02f5ece9cd477694c
-  data.tar.gz: 0b41190f230d497c58696feb317f18deb6ca22d1a9995fd10feb4fd3e38d81417b3d15293fe0ce1991189ebc762364b6b2fe4924063921bfa1730c8df3834aa3
+  metadata.gz: 7885b27a99f48e644a1f4152bdd8919e9dacac8a3109c466d8b87ba61d4934aa1761f381c17563c7c228083ec9ede908154c16572f5291f05f5b3c87d8977875
+  data.tar.gz: f2c6b86bfc74481ba896fa6e8504c7f6f312ab39831775e92465d7f0b09cd3087950ba768e0828d4a8e24e69cb43caf71e70b0125dc420475bf053abf31eba79

data/README.md

@@ -28,6 +28,65 @@ the constraints of various other identifiers such as NCName, and create an
 [isomorphic](http://en.wikipedia.org/wiki/Isomorphism) mapping between
 them.
 
+## _FORMAT DEPRECATION NOTICE_
+
+After careful consideration, I have decided to change the UUID-NCName
+format in a minor yet incompatible way. In particular, I have moved
+the nybble containing
+the [`variant`](https://tools.ietf.org/html/rfc4122#section-4.1.1) to
+the very end of the identifier, whereas it previously was mixed into
+the middle somewhere.
+
+This can be considered an application
+of [Postel's Law](https://en.wikipedia.org/wiki/Postel%27s_law), based
+on the assumption that these identifiers will be generated through
+other methods, and potentially naïvely. Like the `version` field, the
+`variant` field has a limited acceptable range of values. If, for
+example, one were to attempt to generate a conforming identifier by
+simply generating a random Base32 or Base64 string, it will be
+difficult to ensure that the `variant` field will indeed conform when
+the identifier is converted to a standard UUID. By moving the
+`variant` field out to the end of the identifier, everything between
+the `version` and `variant` bookends can be generated randomly without
+any further consideration, like so:
+
+```ruby
+B64_ALPHA = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a + %w(- _)
+
+def make_cheapo_b64_uuid_ncname
+  vals = (1..20).map { rand 64 }               # generate the content
+  vals.push(rand(4) + 8)                       # last digit is special
+  'E' + vals.map { |v| B64_ALPHA[v] }.join('') # 'E' for UUID v4
+end
+
+# voilà:
+
+cheap = make_cheapo_b64_uuid_ncname
+# => "EXSVv8ezPbSKWoKOkBNWKL"
+
+# now try changing it to a standard UUID:
+
+UUID::NCName.from_ncname cheap, version: 1
+# => "5d256ff1-eccf-46d2-b296-a0a3a404d58a"
+```
+
+Furthermore, since the default behaviour is to align the bits of the
+last byte to the size of the encoding symbol, and since the `variant`
+bits are masked, a compliant RFC4122 UUID will _always_ end with `I`,
+`J`, `K`, or `L`, in _both_ Base32 (case-insensitive) and Base64
+variants.
+
+Since I have already released this gem prior to this format change, I
+have added a `:version` parameter to both `to_ncname` and
+`from_ncname`. The version currently defaults to `0`, the old one, but
+will issue a warning if not explicitly set. Later I will change the
+default to `1`, while keeping the warning, then later still, finally
+remove the warning with 1 as the default. This should ensure that any
+code written during the transition produces the correct results.
+
+> Unless you have to support identifiers generated from version 0.1.3
+> or newer, you should be running these methods with `version: 1`.
+
 ## Rationale & Method
 
 The UUID is a generic identifier which is large enough to be globally

data/lib/uuid/ncname.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 require "uuid/ncname/version"
 
 require 'base64'
@@ -8,34 +9,42 @@ module UUID::NCName
   private
 
   ENCODE = {
-    32 => -> bin {
-      bin = bin.unpack 'C*'
-      bin[-1] >>= 1
-      out = ::Base32.encode bin.pack('C*')
+    32 => -> (bin, align = true) {
+      if align
+        bin = bin.unpack 'C*'
+        bin[-1] >>= 1
+        bin = bin.pack 'C*'
+      end
+
+      out = ::Base32.encode bin
 
       out.downcase[0, 25]
     },
-    64 => -> bin {
-      bin = bin.unpack 'C*'
-      bin[-1] >>= 2
-      out = ::Base64.urlsafe_encode64 bin.pack('C*')
+    64 => -> (bin, align = true) {
+      if align
+        bin = bin.unpack 'C*'
+        bin[-1] >>= 2
+        bin = bin.pack 'C*'
+      end
+
+      out = ::Base64.urlsafe_encode64 bin
 
       out[0, 21]
     },
   }
 
   DECODE = {
-    32 => -> str {
+    32 => -> (str, align = true) {
       str = str.upcase[0, 25] + 'A======'
       out = ::Base32.decode(str).unpack 'C*'
-      out[-1] <<= 1
+      out[-1] <<= 1 if align
 
       out.pack 'C*'
     },
-    64 => -> str {
+    64 => -> (str, align = true) {
       str = str[0, 21] + 'A=='
       out = ::Base64.urlsafe_decode64(str).unpack 'C*'
-      out[-1] <<= 2
+      out[-1] <<= 2 if align
 
       out.pack 'C*'
     },
@@ -50,30 +59,62 @@ module UUID::NCName
     bin: -> bin { bin },
   }
 
-  def self.bin_uuid_to_pair data
-    list = data.unpack 'N4'
-    version = (list[1] & 0x0000f000) >> 12
-    list[1] = (list[1] & 0xffff0000) |
-      ((list[1] & 0x00000fff) << 4) | (list[2] >> 28)
-    list[2] = (list[2] & 0x0fffffff) << 4 | (list[3] >> 28)
-    list[3] <<= 4
-
-    return version, list.pack('N4')
-  end
-
-  def self.pair_to_bin_uuid version, data
-    version &= 0xf
-
-    list = data.unpack 'N4'
-    list[3] >>= 4
-    list[3] |= ((list[2] & 0xf) << 28)
-    list[2] >>= 4
-    list[2] |= ((list[1] & 0xf) << 28)
-    list[1] = (
-      list[1] & 0xffff0000) | (version << 12) | ((list[1] >> 4) & 0xfff)
-
-    list.pack 'N4'
-  end
+  TRANSFORM = [
+    # old version prior to shifting out the variant nybble
+    [
+      -> data {
+        list = data.unpack 'N4'
+        version = (list[1] & 0x0000f000) >> 12
+        list[1] = (list[1] & 0xffff0000) |
+          ((list[1] & 0x00000fff) << 4) | (list[2] >> 28)
+        list[2] = (list[2] & 0x0fffffff) << 4 | (list[3] >> 28)
+        list[3] <<= 4
+
+        return version, list.pack('N4')
+      },
+      -> (version, data) {
+        version &= 0xf
+
+        list = data.unpack 'N4'
+        list[3] >>= 4
+        list[3] |= ((list[2] & 0xf) << 28)
+        list[2] >>= 4
+        list[2] |= ((list[1] & 0xf) << 28)
+        list[1] = (
+          list[1] & 0xffff0000) | (version << 12) | ((list[1] >> 4) & 0xfff)
+
+        list.pack 'N4'
+      },
+    ],
+    # current version
+    [
+      -> data {
+        list = data.unpack 'N4'
+        version = (list[1] & 0x0000f000) >> 12
+        variant = (list[2] & 0xf0000000) >> 24
+        list[1] = (list[1] & 0xffff0000) |
+          ((list[1] & 0x00000fff) << 4) | ((list[2] & 0x0fffffff) >> 24)
+        list[2] = (list[2] & 0x00ffffff) << 8 | (list[3] >> 24)
+        list[3] = (list[3] << 8) | variant
+
+        return version, list.pack('N4')
+      },
+      -> (version, data) {
+        version &= 0xf
+
+        list = data.unpack 'N4'
+        variant = (list[3] & 0xf0) << 24
+        list[3] >>= 8
+        list[3] |= ((list[2] & 0xff) << 24)
+        list[2] >>= 8
+        list[2] |= ((list[1] & 0xf) << 24) | variant
+        list[1] = (
+          list[1] & 0xffff0000) | (version << 12) | ((list[1] >> 4) & 0xfff)
+
+        list.pack 'N4'
+      },
+    ],
+  ]
 
   def self.encode_version version
     ((version & 15) + 65).chr
@@ -83,6 +124,17 @@ module UUID::NCName
     (version.upcase.ord - 65) % 16
   end
 
+  def self.warn_version version
+    if version.nil?
+      warn 'Set an explicit :version to remove this warning. See documentation.'
+      version = 0
+    end
+
+    raise 'Version must be 0 or 1' unless [0, 1].include? version
+
+    version
+  end
+
   public
 
   # Converts a UUID (or object that when converted to a string looks
@@ -95,16 +147,36 @@ module UUID::NCName
   #
   # @param radix [32, 64] either the number 32 or the number 64.
   #
+  # @param version [0, 1] An optional formatting version, where 0 is
+  #  the naïve original version and 1 moves the `variant` nybble out
+  #  to the end of the identifier. You will be warned if you do not
+  #  set this parameter explicitly. The default is currently 0, but
+  #  will change in the next version.
+  # 
+  # @param align [true, false] Optional directive to treat the
+  #  terminating character as aligned to the numerical base of the
+  #  representation. Since the version nybble is removed from the
+  #  string and the first 120 bits divide evenly into both Base32 and
+  #  Base64, the overhang is only ever 4 bits. This means that when
+  #  the terminating character is aligned, it will always be in the
+  #  range of the letters A through P in (the RFC 3548/4648
+  #  representations of) both Base32 and Base64. When `version` is 1
+  #  and the terminating character is aligned, RFC4122-compliant UUIDs
+  #  will always terminate with I, J, K, or L. Defaults to `true`.
+  # 
   # @return [String] The NCName-formatted UUID.
 
-  def self.to_ncname uuid, radix: 64
+  def self.to_ncname uuid, radix: 64, version: nil, align: true
     raise 'Radix must be either 32 or 64' unless [32, 64].include? radix
     raise 'UUID must be something stringable' if uuid.nil? or
       not uuid.respond_to? :to_s
+    raise 'Align must be true or false' unless [true, false].include? align
 
-    uuid = uuid.to_s
+    # XXX remove this when appropriate
+    version = warn_version(version)
 
-    bin = nil
+    uuid = uuid.to_s
+    bin  = nil
 
     if uuid.length == 16
       bin = uuid
@@ -113,7 +185,7 @@ module UUID::NCName
       if (m = /^(?:urn:uuid:)?([0-9A-Fa-f-]{32,})$/.match(uuid))
         bin = [m[1].tr('-', '')].pack 'H*'
       elsif (m = /^([0-9A-Za-z+\/_-]+=*)$/.match(uuid))
-        match= m[1].tr('-_', '+/')
+        match = m[1].tr('-_', '+/')
         bin = ::Base64.decode64(match)
       else
         raise "Not sure what to do with #{uuid}"
@@ -123,9 +195,9 @@ module UUID::NCName
     raise 'Binary representation of UUID is shorter than 16 bytes' if
       bin.length < 16
 
-    version, content = bin_uuid_to_pair bin[0, 16]
+    uuidver, content = TRANSFORM[version][0].call bin[0, 16]
 
-    encode_version(version) + ENCODE[radix].call(content)
+    encode_version(uuidver) + ENCODE[radix].call(content, align)
   end
 
   # Converts an NCName-encoded UUID back to its canonical
@@ -139,13 +211,25 @@ module UUID::NCName
   #
   # @param format [:str, :hex, :b64, :bin] An optional formatting
   #  parameter; defaults to `:str`, the canonical string representation.
+  #
+  # @param version [0, 1] See `to_ncname`. Defaults (for now) to 0.
   # 
+  # @param align [true, false, nil] See `to_ncname` for details.
+  #  Setting this parameter to `nil`, the default, will cause the
+  #  decoder to detect the alignment state from the identifier.
+  #
   # @return [String, nil] The corresponding UUID or nil if the input
   #  is malformed.
 
-  def self.from_ncname ncname, radix: nil, format: :str
+  def self.from_ncname ncname,
+      radix: nil, format: :str, version: nil, align: nil
     raise 'Format must be symbol-able' unless format.respond_to? :to_sym
     raise "Invalid format #{format}" unless FORMAT[format]
+    raise 'Align must be true, false, or nil' unless
+      [true, false, nil].include? align
+
+    # XXX remove this when appropriate
+    version = warn_version version
 
     return unless ncname and ncname.respond_to? :to_s
 
@@ -170,11 +254,13 @@ module UUID::NCName
       end
     end
 
-    version, content = match.captures
-    version = decode_version version
-    content = DECODE[radix].call content
+    uuidver, content = match.captures
+
+    align   = !!(content =~ /[A-Pa-p]$/) if align.nil?
+    uuidver = decode_version uuidver
+    content = DECODE[radix].call content, align
 
-    bin = pair_to_bin_uuid version, content
+    bin = TRANSFORM[version][1].call uuidver, content
 
     FORMAT[format].call bin
   end
@@ -182,36 +268,62 @@ module UUID::NCName
   # Shorthand for conversion to the Base64 version
   #
   # @param uuid [#to_s] The UUID
+  # 
+  # @param version [0, 1] See `to_ncname`.
+  # 
+  # @param align [true, false] See `to_ncname`.
+  #
   # @return [String] The Base64-encoded NCName
 
-  def self.to_ncname_64 uuid
-    to_ncname uuid
+  def self.to_ncname_64 uuid, version: nil, align: true
+    to_ncname uuid, version: version, align: align
   end
 
   # Shorthand for conversion from the Base64 version
   #
   # @param ncname [#to_s] The Base64 variant of the NCName-encoded UUID
+  #
   # @param format [:str, :hex, :b64, :bin] The format
+  # 
+  # @param version [0, 1] See `to_ncname`.
+  # 
+  # @param align [true, false] See `to_ncname`.
+  #
+  # @return [String, nil] The corresponding UUID or nil if the input
+  #  is malformed.
 
-  def self.from_ncname_64 ncname, format: :str
+  def self.from_ncname_64 ncname, format: :str, version: nil, align: nil
     from_ncname ncname, radix: 64, format: format
   end
 
   # Shorthand for conversion to the Base32 version
   #
   # @param uuid [#to_s] The UUID
+  # 
+  # @param version [0, 1] See `to_ncname`.
+  # 
+  # @param align [true, false] See `to_ncname`.
+  #
   # @return [String] The Base32-encoded NCName
 
-  def self.to_ncname_32 uuid
-    to_ncname uuid, radix: 32
+  def self.to_ncname_32 uuid, version: nil, align: true
+    to_ncname uuid, radix: 32, version: version, align: align
   end
 
   # Shorthand for conversion from the Base32 version
   #
   # @param ncname [#to_s] The Base32 variant of the NCName-encoded UUID
+  #
   # @param format [:str, :hex, :b64, :bin] The format
+  # 
+  # @param version [0, 1] See `to_ncname`.
+  # 
+  # @param align [true, false] See `to_ncname`.
+  #
+  # @return [String, nil] The corresponding UUID or nil if the input
+  #  is malformed.
 
-  def self.from_ncname_32 ncname, format: :str
+  def self.from_ncname_32 ncname, format: :str, version: nil, align: nil
     from_ncname ncname, radix: 32, format: format
   end
 

data/lib/uuid/ncname/version.rb

@@ -3,5 +3,5 @@ unless Module.const_defined? 'UUID'
 end
 
 module UUID::NCName
-    VERSION = "0.1.3"
+    VERSION = "0.2.0"
 end

data/uuid-ncname.gemspec

@@ -26,6 +26,9 @@ DESC
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  # we use named parameters
+  spec.required_ruby_version = '~> 2.0'
+
   # surprisingly do not need this
   # spec.add_runtime_dependency 'uuidtools', '~> 2.1.5'
   spec.add_runtime_dependency 'base32',    '~> 0.3.2'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uuid-ncname
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Dorian Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-10 00:00:00.000000000 Z
+date: 2018-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -101,9 +101,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="