{"id":20301565,"url":"https://github.com/zero-one-group/fxl","last_synced_at":"2025-04-11T13:36:31.435Z","repository":{"id":47084159,"uuid":"256758457","full_name":"zero-one-group/fxl","owner":"zero-one-group","description":"fxl is a Clojure spreadsheet library","archived":false,"fork":false,"pushed_at":"2021-09-14T09:48:27.000Z","size":235,"stargazers_count":128,"open_issues_count":10,"forks_count":9,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-03-25T09:49:26.264Z","etag":null,"topics":["clojure-library","data","data-oriented","excel","functional-programming","spreadsheet","xlsx"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zero-one-group.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-18T13:18:54.000Z","updated_at":"2024-07-30T18:20:35.000Z","dependencies_parsed_at":"2022-09-03T17:22:05.482Z","dependency_job_id":null,"html_url":"https://github.com/zero-one-group/fxl","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zero-one-group%2Ffxl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zero-one-group%2Ffxl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zero-one-group%2Ffxl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zero-one-group%2Ffxl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zero-one-group","download_url":"https://codeload.github.com/zero-one-group/fxl/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248410187,"owners_count":21098772,"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":["clojure-library","data","data-oriented","excel","functional-programming","spreadsheet","xlsx"],"created_at":"2024-11-14T16:26:32.733Z","updated_at":"2025-04-11T13:36:31.408Z","avatar_url":"https://github.com/zero-one-group.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"logo/fxl.png\" width=\"375px\"\u003e\n\u003c/p\u003e\n\n`fxl` (*/ˈfɪk.səl/* or \"pixel\" with an f) is a Clojure library for manipulating spreadsheets.\n\n[![Continuous Integration](https://github.com/zero-one-group/fxl/workflows/Continuous%20Integration/badge.svg?branch=develop)](https://github.com/zero-one-group/fxl/commits/develop)\n[![Code Coverage](https://codecov.io/gh/zero-one-group/fxl/branch/develop/graph/badge.svg)](https://codecov.io/gh/zero-one-group/fxl)\n[![Clojars Project](https://img.shields.io/clojars/v/zero.one/fxl.svg)](http://clojars.org/zero.one/fxl)\n\nWARNING! This library is still unstable. Some information here may be outdated. Do not use it in production just yet!\n\nSee [docjure](https://github.com/mjul/docjure) and [excel-clj](https://github.com/matthewdowney/excel-clj) for more mature alternatives.\n\n# Introduction\n\nThe goal of the project is to provide a composable data-oriented spreadsheet interface for Clojure. The library is written with simplicity in mind - particularly as discussed in Rich Hickey's talk [Simplicity Matters](https://www.youtube.com/watch?v=rI8tNMsozo0) on the [list-and-order problem](https://youtu.be/rI8tNMsozo0?t=1448).\n\n\u003cblockquote\u003e\n    \u003cp\u003e \n        If order matters, complexity has been introduced to the system\n    \u003c/p\u003e\n    \u0026mdash;\n    \u003ca href=\"https://youtu.be/rI8tNMsozo0\"\u003e\n        Rich Hickey, Simplicity Matters\n    \u003c/a\u003e\n\u003c/blockquote\u003e\n\nWhat `fxl` attempts to do differently to [docjure](https://github.com/mjul/docjure) and [excel-clj](https://github.com/matthewdowney/excel-clj/tree/master/src/excel_clj) is to represent spreadsheets as an unordered collection of maps, instead of relying on tabular formats. This makes it easier to deal with independent, smaller components of the spreadsheet and simply apply `concat` to put together different components of a spreadsheet.\n\n[![cljdoc](https://cljdoc.org/badge/zero.one/fxl)](https://cljdoc.org/d/zero.one/fxl/CURRENT)\n[![slack](https://badgen.net/badge/-/clojurians%2Ffxl?icon=slack\u0026label)](https://clojurians.slack.com/messages/fxl/)\n[![zulip](https://img.shields.io/badge/zulip-clojurians%2Ffxl-brightgreen.svg)](https://clojurians.zulipchat.com/#narrow/stream/257213-fxl)\n\n# Examples\n\n## Map Representation of Cells\n\nA `fxl` cell is represented by a map that tells us its value, location and style. For instance:\n\n```clojure\n{:value -2.2\n :coord {:row 4 :col 3 :sheet \"Growth\"}\n :style {:data-format \"0.00%\" :background-colour :yellow}}\n```\n\nis rendered as a highlighted cell with a value of \"-2.2%\" on the fifth row and fourth column of a sheet called \"Growth\".\n\nBy knowing cells, you know almost all of `fxl`! The rest of the library is composed of IO functions such as `read-xlsx!` and `write-xlsx!` and helper functions to transform Clojure data structures into cell maps.\n\nTo find out more about the available styles, see their [specs](https://gitlab.com/zero-one-open-source/fxl/-/blob/develop/src/zero_one/fxl/specs.clj).\n\n## Creating Simple Spreadsheets with Builtin Clojure\n\nSuppose we would like to create a spreadsheet such as the following:\n\n```\n| Item     | Cost     |\n| -------- | -------- |\n| Rent     | 1000     |\n| Gas      | 100      |\n| Food     | 300      |\n| Gym      | 50       |\n|          |          |\n| Total    | 1450     |\n```\n\nAssume that we have the cost data in the following form:\n\n``` clojure\n(def costs\n  [{:item \"Rent\" :cost 1000}\n   {:item \"Gas\"  :cost 100}\n   {:item \"Food\" :cost 300}\n   {:item \"Gym\"  :cost 50}])\n```\n\nWe would break the spreadsheet down into three components, namely the header, the body and the total:\n\n``` clojure\n(require '[zero-one.fxl.core :as fxl])\n\n(def header-cells\n  [{:value \"Item\" :coord {:row 0 :col 0} :style {}}\n   {:value \"Cost\" :coord {:row 0 :col 1} :style {}}])\n\n(def body-cells\n  (flatten\n    (for [[row cost] (map vector (range) costs)]\n      (list\n        {:value (:item cost) :coord {:row (inc row) :col 0} :style {}}\n        {:value (:cost cost) :coord {:row (inc row) :col 1} :style {}}))))\n\n(def total-cells\n  (let [row        (count costs)\n        total-cost (apply + (map :cost costs))]\n    [{:value \"Total\"    :coord {:row (+ row 2) :col 0} :style {}}\n     {:value total-cost :coord {:row (+ row 2) :col 1} :style {}}]))\n\n(fxl/write-xlsx!\n  (concat header-cells body-cells total-cells)\n  \"examples/spreadsheets/write_to_plain_excel.xlsx\")\n```\n\nIn fact, style is optional, so we can actually remove `:style {}` from all the maps.\n\nWhile both these methods work, dealing with the coordinates can be fiddly. We can make the intent clearer using `fxl` helper functions.\n\n## Creating Simple Spreadsheets with Helper Functions\n\nHere we use `row-\u003ecells`, `table-\u003ecells`, `pad-below` and `concat-below` to help us initialise and navigate relative coordinates.\n\n``` clojure\n(def header-cells (fxl/row-\u003ecells [\"Item\" \"Cost\"]))\n\n(def body-cells\n  (fxl/records-\u003ecells [:item :cost] costs))\n\n(def total-cells\n  (let [total-cost (apply + (map :cost costs))]\n    (fxl/row-\u003ecells [\"Total\" total-cost])))\n\n(fxl/write-xlsx!\n  (fxl/concat-below header-cells\n                    (fxl/pad-below body-cells)\n                    total-cells)\n  \"examples/spreadsheets/write_to_plain_excel_with_helpers.xlsx\")\n```\n\nMore helper functions are available - see [here](https://github.com/zero-one-group/fxl/blob/develop/src/zero_one/fxl/core.clj).\n\n## Modular Styling\n\nWith a Clojure-map representation for cells, manipulating the spreadsheet is easy using built-in functions. Suppose we would like to:\n\n1. highlight the header row and make it bold\n2. make the total row bold\n2. horizontally align all cells to the center\n\nWe can achieve this by composing simple styling functions:\n\n``` clojure\n(defn bold [cell]\n  (assoc-in cell [:style :bold] true))\n\n(defn highlight [cell]\n  (assoc-in cell [:style :background-colour] :grey_25_percent))\n\n(defn align-center [cell]\n  (assoc-in cell [:style :horizontal] :center))\n\n(def all-cells\n  (map align-center\n    (fxl/concat-below\n      (map (comp bold highlight) header-cells)\n      (fxl/pad-below body-cells)\n      (map bold total-cells))))\n```\n\n# Installation\n\nAdd the following to your `project.clj` dependency:\n\n[![Clojars Project](https://clojars.org/zero.one/fxl/latest-version.svg)](http://clojars.org/zero.one/fxl)\n\n# Future Work\n\nFeatures:\n- Core:\n    - Column width and row heights.\n    - Freezing panes.\n    - Excel coords -\u003e index coords.\n    - Support merged cells.\n    - Support data-val cells.\n- Support to Google Sheet API.\n- Error handling with `failjure`.\n- Property-based testing.\n\n# License\n\nCopyright 2020 Zero One Group.\n\nfxl is licensed under Apache License v2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzero-one-group%2Ffxl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzero-one-group%2Ffxl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzero-one-group%2Ffxl/lists"}