uuid-ncname 0.2.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e77f488ca6429c6b7799b8ae23f673c2d17ae2914abaebfb8411cd4408ce498
-  data.tar.gz: a744fad35027fd23aa64795baceeae5b940ef711d475a2e726f5c423df05997c
+  metadata.gz: d17bfbafda1f25ed22fe1b314af7d9add89e66caa92a5f859fe399b81b4a1c63
+  data.tar.gz: 38372398d6460a72212023f6904c2eef6b5785461169f8ff7e1ff4248aa08ea2
 SHA512:
-  metadata.gz: 37652d6a314d6629164f0d616bafa99185cb3d044e9908492d91d5d77a87c13308f5ce894b1a3c05bb382ae9a1cb825e90aaf00152690816a1c2e737b7d20066
-  data.tar.gz: 5740a1c557cbee7efe37ec3af6f3145a83010222cb3f91159fa9500d161c45279e9208d4cb11141197995d7cb9410e2b28dc69e4bcd8d8e30e4c3f1636c2682e
+  metadata.gz: c2f4d687ce200545784b6cd57417d182701faa805bb11e963184418284bc134b02e191a099026a63183aad8f089fd9eb140331fcd3915f33a1ea5e596e97836a
+  data.tar.gz: dcbd3afa99943709d07892fff109659dc567fbb3c7ab285cd5b9281894cb0477d984fd9ca0de12b778bd4d7125643299ce9ac61047fbd3a22ce35a91bb774722

data/.gitignore

@@ -7,6 +7,9 @@ syntax: glob
 /pkg/
 /spec/reports/
 /tmp/
+*.gem
+\#*
+.\#*
 
 # rspec failure tracking
 .rspec_status

data/.yardopts

@@ -0,0 +1,5 @@
+--protected
+--no-private
+--hide-void-return
+--markup markdown
+--readme README.md

data/README.md

@@ -83,11 +83,10 @@ 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.
+`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`.

data/lib/uuid/ncname.rb

@@ -3,11 +3,20 @@ require "uuid/ncname/version"
 
 require 'base64'
 require 'base32'
+require 'base58'
 
 module UUID::NCName
 
   private
 
+  MATCH = /^([A-Pa-p]) # zero-width boundary and version bookend
+  ([2-7A-Za-z]{24}|[-0-9A-Z_a-z]{20}| # base32 and 64
+  (?:[1-9A-HJ-NP-Za-km-z]{15}_{6}|[1-9A-HJ-NP-Za-km-z]{16}_{5}|
+  [1-9A-HJ-NP-Za-km-z]{17}_{4}|[1-9A-HJ-NP-Za-km-z]{18}___|
+  [1-9A-HJ-NP-Za-km-z]{19}__|[1-9A-HJ-NP-Za-km-z]{20}_|
+  [1-9A-HJ-NP-Za-km-z]{21})) # base58 with underscore pad
+  ([-0-9A-Z_a-z])$/x.freeze # lax variant bookend and zero-width boundary
+
   ENCODE = {
     32 => -> (bin, align = true) {
       if align
@@ -18,7 +27,15 @@ module UUID::NCName
 
       out = ::Base32.encode bin
 
-      out.downcase[0, 25]
+      out.downcase[0, 25] # clip off the padding
+    },
+    58 => -> (bin, _) {
+      variant = bin[-1].ord >> 4
+      # note the bitcoin alphabet is the one used in draft-msporny-base58
+      out = ::Base58.binary_to_base58(bin.chop, :bitcoin)
+      # we need to pad base58 with underscores because it is variable length
+      out + (?_ * (21 - out.length)) +
+        encode_version(variant) # encode_version does variant too
     },
     64 => -> (bin, align = true) {
       if align
@@ -29,10 +46,11 @@ module UUID::NCName
 
       out = ::Base64.urlsafe_encode64 bin
 
-      out[0, 21]
+      out[0, 21] # clip off the padding
     },
   }
 
+  # note the version symbol is already removed
   DECODE = {
     32 => -> (str, align = true) {
       str = str.upcase[0, 25] + 'A======'
@@ -41,6 +59,11 @@ module UUID::NCName
 
       out.pack 'C*'
     },
+    58 => -> (str, _) {
+      variant = decode_version(str[-1]) << 4
+      str = str.chop.tr ?_, ''
+      ::Base58.base58_to_binary(str, :bitcoin) + variant.chr
+    },
     64 => -> (str, align = true) {
       str = str[0, 21] + 'A=='
       out = ::Base64.urlsafe_decode64(str).unpack 'C*'
@@ -116,8 +139,9 @@ module UUID::NCName
     ],
   ]
 
-  def self.encode_version version
-    ((version & 15) + 65).chr
+  def self.encode_version version, radix = 64
+    offset = radix == 32 ? 97 : 65
+    ((version & 15) + offset).chr
   end
 
   def self.decode_version version
@@ -127,7 +151,7 @@ module UUID::NCName
   def self.warn_version version
     if version.nil?
       warn 'Set an explicit :version to remove this warning. See documentation.'
-      version = 0
+      version = 1
     end
 
     raise 'Version must be 0 or 1' unless [0, 1].include? version
@@ -137,6 +161,27 @@ module UUID::NCName
 
   public
 
+  # This error gets thrown when a UUID-NCName token can't be
+  # positively determined to be one version or the other.
+  class AmbiguousToken < ArgumentError
+
+    # @return [String] The ambiguous token
+    attr_reader :token
+    # @return [String] The UUID when decoded using version 0
+    attr_reader :v0
+    # @return [String] The UUID when decoded using version 1
+    attr_reader :v1
+
+    # @param token [#to_s] The token in question
+    # @param v0 [#to_s] UUID decoded with decoding scheme version 0
+    # @param v1 [#to_s] UUID decoded with decoding scheme version 1
+
+    def initialize token, v0: nil, v1: nil
+      @v0 = v0 || from_ncname(token, version: 0)
+      @v1 = v1 || from_ncname(token, version: 1)
+    end
+  end
+
   # Converts a UUID (or object that when converted to a string looks
   # like a UUID) to an NCName. By default it produces the Base64
   # variant.
@@ -149,9 +194,9 @@ 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 if you do not
-  #  set this parameter explicitly. The default is currently 0, but
-  #  will change in the next version.
+  #  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.
   # 
   # @param align [true, false] Optional directive to treat the
   #  terminating character as aligned to the numerical base of the
@@ -162,15 +207,17 @@ module UUID::NCName
   #  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`.
+  #  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
-    raise 'Radix must be either 32 or 64' unless [32, 64].include? radix
+    raise 'Radix must be either 32, 58, or 64' unless
+      [32, 58, 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
+    align = !!align # coerce to a boolean
 
     # XXX remove this when appropriate
     version = warn_version(version)
@@ -195,14 +242,14 @@ module UUID::NCName
     raise 'Binary representation of UUID is shorter than 16 bytes' if
       bin.length < 16
 
-    uuidver, content = TRANSFORM[version][0].call bin[0, 16]
+    uuidver, content = TRANSFORM[version].first.call bin[0, 16]
 
-    encode_version(uuidver) + ENCODE[radix].call(content, align)
+    encode_version(uuidver, radix) + ENCODE[radix].call(content, align)
   end
 
   # Converts an NCName-encoded UUID back to its canonical
   # representation. Will return nil if the input doesn't match the
-  # radix (if supplied) or is otherwise malformed.  doesn't match
+  # radix (if supplied) or is otherwise malformed.
   #
   # @param ncname [#to_s] an NCName-encoded UUID, either a
   #  22-character (Base64) variant, or a 26-character (Base32) variant.
@@ -212,17 +259,20 @@ 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 version [0, 1] See ::to_ncname. Defaults to 1.
   # 
-  # @param align [true, false, nil] See `to_ncname` for details.
+  # @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.
   #
+  # @param validate [false, true] Check that the ninth (the variant)
+  #  octet is correctly masked _after_ decoding.
+  #
   # @return [String, nil] The corresponding UUID or nil if the input
   #  is malformed.
-
+  #
   def self.from_ncname ncname,
-      radix: nil, format: :str, version: nil, align: nil
+      radix: nil, format: :str, version: nil, align: nil, validate: false
     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
@@ -234,34 +284,33 @@ module UUID::NCName
     return unless ncname and ncname.respond_to? :to_s
 
     ncname = ncname.to_s.strip.gsub(/\s+/, '')
-    match  = /^([A-Za-z])([0-9A-Za-z_-]{21,})$/.match(ncname) or return
+    match  = MATCH.match(ncname) or return
+    return if align and !/[A-Pa-p]$/.match? ncname # MATCH is lax
 
+    # determine the radix from the input
     if radix
-      raise "Radix must be 32 or 64, not #{radix}" unless [32, 64].any? radix
-      return unless { 32 => 26, 64 => 22 }[radix] == ncname.length
+      raise ArgumentError, "Radix must be 32, 58, or 64, not #{radix}" unless
+        [32, 58, 64].any? radix
+      return unless { 32 => 26, 58 => 23, 64 => 22 }[radix] == ncname.length
     else
-      len = ncname.length
-
-      if ncname =~ /[_-]/
-        radix = 64
-      elsif len >= 26
-        radix = 32
-      elsif len >= 22
-        radix = 64
-      else
-        # uh will this ever get executed now that i put in that return?
-        raise "Not sure what to do with an identifier of length #{len}."
-      end
+      radix = { 26 => 32, 23 => 58, 22 => 64}[ncname.length] or
+        raise ArgumentError,
+        "Not sure what to do with an identifier of length #{ncname.length}."
     end
 
-    uuidver, content = match.captures
+    # note MATCH separates the variant
+    uuidver, *content = match.captures
+    content = content.join
 
-    align   = !!(content =~ /[A-Pa-p]$/) if align.nil?
+    align   = !!(/[A-Pa-p]$/.match? content) if align.nil?
     uuidver = decode_version uuidver
     content = DECODE[radix].call content, align
 
     bin = TRANSFORM[version][1].call uuidver, content
 
+    # double-check the variant (high-order bits have to be 10)
+    return if validate and bin[8].ord >> 6 != 2
+
     FORMAT[format].call bin
   end
 
@@ -269,12 +318,12 @@ module UUID::NCName
   #
   # @param uuid [#to_s] The UUID
   # 
-  # @param version [0, 1] See `to_ncname`.
+  # @param version [0, 1] See ::to_ncname.
   # 
-  # @param align [true, false] See `to_ncname`.
+  # @param align [true, false] See ::to_ncname.
   #
   # @return [String] The Base64-encoded NCName
-
+  #
   def self.to_ncname_64 uuid, version: nil, align: true
     to_ncname uuid, version: version, align: align
   end
@@ -285,27 +334,58 @@ module UUID::NCName
   #
   # @param format [:str, :hex, :b64, :bin] The format
   # 
-  # @param version [0, 1] See `to_ncname`.
+  # @param version [0, 1] See ::to_ncname.
   # 
-  # @param align [true, false] 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
   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
+  #
+  def self.to_ncname_58 uuid, version: nil, align: true
+    to_ncname uuid, radix: 58, version: version, align: align
+  end
+
+  # Shorthand for conversion from the Base58 version
+  #
+  # @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
+  end
+
   # Shorthand for conversion to the Base32 version
   #
   # @param uuid [#to_s] The UUID
   # 
-  # @param version [0, 1] See `to_ncname`.
+  # @param version [0, 1] See ::to_ncname.
   # 
-  # @param align [true, false] See `to_ncname`.
+  # @param align [true, false] See ::to_ncname.
   #
   # @return [String] The Base32-encoded NCName
-
+  #
   def self.to_ncname_32 uuid, version: nil, align: true
     to_ncname uuid, radix: 32, version: version, align: align
   end
@@ -316,35 +396,55 @@ module UUID::NCName
   #
   # @param format [:str, :hex, :b64, :bin] The format
   # 
-  # @param version [0, 1] See `to_ncname`.
+  # @param version [0, 1] See ::to_ncname.
   # 
-  # @param align [true, false] 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
   end
 
-  # Test if the given token is a UUID NCName, with a hint to its version.
+  # Test if the given token is a UUID NCName, with a hint to its
+  # version. This method can positively identify a token as a UUID
+  # NCName, but there is a small subset of UUIDs which will produce
+  # tokens which are valid in both versions. The method returns
+  # `false` if the token is invalid, otherwise it returns `0` or `1`
+  # for the guessed version.
+  #
+  # @note Version 1 tokens always end with `I`, `J`, `K`, or `L` (with
+  #  base32 being case-insensitive), so tokens that end in something
+  #  else will always be version 0.
   #
   # @param token [#to_s] The token to test
   #
+  # @param strict [false, true]
+  #
   # @return [false, 0, 1]
-  def self.valid? token
+  #
+  def self.valid? token, strict: false
     token = token.to_s
-    if /^[A-P](?:[0-9A-Za-z_-]{21}|[2-7A-Za-z]{25})$/.match token
+    if MATCH.match? token
       # false is definitely version zero but true is only maybe version 1
-      version = /[IJKLijkl]$/.match(token) ? 1 : 0
+      version = /^(?:.{21}[I-L]|.{25}[I-Li-l])$/.match(token) ? 1 : 0
 
-      if version == 1
-        uu = from_ncname token, version: 1
-        # lol even this isn't a guarantee
-        /[89ab]/.match(uu[19]) ? 1 : version
-      else
-        version
+      # try decoding with validation on 
+      uu = from_ncname token, version: version, validate: true
+
+      # note that version 1 will always return something because the
+      # method of detecting it is a version 1 also happens to be the
+      # method of determining whether or not it is valid.
+      return false unless uu
+
+      if version == 1 and strict
+        # but we can also check if the input is a valid version 0
+        u0 = from_ncname token, version: 0, validate: true
+        raise AmbiguousToken.new(token, v0: u0, v1: uu) if u0
       end
+
+      version
     else
       false
     end

data/lib/uuid/ncname/version.rb

@@ -1,7 +1,10 @@
+# this is here because it reasonable to expect a *class* in the
+# namespace called UUID, so if you say `module UUID; module NCName`,
+# it will croak with a "TypeError: UUID is not a module".
 unless Module.const_defined? 'UUID'
   module UUID; end
 end
 
 module UUID::NCName
-    VERSION = "0.2.3"
+  VERSION = "0.3.1"
 end

data/uuid-ncname.gemspec

@@ -32,10 +32,11 @@ DESC
   # 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', '~> 1.16'
-  spec.add_development_dependency 'rake',    '~> 10.0'
-  spec.add_development_dependency 'rspec',   '~> 3.0'
+  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'rake',    '~> 13.0'
+  spec.add_development_dependency 'rspec',   '~> 3.9'
 
   # 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.2.3
+  version: 0.3.1
 platform: ruby
 authors:
 - Dorian Taylor
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2019-11-15 00:00:00.000000000 Z
+date: 2021-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -24,48 +24,62 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.3.2
+- !ruby/object:Gem::Dependency
+  name: base58
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.3
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.9'
 description: |
   This module creates an isomorphic representation of a UUID which is
   guaranteed to fit into the grammar of the XML NCName construct, which
@@ -81,6 +95,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
@@ -95,7 +110,7 @@ homepage: https://github.com/doriantaylor/rb-uuid-ncname
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -110,8 +125,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: Format a UUID as a valid NCName.
 test_files: []