.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Spreadsheet::Wright 3pm"
.TH Spreadsheet::Wright 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Spreadsheet::Wright \- simple spreadsheet worker
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # EXCEL spreadsheet
\&
\& use Spreadsheet::Wright;
\&
\& my $s = Spreadsheet::Wright\->new(
\& file => \*(Aqspreadsheet.xls\*(Aq,
\& format => \*(Aqxls\*(Aq,
\& sheet => \*(AqProducts\*(Aq,
\& styles => {
\& money => \*(Aq($#,##0_);($#,##0)\*(Aq,
\& },
\& );
\&
\& $s\->addrow(\*(Aqfoo\*(Aq,{
\& content => \*(Aqbar\*(Aq,
\& type => \*(Aqnumber\*(Aq,
\& style => \*(Aqmoney\*(Aq,
\& font_weight => \*(Aqbold\*(Aq,
\& font_color => 42,
\& font_face => \*(AqTimes New Roman\*(Aq,
\& font_size => 20,
\& align => \*(Aqcenter\*(Aq,
\& valign => \*(Aqvcenter\*(Aq,
\& font_decoration => \*(Aqstrikeout\*(Aq,
\& font_style => \*(Aqitalic\*(Aq,
\& });
\& $s\->addrow(\*(Aqfoo2\*(Aq,\*(Aqbar2\*(Aq);
\& $s\->freeze(1, 0);
\&
\& # CSV file
\&
\& use Spreadsheet::Wright;
\&
\& my $s = Spreadsheet::Wright\->new(
\& file => \*(Aqfile.csv\*(Aq,
\& encoding => \*(Aqiso8859\*(Aq,
\& );
\& die $s\->error if $s\->error;
\& $s\->addrow(\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Spreadsheet::Wright\*(C'\fR is a fork of Spreadsheet::Write and
may be used as a drop-in replacement.
.PP
\&\f(CW\*(C`Spreadsheet::Wright\*(C'\fR writes files in \s-1CSV,\s0 Microsoft Excel,
\&\s-1HTML\s0 and OpenDocument formats. It is especially suitable
for building various dumps and reports where rows are built
in sequence, one after another.
.PP
It is not especially suitable for modifying existing files.
.PP
The name is a not just pun on \*(L"write\*(R" \- the word \*(L"wright\*(R" means
worker or crafter, and \f(CW\*(C`Spreadsheet::Wright\*(C'\fR does a lot of the
work of spreadsheet output for you!
.SS "Constructor"
.IX Subsection "Constructor"
.ie n .IP """Spreadsheet::Wright\->new(%args)""" 4
.el .IP "\f(CWSpreadsheet::Wright\->new(%args)\fR" 4
.IX Item "Spreadsheet::Wright->new(%args)"
.Vb 6
\& $spreadsheet = Spreadsheet::Wright\->new(
\& file => \*(Aqtable.xls\*(Aq,
\& styles => {
\& mynumber => \*(Aq#,##0.00\*(Aq,
\& },
\& );
.Ve
.Sp
Creates a new spreadsheet object. It takes a list of options. The
following are valid:
.RS 4
.IP "\(bu" 4
\&\fBfile\fR \- filename of the new spreadsheet (mandatory)
.IP "\(bu" 4
\&\fBencoding\fR \- encoding of output file (optional, csv format only)
.IP "\(bu" 4
\&\fBformat\fR \- format of spreadsheet \- 'csv', 'xls', 'xlsx', 'html', 'xhtml', 'xml', 'ods', 'json', or 'auto' (default).
.IP "\(bu" 4
\&\fBsheet\fR \- first sheet name (optional, not supported by some formats)
.IP "\(bu" 4
\&\fBstyles\fR \- defines cell formatting shortcuts (optional)
.IP "\(bu" 4
\&\fBfailsafe\fR \- boolean \- if true, falls back to \s-1CSV\s0 in emergencies
.RE
.RS 4
.Sp
If file format is 'auto' (or omitted), the format is guessed from the
filename extension, defaulting to 'csv'.
.RE
.SS "Methods"
.IX Subsection "Methods"
.ie n .IP """addrow($cell_1, $cell_2, ...)""" 4
.el .IP "\f(CWaddrow($cell_1, $cell_2, ...)\fR" 4
.IX Item "addrow($cell_1, $cell_2, ...)"
Adds a row into the spreadsheet. Takes arbitrary number of
arguments. Arguments represent cell values and may be strings or hash
references. If an argument is a hash reference, it takes the following
structure:
.Sp
.Vb 10
\& content value to put into cell
\& style formatting style, as defined in new()
\& type type of the content (defaults to \*(Aqauto\*(Aq)
\& format number format (see Spreadsheet::WriteExcel for details)
\& font_weight weight of font. Only valid value is \*(Aqbold\*(Aq
\& font_style style of font. Only valid value is \*(Aqitalic\*(Aq
\& font_decoration \*(Aqunderline\*(Aq or \*(Aqstrikeout\*(Aq (or both, space separated)
\& font_face font of column; default is \*(AqArial\*(Aq
\& font_color color of font (see Spreadsheet::WriteExcel for color values)
\& font_size size of font
\& align alignment
\& valign vertical alignment
\& width column width, excel units (only makes sense once per column)
\& header boolean; is this cell a header?
.Ve
.Sp
Styles can be used to assign default values for any of these formatting
parameters thus allowing easy global changes. Other parameters specified
override style definitions.
.Sp
Example:
.Sp
.Vb 10
\& my $sp = Spreadsheet::Wright\->new(
\& file => \*(Aqemployees.xls\*(Aq,
\& styles => {
\& important => { font_weight => \*(Aqbold\*(Aq },
\& },
\& );
\& $sp\->addrow(
\& { content => \*(AqFirst Name\*(Aq, font_weight => \*(Aqbold\*(Aq },
\& { content => \*(AqLast Name\*(Aq, font_weight => \*(Aqbold\*(Aq },
\& { content => \*(AqAge\*(Aq, style => \*(Aqimportant\*(Aq },
\& );
\& $sp\->addrow("John", "Doe", 34);
\& $sp\->addrow("Susan", "Smith", 28);
.Ve
.Sp
Note that in this example all header cells will have identical
formatting even though some use direct formats and one uses
style.
.Sp
If you want to store text that looks like a number you might want to use
{ type => 'string', format => '@' } arguments. By default the type detection
is automatic, as done by for instance Spreadsheet::WriteExcel \fBwrite()\fR
method.
.Sp
It is also possible to supply an array reference in the 'content'
parameter of the extended format. It means to use the same formatting
for as many cells as there are elements in this array. Useful for
creating header rows. For instance, the above example can be rewritten
as:
.Sp
.Vb 4
\& $sp\->addrow({
\& style => \*(Aqimportant\*(Aq,
\& content => [\*(AqFirst Name\*(Aq, \*(AqLast Name\*(Aq, \*(AqAge\*(Aq],
\& });
.Ve
.Sp
Not all styling options are supported in all formats.
.ie n .IP """addrows(\e@row_1, \e@row_2, ...)""" 4
.el .IP "\f(CWaddrows(\e@row_1, \e@row_2, ...)\fR" 4
.IX Item "addrows(@row_1, @row_2, ...)"
Shortcut for adding multiple rows.
.Sp
Each argument is an arrayref representing a row.
.Sp
Any argument that is not a reference (i.e. a scalar) is taken to be the
title of a new worksheet.
.ie n .IP """addsheet($name)""" 4
.el .IP "\f(CWaddsheet($name)\fR" 4
.IX Item "addsheet($name)"
Adds a new sheet into the document and makes it active. Subsequent
\&\fBaddrow()\fR calls will add rows to that new sheet.
.Sp
For \s-1CSV\s0 format this call is \s-1NOT\s0 ignored, but produces a fatal error
currently.
.ie n .IP """freeze($row, $col, $top_row, $left_col)""" 4
.el .IP "\f(CWfreeze($row, $col, $top_row, $left_col)\fR" 4
.IX Item "freeze($row, $col, $top_row, $left_col)"
Sets a freeze-pane at the given position, equivalent to Spreadsheet::WriteExcel\->\fBfreeze_panes()\fR.
Only implemented for Excel spreadsheets so far.
.ie n .IP """close""" 4
.el .IP "\f(CWclose\fR" 4
.IX Item "close"
Saves the spreadsheet to disk (some of the modules save incrementally anyway) and
closes the file. Calling this explicitly is usually un-necessary, as the Perl garbage collector
will do the job eventually anyway. Once a spreadsheet is closed, calls to \fBaddrow()\fR will
fail.
.ie n .IP """error""" 4
.el .IP "\f(CWerror\fR" 4
.IX Item "error"
Returns the latest recoverable error.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to .
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Spreadsheet::Write.
.SH "AUTHORS"
.IX Header "AUTHORS"
Toby Inkster .
.PP
Excel and \s-1CSV\s0 output based almost entirely on work by
Nick Eremeev .
.PP
\&\s-1XLSX\s0 output based on work by Andrew Maltsev (\s-1AMALTSEV\s0).
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright 2007 Nick Eremeev.
.PP
Copyright 2010\-2011 Toby Inkster.
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0