uuid-ncname 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d17bfbafda1f25ed22fe1b314af7d9add89e66caa92a5f859fe399b81b4a1c63
-  data.tar.gz: 38372398d6460a72212023f6904c2eef6b5785461169f8ff7e1ff4248aa08ea2
+  metadata.gz: 95ef04d6f41f5d6b98fc5dbd814ef77d7b24e845b212a20fe73a79b2914d2cb0
+  data.tar.gz: ca0c34414228e1aba0b9d430d322bd8a62d533fcc93586a8735f7d64412aac24
 SHA512:
-  metadata.gz: c2f4d687ce200545784b6cd57417d182701faa805bb11e963184418284bc134b02e191a099026a63183aad8f089fd9eb140331fcd3915f33a1ea5e596e97836a
-  data.tar.gz: dcbd3afa99943709d07892fff109659dc567fbb3c7ab285cd5b9281894cb0477d984fd9ca0de12b778bd4d7125643299ce9ac61047fbd3a22ce35a91bb774722
+  metadata.gz: ba2311769361dc7646e354afdf58421e4b2e8f2f3e57780edb340dc9a45900958b793c5ac2bbe0fff124f364b922ff700a2867cbdd74108e7f31cc40255c431a
+  data.tar.gz: d0cfeb74e954dd45b0322771327f022040f8fbe22bebb47ef688b970e790b4d7966a8eb418c5fa8ee097b66d08fb73854355c71d255fb8c1c0d53fbc3b360f89

data/README.md

@@ -7,19 +7,17 @@ require 'uuidtools'
 uu = UUIDTools::UUID.random_create
 # => #<UUID:0x3fff0e597ef8 UUID:df521e0a-9d57-4f04-9a95-fc2888decc5a>
 
-# see below about this :version parameter
-
-nc64 = UUID::NCName.to_ncname uu, version: 1
+nc64 = UUID::NCName.to_ncname uu
 # => "E31IeCp1X8EqV_CiI3sxaJ"
 
-nc32 = UUID::NCName.to_ncname_32 uu, version: 1
+nc32 = UUID::NCName.to_ncname_32 uu
 # => "E35jb4cu5k7yevfp4fcen5tc2j"
 
-orig = UUID::NCName.from_ncname nc64, version: 1
+orig = UUID::NCName.from_ncname nc64
 # => "df521e0a-9d57-4f04-9a95-fc2888decc5a"
 
-orig == UUID::NCName.from_ncname nc32, version: 1 # => true
-orig == uu.to_s                                   # => true
+orig == UUID::NCName.from_ncname nc32 # => true
+orig == uu.to_s                       # => true
 
 # then you can turn it back into an object or whatever
 uu == UUIDTools::UUID.parse(orig)     # => true
@@ -27,69 +25,12 @@ uu == UUIDTools::UUID.parse(orig)     # => true
 
 ## Description
 
-The purpose of this module is to devise an alternative representation
+The purpose of this module is to [devise an alternative
+representation](https://datatracker.ietf.org/doc/html/draft-taylor-uuid-ncname)
 of the [UUID](http://tools.ietf.org/html/rfc4122) which conforms to
-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, as of 0.2.4, now defaults to `1`, the
-current one, but will still issue a warning if not explicitly
-set. Later I will finally remove the warning. 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 older, you should be running these methods with `version: 1`.
+the constraints of various other identifiers such as NCName, and
+create an [isomorphic](http://en.wikipedia.org/wiki/Isomorphism)
+mapping between them.
 
 ## Rationale & Method
 
@@ -198,6 +139,62 @@ representation should be adequate for placeholder symbols in just
 about any programming language, save for those which do not permit
 identifiers as long as 26 characters (which are extremely scarce).
 
+## _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`. This parameter, which controls the compact UUID spec
+behaviour, defaults to `1`, as of the _module_ version 0.2.4.
+
+> Unless you have to support identifiers generated from version 0.1.3
+> or older, you should be running these methods with `version: 1`.
+
 ## Documentation
 
 Generated and deposited

data/lib/uuid/ncname/version.rb

@@ -6,5 +6,5 @@ unless Module.const_defined? 'UUID'
 end
 
 module UUID::NCName
-  VERSION = "0.3.1"
+  VERSION = "0.4.1"
 end

data/lib/uuid/ncname.rb

@@ -61,8 +61,11 @@ module UUID::NCName
     },
     58 => -> (str, _) {
       variant = decode_version(str[-1]) << 4
+      # warn str
       str = str.chop.tr ?_, ''
-      ::Base58.base58_to_binary(str, :bitcoin) + variant.chr
+      # warn str
+      # warn ::Base58.base58_to_binary(str, :bitcoin).length
+      ::Base58.base58_to_binary(str, :bitcoin) + variant.chr.b
     },
     64 => -> (str, align = true) {
       str = str[0, 21] + 'A=='
@@ -77,6 +80,7 @@ module UUID::NCName
 
   FORMAT = {
     str: -> bin { UUF % bin.unpack('C*') },
+    urn: -> bin { "urn:uuid:#{UUF % bin.unpack('C*')}" },
     hex: -> bin { bin.unpack 'H*' },
     b64: -> bin { ::Base64.strict_encode64 bin },
     bin: -> bin { bin },
@@ -125,7 +129,10 @@ module UUID::NCName
       -> (version, data) {
         version &= 0xf
 
+        # warn data.length
+
         list = data.unpack 'N4'
+        # warn list.inspect
         variant = (list[3] & 0xf0) << 24
         list[3] >>= 8
         list[3] |= ((list[2] & 0xff) << 24)
@@ -148,6 +155,16 @@ module UUID::NCName
     (version.upcase.ord - 65) % 16
   end
 
+  def self.assert_version version
+    version = 1 unless version
+    raise ArgumentError, "version #{version.inspect} is not an integer" unless
+      version.respond_to? :to_i
+    version = version.to_i
+    raise ArgumentError, "there is no version #{version}" unless
+      TRANSFORM[version]
+    version
+  end
+
   def self.warn_version version
     if version.nil?
       warn 'Set an explicit :version to remove this warning. See documentation.'
@@ -194,10 +211,8 @@ module UUID::NCName
   #
   # @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 for the time
-  #  being if you do not set this parameter explicitly. The default
-  #  version is 1.
-  # 
+  #  to the end of the identifier. The default version is 1.
+  #
   # @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
@@ -209,7 +224,7 @@ module UUID::NCName
   #  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, version: nil, align: true
@@ -220,7 +235,8 @@ module UUID::NCName
     align = !!align # coerce to a boolean
 
     # XXX remove this when appropriate
-    version = warn_version(version)
+    # version = warn_version(version)
+    version = assert_version version
 
     uuid = uuid.to_s
     bin  = nil
@@ -228,7 +244,7 @@ module UUID::NCName
     if uuid.length == 16
       bin = uuid
     else
-      uuid.gsub!(/\s+/, '')
+      uuid = uuid.gsub(/\s+/, '')
       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))
@@ -253,14 +269,15 @@ module UUID::NCName
   #
   # @param ncname [#to_s] an NCName-encoded UUID, either a
   #  22-character (Base64) variant, or a 26-character (Base32) variant.
-  # 
-  # @param radix [nil, 32, 64] Optional radix; will use heuristic if omitted.
   #
-  # @param format [:str, :hex, :b64, :bin] An optional formatting
+  # @param radix [nil, 32, 58, 64] Optional radix; will use a heuristic
+  #  if omitted.
+  #
+  # @param format [:str, :urn, :hex, :b64, :bin] An optional formatting
   #  parameter; defaults to `:str`, the canonical string representation.
   #
   # @param version [0, 1] See ::to_ncname. Defaults to 1.
-  # 
+  #
   # @param align [nil, true, false] See ::to_ncname for details.
   #  Setting this parameter to `nil`, the default, will cause the
   #  decoder to detect the alignment state from the identifier.
@@ -279,7 +296,8 @@ module UUID::NCName
       [true, false, nil].include? align
 
     # XXX remove this when appropriate
-    version = warn_version version
+    # version = warn_version version
+    version = assert_version version
 
     return unless ncname and ncname.respond_to? :to_s
 
@@ -317,9 +335,9 @@ 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
@@ -333,24 +351,25 @@ module UUID::NCName
   # @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, version: nil, align: nil
-    from_ncname ncname, radix: 64, format: format
+    from_ncname ncname,
+      radix: 64, format: format, version: version, align: align
   end
 
   # Shorthand for conversion to the Base58 version
   #
   # @param uuid [#to_s] The UUID
-  # 
+  #
   # @param version [0, 1] See ::to_ncname.
-  # 
+  #
   # @param align [true, false] See ::to_ncname.
   #
   # @return [String] The Base58-encoded NCName
@@ -364,24 +383,25 @@ module UUID::NCName
   # @param ncname [#to_s] The Base58 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_58 ncname, format: :str, version: nil, align: nil
-    from_ncname ncname, radix: 58, format: format
+    from_ncname ncname,
+      radix: 58, format: format, version: version, align: align
   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
@@ -395,16 +415,17 @@ module UUID::NCName
   # @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, version: nil, align: nil
-    from_ncname ncname, radix: 32, format: format
+    from_ncname ncname,
+      radix: 32, format: format, version: version, align: align
   end
 
   # Test if the given token is a UUID NCName, with a hint to its
@@ -430,7 +451,7 @@ module UUID::NCName
       # false is definitely version zero but true is only maybe version 1
       version = /^(?:.{21}[I-L]|.{25}[I-Li-l])$/.match(token) ? 1 : 0
 
-      # try decoding with validation on 
+      # try decoding with validation on
       uu = from_ncname token, version: version, validate: true
 
       # note that version 1 will always return something because the

data/maint/generate-csv.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'uuid-ncname'
+require 'csv'
+require 'pathname'
+require 'uuidtools'
+
+out = Pathname(ARGV.first).expand_path
+
+CSV.open(out, 'wb') do |csv|
+  uuids = []
+  1000.times { uuids << UUIDTools::UUID.random_create }
+
+  # do the version first
+  (0..1).each do |v|
+    # then he radices
+    uuids.each do |u|
+      row = [v, u.to_s]
+
+      [32, 58, 64].each do |r|
+        row << UUID::NCName.to_ncname(u, radix: r, version: v)
+      end
+
+      csv << row
+    end
+  end
+end
+