uuid-ncname 0.2.1 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e388102139409aff9de824bcff21d8a7793796425d781e896deb04ad1032fce
-  data.tar.gz: 06ff6b9f8f141db4fc5d3458c814be989f315b9f2bb3c77dc9a2ee81ba7d7b0c
+  metadata.gz: f82febb1e1498f1d602bd2225b730b7e9128b7ea7b811472465001ae9925e83d
+  data.tar.gz: 8f403882f98f9509c074e3b53c1aebe58ff0b0adbe9f248baf4df9ded59b7b25
 SHA512:
-  metadata.gz: 66abf5bf9d94bf70b268c5e0a96f99b7579903f6e3dc3c697afcfb99a64acc58da32a1340269d5f93e2a9cec1cdb0f261da21d2c94c94462d5487a80a2301b4b
-  data.tar.gz: 00e7081505f5a836bf5073e0b7a489a3b3a0e2620f54cc7619224786b09019fc5b9af43448a35393b6679a1256d4729f0a3f174d50d6ecb85a383a56fa5832c1
+  metadata.gz: b0c1948dd81504cd7241f2a5ad78e50f661b4d9b0868402fd3e393760a5ddf6d30be82f39b51d700e0ded7681efa65134fb0e37ffa27f2108c238ccb8d2cbdfe
+  data.tar.gz: 2c86dfc2b5ee4b1c1be7c1e8343e844bfa9df0a94ebf20b487fd5988b53df4e138ae05e44d5134b00c4e1092140d24042c3e1c5d90ad9238a87fea65ab165f3c

data/.gitignore

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

data/README.md

@@ -83,14 +83,13 @@ 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 newer, you should be running these methods with `version: 1`.
+> or older, you should be running these methods with `version: 1`.
 
 ## Rationale & Method
 

data/lib/uuid/ncname.rb

@@ -116,8 +116,9 @@ module UUID::NCName
     ],
   ]
 
-  def self.encode_version version
-    ((version & 15) + 65).chr
+  def self.encode_version version, radix
+    offset = radix == 32 ? 97 : 65
+    ((version & 15) + offset).chr
   end
 
   def self.decode_version version
@@ -127,7 +128,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 +138,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.
@@ -148,10 +170,10 @@ 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.
+  #  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.
   # 
   # @param align [true, false] Optional directive to treat the
   #  terminating character as aligned to the numerical base of the
@@ -160,9 +182,10 @@ module UUID::NCName
   #  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
+  #  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.
 
@@ -170,7 +193,7 @@ module UUID::NCName
     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
+    align = !!align # coerce to a boolean
 
     # XXX remove this when appropriate
     version = warn_version(version)
@@ -195,14 +218,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.
@@ -210,19 +233,22 @@ module UUID::NCName
   # @param radix [nil, 32, 64] Optional radix; will use heuristic if omitted.
   #
   # @param format [:str, :hex, :b64, :bin] An optional formatting
-  #  parameter; defaults to `:str`, the canonical string representation.
+  #  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.
-  #  Setting this parameter to `nil`, the default, will cause the
+  # @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
@@ -262,6 +288,9 @@ module UUID::NCName
 
     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,9 +298,9 @@ 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
 
@@ -285,9 +314,9 @@ 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.
@@ -300,9 +329,9 @@ 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 Base32-encoded NCName
 
@@ -316,9 +345,9 @@ 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.
@@ -327,4 +356,46 @@ module UUID::NCName
     from_ncname ncname, radix: 32, format: format
   end
 
+  # 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, strict: false
+    token = token.to_s
+    if /^[A-Pa-p](?:[0-9A-Za-z_-]{21}|[2-7A-Za-z]{25})$/.match token
+      # 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 
+      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
+  end
+
 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.1"
+  VERSION = "0.2.6"
 end

data/uuid-ncname.gemspec

@@ -33,9 +33,9 @@ DESC
   # spec.add_runtime_dependency 'uuidtools', '~> 2.1.5'
   spec.add_runtime_dependency 'base32',    '~> 0.3.2'
 
-  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.1
+  version: 0.2.6
 platform: ruby
 authors:
 - Dorian Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-08-25 00:00:00.000000000 Z
+date: 2020-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -30,42 +30,42 @@ dependencies:
     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
@@ -110,8 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Format a UUID as a valid NCName.