# Exceed
`Exceed` is a high-level stream-oriented library for generating Excel files.
Useful when generating spreadsheets from data sets large enough that they may
exceed available memory—or at least the available memory that one might want
to dedicate to building spreadsheets.
## Installation
``` elixir
def deps do
[
{:exceed, "~> 0.1"}
]
end
```
## Usage
XLSX streams are generated by initializing a workbook (with a creator name),
adding worksheets, and then converting that to a stream.
``` elixir
stream =
Exceed.Workbook.new("Creator Name")
|> Exceed.Workbook.add_worksheet(
Exceed.Worksheet.new("Sheet Name", ["Heading 1", "Heading 2"]
[["Row 1 Cell 1", "Row 1 Cell 2"], ["Row 2 Cell 1", "Row 2 Cell 2"]])
)
|> Exceed.stream!()
stream
|> Stream.into(File.stream!("/tmp/workbook.xslx"))
|> Stream.run()
```
Worksheets may be initialized with lists of lists, or they may be initialized
with a stream of data that maps to a list of cells.
``` elixir
rows =
Stream.unfold(1, fn
10_001 -> nil
row_count -> {["Row #{row_count} Cell 1", "Row #{row_count} Cell 2"], row_count + 1}
end)
Exceed.Worksheet.new("Sheet Name", ["Heading 1", "Heading 2"], rows)
```
## Alternatives & References
This library is inspired by and learns from other great libraries. One may
choose to use those instead of Exceed:
- [elixlsx](https://hex.pm/packages/elixlsx) - Provides fine-grained control
over cells, but is not stream-oriented and thus requires that all source data
and rows be retained in memory until the entire workbook is written.
- [xml_stream](https://hex.pm/packages/xml_stream) - Provides low-level
constructs that may be combined to make an Excel file. Works nicely with
streams. Requires that one know all the ins and outs of
[SpreadsheetML](https://learn.microsoft.com/en-us/office/open-xml/spreadsheet/structure-of-a-spreadsheetml-document?tabs=cs)
in order to make a valid file that Excel can parse.