coradoc-adoc 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c26d9ebfcf6853d33150a149234dbb84d35fa07afe3cba77894fa6bcc96dc0cd
+  data.tar.gz: d9208da701b03723fedcbe52bc40dad2c7c880fbc48d2817e309a7fdfd439d35
+SHA512:
+  metadata.gz: 0c10a653ea35637819bd299247cfa100793dc16ec9a02e4c9d96e4e54dbf8f6d38fd053feab58e8849a5b06d4cf24c2b9a97fd29048e584e76ca1a732cbb0628
+  data.tar.gz: 76fb17f26249012cc48d581cb4dce02ffee066260d41cd010b7bcf8f2c7bfa46ac4ef83330d5d14d568099b059abf2cb910d19b397d4b12401833bb4867a0282

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/lib/coradoc/asciidoc/model/admonition.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Admonition block for AsciiDoc documents.
+      #
+      # Admonitions are special callout boxes that highlight important
+      # information: NOTE, TIP, WARNING, CAUTION, IMPORTANT.
+      #
+      # @!attribute [r] content
+      #   @return [String] The admonition text content
+      #
+      # @!attribute [r] type
+      #   @return [String] The admonition type (e.g., "NOTE", "TIP", "WARNING")
+      #
+      # @!attribute [r] line_break
+      #   @return [String] Line break character (default: "")
+      #
+      # @example Create a note admonition
+      #   admonition = Coradoc::AsciiDoc::Model::Admonition.new
+      #   admonition.type = "NOTE"
+      #   admonition.content = "This is important information"
+      #
+      # @example Create a warning admonition
+      #   admonition = Coradoc::AsciiDoc::Model::Admonition.new
+      #   admonition.type = "WARNING"
+      #   admonition.content = "Be careful!"
+      #
+      class Admonition < Attached
+        attribute :content, :string
+        attribute :type, :string
+        attribute :line_break, :string, default: -> { '' }
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/anchorable.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Mixin for elements that can have anchors (IDs and references).
+      #
+      # The Anchorable module provides functionality for elements that can
+      # be referenced from other parts of the document. It automatically
+      # creates an Inline::Anchor based on the element's id attribute.
+      #
+      # @example Including Anchorable in a class
+      #   class MyElement < Coradoc::AsciiDoc::Model::Base
+      #     include Coradoc::AsciiDoc::Model::Anchorable
+      #     attribute :id, :string
+      #   end
+      #
+      # @example Using the generated anchor
+      #   element = MyElement.new(id: "section1")
+      #   element.anchor.to_adoc # => "[[section1]]"
+      #
+      module Anchorable
+        # Hook called when module is included in a class
+        #
+        # Automatically adds the :anchor attribute to the including class.
+        #
+        # @param base [Class] The class including this module
+        def self.included(base)
+          base.class_eval do
+            attribute :anchor, :string
+          end
+        end
+
+        # Override initialize to set default anchor
+        def initialize(*args)
+          super
+          @anchor ||= default_anchor
+        end
+
+        # Generate the default anchor based on the element's id
+        #
+        # @return [String, nil] The anchor string, or nil if no id
+        def default_anchor
+          id.nil? ? nil : "[[#{id}]]"
+        end
+
+        # Generate the anchor string for serialization
+        #
+        # @param inline [Boolean] If true, don't add trailing newline
+        # @return [String] The serialized anchor string
+        def gen_anchor(inline: false)
+          return '' if anchor.nil?
+
+          anchor_str = anchor.to_adoc
+          if anchor_str.empty?
+            ''
+          else
+            "#{anchor_str}#{inline ? '' : "\n"}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/attached.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Base class for attached elements in AsciiDoc documents.
+      #
+      # Attached elements are those that can be attached to other elements
+      # such as list items or blocks. They include admonitions, paragraphs,
+      # and other block types.
+      #
+      # This class provides the foundation for elements that can be
+      # "attached" to parent elements in the document structure.
+      #
+      # @see Coradoc::AsciiDoc::Model::Admonition
+      # @see Coradoc::AsciiDoc::Model::Paragraph
+      # @see Coradoc::AsciiDoc::Model::Block::Core
+      #
+      class Attached < Base
+        def block_level?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/attribute.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class Attribute < Base
+        attribute :key, :string
+        attribute :value, :string, collection: true
+        attribute :line_break, :string, default: -> { "\n" }
+
+        private
+
+        # Build values from comma-separated string
+        # NOTE: This method allows for multiple values in format-specific attributes.
+        def build_values(value)
+          values = value.split(',').map(&:strip)
+          values.length > 1 ? values : values.first
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/attribute_list/matchers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class AttributeList < Base
+        module Matchers
+          def one(*args)
+            One.new(*args)
+          end
+
+          class One
+            def initialize(*possibilities)
+              @possibilities = possibilities
+            end
+
+            def ===(other)
+              @possibilities.any? { |i| i === other }
+            end
+          end
+
+          def many(*args)
+            Many.new(*args)
+          end
+
+          # NOTE: The Many matcher validates that all values in an array/string match
+          # one of the specified possibilities. Currently accepts all matching values
+          # without selective rejection - this may be enhanced in future versions.
+          class Many
+            def initialize(*possibilities)
+              @possibilities = possibilities
+            end
+
+            def ===(other)
+              other = other.split(',') if other.is_a?(String)
+
+              other.is_a?(Array) &&
+                other.all? { |i| @possibilities.any? { |p| p === i } }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/attribute_list.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Attribute list for AsciiDoc elements.
+      #
+      # Attribute lists represent the square-bracket attribute syntax in AsciiDoc:
+      # [positional1, pos2, name1=value1, name2=value2]
+      #
+      # This class manages both positional and named attributes, with support
+      # for validation and rejection of invalid values.
+      #
+      # @!attribute [r] positional
+      #   @return [Array<Coradoc::AsciiDoc::Model::AttributeListAttribute>] Positional attributes (by position)
+      #
+      # @!attribute [r] named
+      #   @return [Array<Coradoc::AsciiDoc::Model::NamedAttribute>] Named attributes (key-value pairs)
+      #
+      # @!attribute [r] rejected_positional
+      #   @return [Array<Coradoc::AsciiDoc::Model::RejectedPositionalAttribute>] Rejected positional attributes
+      #
+      # @!attribute [r] rejected_named
+      #   @return [Array<Coradoc::AsciiDoc::Model::NamedAttribute>] Rejected named attributes
+      #
+      # @example Create an attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.add_positional("value1")
+      #   attrs.add_named("option", "value")
+      #   attrs.to_adoc # => "[value1,option=value]\n"
+      #
+      # @example Empty attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.to_adoc # => "[]"
+      #
+      # @example Hide empty attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.to_adoc(show_empty: false) # => ""
+      #
+      class AttributeList < Base
+        # Autoload Matchers module
+        autoload :Matchers, 'coradoc/asciidoc/model/attribute_list/matchers'
+
+        # Include Matchers module for validation methods
+        include Matchers
+
+        attribute :positional,
+                  Coradoc::AsciiDoc::Model::AttributeListAttribute,
+                  collection: true,
+                  initialize_empty: true
+        attribute :named, Coradoc::AsciiDoc::Model::NamedAttribute, collection: true, initialize_empty: true
+        attribute :rejected_positional,
+                  Coradoc::AsciiDoc::Model::RejectedPositionalAttribute,
+                  collection: true,
+                  initialize_empty: true
+        attribute :rejected_named,
+                  Coradoc::AsciiDoc::Model::NamedAttribute,
+                  collection: true,
+                  initialize_empty: true
+
+        # Add positional attributes to this list
+        #
+        # @param attr [Array<Object>] Values to add as positional attributes
+        #
+        # @example Adding positional attributes
+        #   attrs.add_positional("value1", "value2")
+        #
+        def add_positional(*attr)
+          attr.each do |a|
+            @positional << AttributeListAttribute.new(value: a)
+          end
+        end
+
+        # Add a named attribute to this list
+        #
+        # @param name [String, Symbol] The attribute name
+        # @param value [Object] The attribute value (will be converted to array)
+        #
+        # @example Adding named attributes
+        #   attrs.add_named("title", "My Title")
+        #   attrs.add_named("cols", "3,2,1")
+        #
+        def add_named(name, value)
+          @named << NamedAttribute.new(
+            name:,
+            value: value.is_a?(Array) ? value : [value]
+          )
+        end
+
+        # Validate named attributes against validators
+        #
+        # @param validators [Hash] Hash of name => matcher pairs
+        # @yield [name, value] Block called for each invalid attribute
+        #
+        # @example Validate with custom validator
+        #   attrs.validate_named(title: /./) do |name, value|
+        #     puts "Invalid #{name}: #{value}"
+        #   end
+        #
+        def validate_named(validators: {})
+          named.each_with_index do |named_attribute, _i|
+            name = named_attribute.name.to_sym
+            value = named_attribute.value
+
+            matcher = validators[name]
+
+            next if matcher && matcher === value
+
+            # Previous implementation would remove the value from the list
+            # named.delete(name)
+            rejected_named << named_attribute.dup
+            yield(name, value) if block_given?
+          end
+        end
+
+        # Validate positional attributes against validators
+        #
+        # @param validators [Array] Array of [position, matcher] pairs
+        # @yield [position, value] Block called for each invalid attribute
+        #
+        # @example Validate positional attributes
+        #   attrs.validate_positional([[0, /./], [1, Integer]])
+        #
+        def validate_positional(validators: [])
+          positional.each_with_index do |positional_attribute, i|
+            matcher = validators[i][1]
+            value = positional_attribute.value
+
+            next unless matcher && !(matcher === value)
+
+            warn "#{value} does not match #{matcher}"
+            # Previous implementation would remove the value from the list
+            # positional[i] = nil
+            rejected_positional << RejectedPositionalAttribute.new(
+              position: i, value:
+            )
+            yield(i, value) if block_given?
+          end
+        end
+
+        # To be overridden in subclasses.
+        # @return [Array] Array of positional validators
+        def positional_validators
+          []
+        end
+
+        # To be overridden in subclasses.
+        # @return [Hash] Hash of named validators
+        def named_validators
+          {}
+        end
+
+        # Validate this attribute list
+        #
+        # @return [Array<Lutaml::Model::Error>] Validation errors (empty if valid)
+        def validate
+          errors = super
+
+          validate_positional(positional_validators) do |i, value|
+            errors << Lutaml::Model::Error.new(
+              "Positional attribute at position #{i} with value '#{value}' is not valid"
+            )
+          end
+
+          validate_named(named_validators) do |name, value|
+            errors << Lutaml::Model::Error.new(
+              "Named attribute #{name} with value '#{value}' is not valid"
+            )
+          end
+
+          errors
+        end
+
+        # Serialize this attribute list to AsciiDoc
+        #
+        # Generates the square-bracket syntax with valid attributes only.
+        #
+        # @param show_empty [Boolean] If true, show "[]" for empty lists (default: true)
+        # @return [String] AsciiDoc representation of this attribute list
+        #
+        # @example Serialize with options
+        #   attrs.to_adoc(show_empty: true)  # => "[value1,name=val]"
+        #   attrs.to_adoc(show_empty: false) # => "[value1,name=val]"
+        #   empty.to_adoc                     # => "[]"
+        #   empty.to_adoc(show_empty: false) # => ""
+        #
+        def to_adoc(show_empty: true)
+          valid_positional = positional.reject.with_index do |_p, i|
+            rejected_positional.any? { |r| r.position == i }
+          end
+
+          valid_named = named.reject do |n|
+            rejected_named.any? { |r| r.name == n.name }
+          end
+
+          adoc = [valid_positional,
+                  valid_named].flatten.map(&:to_adoc).join(',')
+
+          if adoc.empty? && show_empty
+            '[]'
+          elsif adoc.empty?
+            ''
+          else
+            "[#{adoc}]"
+          end
+        end
+
+        def empty?
+          positional.empty? && named.empty?
+        end
+
+        # Get a named attribute value by name
+        # @param name [String, Symbol] The attribute name
+        # @return [Object, nil] The attribute value or nil if not found
+        def [](name)
+          name_str = name.to_s
+          named.find { |n| n.name.to_s == name_str }&.value
+        end
+
+        # Get a named attribute value with default
+        # @param name [String, Symbol] The attribute name
+        # @param default [Object] The default value if not found
+        # @return [Object] The attribute value or default
+        def fetch(name, default = nil)
+          self[name] || default
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/attribute_list_attribute.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class AttributeListAttribute < Base
+        attribute :value, :string
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/audio.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Audio block element for AsciiDoc documents.
+      #
+      # Audio elements are embedded multimedia content with support for
+      # various audio formats and custom attributes.
+      #
+      # @!attribute [r] id
+      #   @return [String, nil] Optional identifier for the audio
+      #
+      # @!attribute [r] title
+      #   @return [String, nil] Optional audio title
+      #
+      # @!attribute [r] src
+      #   @return [String] The audio source URL or path
+      #
+      # @!attribute [r] attributes
+      #   @return [Coradoc::AsciiDoc::Model::AttributeList] Audio attributes
+      #
+      # @!attribute [r] line_break
+      #   @return [String] Line break character (default: "\n")
+      #
+      # @example Create an audio block
+      #   audio = Coradoc::AsciiDoc::Model::Audio.new
+      #   audio.src = "https://example.com/audio.mp3"
+      #   audio.title = "Podcast Episode"
+      #
+      class Audio < Base
+        include Coradoc::AsciiDoc::Model::Anchorable
+
+        attribute :id, :string
+        attribute :title, :string
+        attribute :src, :string, default: -> { '' }
+        attribute :attributes, Coradoc::AsciiDoc::Model::AttributeList, default: lambda {
+          Coradoc::AsciiDoc::Model::AttributeList.new
+        }
+        attribute :line_break, :string, default: -> { "\n" }
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/author.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Author information for document headers.
+      #
+      # Author metadata captures document author names and contact information.
+      #
+      # @!attribute [r] first_name
+      #   @return [String, nil] Author's first name
+      #
+      # @!attribute [r] middle_name
+      #   @return [String, nil] Author's middle name or initial
+      #
+      # @!attribute [r] last_name
+      #   @return [String, nil] Author's last name
+      #
+      # @!attribute [r] email
+      #   @return [String, nil] Author's email address
+      #
+      # @example Create an author
+      #   author = Coradoc::AsciiDoc::Model::Author.new
+      #   author.first_name = "John"
+      #   author.last_name = "Doe"
+      #   author.email = "john@example.com"
+      #
+      class Author < Base
+        attribute :first_name, :string
+        attribute :last_name, :string
+        attribute :email, :string
+        attribute :middle_name, :string
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/base.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# require "lutaml/model"
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Base class for all Coradoc model objects.
+      #
+      # The Base class provides common functionality for all document model elements,
+      # including serialization support, tree traversal, and attribute management.
+      #
+      # All model classes inherit from this class to get:
+      # - Lutaml::Model serialization capabilities
+      # - ComparableModel functionality
+      # - Visit pattern for tree traversal
+      # - Polymorphic content serialization
+      #
+      # @!attribute [r] id
+      #   @return [String, nil] Optional identifier for the element
+      #
+      # @example Implementing a custom model class
+      #   class CustomBlock < Coradoc::AsciiDoc::Model::Base
+      #     attribute :content, :string
+      #     attribute :children, array: true
+      #   end
+      #
+      # @example Using the visit pattern
+      #   doc.visit do |element, phase|
+      #     puts "#{phase}: #{element.class}" if element.is_a?(Paragraph)
+      #   end
+      #
+      class Base < Lutaml::Model::Serializable
+        include Lutaml::Model::ComparableModel
+
+        attribute :id, :string
+
+        # Element classification for spacing and serialization decisions.
+        # Subclasses override these to declare their level.
+        def block_level?
+          false
+        end
+
+        def inline?
+          false
+        end
+
+        # Generate a warning message whenever this method is called.
+        def simplify_block_content(content)
+          warn '[DEPRECATION] #simplify_block_content is called inside a Lutaml Model.  This is still a WIP.'
+          # print part of the stack trace
+          caller_locations(1, 3).each do |location|
+            warn "  #{location.path}:#{location.lineno} in #{location.label}"
+          end
+
+          content
+        end
+
+        # Visit pattern for traversing the document tree
+        def self.visit(element, &block)
+          return element if element.nil?
+
+          element = yield element, :pre
+          element = case element
+                    when Coradoc::AsciiDoc::Model::Base
+                      element.visit(&block)
+                    when Array
+                      element.map { |child| visit(child, &block) }
+                             .flatten.compact
+                    when Hash
+                      result = {}
+                      element.each do |k, v|
+                        result[k] = visit(v, &block)
+                      end
+                      result
+                    else
+                      element
+                    end
+          yield element, :post
+        end
+
+        def visit(&block)
+          self.class.attributes.each_key do |attr_name|
+            child = public_send(attr_name)
+            result = self.class.visit(child, &block)
+            public_send(:"#{attr_name}=", result) if result != child
+          end
+          self
+        end
+
+        # Serialize polymorphic content to AsciiDoc string
+        # Handles: Arrays, Strings, nil, and model objects
+        # Raises ArgumentError for unknown types to force proper handling
+        def serialize_content(content)
+          case content
+          when Array
+            content.map { |elem| serialize_content(elem) }.join
+          when String
+            content
+          when nil
+            ''
+          when Coradoc::AsciiDoc::Model::Base, Lutaml::Model::Serializable
+            # All model objects should respond to to_adoc
+            content.to_adoc
+          else
+            # This is a programming error - we received an unexpected type
+            raise ArgumentError,
+                  "Cannot serialize #{content.class.name} in content. " \
+                  'Expected String, nil, Array, Coradoc::AsciiDoc::Model::Base, or ' \
+                  "Lutaml::Model::Serializable. Got: #{content.inspect[0..100]}"
+          end
+        end
+
+        # Does a shallow attribute dump of the object,
+        # for use when instantiating a new object (e.g. of a subclass) from an
+        # existing one.
+        def to_h
+          self.class.attributes.keys.each_with_object({}) do |attribute, acc|
+            acc[attribute] = public_send(attribute)
+          end
+        end
+
+        # Serialize this model element to AsciiDoc
+        #
+        # This is the unified serialization method for all Model objects.
+        # It uses the ElementRegistry system which provides serializers
+        # for each model type.
+        #
+        # @return [String] AsciiDoc representation of this element
+        #
+        # @example Serialize a paragraph to AsciiDoc
+        #   para = Coradoc::AsciiDoc::Model::Paragraph.new("Hello World")
+        #   para.to_adoc # => "Hello World\n"
+        #
+        def to_adoc
+          Coradoc::AsciiDoc::Serializer.serialize(self)
+        end
+      end
+    end
+  end
+end