glossarist 2.13.11 → 2.13.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c65595f05c44c51808471afe8444211ea1f6dec412d8fe0ad74eee187b11b2
-  data.tar.gz: 9354da2e19de5935ed2e6415436f2b7344e8ad841520a7ee9b70be7c4ddd49da
+  metadata.gz: 5b15e9fa1ab722c42698d7b4f87a9517557aaeffbf44ed56907d20db28a678d3
+  data.tar.gz: 92743d7653a3a64f09da6098aea9308ca809db2a2ac4108766590cf5dbea791c
 SHA512:
-  metadata.gz: a2288cbc327785082b55fa370c622877e7dd41e90545edb8db7063e3fd29d57d974b040197fb015e4a83a6bc99f1ce44c583fbe692aced5b5f2251dbd542382d
-  data.tar.gz: 919ec57825c62a7749afce56ec9bf5f49e7f18a89d537c60290d92e6bf35b97eeb4118f40369e81119113ebf945b371d0fccc942d4416df14e31d2af2359bd7d
+  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/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.11"
+  VERSION = "2.13.12"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.11
+  version: 2.13.12
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model