NAME
Tie::Google::Sheets::Worksheet - Tie a hash to the cells of a single Google Sheets worksheet
VERSION
version 0.02
SYNOPSIS
use Tie::Google::Sheets;
tie my %doc, 'Tie::Google::Sheets', spreadsheet_id => $id, service_account => $key_file;
# $doc{Sheet1} is a plain hashref backed by this class
$doc{Sheet1}{A1} = 'hello';
print $doc{Sheet1}{A1};DESCRIPTION
This class implements a tied hash representing the cells of a single Google Sheets worksheet, keyed by A1 notation (A1, B12, and so on). You do not normally tie this class directly; instead access a worksheet through a Tie::Google::Sheets hash, which returns one of these for each worksheet tab.
Hash keys are case insensitive and are normalized to upper case. A key that does not look like an A1-style cell reference will throw an exception.
TIE METHODS
This class implements the standard perltie TIEHASH protocol; see perltie for the full semantics of each method.
TIEHASH
Constructor, called via tie. Expects client and title named arguments (a Tie::Google::Sheets::Client instance and a worksheet title, respectively).
FETCH
Returns the value of a cell, or undef if it is empty. Returns the cell's formula instead if "fetch_mode" is set to formula.
STORE
Sets the value of a cell.
DELETE
Clears a cell and returns its previous value (or formula; see "fetch_mode").
EXISTS
Returns true if a cell has a defined value.
CLEAR
Clears every cell in the worksheet.
FIRSTKEY, NEXTKEY
Together implement iteration (keys, values, each) over every non-empty cell in the worksheet's used range. If "fetch_mode" is set to formula, values (and each) yield formulas instead of values.
METHODS
These are ordinary (non-tie) methods available on the underlying object via tied %{ $doc{$title} }.
fetch_mode
tied(%{ $doc{$title} })->fetch_mode($mode);
my $mode = tied(%{ $doc{$title} })->fetch_mode;Gets or sets whether "FETCH" (and so reading a cell, iterating with values/each, or deleting a cell) returns a cell's computed value or its formula text. $mode must be value (the default) or formula. Does not affect "STORE": cells are always written the same way regardless of fetch_mode, and writing a string starting with = creates a formula just as it would when typed directly into Google Sheets.
CAVEATS
Every FETCH or STORE is a separate Google Sheets API call, unless the owning Tie::Google::Sheets document was constructed with batch_size, in which case STORE writes are queued and sent together; see "batch_size" in Tie::Google::Sheets. Iterating over the hash (with keys, each, and so on) fetches the whole used range of the worksheet in a single call. There is no local caching, so be mindful of Google's API quotas when accessing many cells.
SEE ALSO
AUTHOR
Graham Ollis <plicease@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Graham Ollis.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.