NOTE: The vignette is still under development. Stuff here is not written in stone. The README on GitHub has gotten alot more love recently, so you might want to read that instead or in addition to this (2015-03-23).
+NOTE: The vignette is still under development. Stuff here is not written in stone. The README on GitHub has gotten alot more love recently, so you should read that instead or in addition to this (2015-05-08). Seriously, we’ve only been making sure this thing compiles, but not updating the text.
library(googlesheets)
suppressMessages(library(dplyr))This vignette shows the basic functionality of googlesheets.
In order to access spreadsheets that are not “published to the web” and in order to access any spreadsheets by title (vs key), you need to authenticate with Google. Many googlesheets functions require authentication and, if necessary, will simply trigger the interactive process we describe here.
The authorize() function uses OAuth2 for authentication, but don’t worry if you don’t know what that means. The first time, you will be kicked into a web browser. You’ll be asked to login to your Google account and give googlesheets permission to access Sheets and Google Drive. Successful login will lead to the creation of an access token, which will automatically be stored in a file named .httr-oath in current working directory. These tokens are perishable and, for the most part, they will be refreshed automatically when they go stale. Under the hood, we use the httr package to manage this.
If you want to switch to a different Google account, run authorize(new_user = TRUE), as this will delete the previously stored token and get a new one for the new account.
The gs_auth() function uses OAuth2 for authentication, but don’t worry if you don’t know what that means. The first time, you will be kicked into a web browser. You’ll be asked to login to your Google account and give googlesheets permission to access Sheets and Google Drive. Successful login will lead to the creation of an access token, which will automatically be stored in a file named .httr-oath in current working directory. These tokens are perishable and, for the most part, they will be refreshed automatically when they go stale. Under the hood, we use the httr package to manage this.
If you want to switch to a different Google account, run gs_auth(new_user = TRUE), as this will delete the previously stored token and get a new one for the new account.
In a hidden chunk, we are logging into Google as a user associated with this package, so we can work with some Google spreadsheets later in this vignette.
If you don’t have any Google Sheets yet, or if you just want to follow along verbatim with this vignette, this bit of code will copy a sheet from the googlesheets Google user into your Drive. The sheet holds some of the Gapminder data.
gap_key <- "1hS762lIJd2TRUTVOqoOP7g-h4MDQs6b2vhkTzohg8bE"
-copy_ss(key = gap_key, to = "Gapminder")As an authenticated user, you can get a (partial) listing of accessible sheets. If you have not yet authenticated, you will be prompted to do so. If it’s been a while since you authenticated, you’ll see a message about refreshing a stale OAuth token.
-my_sheets <- gs_ls()Explore the my_sheets object. Here’s a look at the top of ours, where we’ve truncated the variables sheet_title and sheet_key and suppressed the variable ws_id for readability.
## Source: local data frame [6 x 9]
+my_sheets <- gs_ls()
+my_sheets
+## Source: local data frame [33 x 10]
##
-## sheet_title owner perm version last_updated sheet_key
-## 1 Ari's Anch anahmani r old 2015-05-02 00:56:31 tQKSYVR...
-## 2 gas_mileag woo.kara r new 2015-05-01 23:37:42 1WH65aJ...
-## 3 #rhizo15 # m.hawksey r new 2015-05-01 18:54:05 1oBQNns...
-## 4 EasyTweetS m.hawksey r new 2015-05-02 00:38:33 14mAbIi...
-## 5 test-gs-ol gspreadr rw old 2015-04-30 23:33:48 t0lmRSk...
-## 6 test-gs-mi rpackagetest r new 2015-04-25 18:25:43 1BMtx1V...
-## Variables not shown: alternate (chr), self (chr), alt_key (chr)
-This provides a nice overview of the spreadsheets you can access and is useful for looking up the key of a spreadsheet (see below).
+## sheet_title author perm version updated
+## 1 foo gspreadr rw new 2015-05-08 22:14:30
+## 2 Ari's Anchor Text Scrap… anahmani r old 2015-05-08 18:24:16
+## 3 #rhizo15 #tw m.hawksey r new 2015-05-08 20:00:01
+## 4 EasyTweetSheet - Shared m.hawksey r new 2015-05-08 21:58:48
+## 5 gas_mileage woo.kara r new 2015-05-04 01:14:13
+## 6 #TalkPay Tweets iskaldur r new 2015-05-02 06:25:14
+## 7 test-gs-old-sheet2 gspreadr rw old 2015-04-30 23:33:48
+## 8 test-gs-mini-gapminder rpackagetest r new 2015-04-25 18:25:43
+## 9 test-gs-iris-private gspreadr rw new 2015-04-25 15:18:05
+## 10 1F0iNuYW4v_oG69s7c5Nzdo… gspreadr rw new 2015-04-25 02:32:24
+## .. ... ... ... ... ...
+## Variables not shown: sheet_key (chr), ws_feed (chr), alternate (chr), self
+## (chr), alt_key (chr)This provides a nice overview of the spreadsheets you can access.
Before you can access a spreadsheet, you must first register it. This returns an object that is of little interest to the user, but is needed by various googlesheets functions in order to retrieve or edit spreadsheet data.
Let’s register the Gapminder spreadsheet we spied in the list above and that you may have copied into your Google Drive. We can use str() to get an overview of the spreadsheet.
gap <- register_ss("Gapminder")## Sheet identified!
-## sheet_title: Gapminder
-## sheet_key: 1HT5B8SgkKqHdqHJmn5xiuaC04Ngb7dG9Tv94004vezABefore you can access a spreadsheet, you must first register it. This returns a googlesheets object that is needed by downstream functions in order to retrieve or edit spreadsheet data.
Let’s register the Gapminder spreadsheet we spied in the list above and that you may have copied into your Google Drive. We have a nice print method for these objects, so print to screen for some basic info.
gap <- gs_title("Gapminder")## Sheet successfully identifed: "Gapminder"gap## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:07 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -142,18 +148,19 @@ Register a spreadsheet
By URL: copy and paste the URL in your browser while visiting the spreadsheet.
By the “worksheets feed”: under the hood, this is how googlesheets actually gets spreadsheet information from the API. Unlikely to be relevant to a regular user.
-Here’s an example of using the sheet title to retrieve the key, then registering the sheet by key. While registration by title is handy for interactive use, registration by key is preferred for scripts.
+Here’s an example of registering a sheet via key. While registration by title is handy for interactive use, registration by key might be preferred when programming.
(gap_key <- my_sheets$sheet_key[my_sheets$sheet_title == "Gapminder"])
## [1] "1HT5B8SgkKqHdqHJmn5xiuaC04Ngb7dG9Tv94004vezA"
-ss2 <- register_ss(gap_key)
-## Sheet identified!
-## sheet_title: Gapminder
-## sheet_key: 1HT5B8SgkKqHdqHJmn5xiuaC04Ngb7dG9Tv94004vezA
+ss2 <- gs_key(gap_key)
+## Authentication will be used.
+## Sheet successfully identifed: "Gapminder"
ss2
## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:08 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -168,17 +175,20 @@ Register a spreadsheet
Consuming data from a worksheet
Spreadsheet data is parcelled out into worksheets. To consume data from a Google spreadsheet, you’ll need to specify a registered spreadsheet and, within that, a worksheet. Specify the worksheet either by name or positive integer index.
-There are two ways to consume data.
+There are three ways to consume data.
+- The csv way … bring this over from README
- The “list feed”: only suitable for well-behaved tabular data. Think: data that looks like an R data.frame
- The “cell feed”: for everything else. Of course, you can get well-behaved tabular data with the cell feed but it’s up to 3x slower and will require post-processing (reshaping and coercion).
Example of getting nice tabular data from the “list feed”:
gap
## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:07 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -282,7 +292,7 @@ Consuming data from a worksheet
Visibility stuff
Rework this for the new era.
-Under the hood, gspread functions must access a spreadsheet with either public or private visiblity. Visibility determines whether or not authorization will be used for a request.
+Under the hood, googlesheets functions must access a spreadsheet with either public or private visiblity. Visibility determines whether or not authorization will be used for a request.
No authorization is used when visibility is set to “public”, which will only work for spreadsheets that have been “Published to the Web”. Note that requests with visibility set to “public” will not work for spreadsheets that are made “Public on the web” from the “Visibility options” portion of the sharing dialog of a Google Sheets file. In summary, “Published to the web” and “Public on the web” are different ways to share a spreadsheet.
Authorization is used when visibility is set to “private”.
@@ -301,98 +311,94 @@ Add, delete, rename spreadsheets and worksheets
needs updating; lots of this already in README
Add or delete spreadsheet
-To add or delete a spreadsheet in your Google Drive, use new_ss() or delete_ss() and simply pass in the title of the spreadsheet as a character string. The new spreadsheet by default will contain one worksheet titled “Sheet1”. Recall we demonstrate the use of copy_ss() at the start of this vignette.
+To add a spreadsheet to your Google Drive, use gs_new() and simply pass in the title of the spreadsheet as a character string. The new spreadsheet will contain one worksheet titled “Sheet1” by default. Recall we demonstrate the use of gs_copy() at the start of this vignette, which is another common way to get a new sheet.
+or delete or gs_delete()
# Create a new empty spreadsheet by title
-new_ss("hi I am new here")
-## Sheet "hi I am new here" created in Google Drive.
-## Identifying info is a googlesheet object; googlesheets will re-identify the sheet based on sheet key.
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1OCtwyOb3K83Pyhpak2cMsH7jZbyUTrdq3soQT6t7ZTA
+gs_new("hi I am new here")
+## Sheet "hi I am new here" created in Google Drive.
gs_ls() %>% filter(sheet_title == "hi I am new here")
## Source: local data frame [1 x 10]
##
-## sheet_title owner perm version last_updated
-## 1 hi I am new here gspreadr rw new 2015-05-02 01:38:11
+## sheet_title author perm version updated
+## 1 hi I am new here gspreadr rw new 2015-05-08 22:14:39
## Variables not shown: sheet_key (chr), ws_feed (chr), alternate (chr), self
## (chr), alt_key (chr)
+Delete a spreadsheet with gs_delete(). This function operates on a registered googlesheet, so enclose your sheet identifying information in a suitable function. Here we specify (and delete) the above sheet by title, then confirm it is no longer in our sheet listing.
# Move spreadsheet to trash
-delete_ss("hi I am new here")
-## Sheets found and slated for deletion:
-## hi I am new here
-## Success. All moved to trash in Google Drive.
+gs_delete(gs_title("hi I am new here"))
+## Sheet successfully identifed: "hi I am new here"
+## Success. "hi I am new here" moved to trash in Google Drive.
gs_ls() %>% filter(sheet_title == "hi I am new here")
## Source: local data frame [0 x 10]
##
-## Variables not shown: sheet_title (chr), owner (chr), perm (chr), version
-## (chr), last_updated (time), sheet_key (chr), ws_feed (chr), alternate
-## (chr), self (chr), alt_key (chr)
+## Variables not shown: sheet_title (chr), author (chr), perm (chr), version
+## (chr), updated (time), sheet_key (chr), ws_feed (chr), alternate (chr),
+## self (chr), alt_key (chr)
Add, delete, or rename a worksheet
-To add a worksheet to a spreadsheet, pass in the spreadsheet object, title of new worksheet and the number of rows and columns. To delete a worksheet from a spreadsheet, pass in the spreadsheet object and the title of the worksheet. Note that after adding or deleting a worksheet, the local spreadsheet object will not be automatically updated to include the new worksheet(s) information, you must register the spreadsheet again to update local knowledge about, e.g., the contituent worksheets. Notice that we store the sheet back to x after adding the worksheet. This is because adding a worksheet changes the information associate with a registered sheet and, within editing function like add_ws(), we re-register the sheet and return the current sheet info.
-new_ss("hi I am new here")
-## Sheet "hi I am new here" created in Google Drive.
-## Identifying info is a googlesheet object; googlesheets will re-identify the sheet based on sheet key.
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
-x <- register_ss("hi I am new here")
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+To add a worksheet to a spreadsheet, pass in the spreadsheet object, title of new worksheet and the number of rows and columns. To delete a worksheet from a spreadsheet, pass in the spreadsheet object and the title of the worksheet. Note that after adding or deleting a worksheet, the local googlesheet object will not be automatically updated to include the new worksheet(s) information, you must register the spreadsheet again to update local knowledge about, e.g., the contituent worksheets. Notice that we store the sheet back to x after adding the worksheet. This is because adding a worksheet changes the information associated with a registered sheet and, within editing functions like gs_ws_new(), we re-register the sheet and return the current sheet info.
+gs_new("hi I am new here")
+## Sheet "hi I am new here" created in Google Drive.
+x <- gs_title("hi I am new here")
+## Sheet successfully identifed: "hi I am new here"
x
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:18 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:15 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:49 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:46 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 1 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
-x <- add_ws(x, ws_title = "foo", nrow = 10, ncol = 10)
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
+x <- gs_ws_new(x, ws_title = "foo", nrow = 10, ncol = 10)
## Worksheet "foo" added to sheet "hi I am new here".
x
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:20 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:19 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:49 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:49 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 2 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
## foo: 10 x 10
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
-delete_ws(x, ws = "foo")
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
+gs_ws_delete(x, ws = "foo")
## Accessing worksheet titled "foo"
## Worksheet "foo" deleted from sheet "hi I am new here".
-x <- register_ss("hi I am new here")
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+x <- gs_title("hi I am new here")
+## Sheet successfully identifed: "hi I am new here"
x
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:23 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:20 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:51 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:50 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 1 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
To rename a worksheet, pass in the spreadsheet object, the worksheet’s current name and the new name you want it to be.
-rename_ws(x, "Sheet1", "First Sheet")
+gs_ws_rename(x, "Sheet1", "First Sheet")
## Accessing worksheet titled "Sheet1"
+## Authentication will be used.
+## Sheet successfully identifed: "hi I am new here"
## Worksheet "Sheet1" renamed to "First Sheet".
Tidy up by getting rid of the sheet we’ve playing with.
-delete_ss("hi I am new here")
-## Sheets found and slated for deletion:
-## hi I am new here
-## Success. All moved to trash in Google Drive.
+gs_delete(gs_title("hi I am new here"))
+## Sheet successfully identifed: "hi I am new here"
+## Success. "hi I am new here" moved to trash in Google Drive.
diff --git a/vignettes/basic-usage.md b/vignettes/basic-usage.md
index 4dfd507..b598a6b 100644
--- a/vignettes/basic-usage.md
+++ b/vignettes/basic-usage.md
@@ -2,7 +2,7 @@
Joanna Zhao, Jenny Bryan
`r Sys.Date()`
-__NOTE__: The vignette is still under development. Stuff here is not written in stone. The [README](https://github.com/jennybc/googlesheets) on GitHub has gotten alot more love recently, so you might want to read that instead or in addition to this (2015-03-23).
+__NOTE__: The vignette is still under development. Stuff here is not written in stone. The [README](https://github.com/jennybc/googlesheets) on GitHub has gotten __alot more love recently__, so you should read that instead or in addition to this (2015-05-08). Seriously, we've only been making sure this thing compiles, but not updating the text.
```r
@@ -16,9 +16,9 @@ This vignette shows the basic functionality of `googlesheets`.
In order to access spreadsheets that are not "published to the web" and in order to access __any__ spreadsheets by title (vs key), you need to authenticate with Google. Many `googlesheets` functions require authentication and, if necessary, will simply trigger the interactive process we describe here.
-The `authorize()` function uses OAuth2 for authentication, but don't worry if you don't know what that means. The first time, you will be kicked into a web browser. You'll be asked to login to your Google account and give `googlesheets` permission to access Sheets and Google Drive. Successful login will lead to the creation of an access token, which will automatically be stored in a file named `.httr-oath` in current working directory. These tokens are perishable and, for the most part, they will be refreshed automatically when they go stale. Under the hood, we use the `httr` package to manage this.
+The `gs_auth()` function uses OAuth2 for authentication, but don't worry if you don't know what that means. The first time, you will be kicked into a web browser. You'll be asked to login to your Google account and give `googlesheets` permission to access Sheets and Google Drive. Successful login will lead to the creation of an access token, which will automatically be stored in a file named `.httr-oath` in current working directory. These tokens are perishable and, for the most part, they will be refreshed automatically when they go stale. Under the hood, we use the `httr` package to manage this.
-If you want to switch to a different Google account, run `authorize(new_user = TRUE)`, as this will delete the previously stored token and get a new one for the new account.
+If you want to switch to a different Google account, run `gs_auth(new_user = TRUE)`, as this will delete the previously stored token and get a new one for the new account.
*In a hidden chunk, we are logging into Google as a user associated with this package, so we can work with some Google spreadsheets later in this vignette.*
@@ -34,7 +34,7 @@ If you don't have any Google Sheets yet, or if you just want to follow along ver
```r
gap_key <- "1hS762lIJd2TRUTVOqoOP7g-h4MDQs6b2vhkTzohg8bE"
-copy_ss(key = gap_key, to = "Gapminder")
+gs_copy(gs_key(gap_key), to = "Gapminder")
```
# List your spreadsheets
@@ -44,41 +44,43 @@ As an authenticated user, you can get a (partial) listing of accessible sheets.
```r
my_sheets <- gs_ls()
+my_sheets
```
-Explore the `my_sheets` object. Here's a look at the top of ours, where we've truncated the variables `sheet_title` and `sheet_key` and suppressed the variable `ws_id` for readability.
-
-
```
-## Source: local data frame [6 x 9]
+## Source: local data frame [33 x 10]
##
-## sheet_title owner perm version last_updated sheet_key
-## 1 Ari's Anch anahmani r old 2015-05-02 00:56:31 tQKSYVR...
-## 2 gas_mileag woo.kara r new 2015-05-01 23:37:42 1WH65aJ...
-## 3 #rhizo15 # m.hawksey r new 2015-05-01 18:54:05 1oBQNns...
-## 4 EasyTweetS m.hawksey r new 2015-05-02 00:38:33 14mAbIi...
-## 5 test-gs-ol gspreadr rw old 2015-04-30 23:33:48 t0lmRSk...
-## 6 test-gs-mi rpackagetest r new 2015-04-25 18:25:43 1BMtx1V...
-## Variables not shown: alternate (chr), self (chr), alt_key (chr)
+## sheet_title author perm version updated
+## 1 foo gspreadr rw new 2015-05-08 22:14:30
+## 2 Ari's Anchor Text Scrap… anahmani r old 2015-05-08 18:24:16
+## 3 #rhizo15 #tw m.hawksey r new 2015-05-08 20:00:01
+## 4 EasyTweetSheet - Shared m.hawksey r new 2015-05-08 21:58:48
+## 5 gas_mileage woo.kara r new 2015-05-04 01:14:13
+## 6 #TalkPay Tweets iskaldur r new 2015-05-02 06:25:14
+## 7 test-gs-old-sheet2 gspreadr rw old 2015-04-30 23:33:48
+## 8 test-gs-mini-gapminder rpackagetest r new 2015-04-25 18:25:43
+## 9 test-gs-iris-private gspreadr rw new 2015-04-25 15:18:05
+## 10 1F0iNuYW4v_oG69s7c5Nzdo… gspreadr rw new 2015-04-25 02:32:24
+## .. ... ... ... ... ...
+## Variables not shown: sheet_key (chr), ws_feed (chr), alternate (chr), self
+## (chr), alt_key (chr)
```
-This provides a nice overview of the spreadsheets you can access and is useful for looking up the __key__ of a spreadsheet (see below).
+This provides a nice overview of the spreadsheets you can access.
# Register a spreadsheet
-Before you can access a spreadsheet, you must first __register__ it. This returns an object that is of little interest to the user, but is needed by various `googlesheets` functions in order to retrieve or edit spreadsheet data.
+Before you can access a spreadsheet, you must first __register__ it. This returns a `googlesheets` object that is needed by downstream functions in order to retrieve or edit spreadsheet data.
-Let's register the Gapminder spreadsheet we spied in the list above and that you may have copied into your Google Drive. We can use `str()` to get an overview of the spreadsheet.
+Let's register the Gapminder spreadsheet we spied in the list above and that you may have copied into your Google Drive. We have a nice `print` method for these objects, so print to screen for some basic info.
```r
-gap <- register_ss("Gapminder")
+gap <- gs_title("Gapminder")
```
```
-## Sheet identified!
-## sheet_title: Gapminder
-## sheet_key: 1HT5B8SgkKqHdqHJmn5xiuaC04Ngb7dG9Tv94004vezA
+## Sheet successfully identifed: "Gapminder"
```
```r
@@ -87,9 +89,11 @@ gap
```
## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:07 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -108,7 +112,7 @@ Besides using the spreadsheet title, you can also specify a spreadsheet in three
* By URL: copy and paste the URL in your browser while visiting the spreadsheet.
* By the "worksheets feed": under the hood, this is how `googlesheets` actually gets spreadsheet information from the API. Unlikely to be relevant to a regular user.
-Here's an example of using the sheet title to retrieve the key, then registering the sheet by key. While registration by title is handy for interactive use, registration by key is preferred for scripts.
+Here's an example of registering a sheet via key. While registration by title is handy for interactive use, registration by key might be preferred when programming.
```r
@@ -120,13 +124,12 @@ Here's an example of using the sheet title to retrieve the key, then registering
```
```r
-ss2 <- register_ss(gap_key)
+ss2 <- gs_key(gap_key)
```
```
-## Sheet identified!
-## sheet_title: Gapminder
-## sheet_key: 1HT5B8SgkKqHdqHJmn5xiuaC04Ngb7dG9Tv94004vezA
+## Authentication will be used.
+## Sheet successfully identifed: "Gapminder"
```
```r
@@ -135,9 +138,11 @@ ss2
```
## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:08 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -154,8 +159,9 @@ ss2
Spreadsheet data is parcelled out into __worksheets__. To consume data from a Google spreadsheet, you'll need to specify a registered spreadsheet and, within that, a worksheet. Specify the worksheet either by name or positive integer index.
-There are two ways to consume data.
+There are three ways to consume data.
+ * *The csv way ... bring this over from README*
* The "list feed": only suitable for well-behaved tabular data. Think: data that looks like an R data.frame
* The "cell feed": for everything else. Of course, you can get well-behaved tabular data with the cell feed but it's up to 3x slower and will require post-processing (reshaping and coercion).
@@ -168,9 +174,11 @@ gap
```
## Spreadsheet title: Gapminder
-## Date of googlesheets::register_ss: 2015-05-02 01:38:07 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:37 GMT
## Date of last spreadsheet update: 2015-03-23 20:34:08 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 5 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
@@ -329,7 +337,7 @@ There are two basic modes of consuming data stored in a worksheet (quotes taken
*Rework this for the new era.*
-Under the hood, `gspread` functions must access a spreadsheet with either public or private __visiblity__. Visibility determines whether or not authorization will be used for a request.
+Under the hood, `googlesheets` functions must access a spreadsheet with either public or private __visiblity__. Visibility determines whether or not authorization will be used for a request.
No authorization is used when visibility is set to "public", which will only work for spreadsheets that have been "Published to the Web". Note that requests with visibility set to "public" __will not work__ for spreadsheets that are made "Public on the web" from the "Visibility options" portion of the sharing dialog of a Google Sheets file. In summary, "Published to the web" and "Public on the web" are __different__ ways to share a spreadsheet.
@@ -351,20 +359,19 @@ To access public spreadsheets, you will either need the key of the spreadsheet (
### Add or delete spreadsheet
-To add or delete a spreadsheet in your Google Drive, use `new_ss()` or `delete_ss()` and simply pass in the title of the spreadsheet as a character string. The new spreadsheet by default will contain one worksheet titled "Sheet1". Recall we demonstrate the use of `copy_ss()` at the start of this vignette.
+To add a spreadsheet to your Google Drive, use `gs_new()` and simply pass in the title of the spreadsheet as a character string. The new spreadsheet will contain one worksheet titled "Sheet1" by default. Recall we demonstrate the use of `gs_copy()` at the start of this vignette, which is another common way to get a new sheet.
+
+or delete
+or `gs_delete()`
```r
# Create a new empty spreadsheet by title
-new_ss("hi I am new here")
+gs_new("hi I am new here")
```
```
## Sheet "hi I am new here" created in Google Drive.
-## Identifying info is a googlesheet object; googlesheets will re-identify the sheet based on sheet key.
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1OCtwyOb3K83Pyhpak2cMsH7jZbyUTrdq3soQT6t7ZTA
```
```r
@@ -374,21 +381,23 @@ gs_ls() %>% filter(sheet_title == "hi I am new here")
```
## Source: local data frame [1 x 10]
##
-## sheet_title owner perm version last_updated
-## 1 hi I am new here gspreadr rw new 2015-05-02 01:38:11
+## sheet_title author perm version updated
+## 1 hi I am new here gspreadr rw new 2015-05-08 22:14:39
## Variables not shown: sheet_key (chr), ws_feed (chr), alternate (chr), self
## (chr), alt_key (chr)
```
+Delete a spreadsheet with `gs_delete()`. This function operates on a registered `googlesheet`, so enclose your sheet identifying information in a suitable function. Here we specify (and delete) the above sheet by title, then confirm it is no longer in our sheet listing.
+
+
```r
# Move spreadsheet to trash
-delete_ss("hi I am new here")
+gs_delete(gs_title("hi I am new here"))
```
```
-## Sheets found and slated for deletion:
-## hi I am new here
-## Success. All moved to trash in Google Drive.
+## Sheet successfully identifed: "hi I am new here"
+## Success. "hi I am new here" moved to trash in Google Drive.
```
```r
@@ -398,36 +407,30 @@ gs_ls() %>% filter(sheet_title == "hi I am new here")
```
## Source: local data frame [0 x 10]
##
-## Variables not shown: sheet_title (chr), owner (chr), perm (chr), version
-## (chr), last_updated (time), sheet_key (chr), ws_feed (chr), alternate
-## (chr), self (chr), alt_key (chr)
+## Variables not shown: sheet_title (chr), author (chr), perm (chr), version
+## (chr), updated (time), sheet_key (chr), ws_feed (chr), alternate (chr),
+## self (chr), alt_key (chr)
```
### Add, delete, or rename a worksheet
-To add a worksheet to a spreadsheet, pass in the spreadsheet object, title of new worksheet and the number of rows and columns. To delete a worksheet from a spreadsheet, pass in the spreadsheet object and the title of the worksheet. Note that after adding or deleting a worksheet, the local spreadsheet object will not be automatically updated to include the new worksheet(s) information, you must register the spreadsheet again to update local knowledge about, e.g., the contituent worksheets. Notice that we store the sheet back to `x` after adding the worksheet. This is because adding a worksheet changes the information associate with a registered sheet and, within editing function like `add_ws()`, we re-register the sheet and return the current sheet info.
+To add a worksheet to a spreadsheet, pass in the spreadsheet object, title of new worksheet and the number of rows and columns. To delete a worksheet from a spreadsheet, pass in the spreadsheet object and the title of the worksheet. Note that after adding or deleting a worksheet, the local `googlesheet` object will not be automatically updated to include the new worksheet(s) information, you must register the spreadsheet again to update local knowledge about, e.g., the contituent worksheets. Notice that we store the sheet back to `x` after adding the worksheet. This is because adding a worksheet changes the information associated with a registered sheet and, within editing functions like `gs_ws_new()`, we re-register the sheet and return the current sheet info.
```r
-new_ss("hi I am new here")
+gs_new("hi I am new here")
```
```
## Sheet "hi I am new here" created in Google Drive.
-## Identifying info is a googlesheet object; googlesheets will re-identify the sheet based on sheet key.
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
```
```r
-x <- register_ss("hi I am new here")
+x <- gs_title("hi I am new here")
```
```
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Sheet successfully identifed: "hi I am new here"
```
```r
@@ -436,19 +439,21 @@ x
```
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:18 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:15 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:49 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:46 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 1 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
```
```r
-x <- add_ws(x, ws_title = "foo", nrow = 10, ncol = 10)
+x <- gs_ws_new(x, ws_title = "foo", nrow = 10, ncol = 10)
```
```
@@ -461,20 +466,22 @@ x
```
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:20 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:19 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:49 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:49 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 2 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
## foo: 10 x 10
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
```
```r
-delete_ws(x, ws = "foo")
+gs_ws_delete(x, ws = "foo")
```
```
@@ -483,13 +490,11 @@ delete_ws(x, ws = "foo")
```
```r
-x <- register_ss("hi I am new here")
+x <- gs_title("hi I am new here")
```
```
-## Sheet identified!
-## sheet_title: hi I am new here
-## sheet_key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Sheet successfully identifed: "hi I am new here"
```
```r
@@ -498,26 +503,30 @@ x
```
## Spreadsheet title: hi I am new here
-## Date of googlesheets::register_ss: 2015-05-02 01:38:23 GMT
-## Date of last spreadsheet update: 2015-05-02 01:38:20 GMT
+## Date of googlesheets registration: 2015-05-08 22:14:51 GMT
+## Date of last spreadsheet update: 2015-05-08 22:14:50 GMT
## visibility: private
+## permissions: rw
+## version: new
##
## Contains 1 worksheets:
## (Title): (Nominal worksheet extent as rows x columns)
## Sheet1: 1000 x 26
##
-## Key: 1AxDsu8P4akRfK1ORe9cw8OebiZb5-uZKXRg7hj48T5w
+## Key: 1t5RJT_v6fmljtJXVd01Me9bL6vGHJ11q1-XrSo2KvWM
```
To rename a worksheet, pass in the spreadsheet object, the worksheet's current name and the new name you want it to be.
```r
-rename_ws(x, "Sheet1", "First Sheet")
+gs_ws_rename(x, "Sheet1", "First Sheet")
```
```
## Accessing worksheet titled "Sheet1"
+## Authentication will be used.
+## Sheet successfully identifed: "hi I am new here"
## Worksheet "Sheet1" renamed to "First Sheet".
```
@@ -525,13 +534,12 @@ Tidy up by getting rid of the sheet we've playing with.
```r
-delete_ss("hi I am new here")
+gs_delete(gs_title("hi I am new here"))
```
```
-## Sheets found and slated for deletion:
-## hi I am new here
-## Success. All moved to trash in Google Drive.
+## Sheet successfully identifed: "hi I am new here"
+## Success. "hi I am new here" moved to trash in Google Drive.
```
# Worksheet Operations