Update README and documentation

Author: torfason

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: gitpins
 Type: Package
 Title: Pin urls to local file and version with git
-Version: 0.1.3.9002
+Version: 0.1.3.9003
 Author: Magnus Thor Torfason
 Maintainer: Magnus Thor Torfason <m@zulutime.net>
 Description: Pin URLs to local file and version the pins with git. 

NEWS.md

@@ -0,0 +1,17 @@
+
+Version 0.3.9003
+================
+
+- Custom location for the `gitpin` directory using `gp_options()`
+
+- Target specific "drop" times for the online resources that are being fetched,
+  by using the `gp_dropper()`
+  
+- More consistent function names, `gp_pin()`, `gp_list()`, `gp_options()`, 
+  and `gp_dropper()`
+
+
+Version 0.3.0
+=============
+
+- Initial release.

R/gp_options.R

@@ -1,12 +1,13 @@
 
 
-#' @title Create a gp_options Object
+#' @title Create a `gp_options` Object
 #' @description Constructs a `gp_options` object with configurable parameters.
 #'   The parameters can be set from the defaults, from R options, or directly
 #'   when the options object is created.
 #' @param ... Reserved. All arguments must be named.
 #' @param pin_directory A character string specifying the directory to use
-#'   for the pin repo
+#'   for the pin directory (the local git repository where downloaded resources
+#'   are stored and versioned).
 #' @return A list representing the `gp_options` object.
 #' @export
 gp_options <- function(...,
@@ -27,12 +28,12 @@ gp_options <- function(...,
 }
 
 
-#' @title Verify that x is a valid gp_options object
+#' @title Verify that x is a valid `gp_options` object
 #' @description Verifies that `x` is a `gp_options` object (of class
 #'   `gitpins_gp_options`) and that all elements of the object are
 #'   valid for such an object. Use `gp_options()` to create `gp_options`
 #'   objects.
-#' @param x An object to verify
+#' @param x An object to verify.
 #' @return Unchanged input if valid, otherwise an error is thrown.
 #' @keywords internal
 assert_gp_options <- function(x) {

README.Rmd

@@ -21,13 +21,12 @@ stopifnot(!file.exists(here::here("gitpins")))
 # gitpins
 
 <!-- badges: start -->
-[![R-CMD-check](https://github.com/torfason/gitpins/workflows/R-CMD-check/badge.svg)](https://github.com/torfason/gitpins/actions)
 [![R-CMD-check](https://github.com/torfason/gitpins/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/torfason/gitpins/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
 `r desc::desc_get("Description")`
 
-## The problem
+## The Problem
 
 You want to quickly and easily process an online resource using R functions,
 some of which only accept local files. Thus you would like the following
@@ -40,14 +39,24 @@ properties for your workflow:
 * Have the local copy be easily accessible in a predictable location
 * Not ruin your local copy if the online version should change in a "bad" way
 
-## The solution
+## The Solution
 
 The `gitpins` package downloads a URL to a local file in the `gitpins` folder
-inside your project (the currently fixed path is determined by
-`here("gitpins")`), and then returns the full file name name of the local file,
+(defaults to `here::here("gitpins")`, but can be configured using
+`gp_options()`), and then returns the full file name name of the local file,
 which can be passed as an argument to any function that expects to read such a
 file.
 
+## Installation
+
+Install `gitpins` using `pak`:
+
+```r
+pak::pak("torfason/gitpins")
+```
+
+## Usage
+
 ```{r}
 # Downloads on first try
 pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv") |> 
@@ -81,7 +90,11 @@ pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.cs
 
 The refresh interval is configured with the `refresh_hours` parameter. Use
 `refresh_hours=0` to force a download on every call, and `refresh_hours=Inf` to
-always use the local copy (after the first download).
+always use the local copy (after the first download). A helper function,
+`gp_dropper()` is provided for the case where a new version of the resource
+"drops" at the same time every day. The function allows you to set a lower
+interval in a given time window after the expected drop time, to maximize the
+probability that an updated version gets downloaded quickly.
 
 ```{r}
 # Force a reload by specifying zero refresh time
@@ -93,6 +106,11 @@ pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.cs
 pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv",
        refresh_hours = Inf) |>
   gsub(pattern=".*/(gitpins/.*)", replacement="/home/user/project/\\1")
+
+# Set a lower interval for a given time window after a resource update "drops"
+pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv",
+       refresh_hours = gp_dropper(drop_hour = 12, drop_tz = "US/Eastern")) |>
+  gsub(pattern=".*/(gitpins/.*)", replacement="/home/user/project/\\1")
 ```
 
 The `gitpins` directory is actually a local `git` repository, and each new
@@ -106,56 +124,51 @@ function is provided to list available pins (with or without history), but
 beyond that, the user is expected to use `git` directly for more complex
 retrieval operations.
 
-```{r, include=FALSE}
-old_width <- options(width=130)
-```
-
 ```{r}
-list_pins()
-list_pins(history = TRUE)
+withr::with_options(list(width = 130), {
+  gp_list()
+  gp_list(history = TRUE)
+})
 ```
 
-```{r, include=FALSE}
-options(old_width)
-```
 
-## Installation
+## Function Name Conflicts
 
-Install `gitpins` with either of the following commands:
+For use with with another package that also defines a `pin()` function (such as
+the `pins` package), the `conflicted` package comes highly recommended, but the
+`exclude` option of the `library()` function is also a valid approach. In either
+case, the `gp_pin()` function is provided as an alias for `pin()` so you don't
+need to specify the full package name on each call:
 
-``` r
-pak::pak("torfason/gitpins")
-# or alternatively
-remotes::install_github("torfason/gitpins")
-```
-
-You can then load and use the package like this:
+### Using `conflicted`
 
 ```r
+library(conflicted)
+conflicts_prefer(pins::pin())
+library(pins)
 library(gitpins)
-pin(URL)
+gp_pin(URL)
 ```
 
-To use this concurrently with another package that also defines a `pin()`
-function, exclude this function and use the alias `gitpin()` instead:
+### Using `exclude`
 
 ```r
+library(pins)
 library(gitpins, exclude="pin")
-gitpin(URL)
+gp_pin(URL)
 ```
 
-Note that `gitpins` uses the native pipe operator (`|>`) and so depends on `R
-(>= 4.1.0)`. If this is an issue for you, holler and I can probably be convinced
-of changing it to make it compatible with older versions.
-
-## Related packages and feedback
+## Related Packages, System Requirements, and Feedback
 
 This package was inspired by the `pins` package, and in particular the
 `pins::pin()` function. However, that function stores the actual local file in a
 system location rather than inside the project, so using it did not prove
-reliable reliable. Furthermore, it did not have the desired versioning
-properties, and finally, it is now defined as a legacy function and is not part
-of the new api for that package. As a result, `gitpins` was born.
+reliable. Furthermore, it did not have the desired versioning properties, and
+finally, it is now defined as a legacy function and is not part of the new api
+for that package. As a result, `gitpins` was born.
+
+Note that `gitpins` uses the native pipe operator (`|>`) and so depends on `R
+(>= 4.1.0)`. 
 
 For feature requests, bugs, or other feedback, feel free to file an issue.
 

README.md

@@ -5,7 +5,6 @@
 
 <!-- badges: start -->
 
-[![R-CMD-check](https://github.com/torfason/gitpins/workflows/R-CMD-check/badge.svg)](https://github.com/torfason/gitpins/actions)
 [![R-CMD-check](https://github.com/torfason/gitpins/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/torfason/gitpins/actions/workflows/R-CMD-check.yaml)
 <!-- badges: end -->
 
@@ -14,7 +13,7 @@ are versioned using a local git repository, and if getting a document
 from the web is not successful, a previous local download is made
 available.
 
-## The problem
+## The Problem
 
 You want to quickly and easily process an online resource using R
 functions, some of which only accept local files. Thus you would like
@@ -28,13 +27,23 @@ the following properties for your workflow:
 - Not ruin your local copy if the online version should change in a
   “bad” way
 
-## The solution
+## The Solution
 
 The `gitpins` package downloads a URL to a local file in the `gitpins`
-folder inside your project (the currently fixed path is determined by
-`here("gitpins")`), and then returns the full file name name of the
-local file, which can be passed as an argument to any function that
-expects to read such a file.
+folder (defaults to `here::here("gitpins")`, but can be configured using
+`gp_options()`), and then returns the full file name name of the local
+file, which can be passed as an argument to any function that expects to
+read such a file.
+
+## Installation
+
+Install `gitpins` using `pak`:
+
+``` r
+pak::pak("torfason/gitpins")
+```
+
+## Usage
 
 ``` r
 # Downloads on first try
@@ -90,7 +99,11 @@ pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.cs
 The refresh interval is configured with the `refresh_hours` parameter.
 Use `refresh_hours=0` to force a download on every call, and
 `refresh_hours=Inf` to always use the local copy (after the first
-download).
+download). A helper function, `gp_dropper()` is provided for the case
+where a new version of the resource “drops” at the same time every day.
+The function allows you to set a lower interval in a given time window
+after the expected drop time, to maximize the probability that an
+updated version gets downloaded quickly.
 
 ``` r
 # Force a reload by specifying zero refresh time
@@ -106,6 +119,13 @@ pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.cs
   gsub(pattern=".*/(gitpins/.*)", replacement="/home/user/project/\\1")
 #> pin() found recent version, using it ...
 #> [1] "/home/user/project/gitpins/5ad1e570044be11330713642c682b9db.data"
+
+# Set a lower interval for a given time window after a resource update "drops"
+pin("https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv",
+       refresh_hours = gp_dropper(drop_hour = 12, drop_tz = "US/Eastern")) |>
+  gsub(pattern=".*/(gitpins/.*)", replacement="/home/user/project/\\1")
+#> pin() found recent version, using it ...
+#> [1] "/home/user/project/gitpins/5ad1e570044be11330713642c682b9db.data"
 ```
 
 The `gitpins` directory is actually a local `git` repository, and each
@@ -120,62 +140,58 @@ but beyond that, the user is expected to use `git` directly for more
 complex retrieval operations.
 
 ``` r
-list_pins()
+withr::with_options(list(width = 130), {
+  gp_list()
+  gp_list(history = TRUE)
+})
 #> Loading required namespace: tibble
-#> # A tibble: 2 × 2
-#>   timestamp                 url                                                                          
-#>   <chr>                     <chr>                                                                        
-#> 1 2024-03-28 16:33:23.74682 https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv 
-#> 2 2024-03-28 16:33:23.58968 https://vincentarelbundock.github.io/Rdatasets/csv/datasets/sunspot.month.csv
-list_pins(history = TRUE)
 #> # A tibble: 3 × 2
-#>   timestamp                 url                                                                          
-#>   <chr>                     <chr>                                                                        
-#> 1 2024-03-28 16:33:23.74682 https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv 
-#> 2 2024-03-28 16:33:23.58968 https://vincentarelbundock.github.io/Rdatasets/csv/datasets/sunspot.month.csv
-#> 3 2024-03-28 16:33:23.27699 https://vincentarelbundock.github.io/Rdatasets/csv/openintro/country_iso.csv
+#>   timestamp                 url                                                 
+#>   <chr>                     <chr>                                               
+#> 1 2025-03-21 18:28:24.10695 https://vincentarelbundock.github.io/Rdatasets/csv/…
+#> 2 2025-03-21 18:28:23.92979 https://vincentarelbundock.github.io/Rdatasets/csv/…
+#> 3 2025-03-21 18:28:23.60490 https://vincentarelbundock.github.io/Rdatasets/csv/…
 ```
 
-## Installation
+## Function Name Conflicts
 
-Install `gitpins` with either of the following commands:
+For use with with another package that also defines a `pin()` function
+(such as the `pins` package), the `conflicted` package comes highly
+recommended, but the `exclude` option of the `library()` function is
+also a valid approach. In either case, the `gp_pin()` function is
+provided as an alias for `pin()` so you don’t need to specify the full
+package name on each call:
 
-``` r
-pak::pak("torfason/gitpins")
-# or alternatively
-remotes::install_github("torfason/gitpins")
-```
-
-You can then load and use the package like this:
+### Using `conflicted`
 
 ``` r
+library(conflicted)
+conflicts_prefer(pins::pin())
+library(pins)
 library(gitpins)
-pin(URL)
+gp_pin(URL)
 ```
 
-To use this concurrently with another package that also defines a
-`pin()` function, exclude this function and use the alias `gitpin()`
-instead:
+### Using `exclude`
 
 ``` r
+library(pins)
 library(gitpins, exclude="pin")
-gitpin(URL)
+gp_pin(URL)
 ```
 
-Note that `gitpins` uses the native pipe operator (`|>`) and so depends
-on `R (>= 4.1.0)`. If this is an issue for you, holler and I can
-probably be convinced of changing it to make it compatible with older
-versions.
-
-## Related packages and feedback
+## Related Packages, System Requirements, and Feedback
 
 This package was inspired by the `pins` package, and in particular the
 `pins::pin()` function. However, that function stores the actual local
 file in a system location rather than inside the project, so using it
-did not prove reliable reliable. Furthermore, it did not have the
-desired versioning properties, and finally, it is now defined as a
-legacy function and is not part of the new api for that package. As a
-result, `gitpins` was born.
+did not prove reliable. Furthermore, it did not have the desired
+versioning properties, and finally, it is now defined as a legacy
+function and is not part of the new api for that package. As a result,
+`gitpins` was born.
+
+Note that `gitpins` uses the native pipe operator (`|>`) and so depends
+on `R (>= 4.1.0)`.
 
 For feature requests, bugs, or other feedback, feel free to file an
 issue.

build/build_and_release_process.R

@@ -5,9 +5,10 @@
   if (file.exists(gpdir)) {
     file.rename(gpdir, paste0(gpdir,"_",gitpins:::fstamp(Sys.time())))
   }
-  devtools::build()
   devtools::document()
+  devtools::build()
   devtools::build_readme()
+  devtools::build_site()
   devtools::test()
   message("Build OK")
 }