ironcalc 0.7.1.5 → 0.8.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e511f58c879d0fdac27a5c4b2d06f424d836bb2c995f4a9562d61bef955f7ea4
-  data.tar.gz: 3761670586bb8ed3518e91d270391e51c1f3f9590a8e5aba5e100791de5446c0
+  metadata.gz: 99ad95c481d32e19c1ac19db71a37fac4b4c0239911d28909ba4e55aa1e3e28b
+  data.tar.gz: 3ee57b654e4633a521ef5e0f0e323437150d5a4c4663497c4a244b877f8e278d
 SHA512:
-  metadata.gz: 6728ca159b613acd5dbcd604c286b674a9c2903040a78d2bfdbb51273d31be5e77f0942f8f20587299778586c06fc83cf2e7ae0c2f92f7d2e1b70e1ba5f2aeac
-  data.tar.gz: 4e7b42714f19977be65194cd1af3ffadbf1ac370fc2572613f166c84229f29710b95d95baf0b3688a4387a6e519611e81816f0dd29feda48030ba603f2d18944
+  metadata.gz: ba91db3f951436ec7434c4f6439c216fbb6bd876dbb32ba1f30aa5dbd14d8be2503c955c98861b9a8cd9ecde2d98b744d60973ef7ce3fa180595a266a3dcbe5d
+  data.tar.gz: 13353e79cfac4675511ec1fd1bb1bb20912344ef5d1b8d395422b4012ae54d7f6daa4266c98251e3c2cf94c87be384535e0a0e26c303c6db99129cf22ef5b511

data/.yardopts

@@ -3,6 +3,7 @@
 --readme README.md
 --output-dir doc
 --no-private
+--hide-api private
 lib/**/*.rb
 -
 README.md

data/CHANGELOG.md

@@ -1,3 +1,52 @@
+## 0.8.3.0
+
+- update the IronCalc engine to 0.8.3
+- **breaking**: `fill` styles use a single `color` key; `fg_color` and
+  `bg_color` are gone
+- **breaking**: the default font is now Inter 12, was Calibri 13
+- **breaking**: `UserModel#update_range_style` takes the engine's area as a
+  Hash, `update_range_style({sheet:, row:, column:, width:, height:}, path,
+  value)`, and styles the whole range; it took a single cell before
+- **breaking**: every native method has the engine's name and signature, with
+  `nil` for an optional parameter and Hashes for engine structs. Renamed:
+  - `Model`: `clear_cell_contents(sheet, row, column)` →
+    `range_clear_contents(range)`, `get_cell_content` →
+    `get_localized_cell_content`, `get_cell_style` → `get_style_for_cell`,
+    `set_frozen_rows_count` / `set_frozen_columns_count` → `set_frozen_rows` /
+    `set_frozen_columns`, `rename_sheet(sheet, name)` →
+    `rename_sheet_by_index`; `rename_sheet(old_name, new_name)` renames by name
+  - `UserModel`: `clear_cell_contents(sheet, row, column)` →
+    `range_clear_contents(range)`, `set_column_width(sheet, column, width)` →
+    `set_columns_width(sheet, column_start, column_end, width)`, and likewise
+    `set_rows_height`
+- **breaking**: style Hashes have Symbol keys (`style[:font][:b]`); setters
+  accept Symbol or String keys, but no longer a JSON String
+- **breaking**: `UserModel#set_cell_style` is removed; style a `UserModel` per
+  property with `update_range_style`. It could not write back a style read with
+  `get_cell_style`, and failed part-way through.
+- `set_sheet_color` accepts nil to clear a sheet's color
+- sheet colors read back as nil rather than absent when unset
+- defined names on `Model` and `UserModel`: `defined_names`,
+  `new_defined_name`, `update_defined_name`, `delete_defined_name`,
+  `is_valid_defined_name` (raises with the reason) and `valid_defined_name?`
+- typed cell setters on `Model`: `update_cell_with_text`, `_number`, `_bool`,
+  `_formula`
+- typed cell readers on `Model`: `get_cell_value_by_index`,
+  `get_cell_value_by_ref`, `get_cell_formula`, `is_empty_cell`, `get_all_cells`
+- row and column default styles on `Model`: `get`/`set`/`delete_column_style`,
+  `get`/`set`/`delete_row_style`, plus `copy_cell_style`
+- `range_clear_all` on both APIs, `range_clear_formatting` on `UserModel`
+- `insert_sheet` and `set_sheet_state` on `Model`
+- `pause_evaluation` / `resume_evaluation` on `UserModel`, and `batch` to
+  recalculate once after a block
+- hidden rows and columns: `is_column_hidden` / `is_row_hidden` on both APIs,
+  `set_column_hidden` / `set_row_hidden` on `Model`, `set_columns_hidden` /
+  `set_rows_hidden` on `UserModel`
+- xlsx in memory: `to_xlsx_bytes` on both APIs, `load_from_xlsx_bytes` and
+  `create_user_model_from_xlsx_bytes`
+- fix a memory leak: every constructor leaked its string arguments on each call
+- package only README, CHANGELOG and licenses instead of every `*.md`
+
 ## 0.7.1.5
 
 - link to changelog and documentation in gemspec

data/Cargo.lock

@@ -449,9 +449,9 @@ dependencies = [
 
 [[package]]
 name = "ironcalc"
-version = "0.7.1"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e07dd44af17a9e14e7df372347ee0bfc3f0bbbf38894aba5e9abfb53f32ba95"
+checksum = "384c2a5b1e78741cedfaa4fd3209fdb115c1a52453bc10137dfe970ed92872be"
 dependencies = [
  "bitcode",
  "chrono",
@@ -466,9 +466,9 @@ dependencies = [
 
 [[package]]
 name = "ironcalc_base"
-version = "0.7.1"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9f208abea2365061ed7ce3f6a70e7c1537181ea11780de4974aae3082bf4c6d9"
+checksum = "ce1dd83cada7da742782076daccda92e33162e9f4396a958ae3e7c5bb64e6a01"
 dependencies = [
  "bitcode",
  "chrono",
@@ -477,20 +477,22 @@ dependencies = [
  "js-sys",
  "rand",
  "regex",
+ "regex-lite",
  "ryu",
  "serde",
  "statrs",
+ "wasm-bindgen",
 ]
 
 [[package]]
 name = "ironcalc_ruby"
-version = "0.7.1"
+version = "0.0.0"
 dependencies = [
  "bitcode",
  "ironcalc",
  "magnus",
  "serde",
- "serde_json",
+ "serde_magnus",
 ]
 
 [[package]]
@@ -817,6 +819,12 @@ dependencies = [
  "regex-syntax",
 ]
 
+[[package]]
+name = "regex-lite"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab834c73d247e67f4fae452806d17d3c7501756d98c8808d7c9c7aa7d18f973"
+
 [[package]]
 name = "regex-syntax"
 version = "0.8.11"
@@ -896,6 +904,17 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "serde_magnus"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ff64c88ddd26acdcad5a501f18bcc339927b77b69f4a03bfaf2a6fc5ba2ac4b"
+dependencies = [
+ "magnus",
+ "serde",
+ "tap",
+]
+
 [[package]]
 name = "sha1"
 version = "0.10.6"
@@ -981,6 +1000,12 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "tap"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
+
 [[package]]
 name = "thiserror"
 version = "1.0.69"

data/README.md

@@ -39,24 +39,166 @@ um.get_formatted_cell_value(0, 1, 1)    # => "3"
 diffs = um.flush_send_queue             # binary diff to send to peers
 ```
 
-Coordinates: `sheet` is a 0-based index; `row` and `column` are 1-based. Styles
-are exchanged as plain Ruby hashes via `get_cell_style` / `set_cell_style`.
+Coordinates: `sheet` is a 0-based index; `row` and `column` are 1-based. Method
+names and signatures are the engine's own. Engine structs, such as styles and
+cell ranges, are plain Ruby Hashes keyed by their field names.
 
-### Top-level methods
+### API overview
 
-`create`, `load_from_xlsx`, `load_from_icalc`, `load_from_bytes`,
-`create_user_model`, `create_user_model_from_xlsx`,
-`create_user_model_from_icalc`, `create_user_model_from_bytes`.
+The [API reference](https://jvdp.github.io/IronCalc-Ruby/) documents every method; it shows the latest
+release, and [older versions](https://jvdp.github.io/IronCalc-Ruby/versions.html) are kept too.
+
+- [`IronCalc`](https://jvdp.github.io/IronCalc-Ruby/IronCalc.html) — module functions: the constructors (see
+  [Loading and saving](#loading-and-saving)) and utilities for cell references,
+  such as [`number_to_column`](https://jvdp.github.io/IronCalc-Ruby/IronCalc.html#number_to_column-class_method)
+  and [`parse_reference_a1`](https://jvdp.github.io/IronCalc-Ruby/IronCalc.html#parse_reference_a1-class_method).
+- [`IronCalc::UserModel`](https://jvdp.github.io/IronCalc-Ruby/IronCalc/UserModel.html) — the recommended API.
+  It recalculates after every change, supports `undo` / `redo`, and records
+  diffs for collaboration
+  ([`flush_send_queue`](https://jvdp.github.io/IronCalc-Ruby/IronCalc/UserModel.html#flush_send_queue-instance_method)).
+  Styles are set per property with
+  [`update_range_style`](https://jvdp.github.io/IronCalc-Ruby/IronCalc/UserModel.html#update_range_style-instance_method).
+- [`IronCalc::Model`](https://jvdp.github.io/IronCalc-Ruby/IronCalc/Model.html) — the raw API. You call
+  `evaluate` yourself; in return it offers typed cell access, whole-style
+  reads and writes, and row and column default styles.
+
+### Typed cell access
+
+`set_user_input` parses what you give it, the way typing into a cell does — so
+`"007"` becomes the number 7 and `"=1+1"` becomes a formula. The typed setters
+skip that, and the typed reader gives you a Ruby object instead of a String:
+
+```ruby
+model.update_cell_with_text(0, 1, 1, "007")     # stays the string "007"
+model.update_cell_with_number(0, 1, 2, 42.5)
+model.update_cell_with_bool(0, 1, 3, true)
+model.update_cell_with_formula(0, 1, 4, "=B1*2")
+model.evaluate
+
+model.get_cell_value_by_index(0, 1, 2)  # => 42.5 (Float, not "42.5")
+model.get_cell_value_by_ref("Sheet1!D1")  # => 85.0
+model.get_cell_formula(0, 1, 4)         # => "=B1*2", or nil if not a formula
+model.is_empty_cell(0, 9, 9)            # => true
+model.get_all_cells                     # => [{ index:, row:, column: }, ...]
+```
+
+`get_all_cells` lists every cell the workbook has a record for (`index` is the
+sheet index, the engine's field name). Clearing a
+cell's contents keeps its record, so filter with `is_empty_cell` if you want
+only cells that still hold a value.
+
+Clearing works on a range, given as the engine's `Area`:
+
+```ruby
+b2_c10 = {sheet: 0, row: 2, column: 2, width: 2, height: 9}
+model.range_clear_contents(b2_c10)   # keeps the style
+model.range_clear_all(b2_c10)        # contents and style
+```
+
+On `UserModel`, `range_clear_formatting` does the opposite — style only.
+
+### Rows, columns and sheets
+
+Rows and columns can carry a default style. As with `set_cell_style`, a style is
+a complete structure, so read one, change a field, and pass it back:
+
+```ruby
+style = model.get_style_for_cell(0, 1, 1)
+style[:num_fmt] = "0.00"
+model.set_column_style(0, 2, style)
+model.get_column_style(0, 2)    # => Hash, or nil if the column has no style
+model.delete_column_style(0, 2)
+
+model.copy_cell_style([0, 1, 1], [0, 5, 5])   # style only, works across sheets
+
+model.insert_sheet("Summary", 0, nil)     # position, rather than appending
+model.set_sheet_state(1, "hidden")        # or "visible" / "veryHidden"
+```
+
+### Bulk loading
+
+`UserModel` recalculates after every action. When writing many cells, suspend
+that and evaluate once:
+
+```ruby
+um.batch do |m|
+  rows.each { |r, c, v| m.set_user_input(0, r, c, v) }
+end                             # recalculated once, here
+```
+
+`batch` nests, and recalculates even if the block raises. The underlying
+`pause_evaluation` / `resume_evaluation` pair is still available if you need to
+manage it yourself.
+
+### Defined names
+
+Named ranges, on both APIs. `scope` is a 0-based sheet index, or `nil` for a
+workbook-scoped name. They survive both an xlsx round trip and
+editing in Excel/LibreOffice, so they are also a place to keep your own
+metadata about a sheet.
+
+```ruby
+model.new_defined_name("answer", nil, "Sheet1!$C$1")
+model.set_user_input(0, 1, 1, "=answer")
+model.evaluate
+model.get_formatted_cell_value(0, 1, 1)  # => the value of C1
+
+model.defined_names
+# => [{ name: "answer", scope: nil, formula: "Sheet1!$C$1" }]
+
+model.update_defined_name("answer", nil, "result", nil, "Sheet1!$D$1")
+model.delete_defined_name("result", nil)
+```
+
+`valid_defined_name?(name, scope, formula)` reports whether
+`new_defined_name` would succeed; the name must be an identifier (`"A1"` is
+rejected — it parses as a cell reference), unused in that scope, and the formula
+must parse. `is_valid_defined_name` runs the same check but raises
+`IronCalc::Error` with the reason. On `UserModel` all three mutations are
+undoable.
+
+### Loading and saving
+
+| | `Model` | `UserModel` | save with |
+|---|---|---|---|
+| new workbook | `create` | `create_user_model` | |
+| xlsx file | `load_from_xlsx` | `create_user_model_from_xlsx` | `save_to_xlsx` |
+| xlsx in memory | `load_from_xlsx_bytes` | `create_user_model_from_xlsx_bytes` | `to_xlsx_bytes` |
+| icalc file | `load_from_icalc` | `create_user_model_from_icalc` | `save_to_icalc` |
+| icalc in memory | `load_from_bytes` | `create_user_model_from_bytes` | `to_bytes` |
+
+icalc is IronCalc's own compact format; use xlsx for anything another
+spreadsheet application should open. The constructors take
+`(name_or_path, locale, tz, language_id)`, except that the bytes variants take
+the bytes first, and the icalc ones need only the language.
+
+### Utilities
+
+```ruby
+IronCalc.number_to_column(28)          # => "AB"
+IronCalc.column_to_number("AB")        # => 28
+IronCalc.parse_reference_a1("$B3")     # => {row: 3, column: 2, absolute_row: false, absolute_column: true}
+IronCalc.quote_name("My Sheet")        # => "'My Sheet'"
+```
+
+Also `parse_reference_r1c1`, the `is_valid_*` checks, `get_supported_locales`
+and `get_all_timezones`; see the [`IronCalc` module](https://jvdp.github.io/IronCalc-Ruby/IronCalc.html).
 
 Errors raised by the engine surface as `IronCalc::Error`.
 
 ## Relationship to the Python bindings
 
 `ironcalc-ruby` is a thin binding over the same Rust engine as the
-[IronCalc Python bindings](https://github.com/ironcalc/ironcalc/tree/main/bindings/python),
-and deliberately mirrors their API. Both are compiled native extensions (Python
-via **pyo3**, Ruby via **magnus** / **rb-sys**) exposing a module named
-`ironcalc` backed by the IronCalc engine.
+[IronCalc Python bindings](https://github.com/ironcalc/ironcalc/tree/main/bindings/python).
+Both are compiled native extensions (Python via **pyo3**, Ruby via **magnus** /
+**rb-sys**) exposing a module named `ironcalc` backed by the IronCalc engine.
+
+Both follow the shape of the engine, so the two APIs line up closely and most
+Python examples translate directly. Where Python renamed an engine method, Ruby
+keeps the engine's name: Python's `clear_cell_contents(sheet, row, column)` is
+`range_clear_contents(range)` here, and `Model.get_cell_style` is
+`get_style_for_cell`. They do not cover the same amount of it —
+see [Coverage compared to the Python bindings](#coverage-compared-to-the-python-bindings).
 
 ### What's identical
 
@@ -67,10 +209,10 @@ via **pyo3**, Ruby via **magnus** / **rb-sys**) exposing a module named
   `load_from_icalc`, `load_from_bytes`, `create_user_model`,
   `create_user_model_from_xlsx`, `create_user_model_from_icalc`,
   `create_user_model_from_bytes`.
-- **Method names and signatures** on `Model` / `UserModel` — `set_user_input`,
-  `get_formatted_cell_value`, `evaluate`, `insert_rows`, `set_column_width`,
-  `new_sheet`, `save_to_xlsx`, `to_bytes`, … (Python's `snake_case` is also
-  Ruby's convention, so they match exactly).
+- **Method names and signatures** for everything both take from the engine
+  unchanged — `set_user_input`, `get_formatted_cell_value`, `evaluate`,
+  `insert_rows`, `set_column_width`, `new_sheet`, `save_to_xlsx`, `to_bytes`, …
+  (Python's `snake_case` is also Ruby's convention).
 - **Coordinates**: `sheet` is a 0-based index; `row` and `column` are 1-based.
 - **Semantics**: the same engine, so the same inputs produce the same results.
 
@@ -101,16 +243,56 @@ ports:
 |---|---|---|
 | Module access | `ic.create(...)` | `IronCalc.create(...)` |
 | Error type | `WorkbookError` | `IronCalc::Error` |
-| Cell style | typed `Style` / `Font` / … objects | plain `Hash` (`get_cell_style` / `set_cell_style`) |
+| Cell style | typed `Style` / `Font` / … objects | `Hash` with Symbol keys (`get_style_for_cell` / `set_cell_style`) |
 | Cell type | `CellType` enum | `Symbol` (`:number`, `:text`, …) |
 | Worksheet properties | list of `SheetProperty` objects | array of `Hash`es (`:name`, `:state`, `:sheet_id`, `:color`) |
 | Sheet dimensions | tuple `(min_row, max_row, min_col, max_col)` | 4-element `Array` |
+| Engine structs (`Area`, `CellIndex`) | spread into separate arguments | `Hash` keyed by the struct's field names |
+| Engine tuples | tuple | `Array` |
 | Binary data | `bytes` | binary `String` |
 | Version | `ironcalc.__version__` | `IronCalc::VERSION` |
 
 Rather than reconstruct Python's per-field style classes, Ruby exchanges styles
-as plain hashes (serialized as JSON across the boundary). Everything else is kept
-as close to the Python bindings as the two languages allow.
+as plain Hashes keyed by the engine's field names. A method that shares a
+name with an engine method takes the engine's parameters in the engine's order,
+with `nil` for an `Option`; conveniences get names of their own. So a range is
+one argument, `update_range_style({sheet: 0, row: 2, column: 2, width: 2,
+height: 9}, "font.b", "true")`, where Python spreads it into start and end
+corners.
+
+### Coverage compared to the Python bindings
+
+Both bindings wrap the same engine, so anything both expose behaves the same.
+They do not expose the same amount of it. Counted against **IronCalc 0.8.3**,
+the version this gem tracks, and accurate at the time of writing:
+
+| | Python | Ruby |
+|---|---|---|
+| `Model` | 69 | 62 |
+| `UserModel` | 102 | 52 |
+
+Most of the difference is deliberate. Selection, scrolling, clipboard and
+keyboard state belong to a UI rather than to a library, and are not exposed
+here. Conditional formatting, named styles and themes are a known backlog,
+listed explicitly in `rake parity`'s `ENGINE_DEFERRED` so they stay visible.
+
+What Ruby adds is mostly layering rather than extra engine coverage: Hash-based
+styles, `batch`, and xlsx in memory (`to_xlsx_bytes` / `load_from_xlsx_bytes`).
+
+These numbers move with every engine release; `rake parity` reports the
+current picture.
+
+## AI-assisted development
+
+These bindings are written and maintained with substantial help from
+[Claude Code](https://claude.com/claude-code), Anthropic's coding agent. A
+human maintainer directs the work, reviews every change and makes the releases.
+
+Correctness doesn't rest on review alone. The test suite, run in CI on every
+push, re-runs the engine's own formula regression fixtures through the binding.
+`rake parity` checks the API surface and method signatures against the engine
+and the Python bindings. The conventions agents follow here are in
+[AGENTS.md](https://github.com/jvdp/IronCalc-Ruby/blob/main/AGENTS.md).
 
 ## License
 

data/ext/ironcalc/Cargo.toml

@@ -10,8 +10,8 @@ crate-type = ["cdylib"]
 [dependencies]
 magnus = "0.8"
 serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
+serde_magnus = "0.11"
 bitcode = "0.6.8"
 # The IronCalc engine, published on crates.io as `ironcalc`. Renamed to `xlsx`
 # here so the source can refer to `xlsx::base`, `xlsx::import`, `xlsx::export`.
-xlsx = { package = "ironcalc", version = "0.7.1" }
+xlsx = { package = "ironcalc", version = "0.8.3" }