---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "",
  prompt = TRUE,
  fig.path = "man/figures/README-",
  out.width = "100%"
)
if (dir.exists(".tmp")) unlink(".tmp", recursive = TRUE)
dir.create(".tmp/rstats", recursive = TRUE, showWarnings = FALSE)
knitr::opts_knit$set(root.dir = ".tmp/rstats")
```

[rtweet]: https://rtweet.info

# gathertweet

The goal of gathertweet is to provide a simple command line utility that wraps key functions from [rtweet].

The magic of **gathertweet** is that it grants you the power to **quickly set up twitter monitoring and tweet gathering** while saving you from the pain of **writing a bunch of boilerplate code to save new tweets without losing previously collected tweets, join multiple searches, update tweet stats, simplify stored tweets, and more**.

## Installation

This is a work in progress and may not work well for you yet.
But you are welcome to install **gathertweet** and try it out.

```r
# install.packages("remotes")
remotes::install_github("gadenbuie/gathertweet")
```

Once you've installed the package, you need to run

```r
gathertweet::install_gathertweet()
```

which adds `gathertweet` to `/usr/local/bin` as a symlink (you can adjust where this link is created in `install_gathertweet()`).
If you need admin rights to install, try `sudo Rscript -e "gathertweet::install_gathertweet()` from the command line.

## Example

Create a directory to store tweets

```bash
mkdir rstats
cd rstats
```

```{r include=FALSE}
knitr::opts_knit$set(root.dir = ".tmp/rstats")
```

Get 100 #rstats tweets

```{bash}
gathertweet search --n 100 --quiet "#rstats"
```

Get more tweets, automatically starting from end of the last search

```{r include=FALSE}
Sys.sleep(60)
```

```{bash}
gathertweet search --n 100 --quiet "#rstats"
```

Update the stored data about those #rstats tweets

```{bash}
gathertweet update
```

```{bash}
ls -lh
```

Gather user timelines

```{bash}
gathertweet timeline hadleywickham jennybryan dataandme
```

### Schedule tweet gathering using cron

The primary use case of gathertweet is to make it easy to set up [cron] to periodically gather tweets.
Here's a simple example to download all tweets matching the search term `rstats OR tidyverse` every night at midnight.
The tweets are stored, by default, in `tweets.rds` in `~/rstats-tweets`.

```bash
crontab -e

# m h dom mon dow   command
0 0 * * * (cd ~/rstats-tweets && ~/bin/gathertweet search --polite 'rstats OR tidyverse' >>gathertweet.log)
```

## Documentation

```bash
> gathertweet --help
```

```{bash gathertweet_help, echo=FALSE}
../../inst/gathertweet.R --help
```