coradoc 1.1.8 → 2.0.12

data/lib/coradoc/core_model/list_block.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a single item within a list
+    #
+    # A list item can contain:
+    # - Simple text content
+    # - A nested list
+    # - Child elements (paragraphs, blocks, etc.)
+    #
+    # Note: The nested_list attribute type is set after ListBlock is defined
+    # to avoid circular dependency issues.
+    #
+    # @example Simple list item
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "Item text"
+    #   )
+    #
+    # @example List item with nested list
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "Parent item",
+    #     nested_list: nested_list_block
+    #   )
+    class ListItem < Base
+      # @!attribute marker
+      #   @return [String, nil] the marker character(s) for this item
+      #     (e.g., '*', '**', '.', '..', '-')
+      attribute :marker, :string
+
+      # @!attribute content
+      #   @return [String, nil] text content of the list item
+      attribute :content, :string
+
+      # @!attribute nested_list
+      #   @return [ListBlock, nil] nested list within this item
+      #   Note: Typed as string initially, retyped after ListBlock defined
+      attribute :nested_list, :string
+
+      private
+
+      # Attributes to compare for semantic equivalence
+      #
+      # List items are semantically equivalent if they have the same
+      # content, nested list, and children, regardless of the specific
+      # marker used.
+      #
+      # @return [Array<Symbol>] list of comparable attributes
+      def comparable_attributes
+        %i[content nested_list children]
+      end
+    end
+
+    # Represents a list block with proper nesting support
+    #
+    # Handles all list types:
+    # - Unordered lists
+    # - Ordered lists
+    # - Description lists
+    #
+    # Lists can contain nested lists at multiple levels, with each level
+    # tracked through marker_level.
+    #
+    # @example Creating an unordered list
+    #   list = CoreModel::ListBlock.new(
+    #     marker_type: "unordered",
+    #     marker_level: 1,
+    #     items: [
+    #       ListItem.new(marker: "*", content: "First item"),
+    #       ListItem.new(marker: "*", content: "Second item")
+    #     ]
+    #   )
+    #
+    # @example Creating a nested list
+    #   nested = CoreModel::ListBlock.new(
+    #     marker_type: "unordered",
+    #     marker_level: 2,
+    #     items: [ListItem.new(marker: "**", content: "Nested item")]
+    #   )
+    #   list = CoreModel::ListBlock.new(
+    #     marker_type: "unordered",
+    #     marker_level: 1,
+    #     items: [
+    #       ListItem.new(
+    #         marker: "*",
+    #         content: "Parent item",
+    #         nested_list: nested
+    #       )
+    #     ]
+    #   )
+    class ListBlock < Base
+      # @!attribute marker_type
+      #   @return [String, nil] type of list marker
+      #     (e.g., 'unordered', 'ordered', 'definition')
+      attribute :marker_type, :string
+
+      # @!attribute marker_level
+      #   @return [Integer] nesting level of the list (default: 1)
+      attribute :marker_level, :integer, default: -> { 1 }
+
+      # @!attribute start
+      #   @return [Integer, nil] starting number for ordered lists
+      attribute :start, :integer
+
+      # @!attribute items
+      #   @return [Array<ListItem>] collection of list items
+      attribute :items, ListItem, collection: true
+
+      private
+
+      # Attributes to compare for semantic equivalence
+      #
+      # Lists are semantically equivalent if they have the same marker
+      # type and items, regardless of marker level (which is structural).
+      #
+      # @return [Array<Symbol>] list of comparable attributes
+      def comparable_attributes
+        super + %i[marker_type items]
+      end
+    end
+
+    # Re-open ListItem to properly type nested_list now that ListBlock
+    # is defined
+    class ListItem
+      # Remove the temporary string-typed attribute
+      remove_method :nested_list if method_defined?(:nested_list)
+      remove_method :nested_list= if method_defined?(:nested_list=)
+
+      # Re-define with proper ListBlock type
+      attribute :nested_list, ListBlock
+    end
+  end
+end

data/lib/coradoc/core_model/list_item.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Represents a list item
+    #
+    # List items can contain text content, nested lists, and attached blocks.
+    # They support various marker types and can have different nesting levels.
+    #
+    # @example Creating a simple list item
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "First item"
+    #   )
+    #
+    # @example Creating a list item with nested content
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "Item with nested list",
+    #     nested_list: nested_list_block,
+    #     children: [attached_block]
+    #   )
+    class ListItem < Base
+      attribute :children, Base, collection: true
+
+      include ChildrenContent
+
+      # @!attribute marker
+      #   @return [String] the list marker (*, -, 1., etc.)
+      attribute :marker, :string
+
+      # @!attribute content
+      #   @return [String] the text content of the list item
+      attribute :content, :string
+
+      # @!attribute children
+      #   @return [Array] array of attached blocks/elements (mixed content, via ChildrenContent)
+
+      # Initialize with optional nested structure support
+      # @param args [Hash] initialization arguments
+      def initialize(args = {})
+        # Support :nested as alias for :nested_list
+        args[:nested_list] = args.delete(:nested) if args.key?(:nested)
+        super
+      end
+
+      # Delegate nested to nested_list (lutaml attribute added by list_block.rb)
+      def nested
+        nested_list
+      end
+
+      # Set nested list
+      # @param value [ListBlock, nil] nested list block
+      def nested=(value)
+        self.nested_list = value
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] hash representation of the list item
+      def to_h
+        {
+          marker: marker,
+          content: content,
+          nested_list: nested&.to_h,
+          children: children&.map { |child| child.is_a?(CoreModel::TextContent) ? { text: child.text } : child.to_h }
+        }.compact
+      end
+
+      # Create from hash
+      #
+      # @param hash [Hash] hash representation
+      # @return [ListItem] new list item instance
+      def self.from_h(hash)
+        raw_children = hash[:children] || []
+        children = raw_children.map do |child|
+          if child.is_a?(Hash) && child.key?(:text)
+            CoreModel::TextContent.new(text: child[:text])
+          elsif child.is_a?(CoreModel::Base)
+            child
+          end
+        end.compact
+
+        new(
+          marker: hash[:marker],
+          content: hash[:content],
+          nested: hash[:nested_list],
+          children: children
+        )
+      end
+
+      # Override semantic equivalence to handle nested structures properly
+      def semantically_equivalent?(other)
+        return false unless other.is_a?(self.class)
+        return false unless content == other.content
+
+        # Compare nested lists if present
+        if nested || other.nested
+          return false if nested.nil? != other.nested.nil?
+          return false if nested && !lists_equivalent?(nested, other.nested)
+        end
+
+        # Compare children if present
+        if children || other.children
+          return false if children.nil? != other.children.nil?
+          return false if children && !arrays_equivalent?(children, other.children)
+        end
+
+        true
+      end
+
+      private
+
+      # Compare two list blocks for equivalence
+      def lists_equivalent?(list1, list2)
+        # Both should be ListBlock objects or compatible
+        return true if list1 == list2
+        return false if list1.nil? || list2.nil?
+
+        # Check if both are ListBlock instances
+        if list1.is_a?(Coradoc::CoreModel::ListBlock) &&
+           list2.is_a?(Coradoc::CoreModel::ListBlock)
+          list1.semantically_equivalent?(list2)
+        elsif list1.instance_of?(::Coradoc::CoreModel::ListBlock) &&
+              list2.instance_of?(::Coradoc::CoreModel::ListBlock)
+          # Serialized by Lutaml - compare as objects
+          list1.marker_type == list2.marker_type &&
+            list1.items.to_a == list2.items.to_a
+        else
+          list1 == list2
+        end
+      end
+
+      # Compare two arrays for equivalence
+      def arrays_equivalent?(arr1, arr2)
+        return false unless arr1.size == arr2.size
+
+        arr1.zip(arr2).all? { |a, b| a == b }
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/listing_block.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Listing block — a delimited block for listing/content without source language
+    #
+    # Distinct from SourceBlock: a listing has no language annotation.
+    # When a language is present, SourceBlock should be used instead.
+    class ListingBlock < Block
+      def self.semantic_type = :listing
+    end
+  end
+end

data/lib/coradoc/core_model/literal_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Literal block — a delimited block for preformatted literal text
+    class LiteralBlock < Block
+      def self.semantic_type = :literal
+    end
+  end
+end

data/lib/coradoc/core_model/metadata.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # A single metadata entry (key-value pair)
+    class MetadataEntry < Base
+      attribute :key, :string
+      attribute :value, :string
+    end
+
+    # Represents metadata associated with a document element
+    #
+    # Stores arbitrary key-value pairs for tracking source location,
+    # processing information, and other contextual data.
+    #
+    # @example
+    #   meta = Metadata.new
+    #   meta["source_line"] = 42
+    #   meta["parser_version"] = "1.0.0"
+    class Metadata < Base
+      attribute :entries, MetadataEntry, collection: true
+
+      # Get a metadata value by key
+      # @param key [String] The metadata key
+      # @return [String, nil] The value or nil if not found
+      def [](key)
+        return nil if entries.nil?
+
+        find_entry(key)&.value
+      end
+
+      # Set a metadata value
+      # @param key [String] The metadata key
+      # @param value [String] The value to set
+      def []=(key, value)
+        self.entries ||= []
+        existing = find_entry(key)
+        if existing
+          existing.value = value
+        else
+          entries << MetadataEntry.new(key: key, value: value)
+        end
+      end
+
+      # Check if a key exists
+      # @param key [String] The key to check
+      # @return [Boolean] True if key exists
+      def key?(key)
+        return false if entries.nil?
+
+        !find_entry(key).nil?
+      end
+
+      # Get all keys
+      # @return [Array<String>] List of keys
+      def keys
+        return [] if entries.nil?
+
+        entries.map(&:key)
+      end
+
+      # Convert to hash representation
+      # @return [Hash] Hash of all metadata entries
+      def to_h
+        return {} if entries.nil?
+
+        entries.each_with_object({}) { |entry, hash| hash[entry.key] = entry.value }
+      end
+
+      private
+
+      def find_entry(key)
+        return nil if entries.nil?
+
+        entries.find { |e| e.key == key }
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/open_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Open block — a generic container block with no special rendering
+    class OpenBlock < Block
+      def self.semantic_type = :open
+    end
+  end
+end

data/lib/coradoc/core_model/paragraph_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Paragraph block — a block of prose text
+    class ParagraphBlock < Block
+      def self.semantic_type = :paragraph
+    end
+  end
+end

data/lib/coradoc/core_model/pass_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Pass-through block — raw content passed through without processing
+    class PassBlock < Block
+      def self.semantic_type = :pass
+    end
+  end
+end

data/lib/coradoc/core_model/quote_block.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Quote block — a delimited block for quotations
+    class QuoteBlock < Block
+      def self.semantic_type = :quote
+
+      attribute :attribution, :string
+    end
+  end
+end

data/lib/coradoc/core_model/reviewer_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Reviewer comment block — a block for reviewer annotations
+    class ReviewerBlock < AnnotationBlock
+      def self.semantic_type = :reviewer
+    end
+  end
+end

data/lib/coradoc/core_model/sidebar_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Sidebar block — a delimited block for sidebars
+    class SidebarBlock < Block
+      def self.semantic_type = :sidebar
+    end
+  end
+end

data/lib/coradoc/core_model/source_block.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Specialized block for source code listings
+    class SourceBlock < Block
+      def self.semantic_type = :source_code
+    end
+  end
+end

data/lib/coradoc/core_model/structural_element.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Base class for structural elements
+    #
+    # Represents document structure elements that organize content.
+    # Typed subclasses (SectionElement, DocumentElement, etc.) express
+    # their role via the class hierarchy — the class IS the type.
+    #
+    # Structural elements can contain other elements (blocks, lists, etc.)
+    # and can be nested hierarchically to represent document structure.
+    class StructuralElement < Base
+      # @!attribute level
+      #   @return [Integer, nil] hierarchical level (1-6 for sections)
+      attribute :level, :integer
+
+      # @!attribute content
+      #   @return [String, nil] text content of the element
+      attribute :content, :string
+
+      # @!attribute children
+      #   @return [Array<Base>, nil] child elements (sections, blocks, etc.)
+      attribute :children, Base, collection: true
+
+      # @!attribute attributes
+      #   @return [Metadata, nil] document-level attributes (typed key-value pairs)
+      attribute :attributes, Metadata
+
+      def heading_level
+        level || 1
+      end
+
+      def section? = false
+      def document? = false
+      def preamble? = false
+      def header? = false
+
+      # Derived element_type string for backward compatibility with
+      # templates and legacy consumers. Subclasses override this.
+      def element_type
+        self.class.element_type_name
+      end
+
+      class << self
+        def element_type_name
+          nil
+        end
+      end
+
+      private
+
+      def comparable_attributes
+        [:title] + %i[level children]
+      end
+    end
+
+    # Root document element
+    class DocumentElement < StructuralElement
+      def document? = true
+
+      class << self
+        def element_type_name = 'document'
+      end
+    end
+
+    # Section with a heading at a specific level
+    class SectionElement < StructuralElement
+      def section? = true
+
+      class << self
+        def element_type_name = 'section'
+      end
+    end
+
+    # Preamble content before the first section heading
+    class PreambleElement < StructuralElement
+      def preamble? = true
+
+      class << self
+        def element_type_name = 'preamble'
+      end
+    end
+
+    # Header / title block of a document
+    class HeaderElement < StructuralElement
+      def header? = true
+
+      class << self
+        def element_type_name = 'header'
+      end
+    end
+  end
+end