Module: Coradoc

Extended by:
Configurable
Defined in:
lib/coradoc/coradoc.rb,
lib/coradoc.rb,
lib/coradoc/cli.rb,
lib/coradoc/hooks.rb,
lib/coradoc/query.rb,
lib/coradoc/errors.rb,
lib/coradoc/logger.rb,
lib/coradoc/version.rb,
lib/coradoc/visitor.rb,
lib/coradoc/dispatch.rb,
lib/coradoc/pipeline.rb,
lib/coradoc/registry.rb,
lib/coradoc/core_model.rb,
lib/coradoc/validation.rb,
lib/coradoc/configurable.rb,
lib/coradoc/format_module.rb,
lib/coradoc/introspection.rb,
lib/coradoc/link_rewriter.rb,
lib/coradoc/relative_path.rb,
lib/coradoc/core_model/toc.rb,
lib/coradoc/format_catalog.rb,
lib/coradoc/core_model/base.rb,
lib/coradoc/core_model/term.rb,
lib/coradoc/core_model/block.rb,
lib/coradoc/core_model/image.rb,
lib/coradoc/core_model/table.rb,
lib/coradoc/include_resolver.rb,
lib/coradoc/resolve_includes.rb,
lib/coradoc/include_selectors.rb,
lib/coradoc/core_model/callout.rb,
lib/coradoc/core_model/include.rb,
lib/coradoc/core_model/footnote.rb,
lib/coradoc/core_model/metadata.rb,
lib/coradoc/core_model/list_item.rb,
lib/coradoc/core_model/list_block.rb,
lib/coradoc/core_model/open_block.rb,
lib/coradoc/core_model/pass_block.rb,
lib/coradoc/core_model/stem_block.rb,
lib/coradoc/link_rewriter/visitor.rb,
lib/coradoc/core_model/frontmatter.rb,
lib/coradoc/core_model/quote_block.rb,
lib/coradoc/core_model/verse_block.rb,
lib/coradoc/include_selectors/tags.rb,
lib/coradoc/link_rewriter/identity.rb,
lib/coradoc/performance_regression.rb,
lib/coradoc/core_model/bibliography.rb,
lib/coradoc/core_model/callout_text.rb,
lib/coradoc/core_model/comment_line.rb,
lib/coradoc/core_model/has_children.rb,
lib/coradoc/core_model/id_generator.rb,
lib/coradoc/core_model/source_block.rb,
lib/coradoc/core_model/text_content.rb,
lib/coradoc/include_selectors/lines.rb,
lib/coradoc/core_model/comment_block.rb,
lib/coradoc/core_model/example_block.rb,
lib/coradoc/core_model/listing_block.rb,
lib/coradoc/core_model/literal_block.rb,
lib/coradoc/core_model/sidebar_block.rb,
lib/coradoc/core_model/toc_generator.rb,
lib/coradoc/include_selectors/indent.rb,
lib/coradoc/core_model/inline_content.rb,
lib/coradoc/core_model/inline_element.rb,
lib/coradoc/core_model/reviewer_block.rb,
lib/coradoc/core_model/definition_item.rb,
lib/coradoc/core_model/definition_list.rb,
lib/coradoc/core_model/include_options.rb,
lib/coradoc/core_model/output_artifact.rb,
lib/coradoc/core_model/paragraph_block.rb,
lib/coradoc/core_model/annotation_block.rb,
lib/coradoc/core_model/children_content.rb,
lib/coradoc/include_resolver/filesystem.rb,
lib/coradoc/core_model/element_attribute.rb,
lib/coradoc/core_model/frontmatter/codec.rb,
lib/coradoc/core_model/bibliography_entry.rb,
lib/coradoc/core_model/raw_inline_element.rb,
lib/coradoc/core_model/structural_element.rb,
lib/coradoc/introspection/element_counter.rb,
lib/coradoc/include_selectors/level_offset.rb,
lib/coradoc/core_model/include_level_offset.rb,
lib/coradoc/core_model/horizontal_rule_block.rb,
lib/coradoc/core_model/frontmatter/text_splitter.rb,
lib/coradoc/core_model/frontmatter/field_transform.rb,
lib/coradoc/core_model/frontmatter/schema_resolver.rb,
lib/coradoc/core_model/frontmatter/frontmatter_value.rb

Overview

Coradoc - A hub-and-spoke document transformation library

Coradoc provides a unified document model (CoreModel) and transformation infrastructure for converting between document formats such as AsciiDoc, HTML, and Markdown.

## Architecture

Coradoc uses a hub-and-spoke architecture where CoreModel acts as the canonical document representation. Each format (AsciiDoc, HTML, Markdown) has its own model and transformers to/from CoreModel.

“‘ Source Format → Source Model → CoreModel → Target Model → Target Format “`

## Quick Start

Examples:

Parsing documents

require 'coradoc'

# Parse AsciiDoc to CoreModel
doc = Coradoc.parse("= Title\n\nContent", format: :asciidoc)

Converting between formats

# Convert AsciiDoc to HTML
html = Coradoc.convert(adoc_text, from: :asciidoc, to: :html)

# Convert Markdown to AsciiDoc
adoc = Coradoc.convert(md_text, from: :markdown, to: :asciidoc)

Using the hooks system

Coradoc::Hooks.register(:before_parse) do |content, format:|
  puts "Parsing #{format} document..."
  content
end

See Also:

Defined Under Namespace

Modules: Configurable, CoreModel, FormatCatalog, FormatModule, Hooks, IncludeSelectors, Introspection, LinkRewriter, PerformanceRegression, Pipeline, Query, RelativePath, Validation, Visitor Classes: CLI, CircularIncludeError, Dispatch, Error, FileNotFoundError, IncludeDepthExceededError, IncludeNotFoundError, IncludeResolver, IncludeTooLargeError, Logger, ParseError, Registry, ResolveIncludes, TransformationError, UnsafeIncludeError, UnsupportedFormatError, ValidationError

Constant Summary collapse

ERROR_SUGGESTIONS =

Suggestion patterns for common parsing errors

These patterns are matched against error messages and source content to provide helpful suggestions for fixing common issues.

[
  {
    pattern: /unterminated.*string|unexpected.*end.*of.*input|expected.*["']/i,
    suggestion: 'Check for unclosed quotes or strings',
    examples: ["'text'", '"text"']
  },
  {
    pattern: /unexpected.*indentation|indentation.*error|inconsistent.*indent/i,
    suggestion: 'Check indentation - use consistent spaces or tabs',
    examples: ['  indented line', '    nested item']
  },
  {
    pattern: /missing.*separator|expected.*delimiter|missing.*comma/i,
    suggestion: 'Add missing separator between elements',
    examples: ['item1, item2', 'key: value']
  },
  {
    pattern: /invalid.*attribute|unknown.*attribute|attribute.*not.*allowed/i,
    suggestion: 'Check attribute spelling and allowed values',
    examples: ['[role=example]', '[source,ruby]']
  },
  {
    pattern: /invalid.*heading|heading.*level|expected.*heading/i,
    suggestion: 'Use valid heading syntax with = or # markers',
    examples: ['= Level 1', '== Level 2', '### Level 3']
  },
  {
    pattern: /invalid.*list|list.*marker|expected.*list.*item/i,
    suggestion: 'Use correct list markers (*, -, ., or numbered)',
    examples: ['* bullet', '. ordered', 'term:: definition']
  },
  {
    pattern: /invalid.*link|malformed.*url|link.*syntax/i,
    suggestion: 'Use correct link syntax: text[url] or link:url[]',
    examples: ['Google[https://google.com]', 'link:file.adoc[]']
  },
  {
    pattern: /invalid.*table|table.*delimiter|expected.*separator/i,
    suggestion: 'Check table syntax with | delimiters',
    examples: ["|===\n| Cell 1 | Cell 2\n|==="]
  },
  {
    pattern: /invalid.*block|block.*delimiter|unterminated.*block/i,
    suggestion: 'Ensure block delimiters match (----, ****, ====, etc.)',
    examples: ["----\ncode\n----", "====\nexample\n===="]
  },
  {
    pattern: /invalid.*macro|unknown.*macro|macro.*syntax/i,
    suggestion: 'Check macro syntax: name:target[attributes]',
    examples: ['include::file.adoc[]', 'image::image.png[]']
  }
].freeze
VERSION = 
'2.0.24'

Class Method Summary collapse

Methods included from Configurable

load_configuration, reset_configuration!

Class Method Details

.binary_format?(format) ⇒ Boolean

Returns:

  • (Boolean) 


91
 
# File 'lib/coradoc/coradoc.rb', line 91

def binary_format?(format) = FormatCatalog.binary_format?(format)

.build ⇒ Object 



81
 
# File 'lib/coradoc/coradoc.rb', line 81

def build(...) = Pipeline.build(...)

.config ⇒ Configuration

Shortcut to configuration

Returns:



516
517
518
 
# File 'lib/coradoc/configurable.rb', line 516

def self.config
  Configurable.configuration
end

.configure {|Configuration| ... } ⇒ void

This method returns an undefined value.

Shortcut to configure

Yields:



524
525
526
 
# File 'lib/coradoc/configurable.rb', line 524

def self.configure(&block)
  Configurable.configure(&block) if block_given?
end

.convert(text) ⇒ Object 



75
 
# File 'lib/coradoc/coradoc.rb', line 75

def convert(text, **) = Pipeline.convert(text, **)

.convert_file(path) ⇒ Object 



85
 
# File 'lib/coradoc/coradoc.rb', line 85

def convert_file(path, **) = Pipeline.convert_file(path, **)

.describe_element(elem) ⇒ Object 



111
 
# File 'lib/coradoc/coradoc.rb', line 111

def describe_element(elem) = Introspection.describe_element(elem)

.detect_format(filename) ⇒ Object

—- Format detection (delegates to FormatCatalog) —-



89
 
# File 'lib/coradoc/coradoc.rb', line 89

def detect_format(filename) = FormatCatalog.detect_format(filename)

.document_stats(doc) ⇒ Object 



109
 
# File 'lib/coradoc/coradoc.rb', line 109

def document_stats(doc) = Introspection.document_stats(doc)

.file_info(path) ⇒ Object

—- Introspection (delegates to Introspection) —-



105
 
# File 'lib/coradoc/coradoc.rb', line 105

def file_info(path) = Introspection.file_info(path)

.format_capabilities ⇒ Object 



99
 
# File 'lib/coradoc/coradoc.rb', line 99

def format_capabilities = FormatCatalog.capabilities

.get_format(format_name) ⇒ Object 



63
 
# File 'lib/coradoc/coradoc.rb', line 63

def get_format(format_name) = FormatCatalog.get_format(format_name)

.normalize_format(name) ⇒ Object 



93
 
# File 'lib/coradoc/coradoc.rb', line 93

def normalize_format(name) = FormatCatalog.normalize_format(name)

.parse(text, format:) ⇒ Object

—- Pipeline (delegates to Pipeline) —-



69
 
# File 'lib/coradoc/coradoc.rb', line 69

def parse(text, format:) = Pipeline.parse(text, format: format)

.parse_file(path) ⇒ Object 



83
 
# File 'lib/coradoc/coradoc.rb', line 83

def parse_file(path, **) = Pipeline.parse_file(path, **)

.parse_format?(format) ⇒ Boolean

Returns:

  • (Boolean) 


97
 
# File 'lib/coradoc/coradoc.rb', line 97

def parse_format?(format) = FormatCatalog.parse_format?(format)

.register_format(format_name, format_module, **options) ⇒ Object 



59
60
61
 
# File 'lib/coradoc/coradoc.rb', line 59

def register_format(format_name, format_module, **options)
  FormatCatalog.register_format(format_name, format_module, **options)
end

.registered_formats ⇒ Object 



65
 
# File 'lib/coradoc/coradoc.rb', line 65

def registered_formats = FormatCatalog.registered_formats

.registry ⇒ Object

—- Format registry (delegates to FormatCatalog) —-



57
 
# File 'lib/coradoc/coradoc.rb', line 57

def registry = FormatCatalog.registry

.resolve_includes(document) ⇒ Object 



71
 
# File 'lib/coradoc/coradoc.rb', line 71

def resolve_includes(document, **) = Pipeline.resolve_includes(document, **)

.resolve_output_format(output_file) ⇒ Object 



101
 
# File 'lib/coradoc/coradoc.rb', line 101

def resolve_output_format(output_file, **) = FormatCatalog.resolve_output_format(output_file, **)

.rewrite_links ⇒ Object 



73
 
# File 'lib/coradoc/coradoc.rb', line 73

def rewrite_links(...) = Pipeline.rewrite_links(...)

.serialize(model) ⇒ Object 



79
 
# File 'lib/coradoc/coradoc.rb', line 79

def serialize(model, **) = Pipeline.serialize(model, **)

.serialize_format?(format) ⇒ Boolean

Returns:

  • (Boolean) 


95
 
# File 'lib/coradoc/coradoc.rb', line 95

def serialize_format?(format) = FormatCatalog.serialize_format?(format)

.strip_unicode(string, only: nil) ⇒ String

Strip unicode whitespace from a string.

Parameters:

  • string (String) —

    the string to strip

  • only (Symbol, nil) (defaults to: nil) —

    what to strip: :begin, :end, or nil for both

Returns:

  • (String) —

    the stripped string



120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/coradoc/coradoc.rb', line 120

def strip_unicode(string, only: nil)
  return string if string.nil?

  case only
  when :begin
    string.sub(/^\p{Zs}+/, '')
  when :end
    string.sub(/\p{Zs}+$/, '')
  else
    string.sub(/^\p{Zs}+/, '').sub(/\p{Zs}+$/, '')
  end
end

.to_core(model) ⇒ Object 



77
 
# File 'lib/coradoc/coradoc.rb', line 77

def to_core(model) = Pipeline.to_core(model)

.validate_file(path) ⇒ Object 



107
 
# File 'lib/coradoc/coradoc.rb', line 107

def validate_file(path, **) = Introspection.validate_file(path, **)