anydoc-ruby 0.1.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b73a92386a7dc619a85892686d5fb139df873bd2c762be8e78c29f602261e405
+  data.tar.gz: 694607679a045c2599469b6b499c8970aa4963134364b9aebf1904a321518f50
+SHA512:
+  metadata.gz: 6fef910cd6101ca804b3e6d58b3fbcd4cb6250238349d0b0c387c57e040ed4a4d141e1f8b6814790847d7e070e01ac550547ed43b144ca4e7dc1a4b2ddc8e9ce
+  data.tar.gz: 736c2870384cf448e7fc504e328ce835ac1b255bd6f09fff10011ba6a63b6852b544d6af9643bfa2088d15d80ae6c1c793b2019dedbbbaf3fb3864d29738e71f

data/Cargo.toml

@@ -0,0 +1,12 @@
+# Workspace root for the extension crate. It ships with the source gem, so an
+# installed gem builds against this root instead of walking up into whatever
+# directory RubyGems unpacked it into.
+[workspace]
+members = ["ext/anydoc"]
+resolver = "3"
+
+# Profiles belong to the workspace root, so the extension's release build is
+# configured here.
+[profile.release]
+lto = "thin"
+strip = "symbols"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sideguide Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,149 @@
+# anydoc-ruby
+
+[![Gem](https://img.shields.io/gem/v/anydoc-ruby.svg)](https://rubygems.org/gems/anydoc-ruby)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/honzasterba/anydoc/blob/main/LICENSE)
+
+Convert Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and PDF files into clean GitHub-Flavored Markdown. Ruby bindings for the [anydoc](https://crates.io/crates/anydoc) Rust crate, which is built by [Firecrawl](https://firecrawl.dev).
+
+Every format parses into one shared document model and renders through a single Markdown serializer, so headings, tables, lists, and footnotes come out the same no matter which format goes in. Conversion releases the GVL, so other threads keep running. RBS signatures ship with the gem.
+
+```bash
+bundle add anydoc-ruby
+```
+
+The gem installs as `anydoc-ruby` and requires as `anydoc`, so a Gemfile entry that Bundler auto-requires needs `gem "anydoc-ruby", require: "anydoc"`. Precompiled native gems cover Linux (glibc and musl), macOS, and Windows on Ruby 3.2+; anywhere else, `gem install` builds the extension from source, which needs a [Rust toolchain](https://rustup.rs).
+
+## Supported formats
+
+| Format           | Extensions                                                 |
+| ---------------- | ---------------------------------------------------------- |
+| Word             | `.doc`, `.docx`, `.docm`                                   |
+| PowerPoint       | `.ppt`, `.pps`, `.pot`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm` |
+| Excel            | `.xls`, `.xlsx`, `.xlsm`, `.xlsb`                          |
+| OpenDocument     | `.odt`, `.ods`, `.odp`                                     |
+| Rich Text Format | `.rtf`                                                     |
+| EPUB             | `.epub`                                                    |
+| CSV              | `.csv`                                                     |
+| PDF              | `.pdf`                                                     |
+
+## Usage
+
+```ruby
+require "anydoc"
+
+# From a file path:
+markdown = Anydoc.to_markdown("report.docx")
+
+# From bytes, with the format detected from the content:
+markdown = Anydoc.to_markdown_bytes(data)
+
+# Or name it, which signature-less formats (CSV) need:
+markdown = Anydoc.to_markdown_bytes(data, format: :csv)
+
+# Or stop at the document model, which also carries embedded assets:
+document = Anydoc.to_document(data)
+```
+
+`to_markdown` takes anything path-like, including a `Pathname`. A format is named with a symbol from `Anydoc::FORMATS`; a string is accepted too.
+
+## Errors
+
+A conversion raises only when no meaningful Markdown could come out of the file. The exception class names what went wrong:
+
+```ruby
+begin
+  Anydoc.to_markdown(path)
+rescue Anydoc::EncryptedError, Anydoc::UnsupportedError => error
+  # No document comes out of these, so record the file and take the next one.
+  unconverted << [path, error.class]
+  nil
+end
+```
+
+| Exception                  | Raised when                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `Anydoc::UnsupportedError`   | Unknown format, or one that cannot be converted (an image-only PDF) |
+| `Anydoc::MalformedError`     | Structurally unusable: no meaningful content could be extracted     |
+| `Anydoc::EncryptedError`     | Encrypted or password-protected                                     |
+| `Anydoc::ResourceLimitError` | Crossed a fixed safety limit (decompression, nesting, node count)   |
+| `Anydoc::MissingPartError`   | A part required for any meaningful output is absent                 |
+| `Errno::*`                   | The file could not be read, from `to_markdown` only                 |
+
+The five conversion failures subclass `Anydoc::ConvertError`, so rescuing that handles all of them at once. `MalformedError#part` and `MissingPartError#part` name the package part at fault, `ResourceLimitError#limit` names the limit crossed as a symbol, and `#message` carries the whole message. A `format:` argument naming no supported format raises `ArgumentError`.
+
+## Format detection
+
+The format is read from the file content, using the marker its specification designates: the PDF header, the RTF open group, OLE stream names, the ZIP package mimetype and content types. CSV has no such marker, so detection returns `nil` for it and the extension, or an explicit format, names it instead.
+
+```ruby
+Anydoc.format_from_bytes(data)         # :docx, or nil when nothing matches
+Anydoc.format_from_extension(".pptm")  # :pptx
+Anydoc.format_from_path("report.odt")  # :odt
+```
+
+## The document model
+
+`Anydoc.to_document` stops at the parsed model instead of rendering it. Every class in it is a `Data`, so instances are frozen, compare by value, answer `to_h`, and destructure in `case/in`:
+
+```ruby
+document = Anydoc.to_document(File.binread("report.docx"))
+
+titles = document.blocks.filter_map do |block|
+  case block
+  in Anydoc::Block[kind: :heading, level: 1, content:]
+    content.filter_map(&:text).join
+  else
+    nil
+  end
+end
+```
+
+Variants are a `kind` symbol plus the members that kind carries; members belonging to other kinds are `nil`. `Document#blocks` holds the body, `Document#notes` the footnote and endnote bodies that `:note_ref` inlines point at, and `Document#assets` the embedded bytes.
+
+PDFs convert straight to Markdown and have no document-model form, so `to_document` raises `UnsupportedError` for them; use `to_markdown_bytes`.
+
+## Images and embedded objects
+
+Markdown cannot embed bytes, so an embedded image renders as its alt text while the bytes stay on `document.assets` as binary strings, tagged with a media type and the part they came from. Images that carry an external URL render as ordinary Markdown images.
+
+```ruby
+document.assets.each do |asset|
+  File.binwrite("asset-#{asset.id}", asset.data) if asset.media_type.start_with?("image/")
+end
+```
+
+Full behavior notes and benchmarks live in the [repository README](https://github.com/honzasterba/anydoc#readme).
+
+## Development
+
+From this directory, with a [Rust toolchain](https://rustup.rs) installed:
+
+```bash
+bundle install
+bundle exec rake        # compile the extension, then run the tests
+bundle exec rake compile
+bundle exec rake test
+```
+
+Inside this repository the extension builds against the crate in the parent directory rather than the published one; `.cargo/config.toml` is what redirects it.
+
+### Packaging
+
+The source gem needs nothing but RubyGems:
+
+```bash
+bundle exec rake build          # pkg/anydoc-ruby-<version>.gem
+```
+
+The precompiled gems are cross-compiled in [rb-sys-dock](https://github.com/oxidize-rb/rb-sys) containers, so they need Docker running. Each one carries an extension per Ruby ABI:
+
+```bash
+bundle exec rake gems:x86_64-linux   # one platform
+bundle exec rake gems:all            # the source gem and all seven platforms
+```
+
+Run these through Rake rather than calling `rb-sys-dock` from this directory: the container mounts the shell's working directory, and the build needs the crate one level above it, so the tasks run the CLI from the repository root with `--directory ruby`. The first build of each platform pulls a multi-gigabyte image.
+
+## License
+
+[MIT](https://github.com/honzasterba/anydoc/blob/main/LICENSE)

data/ext/anydoc/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "anydoc"
+version = "0.1.0"
+edition = "2024"
+description = "Ruby bindings for anydoc"
+license = "MIT"
+repository = "https://github.com/honzasterba/anydoc"
+publish = false
+
+[lib]
+# Names the artifact the extension loads (anydoc.so / anydoc.bundle) and the
+# Init_anydoc entry point rb_sys wires up.
+crate-type = ["cdylib"]
+
+[dependencies]
+# From crates.io, so an installed source gem builds anywhere. Builds inside
+# this repository redirect it to the local crate through ruby/.cargo/config.toml,
+# and scripts/check-versions.sh keeps this requirement on the release version.
+anydoc = "0.1.7"
+magnus = "0.8"
+# For rb_thread_call_without_gvl; magnus resolves to the same major version.
+rb-sys = "0.9"

data/ext/anydoc/extconf.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+# Builds ext/anydoc into lib/anydoc/anydoc.<dlext>, whose Init_anydoc entry
+# point is the #[magnus::init] function in src/lib.rs.
+create_rust_makefile("anydoc/anydoc") do |ext|
+  ext.profile = ENV.fetch("RB_SYS_CARGO_PROFILE", "release").to_sym
+end

data/ext/anydoc/src/document.rs

@@ -0,0 +1,310 @@
+//! The document model, built eagerly out of the `Data` classes declared in
+//! `lib/anydoc/document.rb`.
+//!
+//! Variant enums (block kinds, link targets, ...) surface as snake_case
+//! symbols on a `kind` member, with the variant's payload on members that are
+//! `nil` for every other kind - the same shape the Node and Python bindings
+//! give them. Members are passed positionally, in the order the Ruby classes
+//! declare them, which `test/document_test.rb` pins.
+
+use magnus::prelude::*;
+use magnus::{Error, RArray, RClass, RModule, Ruby, Value};
+
+use anydoc::model;
+
+/// Builds one document. The classes are looked up once per conversion rather
+/// than once per node.
+struct Build<'a> {
+    ruby: &'a Ruby,
+    classes: Classes,
+}
+
+struct Classes {
+    document: RClass,
+    block: RClass,
+    inline: RClass,
+    style: RClass,
+    link_target: RClass,
+    image_source: RClass,
+    list: RClass,
+    list_item: RClass,
+    table: RClass,
+    cell_slot: RClass,
+    cell: RClass,
+    note: RClass,
+    asset: RClass,
+}
+
+impl Classes {
+    fn new(ruby: &Ruby) -> Result<Self, Error> {
+        let anydoc: RModule = ruby.class_object().const_get("Anydoc")?;
+        Ok(Classes {
+            document: anydoc.const_get("Document")?,
+            block: anydoc.const_get("Block")?,
+            inline: anydoc.const_get("Inline")?,
+            style: anydoc.const_get("Style")?,
+            link_target: anydoc.const_get("LinkTarget")?,
+            image_source: anydoc.const_get("ImageSource")?,
+            list: anydoc.const_get("List")?,
+            list_item: anydoc.const_get("ListItem")?,
+            table: anydoc.const_get("Table")?,
+            cell_slot: anydoc.const_get("CellSlot")?,
+            cell: anydoc.const_get("Cell")?,
+            note: anydoc.const_get("Note")?,
+            asset: anydoc.const_get("Asset")?,
+        })
+    }
+}
+
+/// Build `Anydoc::Document` from a parsed document.
+pub fn build(ruby: &Ruby, document: model::Document) -> Result<Value, Error> {
+    Build { ruby, classes: Classes::new(ruby)? }.document(document)
+}
+
+impl Build<'_> {
+    fn document(&self, document: model::Document) -> Result<Value, Error> {
+        let blocks = self.array(document.blocks, Self::block)?;
+        let notes = self.array(document.notes, Self::note)?;
+        let assets = self.array(document.assets, Self::asset)?;
+        self.classes.document.funcall("new", (blocks, notes, assets))
+    }
+
+    fn block(&self, block: model::Block) -> Result<Value, Error> {
+        let fields = match block {
+            model::Block::Heading { level, anchor, content } => BlockFields {
+                level: Some(level),
+                anchor,
+                content: Some(self.array(content, Self::inline)?),
+                ..BlockFields::of("heading")
+            },
+            model::Block::Paragraph(content) => BlockFields {
+                content: Some(self.array(content, Self::inline)?),
+                ..BlockFields::of("paragraph")
+            },
+            model::Block::List(list) => {
+                BlockFields { list: Some(self.list(list)?), ..BlockFields::of("list") }
+            }
+            model::Block::Table(table) => {
+                BlockFields { table: Some(self.table(table)?), ..BlockFields::of("table") }
+            }
+            model::Block::BlockQuote(blocks) => BlockFields {
+                blocks: Some(self.array(blocks, Self::block)?),
+                ..BlockFields::of("block_quote")
+            },
+            model::Block::CodeBlock { lang, text } => {
+                BlockFields { lang, text: Some(text), ..BlockFields::of("code_block") }
+            }
+            model::Block::Rule => BlockFields::of("rule"),
+        };
+        self.classes.block.funcall(
+            "new",
+            (
+                self.ruby.sym_new(fields.kind),
+                fields.level,
+                fields.anchor,
+                fields.content,
+                fields.list,
+                fields.table,
+                fields.blocks,
+                fields.lang,
+                fields.text,
+            ),
+        )
+    }
+
+    fn inline(&self, inline: model::Inline) -> Result<Value, Error> {
+        let fields = match inline {
+            model::Inline::Text { text, style } => InlineFields {
+                text: Some(text),
+                style: Some(self.style(style)?),
+                ..InlineFields::of("text")
+            },
+            model::Inline::Link { content, target } => InlineFields {
+                content: Some(self.array(content, Self::inline)?),
+                target: Some(self.link_target(target)?),
+                ..InlineFields::of("link")
+            },
+            model::Inline::Image { alt, source } => InlineFields {
+                alt: Some(alt),
+                source: Some(self.image_source(source)?),
+                ..InlineFields::of("image")
+            },
+            model::Inline::Anchor(id) => {
+                InlineFields { anchor: Some(id), ..InlineFields::of("anchor") }
+            }
+            model::Inline::NoteRef(id) => {
+                InlineFields { note_id: Some(id), ..InlineFields::of("note_ref") }
+            }
+            model::Inline::LineBreak => InlineFields::of("line_break"),
+        };
+        self.classes.inline.funcall(
+            "new",
+            (
+                self.ruby.sym_new(fields.kind),
+                fields.text,
+                fields.style,
+                fields.content,
+                fields.target,
+                fields.alt,
+                fields.source,
+                fields.anchor,
+                fields.note_id,
+            ),
+        )
+    }
+
+    fn style(&self, style: model::Style) -> Result<Value, Error> {
+        self.classes.style.funcall("new", (style.bold, style.italic, style.strike, style.code))
+    }
+
+    fn link_target(&self, target: model::LinkTarget) -> Result<Value, Error> {
+        let (kind, value) = match target {
+            model::LinkTarget::External(value) => ("external", value),
+            model::LinkTarget::Relative(value) => ("relative", value),
+            model::LinkTarget::Anchor(value) => ("anchor", value),
+        };
+        self.classes.link_target.funcall("new", (self.ruby.sym_new(kind), value))
+    }
+
+    fn image_source(&self, source: model::ImageSource) -> Result<Value, Error> {
+        let (kind, url, asset_id) = match source {
+            model::ImageSource::External(url) => ("external", Some(url), None),
+            model::ImageSource::Asset(id) => ("asset", None, Some(id.0)),
+            model::ImageSource::Unavailable => ("unavailable", None, None),
+        };
+        self.classes.image_source.funcall("new", (self.ruby.sym_new(kind), url, asset_id))
+    }
+
+    fn list(&self, list: model::List) -> Result<Value, Error> {
+        let marker = match list.marker {
+            model::MarkerKind::Bullet => "bullet",
+            model::MarkerKind::Decimal => "decimal",
+            model::MarkerKind::LowerAlpha => "lower_alpha",
+            model::MarkerKind::UpperAlpha => "upper_alpha",
+            model::MarkerKind::LowerRoman => "lower_roman",
+            model::MarkerKind::UpperRoman => "upper_roman",
+        };
+        let items = self.array(list.items, Self::list_item)?;
+        self.classes.list.funcall("new", (self.ruby.sym_new(marker), list.start, items))
+    }
+
+    fn list_item(&self, item: model::ListItem) -> Result<Value, Error> {
+        let blocks = self.array(item.blocks, Self::block)?;
+        self.classes.list_item.funcall("new", (blocks, item.checked, item.marker_label))
+    }
+
+    fn table(&self, table: model::Table) -> Result<Value, Error> {
+        let grid = self.ruby.ary_new_capa(table.grid.len());
+        for row in table.grid {
+            grid.push(self.array(row, Self::cell_slot)?)?;
+        }
+        let kind = match table.kind {
+            model::TableKind::Data => "data",
+            model::TableKind::Layout => "layout",
+        };
+        self.classes.table.funcall("new", (grid, table.header_rows, self.ruby.sym_new(kind)))
+    }
+
+    fn cell_slot(&self, slot: model::CellSlot) -> Result<Value, Error> {
+        let (kind, cell, origin) = match slot {
+            model::CellSlot::Origin(cell) => ("origin", Some(self.cell(cell)?), None),
+            model::CellSlot::Covered { origin_row, origin_col } => {
+                ("covered", None, Some((origin_row, origin_col)))
+            }
+        };
+        self.classes.cell_slot.funcall(
+            "new",
+            (self.ruby.sym_new(kind), cell, origin.map(|(row, _)| row), origin.map(|(_, col)| col)),
+        )
+    }
+
+    fn cell(&self, cell: model::Cell) -> Result<Value, Error> {
+        let blocks = self.array(cell.blocks, Self::block)?;
+        self.classes.cell.funcall("new", (blocks, cell.col_span, cell.row_span))
+    }
+
+    fn note(&self, note: model::Note) -> Result<Value, Error> {
+        let kind = match note.kind {
+            model::NoteKind::Footnote => "footnote",
+            model::NoteKind::Endnote => "endnote",
+        };
+        let blocks = self.array(note.blocks, Self::block)?;
+        self.classes.note.funcall("new", (note.id, self.ruby.sym_new(kind), blocks))
+    }
+
+    fn asset(&self, asset: model::Asset) -> Result<Value, Error> {
+        // Binary string: asset bytes are payloads, not text.
+        let data = self.ruby.str_from_slice(&asset.bytes);
+        self.classes.asset.funcall("new", (asset.id.0, asset.media_type, asset.origin_part, data))
+    }
+
+    fn array<T>(
+        &self,
+        items: Vec<T>,
+        build: fn(&Self, T) -> Result<Value, Error>,
+    ) -> Result<RArray, Error> {
+        let array = self.ruby.ary_new_capa(items.len());
+        for item in items {
+            array.push(build(self, item)?)?;
+        }
+        Ok(array)
+    }
+}
+
+/// Every member of `Anydoc::Block`; a variant sets only the ones it carries.
+struct BlockFields {
+    kind: &'static str,
+    level: Option<u8>,
+    anchor: Option<String>,
+    content: Option<RArray>,
+    list: Option<Value>,
+    table: Option<Value>,
+    blocks: Option<RArray>,
+    lang: Option<String>,
+    text: Option<String>,
+}
+
+impl BlockFields {
+    fn of(kind: &'static str) -> BlockFields {
+        BlockFields {
+            kind,
+            level: None,
+            anchor: None,
+            content: None,
+            list: None,
+            table: None,
+            blocks: None,
+            lang: None,
+            text: None,
+        }
+    }
+}
+
+/// Every member of `Anydoc::Inline`; a variant sets only the ones it carries.
+struct InlineFields {
+    kind: &'static str,
+    text: Option<String>,
+    style: Option<Value>,
+    content: Option<RArray>,
+    target: Option<Value>,
+    alt: Option<String>,
+    source: Option<Value>,
+    anchor: Option<String>,
+    note_id: Option<String>,
+}
+
+impl InlineFields {
+    fn of(kind: &'static str) -> InlineFields {
+        InlineFields {
+            kind,
+            text: None,
+            style: None,
+            content: None,
+            target: None,
+            alt: None,
+            source: None,
+            anchor: None,
+            note_id: None,
+        }
+    }
+}