pubid 2.0.5 → 2.0.7

data/lib/pubid/itu/pubid_urn_schema.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Pubid
+  module Itu
+    # The pubid-scheme URN of ITU (issue #656; docs/URN-SCHEMES.adoc).
+    #
+    #   ITU-T G.729 Annex B (1996) Cor. 3 (03/2001)
+    #   urn:pubid:itu:rec:729:sector-T:series-G:anx:B:year-1996:
+    #     cor:3:year-2001:month-03
+    #
+    # The nodes go root first along +base+, so every supplement, annex and
+    # appendix of a Recommendation shares its slug prefix. The official
+    # urn:itu: form (IANA-registered) stays on #to_urn.
+    #
+    # Facets are the flags the ITU classes call rendering-only: the same
+    # document printed two ways ("Suppl.1" and "Suppl. 1", "V.25 ter" and
+    # "V.25ter", "D.502R" and "D.502 R", "Amd. 1/Cor. 1" and "Amd. 1 Cor. 1").
+    # Every other flag is an atom, because it names a different document
+    # ("Technical Cor.", "attachment", the word "series").
+    #
+    # Not placed, so #to_pubid_urn raises rather than drop it: the +parts+ of
+    # a combined designation ("G.780-1/Y.1351-2"), a list inside a list. No
+    # pass fixture has one.
+    PubidUrnSchema = Pubid::PubidUrn.define("itu") do
+      atom "sector", "sector"
+      atom "series", "series"
+      atom "series_word", "seriesword", kind: :bool
+      atom "series_dash", "seriesdash", kind: :bool
+      atom "imp_marker", "imp"
+      atom "subseries", "subseries"
+      atom "parts", "part", kind: :list
+      atom "series_suffix", "suffix"
+      atom "qualifier", "qualifier"
+      atom "range_end", "rangeend"
+      atom "attachment", "attachment", kind: :bool
+      atom "combined.*.series", "combseries"
+      atom "combined.*.number", "combnumber"
+      atom "combined.*.subseries", "combsubseries"
+      atom "combined.*.series_suffix", "combsuffix"
+      atom "combined.*.qualifier", "combqualifier"
+      atom "study_group", "sg"
+      atom "has_bl", "bl", kind: :bool
+      atom "bracketed", "bracketed", kind: :bool
+      atom "has_colon", "colon", kind: :bool
+      atom "technical", "technical", kind: :bool
+      atom "material", "material"
+      atom "version", "v"
+      atom "year", "year"
+      atom "month", "month"
+      atom "day", "day"
+      atom "language", "lang"
+      atom "common_text_twin", "twin", kind: :id
+
+      facet "series_suffix_spaced", "suffixspaced", kind: :bool
+      facet "qualifier_glued", "qualifierglued", kind: :bool
+      facet "combined.*.series_suffix_spaced", "combsuffixspaced",
+            kind: :bools
+      facet "combined.*.qualifier_glued", "combqualifierglued", kind: :bools
+      facet "number_glued", "numberglued", kind: :bool
+      facet "slash_joined", "slashjoined", kind: :bool
+
+      type "pubid:itu:recommendation", "rec"
+      type "pubid:itu:report", "rpt"
+      type "pubid:itu:combined-identifier", "comb"
+      type "pubid:itu:question", "q"
+      type "pubid:itu:handbook", "hb"
+      type "pubid:itu:radio-regulations", "rr"
+      type "pubid:itu:special-publication", "sp"
+      type "pubid:itu:contribution", "c"
+      type "pubid:itu:identifier", "id"
+
+      type "pubid:itu:annex", "annex"
+      type "pubid:itu:annex-of-recommendation", "anx"
+      type "pubid:itu:appendix-of-recommendation", "app"
+      type "pubid:itu:supplement", "sup"
+      type "pubid:itu:amendment", "amd"
+      type "pubid:itu:corrigendum", "cor"
+      type "pubid:itu:addendum", "add"
+      type "pubid:itu:errata", "err"
+    end
+  end
+end

data/lib/pubid/itu.rb

@@ -23,6 +23,7 @@ module Pubid
     autoload :Identifier, "#{__dir__}/itu/identifiers/base"
     autoload :Identifiers, "#{__dir__}/itu/identifiers"
     autoload :Parser, "#{__dir__}/itu/parser"
+    autoload :PubidUrnSchema, "#{__dir__}/itu/pubid_urn_schema"
     autoload :UrnGenerator, "#{__dir__}/itu/urn_generator"
     autoload :UrnParser, "#{__dir__}/itu/urn_parser"
     autoload :Model, "#{__dir__}/itu/model"

data/lib/pubid/nist/CLAUDE.md

@@ -80,3 +80,16 @@ Read this before you change `lib/pubid/nist/` or `spec/pubid/nist/`. The root
   `to_short_style`: the publisher prefixes only when the input carried one
   (`NIST.`/`NBS.`), and a bare `FIPS 140-3` still renders `FIPS.140-3`.
   Locked by `spec/pubid/nist/identifiers/fips_spec.rb`.
+
+- **pubid-scheme URN (issue #656).** `lib/pubid/nist/pubid_urn_schema.rb`
+  covers all 22 types; rulings in `docs/URN-SCHEMES.adoc` (`[[urn-nist]]`).
+  `update` and `update_component` serialize every field, so each field is
+  its own atom (`upd-`, `updyear-`, `uc-` …); reducing them changes
+  `to_hash` and needs a `relaton-data-nist` re-crawl, so it was not done.
+  `publisher_was_parsed` (`false` for a bare `FIPS 140-3`),
+  `parsed_format`, `edition.original_prefix` and the bracketed
+  `translation` are facets. No pass fixture sets `publisher_was_parsed`,
+  `supplement.year_end` or the Integer `year`; the review found them by a
+  sweep of `full/` and the spec literals, so sweep those too when a schema
+  changes. Found in passing, not fixed:
+  `NIST.IR.8259Apt` parses as `NIST IR 8259(por)` and loses the `A`.

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