https://github.com/raku-community-modules/spreadsheet-xlsx
Work with Excel (XLSX) spreadsheets in Raku
https://github.com/raku-community-modules/spreadsheet-xlsx
excel raku
Last synced: 11 months ago
JSON representation
Work with Excel (XLSX) spreadsheets in Raku
- Host: GitHub
- URL: https://github.com/raku-community-modules/spreadsheet-xlsx
- Owner: raku-community-modules
- License: artistic-2.0
- Created: 2020-05-12T16:31:39.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-11-30T15:18:34.000Z (over 1 year ago)
- Last Synced: 2024-11-30T15:26:00.970Z (over 1 year ago)
- Topics: excel, raku
- Language: Raku
- Homepage:
- Size: 210 KB
- Stars: 16
- Watchers: 4
- Forks: 10
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/raku-community-modules/Spreadsheet-XLSX/actions)
NAME
====
Spreadsheet::XLSX - blah blah blah
DESCRIPTION
===========
A Raku module for working with Excel spreadsheets (XLSX format), both reading existing files, creating new files, or modifying existing files and saving the changes. Of note, it:
* Knows how to lazily load sheet content, so if you don't look at a sheet then time won't be spent deserializing it (down to a cell level, even)
* In the modification scenario, tries to leave as much intact as it can, meaning that it's possible to poke data into a sheet more complex than could be produced by the module from scratch
* Only depends on the Raku `LibXML` and `Libarchive` modules (and their respective native dependencies)
This module is currently in development, and supports the subset of XLSX format features that were immediately needed for the use-case it was built for. That isn't so much, for now, but it will handle the most common needs:
* Enumerating worksheets
* Reading text and numbers from cells on a worksheet
* Creating new workbooks with worksheets with text and number cells
* Setting basic styles and number formats on cells in newly created worksheets
* Reading a workbook, making modifications, and saving it again
* Reading and writing column properties (such as column width)
SYNOPSIS
========
Reading existing workbooks
--------------------------
```raku
use Spreadsheet::XLSX;
# Read a workbook from an existing file (can pass IO::Path or a
# Blob in the case it was uploaded).
my $workbook = Spreadsheet::XLSX.load('accounts.xlsx');
# Get worksheets.
say "Workbook has {$workbook.worksheets.elems} sheets";
# Get the name of a worksheet.
say $workbook.worksheets.name;
# Get cell values (indexing is zero-based, done as a multi-dimensional array
# indexing operation [row ; column].
my $cells = $workbook.worksheets[0].cells;
say .value with $cells[0;0]; # A1
say .value with $cells[0;1]; # B1
say .value with $cells[1;0]; # A2
say .value with $cells[1;1]; # B2
```
Creating new workbooks
----------------------
```raku
use Spreadsheet::XLSX;
# Create a new workbook and add some worksheets to it.
my $workbook = Spreadsheet::XLSX.new;
my $sheet-a = $workbook.create-worksheet('Ingredients');
my $sheet-b = $workbook.create-worksheet('Matching Drinks');
# Put some data into a worksheet and style it. This is how the model
# actually works (useful if you want to add styles later).
$sheet-a.cells[0;0] = Spreadsheet::XLSX::Cell::Text.new(value => 'Ingredient');
$sheet-a.cells[0;0].style.bold = True;
$sheet-a.cells[0;1] = Spreadsheet::XLSX::Cell::Text.new(value => 'Quantity');
$sheet-a.cells[0;1].style.bold = True;
$sheet-a.cells[1;0] = Spreadsheet::XLSX::Cell::Text.new(value => 'Eggs');
$sheet-a.cells[1;1] = Spreadsheet::XLSX::Cell::Number.new(value => 6);
$sheet-a.cells[1;1].style.number-format = '#,###';
# However, there is a convenience form too.
$sheet-a.set(0, 0, 'Ingredient', :bold);
$sheet-a.set(0, 1, 'Quantity', :bold);
$sheet-a.set(1, 0, 'Eggs');
$sheet-a.set(1, 1, 6, :number-format('#,###'));
# Save it to a file (string or IO::Path name).
$workbook.save("foo.xlsx");
# Or get it as a blob, e.g. for a HTTP response.
my $blob = $workbook.to-blob();
```
Class / Method reference
========================
class Spreadsheet::XLSX
-----------------------
The actual outward facing class
### has Hash $!archive
Map of files in the decompressed archive we read from, if any.
### has Spreadsheet::XLSX::ContentTypes $.content-types
The content types of the workbook.
### has Associative[Spreadsheet::XLSX::Relationships] %!relationships
Map of loaded relationships for paths. (Those never used are not in here.)
class Attribute+{}.new(handles => $("create-worksheet", "worksheets", "shared-strings", "styles"))
----------------------------------------------------------------------------------------------------------
The workbook itself.
### has Spreadsheet::XLSX::DocProps::Core $!core-props
Document Core Properties
### multi method load
```raku
multi method load(
Str $file
) returns Spreadsheet::XLSX
```
Load an Excel workbook from the file path identified by the given string.
### multi method load
```raku
multi method load(
IO::Path $file
) returns Spreadsheet::XLSX
```
Load an Excel workbook in the specified file.
### multi method load
```raku
multi method load(
Blob $content
) returns Spreadsheet::XLSX
```
Load an Excel workbook from the specified blob. This is useful in the case it was sent over the network, and so never written to disk.
### method find-relationships
```raku
method find-relationships(
Str $path,
Bool :$create = Bool::False
) returns Spreadsheet::XLSX::Relationships
```
Get the relationships for a given path in the XLSX archive.
### method get-file-from-archive
```raku
method get-file-from-archive(
Str $path
) returns Blob
```
Obtain a file from the archive. Will fail if we are not backed by an archive, or if there is no such file.
### method set-file-in-archive
```raku
method set-file-in-archive(
Str $path,
Blob $content
) returns Nil
```
Set the content of a file in the archive, replacing any existing content.
### method to-blob
```raku
method to-blob() returns Blob
```
Serializes the current state of the spreadsheet into XLSX format and returns a Blob containing it.
### multi method save
```raku
multi method save(
Str $file
) returns Nil
```
Saves the Excel workbook to the file path identified by the given string.
### multi method save
```raku
multi method save(
IO::Path $file
) returns Nil
```
Save an Excel workbook to the specified file.
### method sync-to-archive
```raku
method sync-to-archive() returns Nil
```
Synchronizes all changes to the internal representation of the archive. This is performed automatically before saving, and there is no need to explicitly perform it.
CREDITS
=======
Thanks goes to [Agrammon](https://agrammon.ch/) for making the development of this module possible.
AUTHOR
======
Jonathan Worthington
COPYRIGHT AND LICENSE
=====================
Copyright 2020 - 2024 Jonathan Worthington
Copyright 2024 Raku Community
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.