anydoc-ruby 0.1.7

data/ext/anydoc/src/lib.rs

@@ -0,0 +1,182 @@
+//! Ruby bindings for anydoc.
+//!
+//! The Rust side is deliberately thin: it converts, builds the document model
+//! out of the `Data` classes `lib/anydoc/document.rb` declares, and raises the
+//! error classes `lib/anydoc/errors.rb` declares. Argument coercion, keyword
+//! arguments, and file reading live in Ruby, on `Anydoc`.
+
+use magnus::prelude::*;
+use magnus::{
+    Error, Exception, IntoValue, RClass, RModule, RObject, RString, Ruby, StaticSymbol, Symbol,
+    TryConvert, Value, function,
+};
+
+mod document;
+mod nogvl;
+
+use nogvl::nogvl;
+
+/// Format names, as the extension that identifies each format. Container
+/// variants that share a parser (`.docm`, `.xlsm`, `.ppsx`, ...) map onto
+/// these through `format_from_bytes` or `format_from_extension`.
+const FORMATS: [(&str, anydoc::Format); 12] = [
+    ("doc", anydoc::Format::Doc),
+    ("docx", anydoc::Format::Docx),
+    ("odt", anydoc::Format::Odt),
+    ("pdf", anydoc::Format::Pdf),
+    ("ppt", anydoc::Format::Ppt),
+    ("pptx", anydoc::Format::Pptx),
+    ("rtf", anydoc::Format::Rtf),
+    ("epub", anydoc::Format::Epub),
+    ("xlsx", anydoc::Format::Excel),
+    ("ods", anydoc::Format::Ods),
+    ("odp", anydoc::Format::Odp),
+    ("csv", anydoc::Format::Csv),
+];
+
+/// The format a symbol names, or an `ArgumentError` listing the ones that
+/// exist. `nil` asks for detection, which the conversion itself does.
+fn parse_format(ruby: &Ruby, format: Option<Symbol>) -> Result<Option<anydoc::Format>, Error> {
+    let Some(symbol) = format else {
+        return Ok(None);
+    };
+    let name = symbol.name()?;
+    FORMATS
+        .iter()
+        .find(|(candidate, _)| *candidate == name.as_ref())
+        .map(|(_, format)| Some(*format))
+        .ok_or_else(|| {
+            let names: Vec<&str> = FORMATS.iter().map(|(name, _)| *name).collect();
+            Error::new(
+                ruby.exception_arg_error(),
+                format!("unknown format :{name}; expected one of {}", names.join(", ")),
+            )
+        })
+}
+
+/// The symbol naming a format.
+fn format_symbol(ruby: &Ruby, format: anydoc::Format) -> StaticSymbol {
+    let name = FORMATS
+        .iter()
+        .find(|(_, candidate)| *candidate == format)
+        .map(|(name, _)| *name)
+        .expect("every format is named");
+    ruby.sym_new(name)
+}
+
+/// The string's bytes, copied while the GVL is still held: the conversion runs
+/// without it, where another thread could move or mutate the buffer.
+fn bytes(data: RString) -> Vec<u8> {
+    unsafe { data.as_slice() }.to_vec()
+}
+
+/// Run a conversion off the GVL and turn its failure into a Ruby exception.
+fn convert<T>(
+    ruby: &Ruby,
+    conversion: impl FnOnce() -> Result<T, anydoc::ConvertError>,
+) -> Result<T, Error> {
+    match nogvl(conversion) {
+        Ok(Ok(converted)) => Ok(converted),
+        Ok(Err(error)) => Err(convert_error(ruby, error)),
+        Err(_) => Err(Error::new(
+            ruby.exception_runtime_error(),
+            "anydoc panicked while converting; please report this at \
+             https://github.com/firecrawl/anydoc/issues",
+        )),
+    }
+}
+
+/// Raise the subclass that names the failure, carrying the part or limit at
+/// fault where the variant knows one. A variant added later raises the base
+/// class until it is named here.
+fn convert_error(ruby: &Ruby, error: anydoc::ConvertError) -> Error {
+    let message = error.to_string();
+    let (class, detail) = match &error {
+        anydoc::ConvertError::Unsupported(_) => ("UnsupportedError", None),
+        anydoc::ConvertError::Malformed { part, .. } => {
+            ("MalformedError", Some(("@part", part.clone().into_value_with(ruby))))
+        }
+        anydoc::ConvertError::Encrypted => ("EncryptedError", None),
+        anydoc::ConvertError::ResourceLimit { limit, .. } => {
+            ("ResourceLimitError", Some(("@limit", ruby.sym_new(*limit).into_value_with(ruby))))
+        }
+        anydoc::ConvertError::MissingPart { part } => {
+            ("MissingPartError", Some(("@part", part.clone().into_value_with(ruby))))
+        }
+        // Nothing here reads a file, so this is unreachable in practice.
+        anydoc::ConvertError::Io(_) => return Error::new(ruby.exception_io_error(), message),
+        _ => ("ConvertError", None),
+    };
+    build_error(ruby, class, message, detail).unwrap_or_else(|error| error)
+}
+
+fn build_error(
+    ruby: &Ruby,
+    class: &str,
+    message: String,
+    detail: Option<(&str, Value)>,
+) -> Result<Error, Error> {
+    let anydoc: RModule = ruby.class_object().const_get("Anydoc")?;
+    let class: RClass = anydoc.const_get(class)?;
+    // Built as an object so the detail can be set on it, then handed back as
+    // the exception to raise.
+    let exception: RObject = class.funcall("new", (message,))?;
+    if let Some((name, value)) = detail {
+        exception.ivar_set(name, value)?;
+    }
+    Ok(Error::from(Exception::try_convert(exception.as_value())?))
+}
+
+/// Detect the format from the content itself: the signature and identity each
+/// container specification designates (PDF header, RTF open group, OLE stream
+/// names, ZIP package mimetype/content types). Plain-text formats (CSV) carry
+/// no signature and return `nil`; so does anything unrecognized.
+fn format_from_bytes(ruby: &Ruby, data: RString) -> Option<StaticSymbol> {
+    anydoc::Format::from_bytes(unsafe { data.as_slice() }).map(|format| format_symbol(ruby, format))
+}
+
+/// The format a bare extension names (no leading dot), matched
+/// case-insensitively.
+fn format_from_extension(ruby: &Ruby, extension: String) -> Option<StaticSymbol> {
+    anydoc::Format::from_extension(&extension).map(|format| format_symbol(ruby, format))
+}
+
+/// Convert an in-memory document to Markdown. Without a format, it is
+/// detected from the content, which signature-less formats (CSV) have to name
+/// explicitly.
+fn to_markdown_bytes(ruby: &Ruby, data: RString, format: Option<Symbol>) -> Result<String, Error> {
+    let format = parse_format(ruby, format)?;
+    let bytes = bytes(data);
+    convert(ruby, || anydoc::to_markdown_bytes(&bytes, format))
+}
+
+/// Parse an in-memory document into the document model, which also carries the
+/// embedded assets. Without a format, it is detected from the content.
+fn to_document(ruby: &Ruby, data: RString, format: Option<Symbol>) -> Result<Value, Error> {
+    let format = parse_format(ruby, format)?;
+    let bytes = bytes(data);
+    let parsed = convert(ruby, || anydoc::to_document(&bytes, format))?;
+    document::build(ruby, parsed)
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let anydoc = ruby.define_module("Anydoc")?;
+
+    let formats = ruby.ary_new_capa(FORMATS.len());
+    for (name, _) in FORMATS {
+        formats.push(ruby.sym_new(name))?;
+    }
+    formats.freeze();
+    anydoc.const_set("FORMATS", formats)?;
+
+    // The Ruby side wraps these: it takes keyword arguments, accepts strings
+    // where a format symbol is wanted, and reads files.
+    let native = anydoc.define_module("Native")?;
+    native.define_singleton_method("format_from_bytes", function!(format_from_bytes, 1))?;
+    native.define_singleton_method("format_from_extension", function!(format_from_extension, 1))?;
+    native.define_singleton_method("to_markdown_bytes", function!(to_markdown_bytes, 2))?;
+    native.define_singleton_method("to_document", function!(to_document, 2))?;
+
+    Ok(())
+}

data/ext/anydoc/src/nogvl.rs

@@ -0,0 +1,42 @@
+//! Running a conversion with the GVL released.
+
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::ptr::null_mut;
+use std::thread::Result;
+
+/// Run `f` with the GVL released, so other Ruby threads keep running while a
+/// document converts. `f` must not touch the Ruby VM in any way.
+///
+/// No unblocking function is registered: a conversion is a bounded CPU-bound
+/// call with no handle to interrupt, so signals and `Thread#kill` are handled
+/// once it returns.
+///
+/// A panic is caught here rather than left to unwind through the C frame,
+/// which would abort the process; the caller turns it into a Ruby exception.
+pub fn nogvl<F, R>(f: F) -> Result<R>
+where
+    F: FnOnce() -> R,
+{
+    unsafe extern "C" fn call<F, R>(arg: *mut c_void) -> *mut c_void
+    where
+        F: FnOnce() -> R,
+    {
+        // `arg` is the caller's `f` slot, which outlives this call. Ruby calls
+        // the function exactly once, so the closure is there to take.
+        let f = unsafe { &mut *arg.cast::<Option<F>>() }.take().expect("called once");
+        Box::into_raw(Box::new(catch_unwind(AssertUnwindSafe(f)))).cast()
+    }
+
+    let mut f = Some(f);
+    let result = unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(call::<F, R>),
+            (&raw mut f).cast(),
+            None,
+            null_mut(),
+        )
+    };
+    // The callback boxed its result; take ownership of it back.
+    *unsafe { Box::from_raw(result.cast::<Result<R>>()) }
+}

data/lib/anydoc/document.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Anydoc
+  # The document model {Anydoc.to_document} returns.
+  #
+  # Every class here is a +Data+, so instances are frozen, compare by value,
+  # answer +to_h+, and destructure in +case/in+:
+  #
+  #   case block
+  #   in Anydoc::Block[kind: :heading, level:, content:]
+  #     ...
+  #   end
+  #
+  # Variants (block kinds, link targets, ...) are a +kind+ symbol plus the
+  # members that kind carries; members belonging to other kinds are +nil+.
+  #
+  # @!parse
+  #   # Only fully resolved content lives in the model: style cascades,
+  #   # numbering, and references are resolved before it is built.
+  class Document < Data.define(
+    # @return [Array<Block>] body content, in reading order.
+    :blocks,
+    # @return [Array<Note>] footnote and endnote bodies, referenced from text
+    #   by a +:note_ref+ inline.
+    :notes,
+    # @return [Array<Asset>] every embedded asset, indexed by its +id+.
+    :assets
+  )
+  end
+
+  # One block-level piece of content.
+  #
+  # @!attribute [r] kind
+  #   @return [Symbol] +:heading+, +:paragraph+, +:list+, +:table+,
+  #     +:block_quote+, +:code_block+, or +:rule+.
+  # @!attribute [r] level
+  #   @return [Integer, nil] heading: 1-6.
+  # @!attribute [r] anchor
+  #   @return [String, nil] heading: stable anchor id, when the document
+  #     targets this heading.
+  # @!attribute [r] content
+  #   @return [Array<Inline>, nil] heading, paragraph.
+  # @!attribute [r] list
+  #   @return [List, nil]
+  # @!attribute [r] table
+  #   @return [Table, nil]
+  # @!attribute [r] blocks
+  #   @return [Array<Block>, nil] block_quote.
+  # @!attribute [r] lang
+  #   @return [String, nil] code_block.
+  # @!attribute [r] text
+  #   @return [String, nil] code_block.
+  class Block < Data.define(
+    :kind, :level, :anchor, :content, :list, :table, :blocks, :lang, :text
+  )
+  end
+
+  # One inline-level piece of content.
+  #
+  # @!attribute [r] kind
+  #   @return [Symbol] +:text+, +:link+, +:image+, +:anchor+ (a zero-width
+  #     marker for an internal link target at this position), +:note_ref+, or
+  #     +:line_break+.
+  # @!attribute [r] text
+  #   @return [String, nil] text.
+  # @!attribute [r] style
+  #   @return [Style, nil] text.
+  # @!attribute [r] content
+  #   @return [Array<Inline>, nil] link.
+  # @!attribute [r] target
+  #   @return [LinkTarget, nil] link.
+  # @!attribute [r] alt
+  #   @return [String, nil] image.
+  # @!attribute [r] source
+  #   @return [ImageSource, nil] image.
+  # @!attribute [r] anchor
+  #   @return [String, nil] anchor: the anchor id.
+  # @!attribute [r] note_id
+  #   @return [String, nil] note_ref: the id of the note in
+  #     {Document#notes}.
+  class Inline < Data.define(
+    :kind, :text, :style, :content, :target, :alt, :source, :anchor, :note_id
+  )
+  end
+
+  # Fully resolved character style.
+  #
+  # @!attribute [r] bold
+  #   @return [Boolean]
+  # @!attribute [r] italic
+  #   @return [Boolean]
+  # @!attribute [r] strike
+  #   @return [Boolean]
+  # @!attribute [r] code
+  #   @return [Boolean] monospace, from a code or teletype character style.
+  class Style < Data.define(:bold, :italic, :strike, :code)
+    # @return [Boolean] whether no toggle is set.
+    def plain? = !(bold || italic || strike || code)
+  end
+
+  # Where a link points.
+  #
+  # @!attribute [r] kind
+  #   @return [Symbol] +:external+ (absolute URL with a scheme), +:relative+
+  #     (scheme-less reference, preserved as written), or +:anchor+ (an
+  #     internal target: a heading anchor or an +:anchor+ inline).
+  # @!attribute [r] value
+  #   @return [String] the URL, relative reference, or anchor id.
+  class LinkTarget < Data.define(:kind, :value)
+  end
+
+  # Where an image's bytes come from.
+  #
+  # @!attribute [r] kind
+  #   @return [Symbol] +:external+ (absolute URL with a scheme), +:asset+
+  #     (embedded, carried in {Document#assets}), or +:unavailable+ (the
+  #     image's part is missing or unreadable and it has no URL, so only the
+  #     alt text remains).
+  # @!attribute [r] url
+  #   @return [String, nil] external.
+  # @!attribute [r] asset_id
+  #   @return [Integer, nil] asset: index into {Document#assets}.
+  class ImageSource < Data.define(:kind, :url, :asset_id)
+  end
+
+  # A list and the marker family the source document used for it.
+  #
+  # @!attribute [r] marker
+  #   @return [Symbol] +:bullet+, +:decimal+, +:lower_alpha+, +:upper_alpha+,
+  #     +:lower_roman+, or +:upper_roman+.
+  # @!attribute [r] start
+  #   @return [Integer] the ordinal the first item counts from.
+  # @!attribute [r] items
+  #   @return [Array<ListItem>]
+  class List < Data.define(:marker, :start, :items)
+    # @return [Boolean] whether the list is numbered.
+    def ordered? = marker != :bullet
+  end
+
+  # One item of a {List}.
+  #
+  # @!attribute [r] blocks
+  #   @return [Array<Block>]
+  # @!attribute [r] checked
+  #   @return [Boolean, nil] task-list state, when the item carries a
+  #     checkbox.
+  # @!attribute [r] marker_label
+  #   @return [String, nil] literal marker text that overrides the list marker
+  #     when the source number text cannot be reproduced from the marker and
+  #     position alone (composite number text such as +1-a)+).
+  class ListItem < Data.define(:blocks, :checked, :marker_label)
+  end
+
+  # A table as a canonical grid: every logical grid position appears exactly
+  # once. Content and spans live on the origin slot, and each position a span
+  # covers holds a +:covered+ slot pointing back at that origin.
+  #
+  # @!attribute [r] grid
+  #   @return [Array<Array<CellSlot>>] rows of slots. Rows may differ in
+  #     length when the source is ragged.
+  # @!attribute [r] header_rows
+  #   @return [Integer] number of leading rows that are header rows (0 = no
+  #     header).
+  # @!attribute [r] kind
+  #   @return [Symbol] +:data+ for a real data table, +:layout+ for layout
+  #     scaffolding (text boxes, positioning tables).
+  class Table < Data.define(:grid, :header_rows, :kind)
+  end
+
+  # One position in a {Table#grid}: either a cell or the shadow of one.
+  #
+  # @!attribute [r] kind
+  #   @return [Symbol] +:origin+ or +:covered+.
+  # @!attribute [r] cell
+  #   @return [Cell, nil] origin.
+  # @!attribute [r] origin_row
+  #   @return [Integer, nil] covered: row of the origin this position belongs
+  #     to.
+  # @!attribute [r] origin_col
+  #   @return [Integer, nil] covered: column of the origin this position
+  #     belongs to.
+  class CellSlot < Data.define(:kind, :cell, :origin_row, :origin_col)
+  end
+
+  # A table cell and the extent it spans.
+  #
+  # @!attribute [r] blocks
+  #   @return [Array<Block>]
+  # @!attribute [r] col_span
+  #   @return [Integer] columns covered, at least 1.
+  # @!attribute [r] row_span
+  #   @return [Integer] rows covered, at least 1.
+  class Cell < Data.define(:blocks, :col_span, :row_span)
+  end
+
+  # A footnote or endnote body, referenced from text by a +:note_ref+ inline.
+  #
+  # @!attribute [r] id
+  #   @return [String] the id the referencing inline carries.
+  # @!attribute [r] kind
+  #   @return [Symbol] +:footnote+ or +:endnote+, by where the source places
+  #     the note.
+  # @!attribute [r] blocks
+  #   @return [Array<Block>] the note's own content.
+  class Note < Data.define(:id, :kind, :blocks)
+  end
+
+  # An embedded binary asset (image, object payload). Bytes are always
+  # retained, so a document stays self-contained.
+  #
+  # @!attribute [r] id
+  #   @return [Integer] index into {Document#assets}, as referenced by an
+  #     image source.
+  # @!attribute [r] media_type
+  #   @return [String] MIME type, e.g. +image/png+.
+  # @!attribute [r] origin_part
+  #   @return [String] package part or stream the asset came from, for
+  #     provenance.
+  # @!attribute [r] data
+  #   @return [String] the payload, exactly as stored in the source, as a
+  #     binary (ASCII-8BIT) string.
+  class Asset < Data.define(:id, :media_type, :origin_part, :data)
+  end
+end

data/lib/anydoc/errors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Anydoc
+  # Base class for everything this gem raises. Unreadable files raise the
+  # +Errno+ exception any other read of them would, and a format argument
+  # naming no supported format raises +ArgumentError+.
+  class Error < StandardError; end
+
+  # Meaningful conversion was impossible. Rescue this to handle every kind of
+  # failure at once, or one of its subclasses to single one out.
+  #
+  # Recoverable producer quirks never reach here: they are recovered or
+  # skipped while conversion continues.
+  class ConvertError < Error; end
+
+  # The format is unknown, or cannot be converted at all: a scanned or
+  # image-only PDF needs OCR, which anydoc does not do.
+  class UnsupportedError < ConvertError; end
+
+  # The document is structurally unusable: no meaningful content could be
+  # extracted.
+  class MalformedError < ConvertError
+    # @return [String, nil] the package part or stream at fault, or +nil+ when
+    #   no single part is.
+    attr_reader :part
+  end
+
+  # The document is encrypted or password-protected.
+  class EncryptedError < ConvertError; end
+
+  # A fixed safety limit was crossed: decompression, nesting depth, node
+  # count, repeat expansion, or retained asset bytes.
+  class ResourceLimitError < ConvertError
+    # @return [Symbol] the limit that was crossed, e.g. +:max_entry_bytes+.
+    attr_reader :limit
+  end
+
+  # A part required for any meaningful output is absent.
+  class MissingPartError < ConvertError
+    # @return [String] the part or stream that is missing.
+    attr_reader :part
+  end
+end

data/lib/anydoc/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Anydoc
+  # The gem version, which is the version of the anydoc crate it wraps.
+  VERSION = "0.1.7"
+end

data/lib/anydoc.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative "anydoc/version"
+require_relative "anydoc/errors"
+require_relative "anydoc/document"
+
+# Precompiled gems carry one extension per Ruby ABI; a gem built from source
+# puts its single extension straight into lib/anydoc.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "anydoc/#{Regexp.last_match(1)}/anydoc"
+rescue LoadError
+  require_relative "anydoc/anydoc"
+end
+
+# Convert documents (Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV,
+# and PDF) to GitHub-Flavored Markdown.
+#
+#   Anydoc.to_markdown("report.docx")
+#
+# 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.
+#
+# @see FORMATS the formats that can be named explicitly.
+module Anydoc
+  # @!parse
+  #   # Every format anydoc reads, named after the extension that identifies
+  #   # it. Container variants that share a parser (+.docm+, +.xlsm+,
+  #   # +.ppsx+, ...) map onto these through {format_from_bytes} or
+  #   # {format_from_extension}.
+  #   #
+  #   # @return [Array<Symbol>]
+  #   FORMATS = %i[doc docx odt pdf ppt pptx rtf epub xlsx ods odp csv].freeze
+
+  class << self
+    # Convert a document file to Markdown. The format is detected from the
+    # file content; the extension is the fallback for signature-less formats
+    # (CSV) and unrecognizable containers.
+    #
+    # @param path [String, Pathname] the file to convert.
+    # @return [String] GitHub-Flavored Markdown.
+    # @raise [ConvertError] if no meaningful Markdown could come out of it.
+    # @raise [SystemCallError] if the file could not be read.
+    def to_markdown(path)
+      path = File.path(path)
+      data = File.binread(path)
+      format = format_from_bytes(data) || format_from_path(path)
+      unless format
+        raise UnsupportedError,
+              "unsupported input: unrecognized file content and extension: #{path}"
+      end
+
+      to_markdown_bytes(data, format: format)
+    end
+
+    # Convert an in-memory document to Markdown.
+    #
+    # @param data [String] the document's bytes.
+    # @param format [Symbol, String, nil] which format to parse it as. Left
+    #   out, the format is detected from the content, which signature-less
+    #   formats (CSV) have to name explicitly.
+    # @return [String] GitHub-Flavored Markdown.
+    # @raise [ConvertError] if no meaningful Markdown could come out of it.
+    # @raise [ArgumentError] if +format+ names no supported format.
+    def to_markdown_bytes(data, format: nil)
+      Native.to_markdown_bytes(data, format_symbol(format))
+    end
+
+    # Parse an in-memory document into the document model, which also carries
+    # the embedded assets.
+    #
+    # Unsupported for +:pdf+: PDF conversion produces Markdown directly and
+    # has no document-model form; use {to_markdown_bytes}.
+    #
+    # @param data [String] the document's bytes.
+    # @param format [Symbol, String, nil] which format to parse it as. Left
+    #   out, the format is detected from the content.
+    # @return [Document]
+    # @raise [ConvertError] if the document could not be parsed.
+    # @raise [ArgumentError] if +format+ names no supported format.
+    def to_document(data, format: nil)
+      Native.to_document(data, format_symbol(format))
+    end
+
+    # Detect the format from the content itself: the signature and identity
+    # each container specification designates (PDF header, RTF open group, OLE
+    # stream names, ZIP package mimetype/content types).
+    #
+    # @param data [String] the document's bytes.
+    # @return [Symbol, nil] +nil+ for plain-text formats, which carry no
+    #   signature, and for anything unrecognized.
+    def format_from_bytes(data)
+      Native.format_from_bytes(data)
+    end
+
+    # The format an extension names, with or without a leading dot, matched
+    # case-insensitively.
+    #
+    # @param extension [String, Symbol] e.g. +".pptm"+.
+    # @return [Symbol, nil] +nil+ for anything unrecognized.
+    def format_from_extension(extension)
+      Native.format_from_extension(extension.to_s.delete_prefix("."))
+    end
+
+    # The format a path's extension names.
+    #
+    # @param path [String, Pathname] the path to read the extension off.
+    # @return [Symbol, nil] +nil+ when the path has no extension or names
+    #   nothing recognized.
+    def format_from_path(path)
+      extension = File.extname(File.path(path))
+      extension.empty? ? nil : format_from_extension(extension)
+    end
+
+    private
+
+    # Format arguments are symbols; strings are accepted for convenience.
+    def format_symbol(format)
+      case format
+      when nil, Symbol then format
+      when String then format.to_sym
+      else
+        raise ArgumentError, "format must be a Symbol, a String, or nil, got #{format.class}"
+      end
+    end
+  end
+end