pubid 2.0.4 → 2.0.6

data/lib/pubid/iho/identifiers/base.rb

@@ -6,10 +6,17 @@ module Pubid
     # every concrete IHO identifier (Identifiers::*) descends from it.
     #
     # IHO identifiers have the form:
-    #   IHO {S|P|M|B|C}-{number}[ Ap. {appendix}][ Part {part}][ Annex {annex}][ Suppl {supplement}][ {version|year|Vol. N [issue]}]
+    #   IHO {S|P|M|B|C}-{number}[ {edition}| Vol. N [(issue)]]
+    #       [ Sup N][ Part X][ Annex A][ Appendix B[-2]] [(2024)]
     #
-    # The leading IHO publisher prefix is optional on input but always
-    # emitted on output.
+    # Every tail component is a first-class semantic component: a typed
+    # attribute, independently addressable, URN-encodable and matchable.
+    # The canonical faces order the edition BEFORE the part
+    # (`IHO S-100 1.0.0 Part 2`), print the supplement as "Sup" and the
+    # appendix as "Appendix" (with the subnumber after a dash), the
+    # volume issue parenthesized (`IHO P-1 Vol. 30 (2)`), and the
+    # with-year qualifier parenthesized (`IHO S-100 5.0.0 Part 2 (2024)`
+    # — the only year face: a periodical year IS a volume).
     class Identifier < ::Pubid::Identifier
       # Parse an IHO identifier string into an identifier object
       # @param identifier [String] The IHO identifier string to parse
@@ -25,32 +32,55 @@ module Pubid
           raise Pubid::Errors::InvalidInputError, Pubid::INPUT_TOO_LONG_MESSAGE
         end
 
-        parsed = Pubid::Parg::Backend.parse(:iho, identifier.strip)
+        parsed = Pubid::Parg::Model.bound(:iho, identifier.strip)
         Builder.build(parsed)
       end
 
       # `number` overrides the generic Components::Code attribute with a plain
-      # string (same pattern as `part` below); it holds the IHO document
-      # number (e.g. "100", "1/21"). Kept as the generic `number` so the
-      # relaton index sorts/binary-searches on it natively via `id.number`.
+      # string (same pattern as the other string components); it holds the IHO
+      # document number (e.g. "100", "1/21" until the slash-chain volume
+      # parse, "158:100"). Kept as the generic `number` so the relaton index
+      # sorts/binary-searches on it natively via `id.number`.
       attribute :number,     :string
       attribute :publisher,  :string, default: "IHO"
-      attribute :appendix,   :string
-      attribute :part,       :string
-      attribute :annex,      :string
-      attribute :supplement, :string
-      attribute :version,    :string
-      # Series identity components (relaton#407): the year-identified
-      # series (B-7, P-5, P-6) and the volume/issue-identified ones
-      # (P-1 and the IHR) carry no a.b.c edition — their trailing
-      # component is a year or a "Vol. N [issue]" pair instead. Plain
-      # scalars, like every other IHO attribute; the grammar's tail
-      # picks exactly one discriminator, so only one of
-      # version/year/volume is ever present, with issue only
-      # alongside volume.
+      # The official IHO edition is the dotted x.y.z (a plain string — the
+      # ~16 string-edition flavors precede this). `IHO S-100 1.0.0` is
+      # edition-specific, `IHO S-100` edition-non-specific; a year beside an
+      # edition is the with-year qualifier, never a year-keyed docidentifier.
+      attribute :edition,    :string
+      # The with-year qualifier on standards (`(2024)` beside an edition) —
+      # the only year component. A periodical year IS a volume: the bare
+      # legacy year input ("IHO P-5 2024") binds into `volume`, so this
+      # attribute never carries a serial locator.
       attribute :year,       :string
+      # Supplement, part, annex, appendix and volume are independently
+      # publishable (owner ruling: "this can happen with any independently
+      # publishable artifacts"), so each carries an optional edition (+ year
+      # qualifier) of its own, mutually exclusive with the base edition
+      # context: `IHO P-6 1.0.0 Vol. 2` (within-edition) vs
+      # `IHO P-6 Vol. 2 1.0.1` (separately-published). The URN attaches
+      # ed- to the node it follows, so one positional slot records both.
+      attribute :supplement, :string
+      attribute :supplement_edition, :string
+      attribute :supplement_year,    :string
+      attribute :part, :string
+      attribute :part_edition, :string
+      attribute :part_year,    :string
+      attribute :annex, :string
+      attribute :annex_edition, :string
+      attribute :annex_year,    :string
+      # The appendix is a letter or a number; a subnumbered appendix
+      # ("Appendix D-2") keeps the letter in `appendix` and the "2" in
+      # `appendix_subnumber` — two independently addressable components,
+      # not one string.
+      attribute :appendix, :string
+      attribute :appendix_subnumber, :string
+      attribute :appendix_edition,   :string
+      attribute :appendix_year,      :string
       attribute :volume,     :string
       attribute :issue,      :string
+      attribute :volume_edition, :string
+      attribute :volume_year,    :string
 
       # Polymorphic type map for lutaml::Model key_value serialization: maps
       # each subclass's polymorphic_name to its class name so `from_hash` can
@@ -71,31 +101,98 @@ module Pubid
       key_value do
         map "_type",      to: :_type, polymorphic_map: IHO_TYPE_MAP
         map "number",     to: :number
-        map "appendix",   to: :appendix
-        map "part",       to: :part
-        map "annex",      to: :annex
-        map "supplement", to: :supplement
-        map "version",    to: :version
+        map "edition",    to: :edition
         map "year",       to: :year
-        map "volume",     to: :volume
-        map "issue",      to: :issue
+        map "supplement",         to: :supplement
+        map "supplement_edition", to: :supplement_edition
+        map "supplement_year",    to: :supplement_year
+        map "part",               to: :part
+        map "part_edition",       to: :part_edition
+        map "part_year",          to: :part_year
+        map "annex",              to: :annex
+        map "annex_edition",      to: :annex_edition
+        map "annex_year",         to: :annex_year
+        map "appendix",           to: :appendix
+        map "appendix_subnumber", to: :appendix_subnumber
+        map "appendix_edition",   to: :appendix_edition
+        map "appendix_year",      to: :appendix_year
+        map "volume",             to: :volume
+        map "volume_edition",     to: :volume_edition
+        map "volume_year",        to: :volume_year
+        map "issue",              to: :issue
       end
 
       # from_hash is the shared polymorphic dispatch on Pubid::Identifier.
-      # IHO_TYPE_MAP remains as the key_value polymorphic_map.
-
-      # The volume/issue pair is a scalar cluster: a reference that omits
-      # the issue must still match a hit that carries one ("P-1 Vol. 30"
-      # vs "P-1 Vol. 30 (2)"), so excluding the volume nils the issue
-      # with it — the same additive-alias shape the base applies to
-      # :year -> :date. A lone scalar :year needs no override here: the
-      # base nils a declared :year directly (the additive :year -> :date
-      # alias nils whichever name the flavor declares).
+      # IHO_TYPE_MAP remains the key_value polymorphic_map.
+
+      # The volume/issue and appendix/subnumber pairs are scalar clusters:
+      # a reference that omits the finer component must still match a hit
+      # that carries one ("P-1 Vol. 30" vs "P-1 Vol. 30 (2)"), so excluding
+      # the coarser component nils the finer one with it — the same
+      # additive-alias shape the base applies to :year -> :date. A lone
+      # scalar :year needs no override here: the base nils a declared :year
+      # directly (the additive :year -> :date alias nils whichever name the
+      # flavor declares).
       def exclude(*args)
+        args = args.dup
         args << :issue if args.include?(:volume)
+        args << :appendix_subnumber if args.include?(:appendix)
         super
       end
-    end
 
+      # Render the compact face: the code-adjacent components folded onto
+      # the code with separators — the supplement and the part hyphenated
+      # (`IHO M-2-2` for `IHO M-2 Sup 2`, `IHO S-5-B` for `IHO S-5 Part B`,
+      # `IHO S-100-1` for `IHO S-100 Part 1`) and the volume as the slash
+      # chain (`IHO P-5/2024` for `IHO P-5 Vol. 2024`). The canonical
+      # render stays expanded; compact is opt-in. The legacy faces (glued
+      # lettered bases, Suppl, bare years) parse but are never rendered in
+      # any form.
+      def render(format: :human, **opts)
+        compact = opts.delete(:compact)
+        result = super
+        compact && format == :human ? compact_face(result) : result
+      end
+
+      # The shared mr_string path reads `edition&.number` (the base
+      # declares edition as Components::Edition); IHO's edition is a plain
+      # string, so the segment is built from it directly.
+      def mr_edition
+        return nil unless edition
+
+        "ed#{edition}"
+      end
+
+      private
+
+      # Fold " Sup N" / " Part X" / " Vol. N" into the code as "-N" /
+      # "-X" / "/N", keeping everything else in place (the edition
+      # follows the compact code, as in the legacy "S-5A 1.0.2" print
+      # order). The issue keeps its parenthesized print.
+      def compact_face(rendered)
+        result = rendered.sub(/\A#{publisher} #{base_code}(?= |$)/,
+                              "#{publisher} #{compact_code}")
+        folded_segments.each { |segment| result = result.sub(segment, "") }
+        result
+      end
+
+      def base_code
+        "#{self.class.type[:short]}-#{number}"
+      end
+
+      def compact_code
+        code = base_code.dup
+        code << "-#{supplement}" if supplement
+        code << "-#{part}" if part
+        code << "/#{volume}" if volume
+        code
+      end
+
+      def folded_segments
+        [supplement && " Sup #{supplement}",
+         part && " Part #{part}",
+         volume && " Vol. #{volume}"].compact
+      end
+    end
   end
 end

data/lib/pubid/iho/renderer.rb

@@ -4,33 +4,55 @@ module Pubid
   module Iho
     # Human-readable renderer for IHO identifiers.
     #
-    # Produces strings like:
-    #   "IHO S-44 5.0.0"
-    #   "IHO P-1/21 1.0.0"
-    #   "IHO S-100 Part 4a 1.0.0"
-    #   "IHO S-65 Ap. A 1.0.0"
-    #   "IHO P-5 2024"            (year-identified series)
-    #   "IHO P-1 Vol. 30 (2)"     (volume/issue-identified series)
+    # Canonical faces (owner rulings, 2026-11-03):
+    #   "IHO S-100"                     undated (edition-non-specific)
+    #   "IHO S-100 1.0.0"               dated (edition-specific)
+    #   "IHO S-100 5.0.0 Part 2"        edition BEFORE the part
+    #   "IHO S-98 1.0.0 Part A Annex B"
+    #   "IHO S-122 1.0.0 Appendix D-2"  canonical Appendix, subnumber
+    #                                   joined by a dash
+    #   "IHO M-2 Sup 1"                 canonical Sup (Suppl is an input
+    #                                   alias)
+    #   "IHO P-1 Vol. 30 (2)"           volume-keyed series (P-1, P-6)
+    #   "IHO P-5 Vol. 2024"             the yearbook year IS a volume
+    #   "IHO S-100 5.0.0 Part 2 (2024)" the with-year qualifier: a year
+    #                                   beside an edition is the date
+    #                                   qualifier on standards,
+    #                                   parenthesized — the only year face
     #
     # The renderer is registered as the `:human` format in the IHO format
-    # registry and invoked via `render(format: :human)`.
+    # registry and invoked via `render(format: :human)`; the compact face
+    # (`IHO S-100-1 5.0.0`, `IHO M-2-2`, `IHO P-5/2024`) is the opt-in
+    # `compact: true` flag, and `with_publisher: false` drops the leading
+    # publisher as everywhere else. The legacy faces (glued lettered
+    # bases, Suppl, bare years) parse but are never rendered.
     class Renderer < ::Pubid::Renderers::Base
+      # The canonical component faces in print order: edition BEFORE the
+      # part; each independently-publishable component carries its own
+      # edition (+ parenthesized year) right after it; the appendix joins
+      # its subnumber; the issue rides parenthesized after its volume;
+      # the base year prints only as the parenthesized with-year
+      # qualifier.
+      FACES = [
+        [:edition, " %s"],
+        [:supplement, " Sup %s"], [:supplement_edition, " %s"],
+        [:supplement_year, " (%s)"],
+        [:part, " Part %s"], [:part_edition, " %s"], [:part_year, " (%s)"],
+        [:annex, " Annex %s"], [:annex_edition, " %s"], [:annex_year, " (%s)"],
+        [:appendix, " Appendix %s"], [:appendix_subnumber, "-%s"],
+        [:appendix_edition, " %s"], [:appendix_year, " (%s)"],
+        [:volume, " Vol. %s"], [:issue, " (%s)"],
+        [:volume_edition, " %s"], [:volume_year, " (%s)"],
+        [:year, " (%s)"]
+      ].freeze
+
       def render(context: nil, **opts)
         id = @id
-
-        letter = id.class.type[:short]
-        rendered = "#{id.publisher} #{letter}-#{id.number}"
-        rendered << " Ap. #{id.appendix}" if id.appendix
-        rendered << " Part #{id.part}" if id.part
-        rendered << " Annex #{id.annex}" if id.annex
-        rendered << " Suppl #{id.supplement}" if id.supplement
-        # The grammar's tail picks exactly one discriminator: a dotted
-        # version, a year, or a volume (with an optional issue). The
-        # issue prints parenthesized; "Issue N" is an input alias only.
-        rendered << " #{id.version}" if id.version
-        rendered << " #{id.year}" if id.year
-        rendered << " Vol. #{id.volume}" if id.volume
-        rendered << " (#{id.issue})" if id.issue
+        rendered = "#{id.publisher} #{id.class.type[:short]}-#{id.number}"
+        FACES.each do |component, face|
+          value = id.public_send(component)
+          rendered << (face % value) if value
+        end
         rendered
       end
     end

data/lib/pubid/iho/urn_generator.rb

@@ -4,16 +4,33 @@ module Pubid
   module Iho
     # Generates URN strings for IHO identifiers.
     #
-    # Format: urn:iho:{type-letter-lowercase}:{number}[:ap.{appendix}][:part.{part}][:annex.{annex}][:suppl.{supplement}][:vol.{volume}[:issue.{issue}]][:{version}][:y.{year}]
-    # Example: urn:iho:s:44:5.0.0 for "IHO S-44 5.0.0".
-    # Only the dotted version is a bare segment. A year is tagged
-    # ("urn:iho:p:5:y.2024" for "IHO P-5 2024"), and so is a volume with
-    # its optional issue ("urn:iho:p:1:vol.30:issue.2" for
-    # "IHO P-1 Vol. 30 (2)").
+    # The URN is the documented positional segment grammar (see the
+    # grammar header in pubid-grammar's grammars/iho.parg and the flavor
+    # notes): containment-ordered, one semantic atom per segment, every
+    # non-number component a marker-prefixed segment whose marker is the
+    # lowercased human-face token (edition follows ISO's ed- precedent):
     #
-    # The number is not escaped, so "IHO S-158:100" gives
-    # "urn:iho:s:158:100". A bare year would then make "IHO S-158:2024"
-    # and "IHO S-158 2024" share one URN; the y. tag keeps them apart.
+    #   urn:iho:<type>:<number>[:ed-<x.y.z>][:sup-<n>][:part-<X>]
+    #     [:annex-<A>][:appendix-<B>][:<sub>][:vol-<n>][:issue-<n>]
+    #     [:year-<yyyy>]
+    #
+    # Containment: part contains annexes, annex contains appendices, the
+    # subnumber is a child atom of its appendix, the issue a child of its
+    # volume. Letters are case-preserved. The volume carries every serial
+    # locator — the yearbook year IS a volume (P-5 Vol. 2024 gives
+    # vol-2024), so a periodical identifier has no year segment; the
+    # year- segment exists only for the standards with-year qualifier.
+    # Both are marker-tagged so neither can collide with a colon-number
+    # segment (the number is not escaped and may span bare segments:
+    # "IHO S-158:100" gives "urn:iho:s:158:100").
+    #
+    # Examples:
+    # - urn:iho:s:44:ed-5.0.0                     IHO S-44 5.0.0
+    # - urn:iho:s:100:ed-5.0.0:part-2:year-2024   IHO S-100 5.0.0 Part 2 (2024)
+    # - urn:iho:s:122:ed-1.0.0:appendix-D:2       IHO S-122 1.0.0 Appendix D-2
+    # - urn:iho:m:2:sup-1                         IHO M-2 Sup 1
+    # - urn:iho:p:5:vol-2024                      IHO P-5 Vol. 2024
+    # - urn:iho:p:1:vol-30:issue-2                IHO P-1 Vol. 30 (2)
     class UrnGenerator
       attr_reader :identifier
 
@@ -21,22 +38,42 @@ module Pubid
         @identifier = identifier
       end
 
+      # [component, marker] pairs in the containment/canonical-face
+      # order. A component edition/year emits right after its component
+      # (the ed- segment attaches to the node it follows, recording the
+      # separately-published mode). nil markers emit their component as
+      # a BARE atom (the appendix subnumber directly after its
+      # appendix).
+      SEGMENTS = [
+        [:edition, "ed"], [:year, "year"],
+        [:supplement, "sup"], [:supplement_edition, "ed"],
+        [:supplement_year, "year"],
+        [:part, "part"], [:part_edition, "ed"], [:part_year, "year"],
+        [:annex, "annex"], [:annex_edition, "ed"], [:annex_year, "year"],
+        [:appendix, "appendix"], [:appendix_subnumber, nil],
+        [:appendix_edition, "ed"], [:appendix_year, "year"],
+        [:volume, "vol"], [:issue, "issue"], [:volume_edition, "ed"],
+        [:volume_year, "year"]
+      ].freeze
+
       def generate
         parts = ["urn", "iho"]
         parts << identifier.class.type[:short].to_s.downcase
         parts << identifier.number.to_s
-        parts << "ap.#{identifier.appendix}"     if identifier.appendix
-        parts << "part.#{identifier.part}"       if identifier.part
-        parts << "annex.#{identifier.annex}"     if identifier.annex
-        parts << "suppl.#{identifier.supplement}" if identifier.supplement
-        # The grammar's tail picks exactly one discriminator; a volume
-        # may carry an issue beside it.
-        parts << "vol.#{identifier.volume}"      if identifier.volume
-        parts << "issue.#{identifier.issue}"     if identifier.issue
-        parts << identifier.version.to_s if identifier.version
-        parts << "y.#{identifier.year}" if identifier.year
+        parts.concat(component_segments)
         parts.join(":")
       end
+
+      private
+
+      def component_segments
+        SEGMENTS.filter_map do |component, marker|
+          value = identifier.public_send(component)
+          next unless value
+
+          marker ? "#{marker}-#{value}" : value.to_s
+        end
+      end
     end
   end
 end