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]].

Run the (example) function at the bottom of this namespace to see more.

Interface that sits one level above Apache POI.

Handles all apache POI interaction besides styling (style.clj).
See the examples at the bottom of the namespace inside of (comment ...)
expressions for how to use the writers.

Prototype features to be included in v2.0.0 -- everything subject to change.

;; 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 either be a
plain value or a value with style data.

  {:value 0.2345
   :style {: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 -- beyond the things we're accustomed to loving about
clojure data maps as opposed to mutable objects with getters/setters -- other
than declarative syntax 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, which specifies how to
coerce different attributes to POI objects. It has the signature
  (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}))))

A key-value tree for Excel (accounting) data. The format is
[Label [Children]] for nodes and [Label {:column :value}] for leaves.

For some example code, check out the various (comment ...) blocks in this
namespace.