glossarist 2.13.10 → 2.13.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16c44282632761dbbfeb3b63ff619b519648f0af7306ee5aa85fba1606244bd6
-  data.tar.gz: 37e8af5033c014195228ba11f50528b7aca8c06424533196ea0c318d5f78c7f0
+  metadata.gz: 5b15e9fa1ab722c42698d7b4f87a9517557aaeffbf44ed56907d20db28a678d3
+  data.tar.gz: 92743d7653a3a64f09da6098aea9308ca809db2a2ac4108766590cf5dbea791c
 SHA512:
-  metadata.gz: 8dadb718f3a39e49167eb1d8aa8eeada22f826c049be68dcfe151cd0980edb0e80006a51b21f64912dcc9e9d4ef21ff47618002b6d7d1496b88669cb39932620
-  data.tar.gz: 29f66da8f1f743c7f5424e966bf4b19a94e83264146d9c3156243f0f0a39e728874fcc4cbf6f2a2d8c77bd4799406083162d27b5f675dd1fe0aa88246091222d
+  metadata.gz: '02780e9a932c36e5d769d8645b37a36c372fabaa3acee9cc85760d5b6734013b524d0a41d06c9dbb06ace71aba2186797dd022f9f055fc761ffa5c605a42a7bb'
+  data.tar.gz: b41226d8877739287fafa314e1fd7b5be6574475e839dcff4a218f8a003a618549e0b01a89b7bc38a76d3a708390bd6b7a8f8d2f15afea62b181b41add392fc5

data/lib/glossarist/concept_ref.rb

@@ -4,39 +4,44 @@ module Glossarist
   # A typed reference to another concept, used inside n-ary relation
   # members and other internal pointer shapes.
   #
-  # The base ConceptRef carries `source`, `id`, and `text`. The richer
-  # `ConceptReference` (in `glossarist/concept_reference.rb`) extends
-  # this with `term`, `urn`, `version`, `ref_type` for use in
-  # cross-vocabulary references and relevance contexts.
+  # The base ConceptRef carries `source`, `id`, `text`, `external`, and
+  # `ellipsis`. The richer `ConceptReference` (in
+  # `glossarist/concept_reference.rb`) extends this with `term`, `urn`,
+  # `version`, `ref_type` for use in cross-vocabulary references and
+  # relevance contexts.
   #
   # A ConceptRef is identified by `source:id` for external references
   # or just `id` for local references. The `qualified_id` class method
   # is the single SSOT for this string format — used by RelationLoader,
   # the RDF transform, and ConceptRef-bearing data structures.
+  #
+  # == External concepts (parenthetical notation)
+  #
+  # ISO 704:2022 uses parenthetical notation for external concepts —
+  # concepts referenced from this dataset but defined elsewhere. The
+  # `external: true` flag marks such a ref. External refs carry `text`
+  # (the parenthetical label) but NOT `source`/`id`.
+  #
+  # == Ellipsis (structural marker)
+  #
+  # An ellipsis ref marks "further members exist but are not encoded."
+  # It is NOT a concept — it's a structural marker on the hyperedge.
+  # An ellipsis ref carries NO other fields (no source, id, text).
   class ConceptRef < Lutaml::Model::Serializable
     attribute :source, :string
     attribute :id, :string
     attribute :text, :string
+    attribute :external, :boolean, default: -> { false }
+    attribute :ellipsis, :boolean, default: -> { false }
 
     key_value do
       map :source, to: :source
       map :id, to: :id
       map :text, to: :text
+      map :external, to: :external
+      map :ellipsis, to: :ellipsis
     end
 
-    # SSOT for the canonical "qualified identifier" string of a
-    # ConceptRef. Returns:
-    #
-    #   - "{source}:{id}"         when both source and id are present
-    #   - "{id}"                  when only id is present (local ref)
-    #   - "{source}:{text}"       when source and text are present (no id)
-    #   - "{text}"                when only text is present (external
-    #                             concept form, no resolvable id)
-    #   - nil                     when the ref is empty / not a ConceptRef
-    #
-    # Two refs are considered to point at the same concept iff their
-    # qualified_id is equal. Tables and registries can use this
-    # directly as a hash key.
     def self.qualified_id(ref)
       return nil unless ref.is_a?(ConceptRef)
 
@@ -51,14 +56,50 @@ module Glossarist
       end
     end
 
-    # Per-instance convenience delegating to the class method.
     def qualified_id
       self.class.qualified_id(self)
     end
 
-    # True iff +other+ refers to the same concept as self.
     def same_concept?(other)
       qualified_id == self.class.qualified_id(other)
     end
+
+    def resolved?
+      !source.to_s.empty? && !id.to_s.empty?
+    end
+
+    def external?
+      external == true
+    end
+
+    def ellipsis?
+      ellipsis == true
+    end
+
+    def text_only?
+      !text.to_s.empty? && !resolved? && !external?
+    end
+
+    def validate_ref!
+      if ellipsis? && (source || id || text || external?)
+        raise ArgumentError,
+              "ConceptRef with ellipsis: true must not carry any " \
+              "other field (source, id, text, external)"
+      end
+
+      if external? && (source || id)
+        raise ArgumentError,
+              "ConceptRef with external: true must not carry " \
+              "source/id — use text for the parenthetical label"
+      end
+
+      if !source && !id && !text && !external? && !ellipsis?
+        raise ArgumentError,
+              "ConceptRef must have at least one of: source+id, text, " \
+              "external, or ellipsis"
+      end
+
+      self
+    end
   end
 end

data/lib/glossarist/mentions/invalid_mention_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    class InvalidMentionError < StandardError
+      attr_reader :raw, :reason, :position
+
+      def initialize(raw:, reason:, position: 0)
+        @raw = raw
+        @reason = reason
+        @position = position
+        super("Invalid mention at position #{position}: #{reason}")
+      end
+    end
+  end
+end

data/lib/glossarist/mentions/parser.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    # Scans a string for {{kind:target}} patterns and returns a mixed
+    # array of text segments and parsed mention objects.
+    #
+    # Invalid mentions raise InvalidMentionError — they are never
+    # silently passed through.
+    #
+    # @see concept-model docs/design/inline-mentions.md
+    module Parser
+      MENTION_REGEX = /\{\{([^}]+)\}\}/.freeze
+
+      KINDS = %w[concept cite fig table formula bib link image].freeze
+
+      module_function
+
+      # @param text [String] the source text to scan
+      # @return [Array<Hash>] segments — text and mention objects
+      # @raise [InvalidMentionError] on invalid mention syntax
+      def parse(text)
+        return [{ kind: "text", content: "" }] unless text.is_a?(String) && !text.empty?
+
+        segments = []
+        pos = 0
+
+        text.to_enum(:scan, MENTION_REGEX).each do |match|
+          raw_content = match[0]
+          match_start = Regexp.last_match.offset(0)[0]
+
+          if match_start > pos
+            segments << { kind: "text", content: text[pos...match_start] }
+          end
+
+          segment = parse_mention_content(
+            raw_content,
+            raw: "{{#{raw_content}}}",
+            position: match_start,
+          )
+          segments << segment
+          pos = Regexp.last_match.offset(0)[1]
+        end
+
+        segments << { kind: "text", content: text[pos..] } if pos < text.length
+        segments
+      end
+
+      def parse_mention_content(content, raw:, position:)
+        content = content.strip
+
+        unless content =~ /\A(\w+):(.*)\z/m
+          raise InvalidMentionError.new(
+            raw: raw,
+            position: position,
+            reason: "Missing kind prefix; use {{concept:DATASET:ID}} or " \
+                    "{{cite:DATASET:ID}} — got #{raw}",
+          )
+        end
+
+        kind = Regexp.last_match(1).downcase
+        rest = Regexp.last_match(2).strip
+
+        unless KINDS.include?(kind)
+          raise InvalidMentionError.new(
+            raw: raw,
+            position: position,
+            reason: "Unknown kind '#{kind}'; valid kinds: #{KINDS.join(', ')}",
+          )
+        end
+
+        target_str, label = split_target_and_label(rest)
+
+        target = parse_target(target_str, kind: kind, raw: raw, position: position)
+
+        validate_target!(kind, target, raw: raw, position: position)
+
+        {
+          kind: kind,
+          target: target,
+          label: strip_label(label),
+          raw: raw,
+          start: position,
+          end: position + raw.length,
+        }
+      end
+
+      def split_target_and_label(rest)
+        return [rest, nil] unless rest.include?(",")
+
+        parts = rest.split(",", 2)
+        [parts[0].strip, parts[1].to_s.strip]
+      end
+      private_class_method :split_target_and_label
+
+      def parse_target(target_str, kind:, raw:, position:)
+        case target_str
+        when /\Aurn:/i
+          { type: "urn", urn: target_str }
+        when /\Ahttps?:\/\//i
+          { type: "url", url: target_str }
+        when /\A[a-zA-Z][a-zA-Z0-9_-]*:[^:]+/
+          split_dataset_qualified(target_str)
+        when %r{\A[a-zA-Z0-9_./-]+\z}
+          if target_str.include?("/")
+            { type: "path", path: target_str }
+          else
+            { type: "entity_id", id: target_str }
+          end
+        else
+          { type: "entity_id", id: target_str }
+        end
+      end
+      private_class_method :parse_target
+
+      def split_dataset_qualified(target_str)
+        last_colon = target_str.rindex(":")
+        dataset = target_str[0...last_colon]
+        id = target_str[(last_colon + 1)..]
+        { type: "dataset_qualified", dataset: dataset, id: id }
+      end
+      private_class_method :split_dataset_qualified
+
+      def validate_target!(kind, target, raw:, position:)
+        type = target[:type]
+
+        case kind
+        when "concept", "cite"
+          unless %w[urn dataset_qualified].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "#{kind} target must be DATASET:ID or URN; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "fig", "table", "formula"
+          unless %w[entity_id urn].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "#{kind} target must be plain ID or URN; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "bib"
+          unless type == "entity_id"
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "bib target must be a plain ID (same-dataset); " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "link"
+          unless type == "url"
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "link target must be https:// or http:// URL; " \
+                      "got #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "image"
+          unless %w[path url].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "image target must be a path or URL; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        end
+      end
+      private_class_method :validate_target!
+
+      def target_value_for_error(target)
+        target[:urn] || target[:url] || target[:id] ||
+          target[:dataset] ? "#{target[:dataset]}:#{target[:id]}" : target[:path]
+      end
+      private_class_method :target_value_for_error
+
+      def strip_label(label)
+        label.nil? || label.empty? ? nil : label
+      end
+      private_class_method :strip_label
+    end
+  end
+end

data/lib/glossarist/mentions/resolver.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    # Resolves parsed mention segments against a resolution context.
+    # The context provides lookup callables; the resolver dispatches
+    # by mention kind + target type.
+    module Resolver
+      module_function
+
+      # @param mention [Hash] a parsed mention from Parser.parse
+      # @param context [Hash] resolution context with lookup callables
+      # @return [Hash] resolved mention with :status
+      def resolve(mention, context)
+        return mention if mention[:kind] == "text"
+
+        case mention[:kind]
+        when "concept", "cite"
+          resolve_concept(mention, context)
+        when "fig", "table", "formula"
+          resolve_entity(mention, context)
+        when "bib"
+          resolve_bib(mention, context)
+        when "link"
+          { status: "external", kind: "link",
+            url: mention[:target][:url], label: mention[:label] }
+        when "image"
+          resolve_image(mention)
+        else
+          { status: "unresolved", kind: mention[:kind],
+            target: mention[:target], label: mention[:label] }
+        end
+      end
+
+      def resolve_all(mentions, context)
+        mentions.map { |m| resolve(m, context) }
+      end
+
+      def resolve_concept(mention, context)
+        target = mention[:target]
+        concept = lookup_concept(target, context)
+
+        return unresolved(mention) unless concept
+
+        result = {
+          status: "resolved",
+          kind: mention[:kind],
+          concept: concept,
+          label: mention[:label],
+        }
+
+        if mention[:kind] == "cite" && context[:concept]
+          result[:source] = find_matching_source(target, context[:concept])
+        end
+
+        result
+      end
+      private_class_method :resolve_concept
+
+      def resolve_entity(mention, context)
+        target = mention[:target]
+        entity = nil
+
+        case target[:type]
+        when "entity_id"
+          resolver = context[:resolve_entity]
+          entity = resolver&.call(mention[:kind], target[:id]) if resolver
+        when "urn"
+          entity = nil
+        end
+
+        if entity
+          { status: "resolved", kind: mention[:kind],
+            entity: entity, label: mention[:label] }
+        else
+          unresolved(mention)
+        end
+      end
+      private_class_method :resolve_entity
+
+      def resolve_bib(mention, context)
+        target = mention[:target]
+        entry = context[:resolve_bib_entry]&.call(target[:id])
+
+        if entry
+          { status: "resolved", kind: "bib",
+            entry: entry, label: mention[:label] }
+        else
+          unresolved(mention)
+        end
+      end
+      private_class_method :resolve_bib
+
+      def resolve_image(mention)
+        target = mention[:target]
+        if target[:type] == "url"
+          { status: "external_image", kind: "image",
+            url: target[:url], label: mention[:label] }
+        else
+          { status: "local_image", kind: "image",
+            path: target[:path], label: mention[:label] }
+        end
+      end
+      private_class_method :resolve_image
+
+      def lookup_concept(target, context)
+        resolver = context[:resolve_concept]
+        return nil unless resolver
+
+        case target[:type]
+        when "dataset_qualified"
+          resolver.call(dataset: target[:dataset], id: target[:id])
+        when "urn"
+          resolver.call(urn: target[:urn])
+        end
+      end
+      private_class_method :lookup_concept
+
+      def find_matching_source(target, concept)
+        sources = concept.respond_to?(:data) ? concept.data&.sources : concept.sources
+        return nil unless sources
+
+        case target[:type]
+        when "dataset_qualified"
+          sources.find do |s|
+            next unless s.respond_to?(:origin) && s.origin.respond_to?(:ref)
+            ref = s.origin.ref
+            ref && ref.source == target[:dataset] && ref.id == target[:id]
+          end
+        when "urn"
+          nil
+        end
+      end
+      private_class_method :find_matching_source
+
+      def unresolved(mention)
+        { status: "unresolved", kind: mention[:kind],
+          target: mention[:target], label: mention[:label] }
+      end
+      private_class_method :unresolved
+    end
+  end
+end

data/lib/glossarist/mentions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Inline mentions — fully declarative {{kind:target}} syntax per
+  # concept-model docs/design/inline-mentions.md.
+  #
+  # Every mention target is a CANONICAL IDENTIFIER. No magic
+  # combinations, no bare text, no procedural indirection. The parser
+  # REJECTS any non-declarative form with a clear error.
+  module Mentions
+    autoload :InvalidMentionError, "glossarist/mentions/invalid_mention_error"
+    autoload :Parser,              "glossarist/mentions/parser"
+    autoload :Resolver,            "glossarist/mentions/resolver"
+  end
+end

data/lib/glossarist/v3/abstract_hyperedge.rb

@@ -89,8 +89,10 @@ module Glossarist
       # Consumers inject the resolver at query time.
 
       # True if the comprehensive resolves (via the supplied resolver)
-      # to a concept with status: external.
+      # to a concept with status: external. Also true when the
+      # comprehensive ConceptRef itself has external: true (inline form).
       def external_comprehensive?(resolver = nil)
+        return true if comprehensive.is_a?(ConceptRef) && comprehensive.external?
         return false unless comprehensive.is_a?(ConceptRef)
         return false unless resolver
 
@@ -98,8 +100,8 @@ module Glossarist
         concept_is_external?(concept)
       end
 
-      # Array of members whose refs resolve to status: external.
-      # Empty when no resolver is supplied (detection is opt-in).
+      # Array of members whose refs are marked external: true (inline
+      # form) OR resolve (via the supplied resolver) to status: external.
       def external_members(resolver = nil)
         return [] unless resolver
 
@@ -125,6 +127,33 @@ module Glossarist
         candidates.any? { |ref| !has_provided_by?(ref, resolver) }
       end
 
+      # ── Ellipsis / external inline helpers (no resolver needed) ──
+
+      # True if any member has a ConceptRef with external: true.
+      def has_external_members?
+        members.any? { |m| m.is_a?(HyperedgeMember) && m.ref&.external? }
+      end
+
+      # True if the comprehensive ConceptRef has external: true.
+      def has_external_comprehensive?
+        comprehensive.is_a?(ConceptRef) && comprehensive.external?
+      end
+
+      # True if any member has a ConceptRef with ellipsis: true.
+      def has_ellipsis_member?
+        members.any? { |m| m.is_a?(HyperedgeMember) && m.ref&.ellipsis? }
+      end
+
+      # Array of members whose refs are marked external: true.
+      def inline_external_members
+        members.select { |m| m.is_a?(HyperedgeMember) && m.ref&.external? }
+      end
+
+      # Array of members whose refs are marked ellipsis: true.
+      def ellipsis_members
+        members.select { |m| m.is_a?(HyperedgeMember) && m.ref&.ellipsis? }
+      end
+
       # Per-file identity derived from comprehensive + criterion.
       # Format: `<comprehensive-id-dir>/<criterion-slug>` where the
       # dir is `<source>-<id>` (downcased, kebab-case) and the slug

data/lib/glossarist/v3/hyperedge_writer.rb

@@ -68,7 +68,7 @@ module Glossarist
         hash = hyperedge.to_hash
         hash["$id"] = hyperedge.file_id || hyperedge.derived_file_id
         hash["type"] = hyperedge.class::TYPE_TAG
-        # Re-order for stable output.
+        strip_falsey_concept_ref_flags!(hash)
         ordered = {}
         ordered["$id"]         = hash.delete("$id")
         ordered["type"]        = hash.delete("type")
@@ -79,11 +79,28 @@ module Glossarist
         ordered["criterion"]   = hash.delete("criterion") if hash.key?("criterion")
         ordered["sources"]     = hash.delete("sources") if hash.key?("sources")
         ordered["notes"]       = hash.delete("notes") if hash.key?("notes")
-        ordered.merge!(hash) # any future fields append in declaration order
+        ordered.merge!(hash)
+        strip_falsey_concept_ref_flags!(ordered)
         ordered.compact!
 
         YAML.dump(ordered).gsub(/^---\s*\n/, "---\n")
       end
+
+      # Recursively strip `external: false` and `ellipsis: false` from
+      # ConceptRef hashes inside the hyperedge's wire output. Keeps
+      # YAML clean — these flags only appear when true.
+      def strip_falsey_concept_ref_flags!(hash)
+        hash.each_value do |value|
+          case value
+          when Hash
+            value.delete("external") if value["external"] == false
+            value.delete("ellipsis") if value["ellipsis"] == false
+            strip_falsey_concept_ref_flags!(value)
+          when Array
+            value.each { |item| strip_falsey_concept_ref_flags!(item) if item.is_a?(Hash) }
+          end
+        end
+      end
     end
   end
 end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.13.10"
+  VERSION = "2.13.12"
 end

data/lib/glossarist.rb

@@ -65,8 +65,7 @@ module Glossarist
   autoload :ManagedConcept,           "glossarist/managed_concept"
   autoload :ManagedConceptCollection, "glossarist/managed_concept_collection"
   autoload :ManagedConceptData,       "glossarist/managed_concept_data"
-  autoload :MentionParser,            "glossarist/mention_parser"
-  autoload :MentionKinds,             "glossarist/mention_parser"
+  autoload :Mentions,                "glossarist/mentions"
   autoload :NonVerbRep,               "glossarist/non_verb_rep"
   autoload :Pronunciation,            "glossarist/pronunciation"
   autoload :RelatedConcept,           "glossarist/related_concept"
@@ -109,12 +108,11 @@ module Glossarist
     end
   end
 
-  # Parse a single {{...}} mention into a canonical Hash. Defined here
-  # (rather than via autoload) so calling Glossarist.parse_mention(str)
-  # triggers the MentionParser autoload chain transparently — method
-  # calls do not fire autoloads on their own.
-  def self.parse_mention(text)
-    MentionParser.parse_mention(text)
+  # Parse all {{kind:target}} mentions in text. Returns an array of
+  # segments (text + mention objects) per concept-model inline-mentions spec.
+  # @see Glossarist::Mentions::Parser.parse
+  def self.parse_mentions(text)
+    Mentions::Parser.parse(text)
   end
 
   SCHEMA_VERSION = "3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.10
+  version: 2.13.12
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -293,6 +293,10 @@ files:
 - lib/glossarist/managed_concept_collection.rb
 - lib/glossarist/managed_concept_data.rb
 - lib/glossarist/mention_parser.rb
+- lib/glossarist/mentions.rb
+- lib/glossarist/mentions/invalid_mention_error.rb
+- lib/glossarist/mentions/parser.rb
+- lib/glossarist/mentions/resolver.rb
 - lib/glossarist/non_concept_entity.rb
 - lib/glossarist/non_verb_rep.rb
 - lib/glossarist/non_verbal_reference.rb