googlesheets (version 0.3.0)

gs_ls: List sheets a la Google Sheets home screen

Description

Lists spreadsheets that the user would see in the Google Sheets home screen: https://docs.google.com/spreadsheets/. This function returns the information available from the spreadsheets feed of the Google Sheets API. Since this is non-public user data, use of gs_ls will require authorization

Usage

gs_ls(regex = NULL, ..., verbose = TRUE)

Arguments

regex

character; one or more regular expressions; if non-NULL only sheets whose titles match will be listed; multiple regular expressions are concatenated with the vertical bar

...

optional arguments to be passed to grep when matching regex to sheet titles

verbose

logical; do you want informative messages?

Value

a googlesheet_ls object, which is a tbl_df with one row per sheet (we use a custom class only to control how this object is printed)

Details

This listing gives a partial view of the sheets available for access (why just partial? see below). For these sheets, we retrieve sheet title, sheet key, author, user's permission, date-time of last update, version (old vs new sheet?), various links, and an alternate key (only relevant to old sheets).

The resulting table provides a map between readily available information, such as sheet title, and more obscure information you might use in scripts, such as the sheet key. This sort of "table lookup" is exploited in the functions gs_title, gs_key, gs_url, and gs_ws_feed, which register a sheet based on various forms of user input.

Which sheets show up in this table? Certainly those owned by the user. But also a subset of the sheets owned by others but visible to the user. We have yet to find explicit Google documentation on this matter. Anecdotally, sheets owned by a third party but for which the user has read access seem to appear in this listing if the user has visited them in the browser. This is an important point for usability because a sheet can be summoned by title instead of key only if it appears in this listing. For shared sheets that may not appear in this listing, a more robust workflow is to specify the sheet via its browser URL or unique sheet key.

Examples

# NOT RUN {
gs_ls()

yo_names <- paste0(c("yo", "YO"), c("", 1:3))
yo_ret <- yo_names %>% lapply(gs_new)
gs_ls("yo")
gs_ls("yo", ignore.case = TRUE)
gs_ls("yo[23]", ignore.case = TRUE)
gs_grepdel("yo", ignore.case = TRUE)
gs_ls("yo", ignore.case = TRUE)

c("foo", "yo") %>% lapply(gs_new)
gs_ls("yo")
gs_ls("yo|foo")
gs_ls(c("foo", "yo"))
gs_vecdel(c("foo", "yo"))

# }
# NOT RUN {
# }