A lightweight wrapper over cell values that allows combining both simple
and wrapped cells with new styles and dimensions.

Utilities for declarative creation of Excel (.xlsx) spreadsheets,
with higher level abstractions over Apache POI (https://poi.apache.org/).

The highest level data abstraction used to create excel spreadsheets is a
tree, followed by a table, and finally the most basic abstraction is a grid.

The tree and table functions convert tree formatted or tabular data into a
grid of [[cell]].

See the (comment) form with examples at the bottom of this namespace.

To provide some minimal backwards compatibility with v1.x

Write Clojure grids of `[[cell]]` as Excel worksheets, convert Excel
worksheets to PDFs, and read Excel worksheets.

A cell can be either a plain value (a string, java.util.Date, etc.) or such
a value wrapped in a map which also includes style and dimension data.

Check out the (example) function at the bottom of this namespace for more.

Exposes a low level cell writer that uses Apache POI.

See the `example` and `performance-test` functions at the end of
this ns + the adjacent (comment ...) forms for more detail.

;; The style map attributes are converted to camel cased setters
(doto cell-style
  (.setDataFormat :percent)
  (.setFont
    (doto <create a font>
      (.setBold true)
      (.setFontHeightInPoints 10)))))

The basic unit of spreadsheet data is the cell, which can be embellished
with style data, e.g.

  {:data-format :percent,
   :font {:bold true :font-height-in-points 10}}

The goal of the style map is to reuse all of the functionality built in to
the underlying Apache POI objects, but with immutable data structures.

The primary advantage is the ease with which we can merge styles as maps
rather than trying to create some new POI object out of two other objects,
reading and combining all of their attributes and nested attributes.

## Mechanics

Style map data are representative of nested calls to the corresponding setter
methods in the Apache POI framework starting with a `CellStyle` object. That
is, the above example is roughly interpreted as:

  ;; A CellStyle POI object created under the hood during rendering
  (let [cell-style ...]

    ;; The style map attributes are converted to camel cased setters
    (doto cell-style
      (.setDataFormat :percent)
      (.setFont
        (doto <create a font>
          (.setBold true)
          (.setFontHeightInPoints 10)))))

The two nontrivial challenges are
  - creating nested objects, e.g. (.setFont cell-style <font>) needs to be
    called with a POI Font object; and
  - translating keywords like :percent to POI objects.

Both are solved with the `coerce-to-obj` multimethod specifying how to
coerce different attributes to POI objects, which has the shape

  (fn [workbook attribute value] => Object)

and dispatches on the `attribute` (a keyword).

We coerce key value pairs to objects from the bottom of the style map upwards,
meaning that by the time coerce-to-obj is being invoked for some attribute,
any nested attributes in the value have already been coerced.

A more nuanced representation of how the style map 'expands':

  ;; {:data-format :percent, :font {:bold true :font-height-in-points 10}}}
  ;; expands to
  (let [cell-style ..., workbook ...] ;; POI objects created during rendering
    (doto cell-style
      (.setDataFormat (coerce-to-obj workbook :data-format :percent))
      ;; The {:bold true :font-height-in-points 10} expands recursively
      (.setFont
        (coerce-to-obj
          workbook :font {:bold true :font-height-in-points 10}))))

Trees are maps, leaves are maps of something->(not a map).

Use ordered maps (like array-map) to enforce order.