#mbtexcel

#Features

• Create, read, and write XLSX spreadsheets
• Cell value manipulation (strings, numbers, booleans, formulas)
• Cell styling (fonts, colors, borders, alignment, number formats)
• Charts and images
• Data validation and conditional formatting
• Pivot tables and slicers
• Sparklines
• Sheet protection and workbook encryption
• Formula evaluation with 300+ built-in functions
• Typed date/time and duration cells with automatic number formats
• Streaming API for large files
• Embedded cell image reading (WPS DISPIMG, rich-value "Place in cell", IMAGE())
• OOXML package validation and a command-line tool

#Installation

moon add bobzhang/mbtexcel

import {
  "bobzhang/mbtexcel",
}

#Quick Start

#Creating and Reading Workbooks

///|
test "workbook roundtrip" {
  let workbook = @mbtexcel.new_workbook()
  let sheet = workbook.add_sheet("Sheet1")
  sheet.set_cell("A1", "hello")
  sheet.set_cell_formula("B1", "A1", value="hello")
  let bytes = @mbtexcel.write(workbook)
  let parsed = @mbtexcel.read(bytes)
  debug_inspect(parsed.get_cell("Sheet1", "A1"), content="Some(\"hello\")")
  debug_inspect(parsed.get_cell_formula("Sheet1", "B1"), content="Some(\"A1\")")
}

#Row and Column Helpers

///|
test "row and column helpers" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Sheet1"))
  workbook.set_row("Sheet1", 1, ["a", "b", "c"])
  workbook.set_col("Sheet1", 2, ["x", "y"])
  debug_inspect(
    workbook.get_row("Sheet1", 1),
    content=(
      #|["a", "x", "c"]
    ),
  )
  debug_inspect(workbook.get_col("Sheet1", 2), content="[\"x\", \"y\"]")
}

#Cell Reference Utilities

///|
test "cell reference conversion" {
  // Split cell name into column and row
  debug_inspect(@mbtexcel.split_cell_name("AB123"), content="(\"AB\", 123)")

  // Join column and row into cell name
  inspect(@mbtexcel.join_cell_name("AB", 123), content="AB123")

  // Convert between cell name and coordinates (1-indexed)
  debug_inspect(@mbtexcel.cell_name_to_coordinates("B3"), content="(2, 3)")
  inspect(@mbtexcel.coordinates_to_cell_name(2, 3), content="B3")

  // Absolute references
  inspect(@mbtexcel.coordinates_to_cell_name(2, 3, abs=true), content="$B$3")

  // Column name/number conversion
  inspect(@mbtexcel.column_name_to_number("AB"), content="28")
  inspect(@mbtexcel.column_number_to_name(28), content="AB")
}

#Working with Multiple Sheets

///|
test "multiple sheets" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Sales"))
  ignore(workbook.add_sheet("Expenses"))
  ignore(workbook.add_sheet("Summary"))

  // Get list of all sheets
  debug_inspect(
    workbook.get_sheet_list(),
    content="[\"Sales\", \"Expenses\", \"Summary\"]",
  )

  // Access sheet by name
  guard workbook.sheet("Sales") is Some(sales) else { return }
  sales.set_cell("A1", "Revenue")
  debug_inspect(sales.get_cell("A1"), content="Some(\"Revenue\")")
}

#Cell Types and Values

///|
test "cell value types" {
  let workbook = @mbtexcel.new_workbook()
  let sheet = workbook.add_sheet("Data")

  // String values
  sheet.set_cell("A1", "Hello")

  // Numeric values (auto-detected from string)
  sheet.set_cell("A2", "42")
  sheet.set_cell("A3", "3.14159")

  // Using typed CellValue enum for explicit types
  sheet.set_cell_value("B1", String("Text"))
  sheet.set_cell_value("B2", Numeric(100.5))
  sheet.set_cell_value("B3", Bool(true))

  // Read back values
  debug_inspect(sheet.get_cell("A1"), content="Some(\"Hello\")")
  debug_inspect(sheet.get_cell("A2"), content="Some(\"42\")")
  debug_inspect(sheet.get_cell_value_raw("B2"), content="Some(Numeric(100.5))")
  debug_inspect(sheet.get_cell_value_raw("B3"), content="Some(Bool(true))")
}

#Formulas

///|
test "formulas" {
  let workbook = @mbtexcel.new_workbook()
  let sheet = workbook.add_sheet("Calc")

  // Set some values
  sheet.set_cell("A1", "10")
  sheet.set_cell("A2", "20")
  sheet.set_cell("A3", "30")

  // Set formula with cached value
  sheet.set_cell_formula("A4", "SUM(A1:A3)", value="60")

  // Read formula back
  debug_inspect(sheet.get_cell_formula("A4"), content="Some(\"SUM(A1:A3)\")")

  // Calculate formula value
  inspect(workbook.calc_cell_value("Calc", "A4"), content="60")
}

#Merged Cells

///|
test "merged cells" {
  let workbook = @mbtexcel.new_workbook()
  let sheet = workbook.add_sheet("Report")

  // Set value before merging
  sheet.set_cell("A1", "Title")

  // Merge cells A1:D1
  sheet.merge_cells("A1:D1")

  // Get merged cell ranges
  debug_inspect(sheet.merged_cells().to_owned(), content="[\"A1:D1\"]")
}

#Styling Cells

///|
test "cell styling" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Sheet1"))
  workbook.set_cell("Sheet1", "A1", "1234.5")

  // A style combines a number format with a font, fill, border, etc.
  let style = workbook.new_style(
    @xlsx.Style::builtin_number_format(2) // "0.00"
    .with_font(@xlsx.Font::with_values(bold=true, color="#FF0000")),
  )
  workbook.set_cell_style("Sheet1", "A1", style)
  debug_inspect(
    workbook.get_cell_style("Sheet1", "A1"),
    content="Some(\{style})",
  )
}

#Dates and Times

///|
test "typed dates" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Sheet1"))

  // Store a datetime; it is written as an Excel date serial with a default
  // date number format (honoring the workbook's 1900/1904 date system).
  workbook.set_cell_time("Sheet1", "A1", @time.date_time(2024, 7, 3))
  debug_inspect(
    workbook.get_cell("Sheet1", "A1"),
    content=(
      #|Some("45476")
    ),
  )

  // The reverse conversion is available directly.
  inspect(
    @mbtexcel.time_to_excel_date(@time.date_time(2021, 1, 1, hour=12)),
    content="44197.5",
  )
}

#Streaming Large Sheets

///|
test "streaming writer" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Big"))
  let stream = workbook.new_stream_writer("Big")
  for r in 11000 {
    stream.set_row_cells("A\{r}", [
      @xlsx.StreamCell::new("row \{r}"),
      @xlsx.StreamCell::new_value(Numeric(r.to_double())),
    ])
  }
  stream.flush()
  let parsed = @mbtexcel.read(@mbtexcel.write(workbook))
  debug_inspect(
    parsed.get_cell("Big", "B1000"),
    content=(
      #|Some("1000")
    ),
  )
}

#Password Protection

///|
test "password protection" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Secret"))
  workbook.set_cell("Secret", "A1", "classified")

  let encrypted = @mbtexcel.write_with_password(workbook, "s3cret")
  let reopened = @mbtexcel.read_with_password(encrypted, "s3cret")
  debug_inspect(
    reopened.get_cell("Secret", "A1"),
    content=(
      #|Some("classified")
    ),
  )
}

#Validating the Output Package

///|
test "validate output" {
  let workbook = @mbtexcel.new_workbook()
  ignore(workbook.add_sheet("Sheet1"))
  workbook.set_cell("Sheet1", "A1", "hello")
  debug_inspect(
    @xlsx.validate_ooxml_package(@mbtexcel.write(workbook)),
    content="[]",
  )
}

#Unified Office command

moonx bobzhang/office help docx
moonx bobzhang/office identify report.docx --json
moonx bobzhang/office outline report.docx --json
moonx bobzhang/office get report.docx '/docx/body/p[1]' --json
moonx bobzhang/office text report.docx --under '/docx/comments/comment[id="0"]'
moonx bobzhang/office query report.docx --kind paragraph --text revenue --ignore-case --json
moonx bobzhang/office outline book.xlsx --json
moonx bobzhang/office get book.xlsx '/xlsx/sheet[name="Data"]/range[A1:C12]' --json
moonx bobzhang/office text book.xlsx --under '/xlsx/sheet[name="Data"]' --json
moonx bobzhang/office query book.xlsx 'cell[type=formula]' --under '/xlsx/sheet[name="Data"]' --json
moonx bobzhang/office create xlsx new-book.xlsx --sheet Data --json
moonx bobzhang/office batch new-book.xlsx changes.json --out revised.xlsx --json

#XLSX command-line tool

moon run cmd/xlsx -- create book.xlsx --sheet Data
moon run cmd/xlsx -- set book.xlsx Data A1 Hello
moon run cmd/xlsx -- get book.xlsx Data A1          # -> Hello
moon run cmd/xlsx -- sheets book.xlsx               # -> Data
moon run cmd/xlsx -- rows book.xlsx                 # CSV of the sheet
moon run cmd/xlsx -- view book.xlsx                 # sheet as an ASCII table
moon run cmd/xlsx -- validate book.xlsx             # -> valid

+-------+-------+
| Name  | Score |
+-------+-------+
| Alice | 90    |
| Bob   | 7     |
+-------+-------+

moon run --target wasm cmd/xlsx -- view book.xlsx

#Demos

moon run cmd/demos

moon run cmd/demos -- dashboard demos_out
moon run cmd/demos -- stream_big demos_out 50000

scripts/test_demo_roundtrip.sh

scripts/test_parity_gates.sh

#Parity Commands

• docs/excelize-parity.md
• docs/parity-commands.md

scripts/test_parity_gates.sh
scripts/test_semantic_parity.sh
scripts/test_semantic_parity_fast.sh
scripts/test_semantic_parity_ultrasmoke.sh

#API Reference

#Workbook Creation

#Workbook Output

#Cell Reference Utilities

#Color Utilities

#Date Utilities

#Validation

#Core Types

• @xlsx.Workbook - The main workbook container
• @xlsx.Worksheet - A single worksheet
• @xlsx.Cell - Cell data with value, type, formula, and style
• @xlsx.Style - Cell styling (font, fill, border, alignment, number format)
• @xlsx.Options - Read/write options

#Error Handling

• SheetNotFound - Referenced sheet does not exist
• InvalidCellRef - Invalid cell reference format
• InvalidSheetName - Sheet name is invalid or too long
• EncryptedPackage - File is encrypted but no password provided
• InvalidPassword - Decryption failed with given password

///|
fn describe(bytes : Bytes) -> String {
  try {
    let workbook = @mbtexcel.read(bytes)
    "loaded \{workbook.get_sheet_list().length()} sheets"
  } catch {
    err => "read failed: \{err}"
  }
}

#Package Structure

bobzhang/mbtexcel              # Facade package (this package)
  -> bobzhang/mbtexcel/xlsx    # Core implementation
       -> bobzhang/mbtexcel/ooxml  # OOXML metadata helpers
       -> bobzhang/mbtexcel/zip    # ZIP archive handling
       -> bobzhang/mbtexcel/crypto # Cryptographic operations

#License