echoing tmp file, added vignette, and extended README

NEWS.md

@@ -3,7 +3,8 @@
 * possible to set token via environment variable (#68)
 * paginating results (#70)
 * adding ratelimit checking (#43)
-* added pkgdown site(#79)
+* added pkgdown site (#79)
+* added streaming (#84)
 
 # rtoot 0.1.0
 

R/stream_statuses.R

@@ -10,8 +10,8 @@
 #' @inheritParams get_instance
 #' @details
 #' \describe{
-#'   \item{stream_timeline_public}{stream all statuses}
-#'   \item{stream_timeline_hashtag}{stream all statuses containing a specific hashtag }
+#'   \item{stream_timeline_public}{stream all public statuses on any instance}
+#'   \item{stream_timeline_hashtag}{stream all statuses containing a specific hashtag}
 #'   \item{stream_timeline_list}{stream the statuses of a list}
 #' }
 #' @export
@@ -28,6 +28,8 @@
 #' # stream hashtag timeline of mastodon.social  for 30 seconds
 #' stream_timeline_hashtag("rstats", timeout = 30, local = TRUE,
 #'    instance = "fosstodon.org", file_name = "rstats_foss.json")
+#' # json files can be parsed with parse_stream()
+#' parse_stream("rstats_foss.json")
 #' }
 stream_timeline_public <- function(
     timeout = 30,
@@ -131,6 +133,7 @@ stream_toots <- function(timeout,file_name = NULL, append, token, path, params,
 
   if(is.null(file_name)){
     file_name <- tempfile(pattern = "stream_toots", fileext = ".json")
+    message("Writting to ",file_name)
   }
 
   url <- httr::modify_url(url,path = path,query = params)

README.Rmd

@@ -43,6 +43,8 @@ You can install the development version of rtoot from GitHub:
 devtools::install_github("schochastics/rtoot")
 ```
 
+*(The current dev version has many more features than the current version on CRAN)*
+
 ## Authenticate
 
 First you should set up your own credentials (see also `vignette("auth")`)
@@ -129,6 +131,23 @@ post_toot(status = "my first rtoot #rstats", media="path/to/media",
 
 You can mark the toot as sensitive by setting `sensitive = TRUE` and add a spoiler text with `spoiler_text`.
 
+## Streaming 
+
+`rtoot` allows to stream statuses from three different streams.
+To get any public status on any instance use `stream_timeline_public()`
+```{r, eval = FALSE}
+stream_timeline_public(timeout = 30,file_name = "public.json")
+```
+the timeout parameter is the time in seconds data should be streamed (set to `Inf` for indefinite streaming). If just the local timeline is needed, use `local=TRUE` and set an instance (or use your own provided by the token).
+
+`stream_timeline_hashtag()` streams all statuses containing a specific hashtag
+
+```{r, eval = FALSE}
+stream_timeline_hashtag("rstats", timeout = 30, file_name = "rstats_public.json")
+```
+
+The statuses are directly written to file as json. The function `parse_stream()` can be used
+to read in and convert a json to a data frame.
 
 ## Pagination
 

README.md

@@ -33,6 +33,9 @@ You can install the development version of rtoot from GitHub:
 devtools::install_github("schochastics/rtoot")
 ```
 
+*(The current dev version has many more features than the current
+version on CRAN)*
+
 ## Authenticate
 
 First you should set up your own credentials (see also
@@ -140,6 +143,31 @@ post_toot(status = "my first rtoot #rstats", media="path/to/media",
 You can mark the toot as sensitive by setting `sensitive = TRUE` and add
 a spoiler text with `spoiler_text`.
 
+## Streaming
+
+`rtoot` allows to stream statuses from three different streams. To get
+any public status on any instance use `stream_timeline_public()`
+
+``` r
+stream_timeline_public(timeout = 30,file_name = "public.json")
+```
+
+the timeout parameter is the time in seconds data should be streamed
+(set to `Inf` for indefinite streaming). If just the local timeline is
+needed, use `local=TRUE` and set an instance (or use your own provided
+by the token).
+
+`stream_timeline_hashtag()` streams all statuses containing a specific
+hashtag
+
+``` r
+stream_timeline_hashtag("rstats", timeout = 30, file_name = "rstats_public.json")
+```
+
+The statuses are directly written to file as json. The function
+`parse_stream()` can be used to read in and convert a json to a data
+frame.
+
 ## Pagination
 
 All relevant functions in the package support pagination of results if

vignettes/stream.Rmd

@@ -0,0 +1,47 @@
+---
+title: "Live streaming toots"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Live streaming toots}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r setup, eval=FALSE}
+library("rtoot")
+```
+
+The package allows to access three different streams of Mastodon data. 
+Public timelines via `stream_timeline_public()`, timelines from a given hashtag via `stream_timeline_hashtag()` and timelines from lists via `stream_timeline_list()`.
+
+## Specifying parameters
+
+By default, all functions stream statuses for 30 seconds. This can be adjusted via the parameter `timeout`. If set to `Inf`, data is streamed indefinitely. The parameter `file_name` is used to specify to which file the data should be written. If non is provided, a temporary file is created. However, we recommend to always set this parameter explicitely. 
+
+For `stream_timeline_public()` and `stream_timeline_hashtag()`, you can also decide if you want to
+stream globally, or from a specific instance. If you want to stream from a specific instance, set `local=TRUE` and set `instance` to the desired instance. If instance is NULL, then the function uses the instance you obtained a token from (see vignette on  [authentication](auth.html)).
+
+## Streaming and parsing
+
+Once parameters are specified, you can start the desired stream. 
+Streaming will occupy your current instance of R until the specified time has elapsed or any error occurs. Streaming itself shouldn't be very memory intensive so you can start a new R instance in parallel.
+
+```{r eval=FALSE}
+#stream a minute of all statuses
+stream_timeline_public(timeout = 60, file_name = "public.json")
+
+#stream a minute of all statuses using the rstats hashtag
+stream_timeline_public(hashtag = "rstats", timeout = 60, file_name = "public.json")
+```
+
+If `verbose=TRUE`, the functions will indicate when streaming is supposed to stop and the number of statuses that have been written to file.
+
+Note that in contrast to `rtweet`, the streaming functions never directly return any data. 
+This can be done afterwards using `parse_stream()` which reads in the json and converts it to a data frame. Note that this process can take a while depending on the number of statuses in the file.