view release on metacpan or  search on metacpan

lib/Clearbuilt/ExcelErator.pm  view on Meta::CPAN

package Clearbuilt::ExcelErator;
use Modern::Perl;
our $VERSION = '2.0001'; # VERSION
our $AUTHORITY = 'cpan:CLEARBLT'; # AUTHORITY
# ABSTRACT: Write XLSX files in a Clearbuilt-standard way
use Moo;
extends 'Excel::Writer::XLSX';

#
# Attributes
#

has color => (
   is      => 'ro',
   lazy    => 1,
   builder => sub {
      my ($self) = @_;
      return {
         gray30              => $self->set_custom_color( 40, 77,  77,  77 ),
         gray50              => $self->set_custom_color( 40, 127, 127, 127 ),
         gray80              => $self->set_custom_color( 41, 205, 205, 205 ),
         blueaccent1darker50 => $self->set_custom_color( 42, 31,  78,  121 ),
      };
   },
);

has column_lengths => (
   is      => 'ro',
   builder => sub {
      return {};
   },
);

has filename => ( is => 'ro', );

has format_cache => (
   is      => 'rwp',
   lazy    => 1,
   builder => sub {
      my ($self) = @_;
      return {
         richnormal => $self->add_format(),
         richbold   => $self->add_format( bold   => 1 ),
         richitalic => $self->add_format( italic => 1 ),
         settings   => {
            color => {
                    'black' => { color => 'black' },
                    'blue' => { color => 'blue' },
                    'brown' => { color => 'brown' },
                    'cyan' => { color => 'cyan' },
                    'gray' => { color => 'gray' },
                    'green' => { color => 'green' },
                    'lime' => { color => 'lime' },
                    'magenta' => { color => 'magenta' },
                    'navy' => { color => 'navy' },
                    'orange' => { color => 'orange' },
                    'pink' => { color => 'pink' },
                    'purple' => { color => 'purple' },
                    'red' => { color => 'red' },
                    'silver' => { color => 'silver' },
                    'white' => { color => 'white' },
                    'yellow' => { color => 'yellow' },

lib/Clearbuilt/ExcelErator.pm  view on Meta::CPAN

   $workbook->write_the_book( [\%spreadsheet] );

=head1 DESCRIPTION

Clearbuilt::Excelerator is a wrapper around L<Excel::Writer::XLSX> that
simplifies and standardizes its usage. You create a hash defining your
spradsheet, and it does the rest for you!

More documentation of the hash will be added later, but the L</"SYNOPSIS"> above shows a 
simple and common usage, with frequently-used options. A more-extensive example can be found
in the package, in C<examples/create_test_excel_sheet>.

=head1 THE WORKBOOK ARRAY

The workbook is an array of hashes, each of which is a worksheet.

Note that the hash for this simple example is sent as an arrayref-to-the-hash.
The implication of that it is, of course, that you could create multiple
hashes, push them into an array in the order you want, and send a reference
to that array to C<write_the_book> and get a multi-sheet workbook.

=head1 THE WORKSHEET HASH

There are only three valid elements in this hash:

=over 4

=item *
C<title>: The title of the spreadsheet, which will show up in the tabs at the bottom.

=item *
C<col_widths>: A hashref of column widths. The key is the column number (beginning with 1), and the value is the desired width.

=item *
C<rows>: The array of rows for the sheet.

=back

=head1 THE WORKSHEET ROWS ARRAY

The C<rows> array is an array of arrayrefs; each of B<those> is an arrayref of cells.  The cell can be a 
scalar, in which case it is displayed with default formatting, or a hashref with a C<value> and optionally
a C<format>.  If you do not specify a C<format>, you get the default for that cell.

=head1 EXPORTED METHODS

=head2 new({ filename => <filespec>})>

Opens the desired file for writing.  At this time, C<filename> is the only parameter, which is passed
verbatim into L<Excel::Writer::XLSX>; there may be other options in the future.

=head2 write_the_book(\%spreadsheet);

Writes the file, and closes it.  Easy-peasy!

=head1 REQUIRES

=over 4

=item *
L<Modern::Perl>

=item *
L<Moo>

=item *
L<Excel::Writer::XLSX>

=back

=head1 ROADMAP

=over 4

=item *
Add other formatting functions

=item *
Default column formatting

=item *
More documentation

=item *
A robust unit test for C<write_the_book>

=back

=head1 AUTHOR

D Ruth Holloway <ruthh@clearbuilt.com>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Clearbuilt.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut