coradoc-docx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c3d4bb0be28a10758044449cbd23105ebf3b954813322561ae3f338af085e4a
+  data.tar.gz: 8fed48bf56249e71de9e8117f4345f25f6828558c3a1067ee37a786fa52e8506
+SHA512:
+  metadata.gz: b9ea07f47f7468155c3c3aa4e502284193c54609006ffb2768659fca3f0e77e8abd4edb7274bf07a6cf50f06c5922bd119d966f9ba5dfa1de419c65833619537
+  data.tar.gz: f323b453647188ac9ffb716c82263e9bb13bce2ca24efdb6eead3562f01925f07769d39d6f369de37d14e1ef464ea47d07369bbbcf716fb467f5d22ab5c8eceb

data/README.adoc

@@ -0,0 +1,164 @@
+= coradoc-docx
+image:https://img.shields.io/gem/v/coradoc-docx.svg[RubyGems Version]
+
+DOCX (OOXML) format support for the
+https://github.com/lutaml/coradoc[Coradoc] document transformation library.
+
+== Purpose
+
+coradoc-docx reads Microsoft Word `.docx` files via
+https://github.com/lutaml/uniword[Uniword] and transforms the OOXML model
+tree into Coradoc's canonical CoreModel. Once in CoreModel, the document can
+be serialized to AsciiDoc, Markdown, or any other supported output format.
+
+== Installation
+
+Add to your Gemfile:
+
+[source,ruby]
+----
+gem 'coradoc-docx'
+----
+
+Or install directly:
+
+[source,bash]
+----
+gem install coradoc-docx
+----
+
+The gem depends on `coradoc` and `uniword`, which will be installed
+automatically.
+
+== Usage
+
+=== Convert DOCX to AsciiDoc
+
+[source,ruby]
+----
+require 'coradoc'
+require 'coradoc/docx'
+
+adoc = Coradoc.convert("input.docx", from: :docx, to: :asciidoc)
+----
+
+=== Convert DOCX to Markdown
+
+[source,ruby]
+----
+md = Coradoc.convert("input.docx", from: :docx, to: :markdown)
+----
+
+=== Parse DOCX to CoreModel
+
+[source,ruby]
+----
+core = Coradoc.parse("input.docx", format: :docx)
+
+core.title         # => "Document Title"
+core.children      # => Array of sections, paragraphs, tables, etc.
+
+# Serialize to any format
+adoc = Coradoc.serialize(core, to: :asciidoc)
+html = Coradoc.serialize(core, to: :html)
+----
+
+=== CLI
+
+[source,bash]
+----
+# Convert DOCX to AsciiDoc
+coradoc convert document.docx -o output.adoc
+
+# Convert DOCX to Markdown
+coradoc convert document.docx -o output.md
+----
+
+== How It Works
+
+The DOCX pipeline uses Uniword to parse the OOXML zip archive into a typed
+model tree, then transforms it to CoreModel:
+
+....
+DOCX file
+  → Uniword::DocumentFactory.from_file
+  → OOXML model tree (Uniword::Wordprocessingml::*)
+  → Coradoc::Docx::Transform::ToCoreModel (rule-based dispatch)
+  → CoreModel tree (canonical hub)
+  → FromCoreModel (AsciiDoc or Markdown)
+  → Format model tree → Serializer → .adoc or .md file
+....
+
+The transform uses a **rule registry** with priority-based dispatch. Each
+OOXML element type has a dedicated rule class that produces a typed CoreModel
+node. Style-based semantic detection (headings, lists, quotes) is handled by
+`StyleResolver` and `NumberingResolver`.
+
+=== Supported OOXML Elements
+
+| OOXML Element | Style/Condition | CoreModel Target |
+|---------------|-----------------|------------------|
+| `w:p` (Heading style) | pStyle=HeadingN | StructuralElement (section) |
+| `w:p` (numPr) | numbering reference | ListBlock + ListItem |
+| `w:p` (Quote style) | style detection | Block (quote) |
+| `w:p` (Code style) | style detection | Block (source/listing) |
+| `w:p` (default) | - | Block (paragraph) |
+| `w:r` (bold) | rPr/bold | InlineElement (bold) |
+| `w:r` (italic) | rPr/italic | InlineElement (italic) |
+| `w:r` (underline) | rPr/underline | InlineElement (underline) |
+| `w:r` (strike) | rPr/strike | InlineElement (strikethrough) |
+| `w:r` (sub/sup) | rPr/vertAlign | InlineElement (subscript/superscript) |
+| `w:hyperlink` | r:id or w:anchor | InlineElement (link) |
+| `w:tbl` | - | Table |
+| `w:drawing` / `w:pict` | inline or anchor | Image |
+| `m:oMathPara` / `m:oMath` | - | Block or InlineElement (stem) |
+| `w:footnoteReference` | - | FootnoteReference |
+
+== Limitations
+
+* **Parse only** -- DOCX to CoreModel is supported; CoreModel to DOCX is not
+  yet implemented.
+* **Print layout** -- Page size, margins, headers/footers as page regions are
+  discarded (CoreModel is semantic, not print layout).
+* **Complex fields** -- Field characters (TOC, PAGE) are partially handled.
+* **Tracked changes** -- Deleted text is currently skipped.
+* **VML shapes** -- Only inline drawings are extracted.
+
+== Architecture
+
+=== Rule Classes
+
+Each OOXML element type is handled by a dedicated rule class in
+`Coradoc::Docx::Transform::Rules`:
+
+- `HeadingRule` -- Detects heading paragraphs via style or outline level
+- `ListItemRule` -- Detects numbered/bulleted paragraphs via numbering resolver
+- `ParagraphRule` -- Default paragraph transform
+- `RunRule` -- Inline formatting (bold, italic, monospace, links, etc.)
+- `TableRule` -- Table structure with rowspan/colspan
+- `HyperlinkRule` -- External links and bookmarks
+- `ImageRule` -- Inline and anchored drawings
+- `FootnoteRule` -- Footnote references
+- `MathRule` -- OMML math via Plurimath/LaTeX
+
+=== Resolvers
+
+- `StyleResolver` -- Walks the OOXML style definitions to detect semantic
+  roles (heading levels, code style, quote style) including `basedOn` chains
+- `NumberingResolver` -- Resolves numbering definitions to detect ordered vs.
+  unordered lists and their marker types
+
+== Development
+
+Run tests:
+
+[source,bash]
+----
+bundle exec rake spec:coradoc_docx
+----
+
+== License
+
+Copyright:: 2024-2026 Ribose Inc.
+
+Licensed under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache License, Version 2.0].

data/lib/coradoc/docx/transform/context.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Docx
+    module Transform
+      # Shared context for a single OOXML → CoreModel transform pass.
+      #
+      # Holds resolvers, footnote content, image references, and the
+      # rule registry. Passed to every rule's #apply method so rules
+      # can delegate sub-transforms (e.g., transform runs inside a
+      # paragraph).
+      class Context
+        attr_reader :style_resolver, :numbering_resolver,
+                    :footnotes, :image_refs, :registry
+
+        # @param styles_configuration [Object, nil] Uniword styles config
+        # @param numbering_configuration [Object, nil] Uniword numbering config
+        # @param footnotes [Hash{String => Array}] footnote id → content paragraphs
+        # @param registry [RuleRegistry] rule dispatch registry
+        def initialize(styles_configuration: nil, numbering_configuration: nil,
+                       footnotes: {}, registry: nil)
+          @style_resolver = StyleResolver.new(styles_configuration)
+          @numbering_resolver = NumberingResolver.new(numbering_configuration)
+          @footnotes = footnotes
+          @image_refs = []
+          @registry = registry
+        end
+
+        # Transform an element using the registry
+        #
+        # @param element [Object] OOXML element
+        # @return [Coradoc::CoreModel::Base, Array, String, nil]
+        def transform(element)
+          return nil if element.nil?
+
+          rule = @registry.find_rule(element)
+          rule.apply(element, self)
+        end
+
+        # Fetch footnote content by ID
+        #
+        # @param id [String, Integer] footnote ID
+        # @return [String, nil] footnote text content
+        def footnote_content(id)
+          return nil unless id
+
+          paragraphs = @footnotes[id.to_s]
+          return nil unless paragraphs
+
+          paragraphs.map do |para|
+            extract_paragraph_text(para)
+          end.join("\n")
+        end
+
+        # Record an image reference for later extraction
+        #
+        # @param ref [Hash] image reference with :src, :alt, etc.
+        def register_image(ref)
+          @image_refs << ref
+        end
+
+        private
+
+        def extract_paragraph_text(paragraph)
+          return '' unless paragraph.is_a?(Uniword::Wordprocessingml::Paragraph) || paragraph.is_a?(Uniword::Wordprocessingml::Run)
+
+          paragraph.text.to_s
+        end
+      end
+    end
+  end
+end