uuid-ncname 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d0c55013befe4854c49979a826188f10feb869e24a589a0611ae1f97a2ea600
+  data.tar.gz: e78b411fa76e5cfe2c971a6904a0404e8f58ec3e5b64b9fa99620146c62d3b72
+SHA512:
+  metadata.gz: 63c11981cbf9cc492fbdf1dbba02aca38c9afbefef4b839ce70019395d7a6cbca5c77060efe814f1e2b0a68388bd0ced59d3a1defabaa3bb4210b76fa59d45e3
+  data.tar.gz: c0c7c3d145c1245f2aa77184dba53b9cad9157689a2ee3d259c3ffc7d3b6175b990036a8058ebc1ebef97716f3cac27ce0b975685da0a4914e51775e1d864b86

data/.gitignore

@@ -0,0 +1,13 @@
+syntax: glob
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in uuid-ncname.gemspec
+gemspec

data/README.md

@@ -0,0 +1,159 @@
+# UUID::NCName: Turn UUIDs into NCNames (and back)
+
+```ruby
+require 'uuid-ncname'
+require 'uuidtools'
+
+uu = UUIDTools::UUID.random_create
+# => #<UUID:0x3fff0e597ef8 UUID:df521e0a-9d57-4f04-9a95-fc2888decc5a>
+
+nc64 = UUID::NCName.to_ncname uu    # => "E31IeCp1X8EmpX8KIjezFK"
+nc32 = UUID::NCName.to_ncname_32 uu # => "E35jb4cu5k7yetkk7ykei33gfk"
+
+orig = UUID::NCName.from_ncname nc64
+# => "df521e0a-9d57-4f04-9a95-fc2888decc5a"
+
+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
+```
+
+## Description
+
+The purpose of this module is to devise an alternative representation
+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.
+
+## Rationale & Method
+
+The UUID is a generic identifier which is large enough to be globally
+unique. This makes it useful as a canonical name for data objects in
+distributed systems, especially those that cross administrative
+jurisdictions, such as the World-Wide Web. The
+[representation](http://tools.ietf.org/html/rfc4122#section-3),
+however, of the UUID, precludes it from being used in many places
+where it would be useful to do so.
+
+In particular, there are grammars for many types of identifiers which
+must not begin with a digit. Others are case-insensitive, or
+prohibited from containing hyphens (present in both the standard
+notation and Base64URL), or indeed anything outside of
+`^[A-Za-z_][0-9A-Za-z_]*$`.
+
+The hexadecimal notation of the UUID has a 5/8 chance of beginning
+with a digit, Base64 has a 5/32 chance, and Base32 has a 3/16
+chance. As such, the identifier must be modified in such a way as to
+guarantee beginning with an alphabetic letter (or underscore `_`, but
+some grammars even prohibit that, so we omit it as well).
+
+While it is conceivable to simply add a padding character, there are a
+few considerations which make it more appealing to derive the initial
+character from the content of the UUID itself:
+
+* UUIDs are large (128-bit) identifiers as it is, and it is
+  undesirable to add meaningless syntax to them if we can avoid doing
+  so.
+
+* 128 bits is an inconvenient number for aligning to both Base32 (130)
+  and Base64 (132), though 120 divides cleanly into 5, 6 and 8.
+
+* The 13th quartet, or higher four bits of the
+  `time_hi_and_version_field` of the UUID is constant, as it indicates
+  the UUID's version. If we encode this value using the scheme common
+  to both Base64 and Base32, we get values between `A` and `P`, with
+  the valid subset between `B` and `F`.
+
+**Therefore:** extract the UUID's version quartet, shift all
+subsequent data 4 bits to the left, zero-pad to the octet, encode with
+either _base64url_ or _base32_, truncate, and finally prepend the
+encoded version character. Voilà, one token-safe UUID.
+
+## Applications
+
+### XML IDs
+
+The `ID` production appears to have been constricted, inadvertently or
+otherwise, from [Name](http://www.w3.org/TR/xml11/#NT-Name) in both
+the XML 1.0 and 1.1 specifications,
+to [NCName](http://www.w3.org/TR/xml-names/#NT-NCName)
+by [XML Schema Part 2](http://www.w3.org/TR/xmlschema-2/#ID). This
+removes the colon character `:` from the grammar. The net effect is
+that
+
+    <foo id="urn:uuid:b07caf81-baae-449d-8a2e-48c0f5fa5538"/>
+
+while being a _well-formed_ ID _and_ valid under DTD validation, is
+_not_ valid per XML Schema Part 2 or anything that uses it (e.g. Relax
+NG).
+
+### RDF blank node identifiers
+
+Blank node identifiers in RDF are intended for serialization, to act
+as a handle so that multiple RDF statements can refer to the same
+blank
+node. The
+[RDF abstract syntax specifies](http://www.w3.org/TR/rdf-concepts/#section-URI-Vocabulary) that
+the validity constraints of blank node identifiers be delegated to the
+concrete syntax
+specifications. The
+[RDF/XML syntax specification](http://www.w3.org/TR/rdf-syntax-grammar/#rdf-id) lists
+the blank node identifier as NCName. However, according
+to [the Turtle spec](http://www.w3.org/TR/turtle/#BNodes), this is a
+valid blank node identifier:
+
+    _:42df00ec-30a2-431f-be9e-e3a612b325db
+
+despite
+[an older version](http://www.w3.org/TeamSubmission/turtle/#nodeID)
+listing a production equivalent to the more conservative
+NCName. NTriples syntax is
+[even more constrained](http://www.w3.org/TR/rdf-testcases/#ntriples),
+given as `^[A-Za-z][0-9A-Za-z]*$`.
+
+### Generated symbols
+
+> There are only two hard things in computer science: cache
+> invalidation and naming things [and off-by-one errors].
+>
+> -- Phil Karlton [extension of unknown origin]
+
+Suppose you wanted to create a [literate
+programming](http://en.wikipedia.org/wiki/Literate_programming) system
+(I do). One of your (my) stipulations is that the symbols get defined
+in the *prose*, rather than the _code_. However, you (I) still want
+to be able to validate the code's syntax, and potentially even run the
+code, without having to commit to naming anything. You are (I am) also
+interested in creating a global map of classes, datatypes and code
+fragments, which can be operated on and tested in isolation, ported to
+other languages, or transplanted into the more conventional packages
+of programs, libraries and frameworks. The Base32 UUID NCName
+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).
+
+## Documentation
+
+Generated and deposited
+[in the usual place](http://www.rubydoc.info/gems/uuid-ncname/).
+
+## Installation
+
+You know how to do this:
+
+    $ gem install uuid-ncname
+
+Or, [download it off rubygems.org](https://rubygems.org/gems/uuid-ncname).
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[the GitHub repository](https://github.com/doriantaylor/rb-uuid-ncname).
+
+## License
+
+This software is provided under
+the [Apache License, 2.0](https://www.apache.org/licenses/LICENSE-2.0).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "uuid/ncname"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/uuid/ncname.rb

@@ -0,0 +1,218 @@
+require "uuid/ncname/version"
+
+require 'base64'
+require 'base32'
+
+module UUID::NCName
+
+  private
+
+  ENCODE = {
+    32 => -> bin {
+      bin = bin.unpack 'C*'
+      bin[-1] >>= 1
+      out = ::Base32.encode bin.pack('C*')
+
+      out.downcase[0, 25]
+    },
+    64 => -> bin {
+      bin = bin.unpack 'C*'
+      bin[-1] >>= 2
+      out = ::Base64.urlsafe_encode64 bin.pack('C*')
+
+      out[0, 21]
+    },
+  }
+
+  DECODE = {
+    32 => -> str {
+      str = str.upcase[0, 25] + 'A======'
+      out = ::Base32.decode(str).unpack 'C*'
+      out[-1] <<= 1
+
+      out.pack 'C*'
+    },
+    64 => -> str {
+      str = str[0, 21] + 'A=='
+      out = ::Base64.urlsafe_decode64(str).unpack 'C*'
+      out[-1] <<= 2
+
+      out.pack 'C*'
+    },
+  }
+
+  UUF = (['%02x' * 4] + ['%02x' * 2] * 3 + ['%02x' * 6]).join '-'
+
+  FORMAT = {
+    str: -> bin { UUF % bin.unpack('C*') },
+    hex: -> bin { bin.unpack 'H*' },
+    b64: -> bin { ::Base64.strict_encode64 bin },
+    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
+
+  def self.encode_version version
+    ((version & 15) + 65).chr
+  end
+
+  def self.decode_version version
+    (version.upcase.ord - 65) % 16
+  end
+
+  public
+
+  # 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.
+  #
+  # @param uuid [#to_s] whatever it is, it had better look like a
+  #  UUID. This includes UUID objects, URNs, 32-character hex strings,
+  #  16-byte binary strings, etc.
+  #
+  # @param radix [32, 64] either the number 32 or the number 64.
+  #
+  # @return [String] The NCName-formatted UUID.
+
+  def self.to_ncname uuid, radix: 64
+    raise 'Radix must be either 32 or 64' unless [32, 64].any? radix
+    raise 'UUID must be something stringable' if uuid.nil? or
+      not uuid.respond_to? :to_s
+
+    uuid = uuid.to_s
+
+    bin = nil
+
+    if uuid.length == 16
+      bin = uuid
+    else
+      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))
+        match= m[1].tr('-_', '+/')
+        bin = ::Base64.decode64(match)
+      else
+        raise "Not sure what to do with #{uuid}"
+      end
+    end
+
+    raise 'Binary representation of UUID is shorter than 16 bytes' if
+      bin.length < 16
+
+    version, content = bin_uuid_to_pair bin[0, 16]
+
+    encode_version(version) + ENCODE[radix].call(content)
+  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
+  #
+  # @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
+  #  parameter; defaults to `:str`, the canonical string representation.
+  # 
+  # @return [String, nil] The corresponding UUID or nil if the input
+  #  is malformed.
+
+  def self.from_ncname ncname, radix: nil, format: :str
+    raise 'Format must be symbol-able' unless format.respond_to? :to_sym
+    raise "Invalid format #{format}" unless FORMAT[format]
+
+    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
+
+    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
+    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
+    end
+
+    version, content = match.captures
+    version = decode_version version
+    content = DECODE[radix].call content
+
+    bin = pair_to_bin_uuid version, content
+
+    FORMAT[format].call bin
+  end
+
+  # Shorthand for conversion to the Base64 version
+  #
+  # @param uuid [#to_s] The UUID
+  # @return [String] The Base64-encoded NCName
+
+  def self.to_ncname_64 uuid
+    to_ncname uuid
+  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
+
+  def self.from_ncname_64 ncname, format: :str
+    from_ncname ncname, radix: 64, format: format
+  end
+
+  # Shorthand for conversion to the Base32 version
+  #
+  # @param uuid [#to_s] The UUID
+  # @return [String] The Base32-encoded NCName
+
+  def self.to_ncname_32 uuid
+    to_ncname uuid, radix: 32
+  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
+
+  def self.from_ncname_32 ncname, format: :str
+    from_ncname ncname, radix: 32, format: format
+  end
+
+end

data/lib/uuid/ncname/version.rb

@@ -0,0 +1,5 @@
+module UUID
+  module NCName
+    VERSION = "0.1.0"
+  end
+end

data/uuid-ncname.gemspec

@@ -0,0 +1,40 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "uuid/ncname/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "uuid-ncname"
+  spec.version       = UUID::NCName::VERSION
+  spec.authors       = ["Dorian Taylor"]
+  spec.email         = ["code@doriantaylor.com"]
+
+  spec.homepage      = "https://github.com/doriantaylor/rb-uuid-ncname"
+  spec.summary       = %q{Format a UUID as a valid NCName.}
+  spec.description   = <<DESC
+This module creates an isomorphic representation of a UUID which is
+guaranteed to fit into the grammar of the XML NCName construct, which
+also happens to exhibit (modulo case and hyphens) the same constraints
+as identifiers in nearly all programming languages. Provides case
+sensitive (Base64) and case-insensitive (Base32) variants.
+DESC
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # surprisingly do not need this
+  # 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'
+
+  # only need it for testing, who knew
+  # spec.add_development_dependency 'uuidtools', '~> 2.1.5'
+  # actually don't even need it for that
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: uuid-ncname
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dorian Taylor
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-05-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base32
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: |
+  This module creates an isomorphic representation of a UUID which is
+  guaranteed to fit into the grammar of the XML NCName construct, which
+  also happens to exhibit (modulo case and hyphens) the same constraints
+  as identifiers in nearly all programming languages. Provides case
+  sensitive (Base64) and case-insensitive (Base32) variants.
+email:
+- code@doriantaylor.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/uuid/ncname.rb
+- lib/uuid/ncname/version.rb
+- uuid-ncname.gemspec
+homepage: https://github.com/doriantaylor/rb-uuid-ncname
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Format a UUID as a valid NCName.
+test_files: []