The Ruby API is the primary interface for working with Uniword. It provides four layers of abstraction for creating, reading, and modifying OOXML documents.

1. Document lifecycle

Every Uniword workflow follows one of two paths:

Create from scratch — Build a new document using Document.new or the fluent Builder API, then save it.

Load and modify — Open an existing DOCX or MHTML file with DocumentFactory.from_file, modify the content, and save it back.

# Create
doc = Uniword::Document.new
doc.add_paragraph("Hello World")
doc.save("output.docx")

# Load and modify
doc = Uniword::DocumentFactory.from_file("input.docx")
doc.add_paragraph("Appended paragraph")
doc.save("modified.docx")

2. Builder API

The Builder provides a fluent, declarative interface for constructing documents. Each method returns the builder, allowing method chaining.

doc = Uniword::Builder.new
  .add_heading("My Document", level: 1)
  .add_paragraph("Introduction paragraph")
  .add_table do
    row do
      cell "Header 1", bold: true
      cell "Header 2", bold: true
    end
    row do
      cell "Data 1"
      cell "Data 2"
    end
  end
  .build

See Builder API for the full reference.

3. Model classes

Beneath the Builder, Uniword exposes a complete set of OOXML model classes representing 760 elements across 22 namespaces. Every class inherits from Lutaml::Model::Serializable and supports automatic XML serialization.

# Direct model manipulation
para = Uniword::Paragraph.new
para.add_text("Bold text", bold: true)

table = Uniword::Table.new
row = Uniword::TableRow.new
cell = Uniword::TableCell.new
cell.add_paragraph("Cell content")
row.add_cell(cell)
table.add_row(row)

4. Resource system

Uniword ships with open-source resources that replace proprietary Microsoft Word assets:

  • Themes — 29 bundled color and font schemes (.thmx or YAML)

  • StyleSets — 12 bundled style definitions (.dotx or YAML)

  • Document elements — 240 templates across 30 locales

# Apply a theme and styleset
doc.apply_theme("celestial")
doc.apply_styleset("distinctive")

5. Feature API

DocumentRoot provides convenience methods for common document operations. All mutator methods return self for chaining.

5.1. Review (comments & tracked changes) 

doc.list_comments                          # => Array<Comment>
doc.add_comment(text: "Fix", author: "Al") # => self
doc.accept_all_changes                     # => self
doc.reject_all_changes                     # => self
doc.clear_comments                         # => self

5.2. Document comparison 

# Document-level: content, formatting, structure, metadata, styles
result = doc.diff(other_doc)
result = doc.diff(other_doc, text_only: true)
# => DiffResult with text_changes, format_changes, structure_changes,
#    metadata_changes, style_changes

# Package-level: ZIP parts, XML content, OPC validation
require "uniword/diff/package_differ"
result = Uniword::Diff::PackageDiffer.new("old.docx", "new.docx",
  canon: true).diff
# => PackageDiffResult with added/removed/modified parts,
#    zip_metadata_changes, opc_issues, canon equivalence

5.3. Spell and grammar checking 

result = doc.spellcheck              # default: en_US
result = doc.spellcheck(language: "en_GB")
# => SpellcheckResult with misspellings, grammar_issues, clean?

5.4. Image management 

doc.list_images                    # => Array<ImageInfo>
doc.extract_images("/tmp/imgs")    # => Integer (count)
doc.insert_image("photo.png",
      width: "6in", height: "4in") # => self
doc.remove_image("image1.png")     # => self

5.5. Watermarks 

doc.add_watermark("DRAFT",
      color: "#FF0000", font_size: 96)  # => self
doc.remove_watermark                      # => self
doc.watermark?                            # => true/false
doc.list_watermarks                       # => Array<String>

5.6. Table of Contents 

entries = doc.generate_toc(max_level: 3)
# => Array<TocEntry> with level, text, style_name, paragraph_index

doc.insert_toc(position: 0, max_level: 3) # => self
doc.update_toc(max_level: 6)              # => self

5.7. Headers & footers 

doc.list_headers                   # => Array<Hash>
doc.list_footers                   # => Array<Hash>
doc.add_header("Confidential",
      type: "default")             # => self
doc.add_footer("Page 1")          # => self
doc.remove_headers(type: "first") # => self
doc.remove_footers(type: "even")  # => self

5.8. Document protection 

doc.protect(:read_only, password: "secret")  # => self
doc.protect(:tracked_changes)                # => self
doc.protection_active?                       # => true/false
doc.protection_info                          # => Hash or nil
doc.unprotect                                # => self

5.9. Chaining

All mutator methods return self, enabling fluent chains:

doc = Uniword.load("report.docx")
doc.add_comment(text: "Reviewed", author: "QA")
    .add_watermark("APPROVED", color: "#008000")
    .insert_toc(max_level: 3)
    .protect(:comments)
    .save("final.docx")

6. Topics

Table of contents