{"id":13508746,"url":"https://github.com/jsonkenl/xlsxir","last_synced_at":"2026-02-22T19:03:31.643Z","repository":{"id":5492440,"uuid":"53290944","full_name":"jsonkenl/xlsxir","owner":"jsonkenl","description":"Xlsx parser for the Elixir language.","archived":false,"fork":false,"pushed_at":"2024-08-14T09:21:20.000Z","size":1736,"stargazers_count":215,"open_issues_count":27,"forks_count":92,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-17T01:07:06.827Z","etag":null,"topics":["elixir","elixir-lang","excel","libreoffice","parser","xlsx"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsonkenl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-07T02:51:47.000Z","updated_at":"2025-01-08T08:11:04.000Z","dependencies_parsed_at":"2023-02-10T16:30:27.044Z","dependency_job_id":"47b0e17a-d38c-4e0c-a8d8-bb7aa2e145a9","html_url":"https://github.com/jsonkenl/xlsxir","commit_stats":{"total_commits":215,"total_committers":36,"mean_commits":5.972222222222222,"dds":"0.38604651162790693","last_synced_commit":"4dbebf2eec01ee661d21d78d3ad5b70a91c3339a"},"previous_names":["kennellroxco/xlsxir"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonkenl%2Fxlsxir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonkenl%2Fxlsxir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonkenl%2Fxlsxir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsonkenl%2Fxlsxir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsonkenl","download_url":"https://codeload.github.com/jsonkenl/xlsxir/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246314015,"owners_count":20757453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","elixir-lang","excel","libreoffice","parser","xlsx"],"created_at":"2024-08-01T02:00:57.835Z","updated_at":"2025-10-21T19:02:12.906Z","avatar_url":"https://github.com/jsonkenl.png","language":"Elixir","funding_links":[],"categories":["Office"],"sub_categories":[],"readme":"# Xlsxir\n\n[![Build Status](https://travis-ci.org/jsonkenl/xlsxir.svg?branch=master)](https://travis-ci.org/jsonkenl/xlsxir)\n[![Hex.pm Version](http://img.shields.io/hexpm/v/xlsxir.svg)](https://hex.pm/packages/xlsxir)\n[![Hex docs](http://img.shields.io/badge/hex.pm-docs-blue.svg?style=flat)](https://hexdocs.pm/xlsxir)\n[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/kennellroxco/xlsxir/master/LICENSE)\n\nXlsxir is an Elixir library that parses `.xlsx` files using Simple API for XML (SAX) parsing via the [Erlsom](https://github.com/willemdj/erlsom) Erlang library, extracts the data to an Erlang Term Storage (ETS) process and provides various functions for accessing the data. Please submit any issues found and they will be addressed ASAP.\n\n## Installation\n\nYou can add Xlsxir as a dependency to your Elixir project via the Hex package manager by adding the following to your `mix.exs` file:\n\n```elixir\ndef deps do\n  [ {:xlsxir, \"~\u003e 1.6.4\"} ]\nend\n```\n\nOr, you can directly reference the GitHub repo:\n\n```elixir\ndef deps do\n  [ {:xlsxir, github: \"jsonkenl/xlsxir\"} ]\nend\n```\n\nThen start an OTP application:\n\n```elixir\ndefp application do\n  [applications: [:xlsxir]]\nend\n```\n\n## Basic Usage\n\n**Xlsxir.extract/3 is deprecated, please use Xlsxir.multi_extract/1-5 going forward.**\n\nXlsxir parses a `.xlsx` file located at a given `path` and extracts the data to an ETS process via the `Xlsxir.multi_extract/1-5`, `Xlsxir.peek/3-4` and `Xlsxir.stream_list/2-3` functions:\n\n```elixir\nXlsxir.multi_extract(path, index \\\\ nil, timer \\\\ false, excel \\\\ nil, options \\\\ [])\nXlsxir.peek(path, index, rows, options \\\\ [])\nXlsxir.stream_list(path, index, options \\\\ [])\n```\n\nThe `peek/3-4` functions return only the given number of rows from the worksheet at a given index. The `multi_extract/1-5` functions allow multiple worksheets to be parsed by creating a separate ETS process for each worksheet and returning a unique table identifier for each. This option will parse all worksheets by default (when `index == nil`), returning a list of tuple results.\n\nArgument descriptions:\n- `path` the path of the file to be parsed in `string` format\n- `index` is the position of the worksheet you wish to parse (zero-based index)\n- `timer` is a boolean flag that controls an extraction timer that returns time elapsed when set to `true`. Defalut value is `false`.\n- `rows` is an integer representing the number of rows to be extracted from the given worksheet.\n- `options` - see function documentation for option detail.\n\nUpon successful completion, the extraction process returns:\n- for `multi_extract/3`:\n    * `[{:ok, table_1_id}, ...]` with `timer` set to `false`\n    * `{:ok, table_id}` when given a specific worksheet `index`\n    * `[{:ok, table_1_id, time_elapsed}, ...]` with `timer` set to `true`\n    * `{:ok, table_id, time_elapsed}` when given a specific worksheet `index`\n- for `peek/3`: `{:ok, table_id}`\n\nUnsucessful parsing of a specific worksheet returns `{:error, reason}`.\n\n\u003cbr/\u003e\nThe extracted worksheet data can be accessed using any of the following functions:\n\n```\nXlsxir.get_list(table_id)\nXlsxir.get_map(table_id)\nXlsxir.get_mda(table_id)\nXlsxir.get_cell(table_id, cell_ref)\nXlsxir.get_row(table_id, row_num)\nXlsxir.get_col(table_id, col_ltr)\nXlsxir.get_info(table_id, num_type)\n```\n\n`Xlsxir.get_list/1` returns entire worksheet in a list of row lists (i.e. `[[row 1 values], ...]`)\u003cbr/\u003e\n`Xlsxir.get_map/1` returns entire worksheet in a map of cell names and values (i.e. `%{\"A1\" =\u003e value, ...}`)\u003cbr/\u003e\n`Xlsxir.get_mda/1` returns entire worksheet in an indexed map which can be accessed like a multi-dimensional array (i.e. `some_var[0][0]` for cell \"A1\")\u003cbr/\u003e\n`Xlsxir.get_cell/2` returns value of specified cell (i.e. `\"A1\"` returns value contained in cell A1)\u003cbr/\u003e\n`Xlsxir.get_row/2` returns values of specified row (i.e. `1` returns the first row of data)\u003cbr/\u003e\n`Xlsxir.get_col/2` returns values of specified column (i.e. `\"A\"` returns the first column of data)\u003cbr/\u003e\n`Xlsxir.get_info/1` and `Xlsxir.get_multi_info/2` return count data for `num_type` specified (i.e. `:rows`, `:cols`, `:cells`, `:all`)\u003cbr/\u003e\n\nOnce the table data is no longer needed, run the following function to delete the ETS process and free memory:\n```elixir\nXlsxir.close(table_id)\n```\n\nRefer to [Xlsxir documentation](https://hexdocs.pm/xlsxir/index.html) for more detailed examples.\n\n## Considerations\n\nCell references are formatted as a string (i.e. \"A1\"). Strings will be returned as type `string`, resulting values for functions from within the worksheet are returned as type `string`, `integer` or `float` depending on the type of the resulting value, data formatted as a number in the worksheet will be returned as type `integer` or `float`, date formatted values will be returned in Erlang `:calendar.date()` type format (i.e. `{year, month, day}`), and datetime values will be returned as an Elixir `naive datetime`. Xlsxir does not currently support dates prior to 1/1/1900.\n\n## Contributing\n\nContributions are encouraged. Feel free to fork the repo, add your code along with appropriate tests and documentation (ensuring all existing tests continue to pass) and submit a pull request.\n\n## Bug Reporting\n\nPlease report any bugs or request future enhancements via the [Issues](https://github.com/kennellroxco/xlsxir/issues) page.\n\n## Acknowledgements\n\nI'd like to thank the following people who were a big help in the development of this library:\n\n- Paulo Almeida (@pma) helped with testing and has provided several great ideas for development.\n- Benjamin Tan's (@benjamintanweihao) article on [SAX parsing with Elrsom](http://benjamintan.io/blog/2014/10/01/parsing-wikipedia-xml-dump-in-elixir-using-erlsom/) was invaluable.\n- Daniel Berkompas' (@danielberkompas) article [Multidimensional Arrays in Elixir](http://blog.danielberkompas.com/2016/04/23/multidimensional-arrays-in-elixir.html?utm_campaign=elixir_radar_48\u0026utm_medium=email\u0026utm_source=RD+Station) inspired `Xlsxir.get_mda/0`.\n- Alex Kovalevych's (@alexkovalevych) contributions greatly improved the parsing performance of Xlsxir. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonkenl%2Fxlsxir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsonkenl%2Fxlsxir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsonkenl%2Fxlsxir/lists"}