coradoc 1.1.7 → 2.0.2

data/lib/coradoc/visitor.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Document visitor pattern for traversing and processing document trees.
+  #
+  # The visitor pattern enables clean separation of document traversal logic
+  # from processing logic. Visitors can be used for:
+  # - Document transformation
+  # - Content extraction
+  # - Validation
+  # - Custom rendering
+  #
+  # @example Basic visitor
+  #   class WordCounter < Coradoc::Visitor::Base
+  #     attr_reader :count
+  #
+  #     def initialize
+  #       @count = 0
+  #     end
+  #
+  #     def visit_block(block)
+  #       @count += block.content.to_s.split.length if block.content
+  #       super
+  #     end
+  #   end
+  #
+  #   counter = WordCounter.new
+  #   document.accept(counter)
+  #   puts counter.count
+  #
+  module Visitor
+    # Registry mapping CoreModel classes to visitor method names.
+    # CoreModel types self-register via register_visitor on load.
+    DISPATCH_TABLE = {}
+
+    # Register a CoreModel class to a visitor method name.
+    # Called during CoreModel type definition.
+    def self.register_visitor(klass, method_name)
+      DISPATCH_TABLE[klass] = method_name
+    end
+
+    # Base class for document visitors.
+    #
+    # Provides default traversal behavior for all CoreModel types.
+    # Override specific visit_* methods to customize behavior.
+    class Base
+      # Visit a document element (dispatch method)
+      # @param element [CoreModel::Base] Element to visit
+      # @return [void]
+      def visit(element)
+        return if element.nil?
+
+        method_name = DISPATCH_TABLE[element.class]
+        if method_name
+          send(method_name, element)
+        elsif element.is_a?(Array)
+          visit_array(element)
+        else
+          visit_unknown(element)
+        end
+      end
+
+      # Visit a structural element (document, section)
+      def visit_structural_element(element)
+        visit_children(element.children)
+      end
+
+      # Visit a block element
+      def visit_block(block)
+        visit_children(block.children)
+      end
+
+      # Visit an inline element
+      def visit_inline_element(element)
+        visit_children(element.nested_elements)
+      end
+
+      # Visit a list block
+      def visit_list_block(list)
+        visit_children(list.items)
+      end
+
+      # Visit a list item
+      def visit_list_item(item)
+        visit_children(item.children)
+      end
+
+      # Visit a table
+      def visit_table(table)
+        visit_children(table.rows)
+      end
+
+      # Visit a table row
+      def visit_table_row(row)
+        visit_children(row.cells)
+      end
+
+      # Visit a table cell
+      def visit_table_cell(cell)
+        # TableCell typically contains text or nested elements
+      end
+
+      # Visit an image
+      def visit_image(image)
+        # Image is typically a leaf node
+      end
+
+      # Visit a term (definition list term)
+      def visit_term(term)
+        # Term is typically a leaf node
+      end
+
+      # Visit an annotation block (admonition)
+      def visit_annotation_block(block)
+        visit_children(block.children)
+      end
+
+      # Visit a footnote
+      def visit_footnote(element)
+        # Footnote is typically a leaf node
+      end
+
+      # Visit a footnote reference
+      def visit_footnote_reference(element)
+        # FootnoteReference is typically a leaf node
+      end
+
+      # Visit an abbreviation
+      def visit_abbreviation(element)
+        # Abbreviation is typically a leaf node
+      end
+
+      # Visit a definition list
+      def visit_definition_list(element)
+        visit_children(element.items)
+      end
+
+      # Visit a definition item
+      def visit_definition_item(element)
+        # DefinitionItem is typically a leaf node
+      end
+
+      # Visit a bibliography
+      def visit_bibliography(element)
+        visit_children(element.entries)
+      end
+
+      # Visit a bibliography entry
+      def visit_bibliography_entry(element)
+        # BibliographyEntry is typically a leaf node
+      end
+
+      # Visit a table of contents
+      def visit_toc(element)
+        visit_children(element.entries)
+      end
+
+      # Visit a TOC entry
+      def visit_toc_entry(element)
+        visit_children(element.children)
+      end
+
+      # Visit metadata
+      def visit_metadata(element)
+        visit_children(element.entries)
+      end
+
+      # Visit a metadata entry
+      def visit_metadata_entry(element)
+        # MetadataEntry is a leaf node
+      end
+
+      # Visit an element attribute
+      def visit_element_attribute(element)
+        # ElementAttribute is a leaf node
+      end
+
+      # Visit an array of elements
+      def visit_array(array)
+        array.each { |element| visit(element) }
+      end
+
+      # Visit an unknown element type
+      def visit_unknown(element)
+        # Override to handle unknown types
+      end
+
+      private
+
+      # Visit children elements
+      def visit_children(children)
+        children&.each { |child| visit(child) }
+      end
+    end
+
+    # Visitor that collects matching elements
+    class Collector < Base
+      attr_reader :items
+
+      def initialize(*types)
+        @types = types.flatten
+        @items = []
+      end
+
+      def match?(element)
+        return true if @types.empty?
+
+        @types.any? { |type| element.is_a?(type) }
+      end
+
+      def visit(element)
+        @items << element if match?(element)
+        super
+      end
+    end
+
+    # Visitor that transforms elements
+    class Transformer < Base
+      attr_reader :transformer
+
+      def initialize(&block)
+        @transformer = block
+      end
+
+      def visit(element)
+        transformer&.call(element)
+        super
+      end
+    end
+
+    # Visitor that searches for elements matching criteria
+    class Finder < Base
+      attr_reader :results
+
+      def initialize(&block)
+        @predicate = block
+        @results = []
+      end
+
+      def visit(element)
+        @results << element if @predicate&.call(element)
+        super
+      end
+
+      def first
+        @results.first
+      end
+
+      def all
+        @results
+      end
+    end
+
+    # Self-register all CoreModel types
+    register_visitor CoreModel::StructuralElement, :visit_structural_element
+    register_visitor CoreModel::AnnotationBlock, :visit_annotation_block
+    register_visitor CoreModel::Block, :visit_block
+    register_visitor CoreModel::InlineElement, :visit_inline_element
+    register_visitor CoreModel::ListBlock, :visit_list_block
+    register_visitor CoreModel::ListItem, :visit_list_item
+    register_visitor CoreModel::Table, :visit_table
+    register_visitor CoreModel::TableRow, :visit_table_row
+    register_visitor CoreModel::TableCell, :visit_table_cell
+    register_visitor CoreModel::Image, :visit_image
+    register_visitor CoreModel::Term, :visit_term
+    register_visitor CoreModel::Footnote, :visit_footnote
+    register_visitor CoreModel::FootnoteReference, :visit_footnote_reference
+    register_visitor CoreModel::Abbreviation, :visit_abbreviation
+    register_visitor CoreModel::DefinitionList, :visit_definition_list
+    register_visitor CoreModel::DefinitionItem, :visit_definition_item
+    register_visitor CoreModel::Bibliography, :visit_bibliography
+    register_visitor CoreModel::BibliographyEntry, :visit_bibliography_entry
+    register_visitor CoreModel::Toc, :visit_toc
+    register_visitor CoreModel::TocEntry, :visit_toc_entry
+    register_visitor CoreModel::Metadata, :visit_metadata
+    register_visitor CoreModel::MetadataEntry, :visit_metadata_entry
+    register_visitor CoreModel::ElementAttribute, :visit_element_attribute
+  end
+end

data/lib/coradoc.rb

@@ -1,25 +1,45 @@
 # frozen_string_literal: true
 
-require "pathname"
+# Coradoc - Canonical Document Model and Transformation Hub
+#
+# Coradoc provides a hub-and-spoke architecture for document transformations.
+# The CoreModel serves as the canonical, format-agnostic representation,
+# enabling transformations between AsciiDoc, HTML, Markdown, DOCX, and more.
+#
+# @example Converting between formats
+#   require 'coradoc'
+#   html = Coradoc.convert("# Hello", from: :markdown, to: :html)
+#
+# @example Parsing and serializing
+#   doc = Coradoc.parse("# Title\n\nContent", format: :markdown)
+#   html = Coradoc.serialize(doc, to: :html)
+#
+# @example File-based conversion
+#   doc = Coradoc.parse_file("input.md")
+#   html = Coradoc.convert_file("input.md", to: :html)
+#
+# @example Manipulating documents
+#   doc = Coradoc.parse(text, format: :asciidoc)
+#   html = Coradoc.manipulate(doc)
+#              .transform_text(&:upcase)
+#              .add_toc
+#              .to_html
+#
+# @example Building documents programmatically
+#   doc = Coradoc.build do
+#     title "My Document"
+#     section "Intro" do
+#       paragraph "Hello world"
+#     end
+#   end.to_core
+#   Coradoc.serialize(doc, to: :html)
 
-require "parslet"
-require "coradoc/version"
-require "coradoc/util"
-require "coradoc/parser"
-require "coradoc/transformer"
-require "coradoc/generator"
-require "coradoc/converter"
-require "coradoc/input"
-require "coradoc/output"
+require_relative 'coradoc/coradoc'
 
 module Coradoc
-  class Error < StandardError; end
-
-  def self.root
-    File.dirname(__dir__)
-  end
-
-  def self.root_path
-    Pathname.new(Coradoc.root)
-  end
+  autoload :CLI, 'coradoc/cli'
+  autoload :DocumentBuilder, 'coradoc/document_builder'
+  autoload :DocumentManipulator, 'coradoc/document_manipulator'
+  autoload :Visitor, 'coradoc/visitor'
+  autoload :Serializer, 'coradoc/serializer/registry'
 end

data/lychee.toml

@@ -0,0 +1,84 @@
+# Lychee link checker configuration for Coradoc documentation
+
+# Exclude patterns
+exclude = [
+  # Local development links
+  "^http://localhost",
+  "^http://127.0.0.1",
+  "^http://0.0.0.0",
+
+  # Unmerged/draft PRs
+  "github.com/metanorma/coradoc/pull/",
+  "github.com/metanorma/coradoc/pull/[0-9]+$",
+
+  # Example domains
+  "example.com",
+  "example.org",
+  "example.net",
+
+  # Internal anchor links (handled by Jekyll)
+  "^#",
+
+  # GitHub features that may not have stable URLs
+  "github.com/metanorma/coradoc/actions",
+  "github.com/metanorma/coradoc/projects",
+  "github.com/metanorma/coradoc/wiki",
+  "github.com/metanorma/coradoc/security",
+
+  # GitHub user/profile links (may change)
+  "github.com/*",
+
+  # Test/example content
+  "test:",
+  "testing:",
+  "localhost:",
+]
+
+# Accept these HTTP status codes
+accept = [
+  200,    # OK
+  204,    # No Content
+  301,    # Moved Permanently
+  302,    # Found
+  303,    # See Other
+  307,    # Temporary Redirect
+  308,    # Permanent Redirect
+  429,    # Too Many Requests (rate limiting)
+]
+
+# Cache configuration
+cache = true
+
+# Maximum number of redirects to follow
+max_redirects = 10
+
+# Request timeout in seconds
+timeout = 20
+
+# Number of concurrent requests
+max_concurrency = 8
+
+# User agent for requests
+user_agent = "Mozilla/5.0 (compatible; Lychee/2.0; +https://github.com/lycheeverse/lychee)"
+
+# Retry configuration
+retry = true
+max_retries = 3
+
+# Verbose output
+verbose = true
+
+# Show progress
+progress = true
+
+# Exclude private/internal IP addresses
+exclude_private = true
+
+# Exclude all private IPs
+exclude_all_private = true
+
+# Exclude mail addresses (optional)
+exclude_mail = true
+
+# Include mail addresses (override exclude_mail if needed)
+include_mail = false

data/utils/inspect_asciidoc.rb

@@ -1,6 +1,8 @@
-$LOAD_PATH.unshift("../coradoc/lib")
-require "coradoc"
-require "pp"
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift('../coradoc/lib')
+require 'coradoc'
+require 'pp'
 
 def pretty_print_obj(obj)
   sio = StringIO.new
@@ -11,9 +13,9 @@ end
 def print_parsed(str)
   parse = Coradoc::Parser::Base.new.parse(str)
   puts str
-  puts ""
+  puts ''
   pretty_print_obj parse[:document]
-  puts ""
+  puts ''
   doc = Coradoc::Transformer.transform(parse[:document])
   pp doc
   puts Coradoc::Generator.gen_adoc(doc)

data/utils/parser_analyzer.rb

@@ -1,28 +1,30 @@
-require "rubocop"
+# frozen_string_literal: true
+
+require 'rubocop'
 
 def ast_from(string)
   RuboCop::ProcessedSource.new(string, RUBY_VERSION.to_f).ast
 end
 
 def is_def?(arr)
-  if Array === arr
-    if arr[0] == :def
-      $defs << arr
-    else
-      arr.each do |e|
-        is_def?(e)
-      end
+  return unless arr.is_a?(Array)
+
+  if arr[0] == :def
+    $defs << arr
+  else
+    arr.each do |e|
+      is_def?(e)
     end
   end
 end
 
-path = "lib/coradoc/parser/asciidoc/"
+path = 'lib/coradoc/parser/asciidoc/'
 class_files = Dir.entries(path).select { |x| File.file?(path + x) }
 
 $all_defs = {}
 
 class_files.each do |cf|
-  a = ast_from(File.open(path + cf).read)
+  a = ast_from(File.read(path + cf))
   next if a.nil?
 
   sexp = a.to_sexp_array
@@ -31,14 +33,15 @@ class_files.each do |cf|
   $all_defs[cf] = $defs
 end
 
-relevant_names = $all_defs.map { |_fn, defs| defs.map { |d| d[1] } }.flatten
+relevant_names = $all_defs.map { |_fn, defs| defs.map { |d| d[1] } }
+                          .flatten
 
-require "graphviz"
+require 'graphviz'
 
 g = GraphViz.new(:G, type: :digraph)
 
 g[:fontsize] = 8
-g[:rankdir] = "LR"
+g[:rankdir] = 'LR'
 g[:overlap] = false
 g[:splines] = false
 

data/utils/round_trip.rb

@@ -1,23 +1,25 @@
-$LOAD_PATH.unshift("../coradoc/lib")
+# frozen_string_literal: true
 
-require "coradoc"
-require "coradoc/input/html"
+$LOAD_PATH.unshift('../coradoc/lib')
 
-require "pp"
-require "stringio"
+require 'coradoc'
+require 'coradoc/input/html'
+
+require 'pp'
+require 'stringio'
 
 rt = ARGV[0]
 
-rt_path = if rt == "rice-2023"
-            "../mn-samples-iso/sources/international-standard/rice-2023/"
-          elsif rt.to_s.include? "samples"
-            "../mn-samples-iso/sources/"
+rt_path = if rt == 'rice-2023'
+            '../mn-samples-iso/sources/international-standard/rice-2023/'
+          elsif rt.to_s.include? 'samples'
+            '../mn-samples-iso/sources/'
           else
-            "./spec/fixtures/"
+            './spec/fixtures/'
           end
 
-if !Dir.exist?(rt_path)
-  puts "pleas set path to rice-2023"
+unless Dir.exist?(rt_path)
+  puts 'pleas set path to rice-2023'
   exit
 end
 
@@ -31,21 +33,21 @@ adoc_files.each do |file_path|
   FileUtils.rm(file_path_rt) if File.exist?(file_path_rt)
   FileUtils.rm(file_path_diff) if File.exist?(file_path_diff)
   # begin
-  adoc_file = File.open(file_path).read
+  adoc_file = File.read(file_path)
   next if adoc_file.empty?
 
-  puts "parsing..."
+  puts 'parsing...'
   ast = Coradoc::Parser::Base.new.parse(adoc_file)
   sio = StringIO.new
   PP.pp(ast, sio)
   ast_string = sio.string
-  File.open(file_path_ast, "w") { |f| f.write(ast_string) }
-  puts "transforming..."
+  File.write(file_path_ast, ast_string)
+  puts 'transforming...'
   doc = Coradoc::Transformer.transform(ast[:document])
-  puts "generating..."
+  puts 'generating...'
   generated_adoc = Coradoc::Generator.gen_adoc(doc)
   cleaned_adoc = Coradoc::Input::HTML.cleaner.tidy(generated_adoc)
-  File.open("#{file_path}.roundtrip", "w") { |f| f.write(cleaned_adoc) }
+  File.write("#{file_path}.roundtrip", cleaned_adoc)
   `diff -B #{file_path} #{file_path}.roundtrip > #{file_path}.roundtrip.diff`
   # rescue
   # puts "unsuccessful..."