{"id":26018848,"url":"https://github.com/peterbecker/xls-utils","last_synced_at":"2025-10-26T05:50:13.811Z","repository":{"id":43847603,"uuid":"176066809","full_name":"peterbecker/xls-utils","owner":"peterbecker","description":"Kotlin utilities for dealing with Excel files","archived":false,"fork":false,"pushed_at":"2024-08-14T18:02:20.000Z","size":367,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-08-15T17:04:48.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","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/peterbecker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2019-03-17T06:55:59.000Z","updated_at":"2024-08-14T18:02:23.000Z","dependencies_parsed_at":"2023-12-01T01:27:25.133Z","dependency_job_id":"bb14f25d-2483-4696-81e0-64181c4e86eb","html_url":"https://github.com/peterbecker/xls-utils","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterbecker%2Fxls-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterbecker%2Fxls-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterbecker%2Fxls-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterbecker%2Fxls-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterbecker","download_url":"https://codeload.github.com/peterbecker/xls-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242163839,"owners_count":20082223,"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":[],"created_at":"2025-03-06T06:38:12.269Z","updated_at":"2025-10-26T05:50:13.715Z","avatar_url":"https://github.com/peterbecker.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"Excel Libraries and Tools\n=========================\n\n[![Build Status](https://github.com/peterbecker/xls-utils/workflows/Build/badge.svg)](https://github.com/peterbecker/xls-utils/actions)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.peterbecker/kotlin-xls/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.peterbecker/kotlin-xls)\n\nThis is a collection of libraries and tools to work with Excel\nfiles from Kotlin, building on the [Apache POI library](https://poi.apache.org/).\n\nContents:\n\n* `kotlin-xls` - a wrapper around POI to make handling Excel files easier, also includes code to compare\n   Excel workbooks, aimed primarily at unit testing\n* `db2xls` - a command line utility to run an SQL query via JDBC and write the results into an Excel file\n* `db2xls-bundle` - a version of `db2xls` bundled into a single JAR with all dependencies and some common\n  JDBC drivers\n\n\nQuick Start\n===========\n\nUsing the Library\n-----------------\n\nFollow the \"maven central\" banner above to find the correct dependency for your build tool.\n\nWhen writing data, the primary method to use is to open a standard POI `XSSFWorkbook` object from a template file, then \ncall the `writeData(targetName: String, rows: Iterator\u003cList\u003cAny?\u003e\u003e)` function on this. The `targetName` is the name of \na range or named table in the input file. This will be filled with the data in `rows`, with each item of the iterator\nrepresenting the data for the row. The target structure (range/table) will automatically be expanded and the styles\ncopied into newly created rows.\n\nIf charts are used, then the `expandChartReferences(area: AreaReference)` needs to be called as well, as Excel will not\nautomatically update charts. Note the limitations listed below.\n\nA full use looks something like this (excluding error handling):\n\n```kotlin\nval wb = XSSFWorkbook(File(\"my_template.xlsx\"))\nval areaRef = wb.writeData(\"my_target_range\", dataToIterateOver)\nwb.expandChartReferences(areaRef) // needed only when charts are used\nwb.write(targetOutputStream)\n```\n\n[The Db2Xls class](https://github.com/peterbecker/xls-utils/blob/master/db2xls/src/main/kotlin/de/peterbecker/xls/Db2Xls.kt)\nshows a more complete usage example.\n\nThere are a number of additional extensions \n[inside the main library code](https://github.com/peterbecker/xls-utils/tree/master/kotlin-xls/src/main/kotlin/de/peterbecker/xls)\n- these are grouped by the names of the POI objects they extend.\n\nThere is [an additional set of functions to compare workbooks and their elements](https://github.com/peterbecker/xls-utils/blob/master/kotlin-xls/src/main/kotlin/de/peterbecker/xls/diff/CompareXls.kt).\nThis is primarily intended for unit testing, see [its test cases](https://github.com/peterbecker/xls-utils/tree/master/kotlin-xls/src/test/kotlin/de/peterbecker/xls/diff)\nas to how it can be used.\n\nDownloading the Bundled Version\n-------------------------------\n\nYou can find the pre-packaged bundles on [the GitHub releases](https://github.com/peterbecker/xls-utils/releases), these\ncontain the program itself with some common database connectors. \n\nBuilding from Source\n--------------------\n\nTo build the tool, get a copy of the source by cloning this repository or downloading a ZIP from the release page. Then\nrun this command inside the project folder:\n\n```shell script\nmvn package\n```\n\nThis requires a [Java Development Kit (JDK) 11 or greater](https://adoptopenjdk.net/), and \n[Maven 3.5](https://maven.apache.org/) or greater.\n\nRunning the Example\n-------------------\n\nThe documentation on running the example assumes you downloaded or checked out a copy of the source code as well.\n\nOnce the build has finished, go into `db2xls-bundle/sample` -- this contains a fully functional example with a\nscript `run.sh` to execute it (it's a single command, if you can't use the script run it directly).\n\nIf you downloaded the tool, copy the file into this folder and run:\n\n```shell script\njava -jar db2xls-bundle.jar countries.conf\n```\n\nThis will:\n* load the configuration from the `countries.conf` file\n* load the template `countries.template.xlsx` as per configuration file\n* open the database specified in the configuration -- this is an embedded database, which will be initialized using the\n  `init.sql` script, which contains data about countries\n* run queries as specified in the top left cells of the `Query_...` sheets\n* fill in the tables with matching names (e.g. the query from `Query_Population` will fill the table named `Population`)\n* write the result to `Countries.xlsx` as per configuration file\n\nRunning Other Queries\n---------------------\n\nThe bundled version of this tool includes a number of database driver, currently:\n\n* H2 (the embedded engine used in the example)\n* PostgreSQL\n* MySQL/MariaDB\n* MS SQL Server\n\nThis means that the tool can connect to each of these by configuring a matching JDBC URL in the configuration file,\nalong with the username and password for the connection.\n\nThe only other two options are the input template and the name for the output file.\n\nTo set up your own template just take any Excel file and add new sheets named \"Query_\" followed by a name to identify\nthe query. Note that the prefix and the name are case sensitive, i.e. you need the `Q` capitalized and the name for\nyour query will have to match in capitalization as well. You can create any number of these query sheets, the tool\ndoes not limit the number, although a very large number may create files that are too much for Excel to handle.\n\nFor each query create an Excel table (\"Format as Table\" in the Home ribbon). Then rename the table to match the query\nname, e.g. if you created a sheet \"Query_Recent_Sales\", then the table should be named \"Recent_Sales\". Note that there\nare limitations on table names, see [the documentation on renaming tables in Excel](https://support.microsoft.com/en-us/office/rename-an-excel-table-fbf49a4f-82a3-43eb-8ba2-44d21233b114). \n\nThe table needs\nto have the right width for the query result, so if the query results in 9 columns, then the table should be 9 columns\nwide -- the tool will add rows as needed, but it will not change the width of the table. No rows will be \ndeleted, so the table in the template should not contain data. Ideally it is only a header and a single empty data row.\n\nYou can also use named ranges\nas targets, but tables produce nicer looking results and allow for easy sorting and filtering afterwards.\n\nThe target tables/ranges can be anywhere in the workbook, but the sheets named \"Query_*\" will be deleted after\nthe query was executed, so you need at least one more sheet for the output.\n\nOnce that is done, name the input template in the configuration file, give the output file a name, and run the tool\nvia this command:\n\n```shell script\njava -jar db2xls-bundle*.jar MY_CONFIG.conf\n```\n\nIf you have more than one version of the tool, expand the `*` to the one you want to use.\n\nDeployment\n==========\n\nTo run the tool on another machine a Java 11+ runtime is required plus the following files:\n* the bundle JAR file\n* the configuration file\n* the template file\n\n\nUsing other Database Systems\n============================\n\nIf you need to query a database engine not supported out of the box, you also need the matching JDBC driver for this. \nMost RDBMS offer such a driver. You then need to run the following command instead:\n\n```shell script\njava -cp db2xls-bundle*.jar:JBDC_DRIVER_FILE.jar de.peterbecker.xls.Db2XlsKt MY_CONFIG.conf\n```\n\nOn Windows the separator has to be a semicolon instead of the colon. Alternatively you can edit `db2xls-bundle/pom.xml`\nto tailor the JDBC drivers in the file -- you can remove any you don't need this way as well. Note that the ones\nspecified in this file will pick up a version from the `pom.xml` in the top folder, you will have to specify the\nversion when adding custom ones, but this can be done directly in `db2xls-bundle/pom.xml`.\n\nProgrammatic Use\n================\n\nThe logic behind the command line tool is all behind a single method in the `db2xls` module:\n\n```\nde.peterbecker.xls.Db2Xls::runReports(..)\n```\n\nThis operates on POI `Workbook` objects, it takes the template and a JDBC connection and returns the modified workbook.\nNote that at the time of writing it will operate on the input, so the template will have to be copied or loaded before\neach use.\n\nThe workbook objects can be written to any output stream, which can be used to upload files somewhere or to use them\nas a response to a HTTP request.\n\nThe `kotlin-xls` library contains lower-level functions that are not relating to database interactions. This includes\nthe ability to write in-memory data into the named tables or ranges.\n\nLimitations\n===========\n\nExcel does not reference named ranges or tables by their name, but the actual range. Whenever the range changes, all\ncharts and other visualizations need to be updated. This is currently not fully implemented. The following \nvisualizations are supported, others will not be updated to reflect the data loaded:\n\n* Line Charts\n* Pie Charts\n* 3D Pie Charts\n* Doughnut Charts\n\nPlease feel free to request support for others as needed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterbecker%2Fxls-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterbecker%2Fxls-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterbecker%2Fxls-utils/lists"}