@spec parse(
  binary(),
  keyword()
) :: {:ok, list() | [{String.t(), list()}]} | {:error, binary()}

Parses a specific sheet or all sheets from a spreadsheet file or binary content.

When called without the :sheet option, parses all sheets and returns a list of tuples containing {sheet_name, sheet_data}.

When called with the :sheet option, parses only the specified sheet and returns its data as a list of lists.

Returns the sheet data as a list of lists, where each inner list represents a row. The first row typically contains headers.

Dates are automatically parsed to NaiveDateTime when possible, and empty cells are converted to nil.

Options

• :sheet - The name of the sheet to parse. If not provided, parses all sheets.
• :format - Specifies the input format. Either :filename (default) or :binary.
• :hidden - When false, excludes hidden sheets from all-sheets parsing. Defaults to true.

Examples

# Parse a specific sheet from a file path
Spreadsheet.parse("sales.xlsx", sheet: "Q1 Data")
{:ok, [
  ["Product", "Sales", "Date"],
  ["Widget A", 1500.0, ~N[2024-01-15 00:00:00]]
]}

# Parse all sheets from a file path
Spreadsheet.parse("sales.xlsx")
{:ok, [
  {"Q1 Data", [
    ["Product", "Sales", "Date"],
    ["Widget A", 1500.0, ~N[2024-01-15 00:00:00]]
  ]},
  {"Q2 Data", [
    ["Product", "Sales", "Date"],
    ["Widget B", 2300.0, ~N[2024-04-15 00:00:00]]
  ]}
]}

# Parse all sheets from binary content
content = File.read!("sales.xlsx")
Spreadsheet.parse(content, format: :binary)
{:ok, [
  {"Q1 Data", [...]},
  {"Q2 Data", [...]}
]}

# Parse all sheets excluding hidden ones
Spreadsheet.parse("sales.xlsx", hidden: false)
{:ok, [{"Visible Sheet", [...]}]}

# Parse specific sheet from binary
Spreadsheet.parse(content, sheet: "Q1 Data", format: :binary)
{:ok, [[...]]}

@spec parse_from_binary(binary(), binary()) :: {:ok, list()} | {:error, String.t()}

Parses a specific sheet from spreadsheet binary content.

This function is deprecated. Use parse/2 with sheet: and format: :binary options instead.

Returns the sheet data as a list of lists, where each inner list represents a row.

Dates are automatically parsed to NaiveDateTime when possible, and empty cells are converted to nil.

@spec sheet_names(
  binary(),
  keyword()
) :: {:ok, [String.t()]} | {:error, String.t()}

Returns a list of sheet names from a spreadsheet file or binary content.

Supports Excel (.xlsx, .xls) and LibreOffice (.ods) file formats.

Options

• :format - Specifies the input format. Either :filename (default) or :binary.
• :hidden - When false, excludes hidden sheets. Defaults to true.

Examples

# From a file path (default)
Spreadsheet.sheet_names("workbook.xlsx")
{:ok, ["Sheet1", "Sheet2"]}

# From a file path (explicit)
Spreadsheet.sheet_names("workbook.xlsx", format: :filename)
{:ok, ["Sheet1", "Sheet2"]}

# From binary content
content = File.read!("workbook.xlsx")
Spreadsheet.sheet_names(content, format: :binary)
{:ok, ["Sheet1", "Sheet2"]}

# Exclude hidden sheets
Spreadsheet.sheet_names("workbook.xlsx", hidden: false)
{:ok, ["Sheet1"]}

@spec sheet_names_from_binary(
  binary(),
  keyword()
) :: {:ok, [String.t()]} | {:error, String.t()}

Returns a list of sheet names from spreadsheet binary content.

This function is deprecated. Use sheet_names/2 with format: :binary instead.

Options

• :hidden - When false, excludes hidden sheets. Defaults to true.