/ 
Tie-Google-Sheets-0.01
/ Tie::Google::Sheets

NAME

Tie::Google::Sheets - Tie perl variables to Google Sheets

VERSION

version 0.01

SYNOPSIS

use Tie::Google::Sheets;

tie my %doc, 'Tie::Google::Sheets',
    spreadsheet_id  => '1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms',
    service_account => '/path/to/service-account-key.json';

# read and write individual cells
my $name = $doc{Employees}{A1};
$doc{Employees}{A2} = 'Grace Hopper';

# create a new worksheet, optionally pre-populated
tied(%doc)->add_worksheet('Report', { A1 => 'Total', B1 => 42 });

# iterate over worksheet tabs
for my $title (keys %doc) {
    print "$title\n";
}

# remove a worksheet
delete $doc{Report};

DESCRIPTION

This module ties a Perl hash to a Google Sheets spreadsheet document. The outer hash is keyed by worksheet (tab) title; each value is itself a hash (implemented by Tie::Google::Sheets::Worksheet) keyed by cell reference in A1 notation (A1, B12, and so on), so that a spreadsheet can be read and written using ordinary Perl hash syntax:

$doc{'Sheet1'}{'A1'} = 'hello';
print $doc{'Sheet1'}{'A1'};

Authentication is via a Google service account. Remember to share the spreadsheet (or its containing folder) with the service account's client_email address, the same way you would share it with any other Google account, otherwise API calls will fail with a permission error.

CONSTRUCTOR

tie my %doc, 'Tie::Google::Sheets', %options;

%options may contain:

spreadsheet_id

The id of the spreadsheet, taken from its URL (https://docs.google.com/spreadsheets/d/<id>/edit). Required unless "spreadsheet_url" is given instead.

spreadsheet_url

The full URL of the spreadsheet, from which the spreadsheet id will be extracted. Ignored if "spreadsheet_id" is also given.

service_account

Either a hash reference containing the decoded contents of a Google service account JSON key file, or a path to the key file itself. Required unless "access_token" is given instead.

access_token

An OAuth2 bearer token (or a code reference which returns one) to use instead of authenticating with a service account. Useful when the caller already has its own way of obtaining and refreshing tokens (or, in tests, for supplying a fake token).

ua

A user agent object (for example an HTTP::Tiny or LWP::UserAgent instance) to be wrapped in an HTTP::AnyUA. Defaults to a plain HTTP::Tiny instance.

any_ua

An already constructed HTTP::AnyUA compatible object (that is, anything providing a request($method, $url, \%options) method with the same contract as HTTP::Tiny). Used as-is instead of wrapping "ua". Mutually exclusive with "ua".

TIE METHODS

This class implements the standard perltie TIEHASH protocol; see perltie for the full semantics of each method.

TIEHASH

Constructor, called via tie; see "CONSTRUCTOR" above.

FETCH

Returns the worksheet named by the given key, as a hashref implemented by Tie::Google::Sheets::Worksheet. The worksheet does not need to already exist on the server; accessing cells on one that doesn't will fail.

STORE

Creates a new worksheet. The key is the new worksheet's title; the value must be undef or a hashref of cell reference / value pairs to populate it with. Croaks if a worksheet with that title already exists.

DELETE

Deletes a worksheet.

EXISTS

Returns true if a worksheet with the given title exists.

CLEAR

Always croaks: a spreadsheet must keep at least one worksheet, so the tied hash cannot be emptied wholesale.

FIRSTKEY, NEXTKEY

Together implement iteration (keys, values, each) over the spreadsheet's worksheet titles.

METHODS

These are ordinary (non-tie) methods available on the underlying object via tied %doc.

add_worksheet

tied(%doc)->add_worksheet($title);
tied(%doc)->add_worksheet($title, \%cells);

Creates a new worksheet named $title. If \%cells is given, its key/value pairs are written into the new worksheet as cell reference / value pairs. Returns the new worksheet hashref, the same as $doc{$title}.

This is equivalent to $doc{$title} = \%cells.

delete_worksheet

tied(%doc)->delete_worksheet($title);

Deletes the worksheet named $title. Equivalent to delete $doc{$title}.

worksheet_titles

my @titles = tied(%doc)->worksheet_titles;

Returns the titles of all worksheets in the spreadsheet, in the order Google Sheets returns them. Equivalent to keys %doc.

CAVEATS

  • Every cell access is a separate Google Sheets API call; there is no local caching or batching. Be mindful of Google's API quotas if you access many cells.

  • A spreadsheet must always have at least one worksheet, so %doc cannot be emptied with %doc = (); delete worksheets individually instead.

  • Only cell values are read and written; formatting, formulas results vs formula text, and other cell metadata are not exposed.

SEE ALSO

Tie::Google::Sheets::Worksheet

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.