coradoc 1.1.7 → 2.0.2

data/docs/lutaml-model-recursive-types-proposal.md

@@ -0,0 +1,146 @@
+# Proposal: Support for Recursive/Self-Referential Types in lutaml-model
+
+## Problem Description
+
+When a lutaml-model class has an attribute that references itself (recursive/self-referential type), calling `to_hash` or `to_json` causes a `SystemStackError` (stack level too deep).
+
+### Example
+
+```ruby
+class InlineElement < Lutaml::Model::Serializable
+  attribute :format_type, :string
+  attribute :content, :string
+
+  # This causes infinite recursion in to_hash
+  attribute :nested_elements, InlineElement, collection: true
+end
+
+# This throws SystemStackError
+element = InlineElement.new(format_type: "bold", content: "text")
+element.to_hash  # => SystemStackError: stack level too deep
+```
+
+## Root Cause Analysis
+
+The error occurs in `Lutaml::Model::KeyValue::Transformation.compile_rules` when the transformation tries to recursively compile mapping rules for nested types. Since `InlineElement` references itself, the compilation never terminates.
+
+### Stack Trace (truncated)
+
+```
+/lutaml/model/key_value/transformation.rb:37:in `block in compile_rules': stack level too deep (SystemStackError)
+	from /lutaml/model/key_value/transformation.rb:36:in `each'
+	from /lutaml/model/key_value/transformation.rb:36:in `compile_rules'
+	from /lutaml/model/transformation.rb:39:in `initialize'
+	from /lutaml/model/key_value/transformation.rb:208:in `new'
+	from /lutaml/model/key_value/transformation.rb:208:in `build_child_transformation'
+	from /lutaml/model/key_value/transformation.rb:108:in `compile_mapping_rule'
+	from /lutaml/model/key_value/transformation.rb:37:in `block in compile_rules'
+	... 8326 levels...
+```
+
+## Proposed Solution
+
+### Option A: Track Visited Types During Rule Compilation
+
+Add a type tracking mechanism to prevent infinite recursion during rule compilation:
+
+```ruby
+module Lutaml::Model::KeyValue::Transformation
+  def compile_rules
+    # Track types currently being compiled
+    @compiling_types ||= Set.new
+
+    mapping.rules.each do |rule|
+      next unless rule.custom_methods[:to].nil?
+
+      # Check for recursive reference
+      if rule.type.is_a?(Class) && rule.type < Lutaml::Model::Serializable
+        type_name = rule.type.name
+
+        if @compiling_types.include?(type_name)
+          # Skip recursive reference - will be handled at runtime
+          next
+        end
+
+        @compiling_types.add(type_name)
+        compile_mapping_rule(rule)
+        @compiling_types.delete(type_name)
+      else
+        compile_mapping_rule(rule)
+      end
+    end
+  end
+end
+```
+
+### Option B: Lazy Evaluation of Nested Types
+
+Defer the compilation of nested type rules until they are actually needed:
+
+```ruby
+def compile_mapping_rule(rule)
+  # For recursive types, create a lazy evaluator
+  if recursive_type?(rule.type)
+    define_singleton_method("transform_#{rule.name}") do |value, doc|
+      next if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      value.map do |item|
+        # Compile lazily at runtime
+        item.to_hash
+      end
+    end
+  else
+    # Existing behavior
+    build_child_transformation(rule.type)
+  end
+end
+```
+
+### Option C: Add `recursive: true` Option
+
+Allow users to mark attributes as recursive, signaling lutaml-model to handle them specially:
+
+```ruby
+class InlineElement < Lutaml::Model::Serializable
+  attribute :format_type, :string
+  attribute :content, :string
+
+  # Mark as recursive - lutaml-model handles serialization specially
+  attribute :nested_elements, InlineElement, collection: true, recursive: true
+end
+```
+
+## Workaround for Current Version
+
+Users can currently work around this by:
+
+1. Using instance variable inspection instead of `to_hash`:
+```ruby
+def to_custom_hash
+  result = {}
+  instance_variables.each do |var|
+    key = var.to_s.delete_prefix("@")
+    value = instance_variable_get(var)
+    result[key] = normalize(value)
+  end
+  result
+end
+```
+
+2. Avoiding recursive type definitions and using a separate containment model
+
+## Impact
+
+This issue affects any document model that supports:
+- Nested inline formatting (bold containing italic, etc.)
+- Tree structures (sections containing sections)
+- Graph-like data structures
+
+## Related Classes in coradoc
+
+- `Coradoc::CoreModel::InlineElement` - nested inline formatting
+- `Coradoc::CoreModel::StructuralElement` - sections containing sections
+
+---
+
+Please let me know if you need more details or a pull request implementation.

data/docs/pages.adoc

@@ -0,0 +1,35 @@
+---
+title: Core Pages
+nav_order: 2
+has_children: true
+---
+
+= Core Pages
+
+This section contains the foundational documentation for Coradoc. These pages explain the core concepts, architecture, and features of the library.
+
+== Overview
+
+The Core Pages are organized to help you understand Coradoc from multiple perspectives:
+
+* link:/coradoc/pages/getting-started/[Getting Started] - Begin here if you're new to Coradoc
+* link:/coradoc/pages/architecture/[Architecture] - Understand how Coradoc works internally
+* link:/coradoc/pages/parsing/[Parsing] - Learn about the parsing layer
+* link:/coradoc/pages/transformation/[Transformation] - Understand AST to Model conversion
+* link:/coradoc/pages/model/[Document Model] - Explore the document object model
+* link:/coradoc/pages/serialization/[Serialization] - Learn about output generation
+
+== Navigation
+
+* link:/coradoc/pages/getting-started/[Getting Started] - Installation and quick start
+* link:/coradoc/pages/architecture/[Architecture] - System architecture and data flow
+* link:/coradoc/pages/parsing/[Parsing] - AsciiDoc parsing with Parslet
+* link:/coradoc/pages/transformation/[Transformation] - Transformer layer explanation
+* link:/coradoc/pages/model/[Document Model] - Document model classes
+* link:/coradoc/pages/serialization/[Serialization] - AsciiDoc serialization
+
+== Related Documentation
+
+* link:/coradoc/tutorials/[Tutorials] - Hands-on learning with examples
+* link:/coradoc/guides/[Guides] - Task-oriented documentation
+* link:/coradoc/references/[References] - Technical specifications

data/docs/references.adoc

@@ -0,0 +1,62 @@
+---
+title: References
+nav_order: 5
+has_children: true
+---
+
+= References
+
+== Purpose
+
+This section contains technical specifications and detailed reference documentation for Coradoc.
+
+== Overview
+
+References are organized by topic:
+
+=== API References
+
+* link:/coradoc/references/api-reference/[API Reference] - Complete API documentation
+* link:/coradoc/references/ruby-methods/[Ruby Methods Reference] - Ruby API methods reference
+* link:/coradoc/references/coremodel-types/[CoreModel Types] - CoreModel type definitions
+
+=== Syntax Guides
+
+* link:/coradoc/references/asciidoc-syntax/[AsciiDoc Syntax] - AsciiDoc authoring guide
+* link:/coradoc/references/markdown-syntax/[Markdown Syntax] - Markdown authoring guide
+
+=== Tools Reference
+
+* link:/coradoc/references/cli-commands/[CLI Commands] - Command-line interface reference
+* link:/coradoc/references/error-codes/[Error Codes] - Error codes and recovery strategies
+* link:/coradoc/references/feature-matrix/[Feature Matrix] - Feature support across formats
+
+=== Model and Extensions
+
+* link:/coradoc/references/model-classes/[Model Classes] - All model classes catalog
+* link:/coradoc/references/output-formats/[Output Formats] - Format options and converters
+* link:/coradoc/references/extension-points/[Extension Points] - Extension API specification
+
+== Reference Structure
+
+Each reference provides:
+
+* **Specification** - Formal definition
+* **Parameters** - Method/class parameters
+* **Returns** - Return types and values
+* **Raises** - Exceptions that may be raised
+* **Examples** - Usage examples
+* **Notes** - Important considerations
+
+== When to Use References
+
+* **API Reference** - Look up method signatures and parameters
+* **Model Classes** - Find model class inheritance and attributes
+* **Output Formats** - Understand format options
+* **Extension Points** - Learn extension APIs
+
+== Related Documentation
+
+* link:/coradoc/pages/[Core Pages] - Conceptual documentation
+* link:/coradoc/tutorials/[Tutorials] - Step-by-step learning
+* link:/coradoc/guides/[Guides] - Task-oriented guides

data/docs/tutorials.adoc

@@ -0,0 +1,61 @@
+---
+title: Tutorials
+nav_order: 3
+has_children: true
+---
+
+= Tutorials
+
+== Purpose
+
+This section contains step-by-step tutorials to help you learn Coradoc through hands-on examples. Each tutorial builds on previous concepts and includes runnable code.
+
+== Overview
+
+Tutorials are organized by skill level and topic:
+
+* link:/coradoc/tutorials/basic-parsing/[Basic Parsing] - Parse your first AsciiDoc document
+* link:/coradoc/tutorials/document-modeling/[Document Modeling] - Work with the document model
+* link:/coradoc/tutorials/serialization/[Serialization] - Serialize models to AsciiDoc
+* link:/coradoc/tutorials/round-tripping/[Round-tripping] - Preserve semantics through parse cycles
+* link:/coradoc/tutorials/html-conversion/[HTML Conversion] - Convert HTML to AsciiDoc
+
+== Tutorial Structure
+
+Each tutorial follows this structure:
+
+* **Purpose** - What you'll learn
+* **Prerequisites** - What you should know first
+* **Examples** - Step-by-step runnable code
+* **Exercises** - Practice what you learned
+* **Next Steps** - What to learn next
+
+== Learning Path
+
+We recommend this order for learning Coradoc:
+
+. link:/coradoc/tutorials/basic-parsing/[Basic Parsing] - Start here if you're new
+. link:/coradoc/tutorials/document-modeling/[Document Modeling] - Understand the model
+. link:/coradoc/tutorials/serialization/[Serialization] - Generate AsciiDoc output
+. link:/coradoc/tutorials/round-tripping/[Round-tripping] - Learn about preservation
+. link:/coradoc/tutorials/html-conversion/[HTML Conversion] - Advanced conversion
+
+== Example Code
+
+All code examples in tutorials are runnable. You can execute them by:
+
+[source,ruby]
+----
+# Save to a file (e.g., tutorial.rb)
+# Then run with: ruby tutorial.rb
+
+require 'coradoc'
+
+# Paste the example code here
+----
+
+== Related Documentation
+
+* link:/coradoc/pages/[Core Pages] - Conceptual documentation
+* link:/coradoc/guides/[Guides] - Task-oriented guides
+* link:/coradoc/references/[References] - Technical specifications

data/examples/README.adoc

@@ -0,0 +1,132 @@
+= Coradoc Examples
+
+This directory contains examples demonstrating how to use Coradoc for parsing, modeling, and serializing AsciiDoc documents.
+
+## Running the Examples
+
+To run any of the Ruby examples:
+
+[source,bash]
+----
+ruby examples/basic_parsing.rb
+----
+
+## Examples by Category
+
+=== Basic Parsing
+
+`basic_parsing.rb` - Demonstrates how to parse AsciiDoc documents.
+
+Topics covered:
+
+* Parse a simple document
+* Parse from a file
+* Parse with inline formatting
+* Parse lists
+* Parse blocks
+
+=== Document Modeling
+
+`document_modeling.rb` - Demonstrates how to work with the Coradoc document model.
+
+Topics covered:
+
+* Accessing document structure
+* Working with paragraphs
+* Working with lists
+* Working with tables
+* Working with inline elements
+* Working with attributes
+* Working with blocks
+
+=== Serialization
+
+`serialization.rb` - Demonstrates how to serialize Coradoc document models to AsciiDoc.
+
+Topics covered:
+
+* Basic serialization
+* Serialize individual elements
+* Serialize lists
+* Serialize tables
+* Serialize blocks
+* Serialize inline elements
+* Round-trip preservation
+* Using `Coradoc.convert`
+
+=== Custom Blocks
+
+`custom_blocks.rb` - Demonstrates how to create custom block types.
+
+Topics covered:
+
+* Create a custom callout block
+* Create a custom tip block
+* Create a custom remark block
+* Use custom blocks in a document
+* Custom block with attributes
+* Custom block with title
+
+=== Custom Inline Elements
+
+`custom_inline.rb` - Demonstrates how to create custom inline elements.
+
+Topics covered:
+
+* Create a custom highlight element
+* Create a custom code element
+* Create a custom mark element
+* Create a custom keycap element
+* Use custom inline elements in a paragraph
+* Mix custom and built-in inline elements
+* Custom icon element
+* Custom menu element
+
+## Example Documents
+
+The `documents/` directory contains sample AsciiDoc files for testing:
+
+* `basic_document.adoc` - A simple document demonstrating basic features
+* `technical_documentation.adoc` - Technical documentation with code examples, tables, and admonitions
+* `article.adoc` - An article with abstracts, block quotes, and callouts
+
+To parse these documents:
+
+[source,ruby]
+----
+doc = Coradoc.parse_file("examples/documents/basic_document.adoc")
+puts doc.to_adoc
+----
+
+## Quick Reference
+
+=== Parse a Document
+
+[source,ruby]
+----
+doc = Coradoc.parse("= Title\n\nContent")
+----
+
+=== Parse from File
+
+[source,ruby]
+----
+doc = Coradoc.parse_file("document.adoc")
+----
+
+=== Serialize to AsciiDoc
+
+[source,ruby]
+----
+output = doc.to_adoc
+----
+
+=== Access Document Structure
+
+[source,ruby]
+----
+doc.header.title           # Document title
+doc.sections              # Array of sections
+doc.sections.first.title  # First section title
+doc.sections.first.paragraphs # First section paragraphs
+----

data/examples/basic_parsing.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# Basic parsing examples for Coradoc
+#
+# This file demonstrates how to parse AsciiDoc documents using Coradoc.
+
+require_relative '../lib/coradoc'
+
+# Helper method to find first actual Section
+def find_first_section(doc)
+  doc.sections.find { |s| s.is_a?(Coradoc::Model::Section) }
+end
+
+# Example 1: Parse a simple document
+puts '=== Example 1: Parse a simple document ==='
+input = <<~ASCIIDOC
+  = Hello World
+
+  This is a paragraph.
+
+  == Section 1
+
+  This is content in section 1.
+ASCIIDOC
+
+doc = Coradoc.parse(input)
+puts "Document title: #{doc.header.title}"
+puts "Number of sections: #{doc.sections.size}"
+section = find_first_section(doc)
+puts "First section title: #{section.title.content}" if section
+puts
+
+# Example 2: Parse from file
+puts '=== Example 2: Parse from file ==='
+temp_file = '/tmp/coradoc_example.adoc'
+File.write(temp_file, <<~ASCIIDOC)
+  = Document Title
+  Author Name <author@example.com>
+
+  == Introduction
+
+  This is the introduction paragraph.
+
+  * List item 1
+  * List item 2
+  * List item 3
+ASCIIDOC
+
+doc = Coradoc.parse_file(temp_file)
+puts "Document title: #{doc.header.title}"
+puts "Author: #{doc.header.author&.first&.name}"
+section = find_first_section(doc)
+if section
+  paragraphs = section.contents.select { |c| c.is_a?(Coradoc::Model::Paragraph) }
+  lists = section.contents.select { |c| c.is_a?(Coradoc::Model::List::Core) }
+  puts "Number of paragraphs: #{paragraphs.size}"
+  puts "Number of lists: #{lists.size}"
+end
+puts
+
+# Example 3: Parse with inline formatting
+puts '=== Example 3: Parse with inline formatting ==='
+input = <<~ASCIIDOC
+  = Formatting Examples
+
+  This has *bold text* and _italic text_.
+
+  This has `monospace text` and a https://example.com[link].
+ASCIIDOC
+
+doc = Coradoc.parse(input)
+paragraph = doc.sections.find { |s| s.is_a?(Coradoc::Model::Paragraph) }
+if paragraph
+  puts "Paragraph has #{paragraph.content.size} content elements"
+  paragraph.content.each do |element|
+    puts "  - #{element.class.name}"
+  end
+end
+puts
+
+# Example 4: Parse lists
+puts '=== Example 4: Parse lists ==='
+input = <<~ASCIIDOC
+  = Lists
+
+  * Unordered item 1
+  ** Nested item
+  * Unordered item 2
+
+  . Ordered item 1
+  . Ordered item 2
+  . Ordered item 3
+
+  [horizontal]
+  Term 1:: Definition 1
+  Term 2:: Definition 2
+ASCIIDOC
+
+doc = Coradoc.parse(input)
+lists = doc.sections.select { |s| s.is_a?(Coradoc::Model::List::Core) }
+puts "Number of lists: #{lists.size}"
+lists.each_with_index do |list, i|
+  puts "  List #{i + 1}: #{list.class.name} with #{list.items.size} items"
+end
+puts
+
+# Example 5: Parse blocks
+puts '=== Example 5: Parse blocks ==='
+input = <<~ASCIIDOC
+  = Blocks
+
+  [source,ruby]
+  ----
+  def hello
+    puts "Hello, World!"
+  end
+  ----
+
+  ____
+  Quoted text block.
+  ____
+
+  NOTE: This is a note admonition.
+ASCIIDOC
+
+doc = Coradoc.parse(input)
+section = find_first_section(doc)
+section&.contents&.each do |block|
+  puts "Block type: #{block.class.name}"
+end
+puts
+
+# Cleanup
+File.delete(temp_file) if File.exist?(temp_file)
+
+puts '=== All examples completed ==='