pubid 2.0.6 → 2.0.7

data/lib/pubid/nist/pubid_urn_schema.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Nist
+    # The pubid-scheme URN of NIST (issue #656; docs/URN-SCHEMES.adoc).
+    #
+    #   NIST SP 800-53r5
+    #   urn:pubid:nist:sp:800-53:pub-NIST:series-SP:subseries-800:edtype-r:ed-5
+    #
+    # The core is the document number. +publisher+ and +series+ are atoms,
+    # because a few series print no number ("NIST OWMWP 06-13-2018" keeps
+    # its date there) and the series spelling varies inside one type
+    # ("CIRC", "NBS.CIRC", "LCIRC").
+    #
+    # +update+ and +update_component+ serialize every field of their
+    # component, so each field is its own atom. Reducing them to one
+    # identifying value changes #to_hash and needs a relaton-data-nist
+    # re-crawl; that is a separate decision (docs/URN-SCHEMES.adoc).
+    #
+    # Facets: +parsed_format+ (the input was an MR string), the printed
+    # prefix of a revision (" Rev. " against "r") and the bracketed
+    # +translation+ ("(spa)"), whose code is the +lang+ atom.
+    PubidUrnSchema = Pubid::PubidUrn.define("nist") do
+      atom "publisher", "pub"
+      atom "series", "series"
+      atom "subseries", "subseries"
+      atom "part.type", "parttype"
+      atom "part.value", "part"
+      atom "section", "section"
+      atom "volume", "vol"
+      atom "edition.type", "edtype"
+      atom "edition.id", "ed"
+      atom "edition.additional_text", "edtext"
+      atom "edition_year", "edyear"
+      atom "supplement.number", "sup"
+      atom "supplement.suffix", "supsuffix"
+      atom "supplement.year", "supyear"
+      atom "supplement.month", "supmonth"
+      atom "supplement.year_end", "supyearend"
+      atom "supplement_date_range_start", "suprangestart"
+      atom "supplement_date_range_end", "suprangeend"
+      atom "supplement.has_revision", "suprev", kind: :bool
+      atom "implicit_supplement", "implicitsup", kind: :bool
+      atom "update.prefix", "updprefix"
+      atom "update.number", "upd"
+      atom "update.year", "updyear"
+      atom "update.month", "updmonth"
+      atom "update_component.prefix", "ucprefix"
+      atom "update_component.number", "uc"
+      atom "update_component.year", "ucyear"
+      atom "update_component.month", "ucmonth"
+      atom "revision_year", "revyear"
+      atom "revision_month", "revmonth"
+      atom "revised_date", "reviseddate"
+      atom "update_number", "updnumber"
+      atom "update_year", "updnumberyear"
+      atom "stage.type", "stagetype"
+      atom "stage.id", "stage"
+      atom "draft_number", "draftnumber"
+      atom "version_component.value", "v"
+      atom "version", "version"
+      atom "year", "year", kind: :int
+      atom "month", "month", kind: :int
+      atom "date_year", "dateyear"
+      atom "date_month", "datemonth"
+      atom "date_day", "dateday"
+      atom "dated_seq", "datedseq"
+      atom "prefix", "prefix"
+      atom "range_notation", "range"
+      atom "translation_component.code", "lang"
+      atom "draft", "draft"
+      atom "index", "index"
+      atom "insert", "insert"
+      atom "errata", "errata"
+      atom "appendix", "appendix"
+      atom "addendum", "addendum"
+      atom "addendum_number", "addendumnumber"
+
+      facet "publisher_was_parsed", "pubparsed", kind: :bool
+      facet "parsed_format", "format"
+      facet "edition.original_prefix", "edprefix"
+      facet "translation", "translationsrc"
+
+      type "pubid:nist:identifier", "id"
+      type "pubid:nist:circular", "circ"
+      type "pubid:nist:circular-supplement", "circsup"
+      type "pubid:nist:commercial-standard", "cs"
+      type "pubid:nist:commercial-standard-emergency", "cse"
+      type "pubid:nist:commercial-standards-monthly", "csm"
+      type "pubid:nist:crpl-report", "crpl"
+      type "pubid:nist:dated-document", "dd"
+      type "pubid:nist:federal-information-processing-standards", "fips"
+      type "pubid:nist:grant-contractor-report", "gcr"
+      type "pubid:nist:handbook", "hb"
+      type "pubid:nist:interagency-report", "ir"
+      type "pubid:nist:letter-circular", "lc"
+      type "pubid:nist:miscellaneous-publication", "mp"
+      type "pubid:nist:monograph", "mono"
+      type "pubid:nist:ncstar", "ncstar"
+      type "pubid:nist:nsrds", "nsrds"
+      type "pubid:nist:owmwp", "owmwp"
+      type "pubid:nist:report", "rpt"
+      type "pubid:nist:special-publication", "sp"
+      type "pubid:nist:technical-note", "tn"
+      type "pubid:nist:supplement-identifier", "sup"
+    end
+  end
+end

data/lib/pubid/nist.rb

@@ -21,6 +21,7 @@ module Pubid
     autoload :Caster, "#{__dir__}/nist/caster"
     autoload :CircularSupplementBuilder, "#{__dir__}/nist/circular_supplement_builder"
     autoload :Components, "#{__dir__}/nist/components"
+    autoload :PubidUrnSchema, "#{__dir__}/nist/pubid_urn_schema"
     autoload :Configuration, "#{__dir__}/nist/configuration"
     autoload :Identifier, "#{__dir__}/nist/identifiers/base"
     autoload :Identifiers, "#{__dir__}/nist/identifiers"

data/lib/pubid/pubid_urn/decoder.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Pubid
+  module PubidUrn
+    # Reads the body of a pubid-scheme URN back into an identifier hash.
+    # The inverse of Encoder; strict about structure. Canonical form (atom
+    # order, escapes, trailing "~") is checked by PubidUrn.parse, which
+    # re-encodes the result and compares.
+    class Decoder
+      FACET = /\A(\d+)\.([a-z0-9]+)-(.*)\z/
+
+      def initialize(body)
+        @body = body
+      end
+
+      # @return [Hash] the identifier hash (+_type+ and +base+ included)
+      def to_identifier_hash
+        flavor, rest = @body.split(":", 2)
+        fail!("no type segment") if rest.nil? || rest.empty?
+        decode_identifier(rest, flavor)
+      end
+
+      private
+
+      def decode_identifier(body, flavor)
+        tokens = PubidUrn.split_top(body, ":")
+        nodes = []
+        schemas = []
+        i = 0
+        while i < tokens.size
+          token = tokens[i]
+          if token == "f"
+            decode_facets(tokens.drop(i + 1), nodes, schemas)
+            break
+          end
+
+          schema = node_schema(token, flavor)
+          node = { "_type" => schema.type }
+          i = decode_core(tokens, i + 1, node, schema)
+          i = decode_atoms(tokens, i, node, schema)
+          nodes << node
+          schemas << schema
+        end
+        fail!("no identifier") if nodes.empty?
+
+        nodes.each_cons(2) { |base, node| node["base"] = base }
+        nodes.last
+      end
+
+      def node_schema(token, flavor)
+        if token == "type"
+          fail!("type-metadata URN names a type, not a document")
+        end
+
+        schema = if PubidUrn.structural?(token)
+                   owner, name = PubidUrn.split_token(token, flavor)
+                   PubidUrn.flavor_schema(owner)&.for_token(name)
+                 end
+        fail!("unknown type or segment #{token.inspect}") unless schema
+
+        schema
+      end
+
+      def decode_core(tokens, index, node, schema)
+        schema.core.each do |parts|
+          break if index >= tokens.size
+
+          token = tokens[index]
+          break if PubidUrn.structural?(token)
+
+          Paths.put(node, parts, Escape.decode(token)) unless token == NULL
+          index += 1
+        end
+        index
+      end
+
+      def decode_atoms(tokens, index, node, schema)
+        last = -1
+        while index < tokens.size &&
+            (position = schema.atom_position(tokens[index]))
+          if position <= last
+            fail!("atom #{tokens[index].inspect} is out of order or repeated")
+          end
+
+          last = position
+          atom = schema.atoms[position]
+          raw = tokens[index].split("-", 2).last
+          Paths.put(node, atom.parts, atom_value(raw, atom))
+          index += 1
+        end
+        index
+      end
+
+      def atom_value(raw, atom)
+        case atom.kind
+        when :int then integer(raw)
+        when :id then nested(raw)
+        when :ids then PubidUrn.split_top(raw, ",").map { |item| nested(item) }
+        else slot_value(raw, atom)
+        end
+      end
+
+      # The value of a :string, :bool or list atom, or of a facet.
+      def slot_value(raw, slot)
+        return scalar(raw, slot) unless slot.list?
+
+        PubidUrn.split_top(raw, ",", allow_empty: true).map do |item|
+          item == NULL ? nil : scalar(item, slot)
+        end
+      end
+
+      def scalar(raw, slot)
+        slot.element == :bool ? boolean(raw) : Escape.decode(raw)
+      end
+
+      def boolean(raw)
+        return true if raw == "true"
+        return false if raw == "false"
+
+        fail!("#{raw.inspect} is not a boolean")
+      end
+
+      def integer(raw)
+        unless /\A-?[0-9]+\z/.match?(raw)
+          fail!("#{raw.inspect} is not an integer")
+        end
+
+        Integer(raw, 10)
+      end
+
+      def nested(raw)
+        unless raw.start_with?("(") && raw.end_with?(")")
+          fail!("nested identifier #{raw.inspect} needs brackets")
+        end
+
+        Decoder.new(raw[1..-2]).to_identifier_hash
+      end
+
+      def decode_facets(tokens, nodes, schemas)
+        fail!("empty facet group") if tokens.empty?
+
+        tokens.each do |token|
+          match = FACET.match(token) || fail!("bad facet #{token.inspect}")
+          index = Integer(match[1], 10)
+          schema = schemas[index] || fail!("facet #{token.inspect} has no node")
+          facet = schema.facet(match[2]) || fail!("bad facet #{token.inspect}")
+          Paths.put(nodes[index], facet.parts, slot_value(match[3], facet))
+        end
+      end
+
+      def fail!(message)
+        raise Errors::UrnParseError, "pubid URN #{@body.inspect}: #{message}"
+      end
+    end
+  end
+end

data/lib/pubid/pubid_urn/encoder.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Pubid
+  module PubidUrn
+    # Writes the pubid-scheme URN of an identifier hash.
+    #
+    #   urn:pubid:<flavor>:<node>[:<node>…][:f:<facet>…]
+    #   <node> = <type>[:<core>…][:<prefix>-<value>…]
+    #
+    # The nodes go root first, along +base+: "ISO 9001:2015/Amd 1:2016" is
+    # "is:9001:year-2015:amd:1:year-2016", so every supplement of a document
+    # shares its slug prefix. A core value is positional; an absent one in
+    # the middle is "~", and absent ones at the end are dropped. An optional
+    # value is a prefixed atom, so it leaves no segment when it is absent.
+    class Encoder
+      def initialize(hash)
+        @hash = hash
+      end
+
+      # @return [String] the body after "urn:pubid:"
+      def body
+        flavor = PubidUrn.flavor_segment(@hash["_type"])
+        "#{flavor}:#{encode_identifier(@hash, flavor)}"
+      end
+
+      private
+
+      def encode_identifier(hash, flavor)
+        segments = []
+        facets = []
+        chain(hash).each_with_index do |node, index|
+          schema = PubidUrn.type_schema!(node["_type"],
+                                         error: Errors::InvalidInputError)
+          node = deep_dup(node)
+          node.delete("_type")
+          segments << token(schema, flavor)
+          segments.concat(core_segments(node, schema))
+          segments.concat(atom_segments(node, schema))
+          facets.concat(facet_segments(node, schema, index))
+          check_placed!(node, schema)
+        end
+        segments.push("f", *facets) unless facets.empty?
+        segments.join(":")
+      end
+
+      # The nodes from the root document to +hash+ itself.
+      def chain(hash)
+        nodes = []
+        node = hash
+        while node
+          unless node.is_a?(Hash) && node["_type"].is_a?(String)
+            raise Errors::InvalidInputError,
+                  "a pubid URN base must be an identifier hash, " \
+                  "got #{node.inspect}"
+          end
+
+          nodes.unshift(node.except("base"))
+          node = node["base"]
+        end
+        nodes
+      end
+
+      def token(schema, flavor)
+        return schema.token if schema.flavor == flavor
+
+        "#{schema.flavor}.#{schema.token}"
+      end
+
+      def core_segments(node, schema)
+        values = schema.core.map { |parts| Paths.take(node, parts) }
+        values.pop while !values.empty? && values.last.nil?
+        values.map do |value|
+          value.nil? ? NULL : core_value(value, schema)
+        end
+      end
+
+      # A core value that has the shape of structure (PubidUrn::STRUCTURE)
+      # gets its first character escaped.
+      def core_value(value, schema)
+        unless value.is_a?(String) && !value.empty?
+          raise Errors::InvalidInputError,
+                "core value of #{schema.type} must be a non-empty String, " \
+                "got #{value.inspect}"
+        end
+
+        encoded = Escape.encode(value)
+        return encoded unless PubidUrn.structural?(encoded)
+
+        Escape.force(value[0]) + Escape.encode(value[1..])
+      end
+
+      def atom_segments(node, schema)
+        schema.atoms.filter_map do |atom|
+          value = Paths.take(node, atom.parts)
+          next if value.nil?
+
+          "#{atom.prefix}-#{atom_value(value, atom, schema)}"
+        end
+      end
+
+      def atom_value(value, atom, schema)
+        case atom.kind
+        when :int then typed(value, Integer, atom, schema).to_s
+        when :id then nested(typed(value, Hash, atom, schema))
+        when :ids then nested_list(typed(value, Array, atom, schema))
+        else slot_value(value, atom, schema)
+        end
+      end
+
+      # The value of a :string, :bool or list atom, or of a facet.
+      def slot_value(value, slot, schema)
+        return scalar(value, slot, schema) unless slot.list?
+
+        typed(value, Array, slot, schema).map do |item|
+          item.nil? ? NULL : scalar(item, slot, schema)
+        end.join(",")
+      end
+
+      def scalar(value, slot, schema)
+        if slot.element == :bool
+          typed(value, [true, false], slot, schema).to_s
+        else
+          Escape.encode(typed(value, String, slot, schema))
+        end
+      end
+
+      def nested(hash)
+        "(#{Encoder.new(hash).body})"
+      end
+
+      def nested_list(hashes)
+        hashes.map { |hash| nested(hash) }.join(",")
+      end
+
+      def facet_segments(node, schema, index)
+        schema.facets.filter_map do |facet|
+          value = Paths.take(node, facet.parts)
+          next if value.nil?
+
+          "#{index}.#{facet.name}-#{slot_value(value, facet, schema)}"
+        end
+      end
+
+      def typed(value, expected, slot, schema)
+        ok = if expected.is_a?(Array)
+               expected.include?(value)
+             else
+               value.is_a?(expected)
+             end
+        return value if ok
+
+        raise Errors::InvalidInputError,
+              "#{schema.type} #{slot.path}: #{value.inspect} " \
+              "is not #{slot.kind}"
+      end
+
+      def check_placed!(node, schema)
+        left = node.reject { |_, value| Paths.blank?(value) }
+        return if left.empty?
+
+        raise Errors::InvalidInputError,
+              "the pubid URN schema of #{schema.type} " \
+              "does not place #{left.inspect}"
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash then value.to_h { |k, v| [k, deep_dup(v)] }
+        when Array then value.map { |v| deep_dup(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/pubid/pubid_urn/escape.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pubid
+  module PubidUrn
+    # The value escape of the pubid-scheme URN.
+    #
+    # The URN is also an HTTP path slug (relaton/relaton#441), so it cannot
+    # use "%": servers and proxies decode "%2F" before they route, or they
+    # refuse it. "~XX" (uppercase hex of one UTF-8 byte) has no meaning in a
+    # path, and "~" is an RFC 3986 unreserved character. Every byte outside
+    # SAFE is escaped, so ":" "," "(" ")" "~" never occur raw in a value and
+    # stay free for the structure of the URN.
+    module Escape
+      SAFE = /[A-Za-z0-9._-]/
+      RAW_TOKEN = /\A(?:[A-Za-z0-9._-]|~[0-9A-F]{2})*\z/
+
+      module_function
+
+      # @param value [String]
+      # @return [String]
+      def encode(value)
+        value.to_s.each_char.map { |char| encode_char(char) }.join
+      end
+
+      # Escape every character of +char+, safe or not. The codec uses it on
+      # the first character of a core value that would otherwise read as
+      # structure ("amd" -> "~61md").
+      #
+      # @param char [String] one character
+      # @return [String]
+      def force(char)
+        char.b.each_byte.map { |byte| format("~%02X", byte) }.join
+      end
+
+      # @param token [String]
+      # @return [String]
+      # @raise [Pubid::Errors::UrnParseError] for a raw character outside the
+      #   safe set, or a malformed or lower-case escape
+      def decode(token)
+        unless RAW_TOKEN.match?(token)
+          raise Pubid::Errors::UrnParseError,
+                "bad character or escape in pubid URN value #{token.inspect}"
+        end
+
+        bytes = token.b.gsub(/~([0-9A-F]{2})/n) { Regexp.last_match(1).hex.chr }
+        decoded = bytes.force_encoding(Encoding::UTF_8)
+        unless decoded.valid_encoding?
+          raise Pubid::Errors::UrnParseError,
+                "escape in pubid URN value #{token.inspect} is not UTF-8"
+        end
+
+        decoded
+      end
+
+      def encode_char(char)
+        SAFE.match?(char) ? char : force(char)
+      end
+    end
+  end
+end

data/lib/pubid/pubid_urn/paths.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Pubid
+  module PubidUrn
+    # Reads and writes a dotted key path ("edition.number",
+    # "languages.*.code") in an identifier hash.
+    #
+    # +take+ removes what it reads, so after every core path, atom and facet
+    # has been taken, anything left in the node is a key that the schema
+    # does not place — the encoder refuses it rather than drop it silently.
+    #
+    # A degenerate component may serialize as a bare scalar ("edition" =>
+    # "2" rather than {"number" => "2"}, see FLAT_SCALAR_FIELDS). Where a
+    # path expects a Hash and finds a scalar, the scalar IS the value of
+    # the path. +put+ always writes the nested form, which +from_hash+ reads
+    # as well, so the rebuilt identifier serializes alike.
+    module Paths
+      module_function
+
+      # @return [Object, nil] the value, or nil when the path is absent
+      def take(container, parts)
+        return nil unless container.is_a?(Hash) && container.key?(parts.first)
+
+        key, *rest = parts
+        return container.delete(key) if rest.empty?
+
+        value = container[key]
+        if rest.first == "*"
+          take_elements(container, key, value, rest.drop(1))
+        elsif value.is_a?(Hash)
+          take(value, rest)
+        elsif rest.size == 1
+          container.delete(key)
+        end
+      end
+
+      def take_elements(container, key, value, rest)
+        return nil unless value.is_a?(Array)
+        return container.delete(key) if rest.empty?
+
+        values = value.each_with_index.map do |element, i|
+          if element.is_a?(Hash)
+            take(element, rest)
+          elsif rest.size == 1 && !element.nil?
+            value[i] = {}
+            element
+          end
+        end
+        values.all?(&:nil?) ? nil : values
+      end
+
+      # Write +value+ (nil writes nothing).
+      def put(container, parts, value)
+        return if value.nil?
+
+        key, *rest = parts
+        if rest.empty?
+          container[key] = value
+        elsif rest.first == "*"
+          put_elements(container, key, value, rest.drop(1))
+        else
+          put(container[key] ||= {}, rest, value)
+        end
+      end
+
+      def put_elements(container, key, values, rest)
+        return container[key] = values if rest.empty?
+
+        elements = (container[key] ||= [])
+        values.each_with_index do |value, i|
+          next if value.nil?
+
+          put(elements[i] ||= {}, rest, value)
+        end
+      end
+
+      # True when nothing but empty containers is left.
+      def blank?(value)
+        case value
+        when Hash then value.each_value.all? { |v| blank?(v) }
+        when Array then value.all? { |v| blank?(v) }
+        else false
+        end
+      end
+    end
+  end
+end