uuid-ncname 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d17bfbafda1f25ed22fe1b314af7d9add89e66caa92a5f859fe399b81b4a1c63
-  data.tar.gz: 38372398d6460a72212023f6904c2eef6b5785461169f8ff7e1ff4248aa08ea2
+  metadata.gz: 471f6d4d6e5124454b7bcc1a7ab46fc3f6fbf6951f4ba988c80a9b04f0051be1
+  data.tar.gz: 03265d39a6f8b4c38ad9d86ddab9753563216c4ac3421a5cff9f38f1e536d4e1
 SHA512:
-  metadata.gz: c2f4d687ce200545784b6cd57417d182701faa805bb11e963184418284bc134b02e191a099026a63183aad8f089fd9eb140331fcd3915f33a1ea5e596e97836a
-  data.tar.gz: dcbd3afa99943709d07892fff109659dc567fbb3c7ab285cd5b9281894cb0477d984fd9ca0de12b778bd4d7125643299ce9ac61047fbd3a22ce35a91bb774722
+  metadata.gz: 311e0f9856467d875782d37ac759ec2479d74276ad2ec427588954ab22335e233d69f2d32e6ceaf20a24e91eba8a2cd780721f89f5a829c7acf346ab78b20401
+  data.tar.gz: d9458bc9b998ac9fb0d5450e66a73d49bbc5bd546250d221045c4b17361cc9a02fa9a0c9b2dbf012686e4bc0c60336635b6946e7f531a8ba80900336e24affa9

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.0"
 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,9 +211,7 @@ 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
@@ -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
@@ -254,9 +270,10 @@ 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 radix [nil, 32, 58, 64] Optional radix; will use a heuristic
+  #  if omitted.
   #
-  # @param format [:str, :hex, :b64, :bin] An optional formatting
+  # @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.
@@ -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
 
@@ -342,7 +360,8 @@ module UUID::NCName
   #  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
@@ -373,7 +392,8 @@ module UUID::NCName
   #  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
@@ -404,7 +424,8 @@ module UUID::NCName
   #  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

data/uuid-ncname.gemspec

@@ -27,16 +27,16 @@ DESC
   spec.require_paths = ["lib"]
 
   # we use named parameters
-  spec.required_ruby_version = '~> 2.0'
+  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'
   spec.add_runtime_dependency 'base58',    '~> 0.2.3'
 
-  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'bundler', '~> 2.2'
   spec.add_development_dependency 'rake',    '~> 13.0'
-  spec.add_development_dependency 'rspec',   '~> 3.9'
+  spec.add_development_dependency 'rspec',   '~> 3.10'
 
   # only need it for testing, who knew
   # spec.add_development_dependency 'uuidtools', '~> 2.1.5'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uuid-ncname
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Dorian Taylor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-16 00:00:00.000000000 Z
+date: 2021-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '3.10'
 description: |
   This module creates an isomorphic representation of a UUID which is
   guaranteed to fit into the grammar of the XML NCName construct, which
@@ -116,7 +116,7 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -125,7 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Format a UUID as a valid NCName.