GitHub - vorpalvorpal/vigil: Cross-Platform File System Watching for R

Branches Tags

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
R		R
inst		inst
man		man
tests		tests
vignettes		vignettes
.Rbuildignore		.Rbuildignore
.gitignore		.gitignore
DESCRIPTION		DESCRIPTION
LICENSE		LICENSE
NAMESPACE		NAMESPACE
README		README
vigil.Rproj		vigil.Rproj

Repository files navigation

# vigil: Cross-Platform File System Watching for R

The vigil package provides a unified interface for file system watching across Windows and Unix-like systems. It uses SQLite for robust event tracking and supports pattern matching, custom callbacks, and persistent watchers through native system services.

## Features

* Cross-platform file system watching
* Pattern matching with regular expressions
* Custom R callbacks for file events
* Persistent watchers that survive R session restarts
* Robust event tracking via SQLite
* Service integration (Task Scheduler, systemd, launchd)

## Installation

```r
# Install from GitHub:
remotes::install_github("vorpalvorpal/vigil")
```

## Platform-Specific Requirements

The package has different requirements depending on your operating system:

### Windows
* Basic file watching: No additional requirements
* SQLite ODBC Driver: Recommended but not required
  * Download from: http://www.ch-werner.de/sqliteodbc/
* Persistent watchers: Requires the taskscheduleR package
  ```r
  install.packages("taskscheduleR")
  ```

### Linux
* inotify-tools:
  ```bash
  # Ubuntu/Debian
  sudo apt-get install inotify-tools

  # Fedora
  sudo dnf install inotify-tools

  # Arch Linux
  sudo pacman -S inotify-tools
  ```
* sqlite3:
  ```bash
  sudo apt-get install sqlite3  # or equivalent
  ```
* systemd (included in most distributions)

### macOS
* fswatch:
  ```bash
  brew install fswatch
  ```
* sqlite3:
  ```bash
  brew install sqlite3
  ```

## Usage

### Basic Watching

```r
library(vigil)

# Watch a directory for any changes
watc
59A4
h("path/to/watch")

# Watch only for new files matching a pattern
watch("path/to/watch",
      file_pattern = "\\.csv$",
      change_type = "created")

# Watch with a callback
watch("path/to/watch",
      callback = function(event) {
        cat(sprintf("File %s was %s at %s\n",
                   event$file_path,
                   event$event_type,
                   event$timestamp))
      })
```

### Persistent Watching

```r
# Create a watcher that continues after R exits
watch("path/to/watch",
      watch_mode = "persistent",
      callback = "path/to/callback.R")

# List active watchers
list_watchers()

# Kill a specific watcher
kill_watcher(id)

# Kill all watchers
kill_all_watchers()
```

### Wait for Events

```r
# Wait for a specific change
result <- watch_until("path/to/watch",
                     file_pattern = "\\.txt$",
                     change_type = "created",
                     timeout = 60)  # timeout in seconds

if (!is.null(result)) {
  cat("New text file:", result$file_path, "\n")
}
```

## License

MIT