Package 'ghactions4r'

Add platform-specific additional arguments to a GitHub workflow YAML file

Description

Add platform-specific additional arguments to a GitHub workflow YAML file

Usage

add_args(workflow_name, additional_args, txt = NULL, prev_line = NULL)

Arguments

workflow_name	What to name the github action workflow locally. Must have the file extension .yml
additional_args	A named list of additional command line arguments to be passed to the workflow. The names of the list represent the platforms (windows, macos, or ubuntu), and the values are character vectors of arguments. These additional arguments are executed after the step that checks out the repository and before the step that sets up R.
txt	A character vector of YAML file lines. If NULL, the function reads the YAML file automatically. Default is NULL.
prev_line	An integer specifying the line number in txt where the arguments should be added. If NULL, the function determines this value automatically. Default is NULL.

---

Check the workflow name is formatted correctly

Description

Basically check that it is a filename that ends in .yml

Usage

check_workflow_name(workflow_name)

Arguments

workflow_name

What to name the github action workflow locally. Must have the file extension .yml

---

Replace dollar sign operator in a file

Description

The dollar sign is convenient to write, but allows for partial matching, which we don't often want. This function takes a file and changes all dollar signs to double brackets with names in quotations instead. Note that this function will incorrectly convert text enclosed in backticks that includes a dollar sign.

Usage

rm_dollar_sign(file, out_file = file, allow_recursive = TRUE, max_loops = 5)

Arguments

file	Filename either with full path or relative to working directory.
out_file	The name or path of a new file to write to. This is by default the same as the original file. Set to NULL to avoid writing a new file.
allow_recursive	Should dollar sign references of list in list be replaced? If this is FALSE, then only the first reference will be replaced. For example, F$first$second would become F[["first"]]$second when allow_recursive is FALSE, but would become F[["first"]][["second"]] if TRUE.
max_loops	How many times should dollar signs be looked for recursively, if allow_recursive is TRUE? Defaults to 5. This is meant to prevent an infinite loop in case the function does not work properly.

Value

A character vector of the modified text. As a side effect, produces a text file (name specified in out_file) written out from R using writeLines().

Author(s)

Kathryn Doering

Examples

test_text <- c(
  "x$my_name <- y$test",
  "x[['my_name']]",
  "no_replace_here <- 44",
  "x$names<-new_assign;x$`22`",
  "x$names <- new_assign; x$`22`",
  "x$`$$weirdcharacters`<-222",
  "x$`nameinbacktick`",
  "x$mylist$my_col$YetAnotherCol",
  "x$mylist$my_col$`1_somename`"
)
writeLines(test_text, "test_rm_dollar_sign.txt")
new_text <- rm_dollar_sign(
  file = "test_rm_dollar_sign.txt",
  out_file = NULL
)
new_text
file.remove("test_rm_dollar_sign.txt")

---

use workflow in current pkg to check pkgdown site builds.

Description

use workflow in current pkg to check pkgdown site builds.

Usage

use_build_pkgdown(
  workflow_name = "call-build-pkgdown.yml",
  additional_args = NULL
)

Arguments

workflow_name	What to name the github action workflow locally. Must have the file extension .yml
additional_args	A named list of additional command line arguments to be passed to the workflow. The names of the list represent the platforms (windows, macos, or ubuntu), and the values are character vectors of arguments. These additional arguments are executed after the step that checks out the repository and before the step that sets up R.

Examples

## Not run: 
use_build_pkgdown(
  additional_args = list(
    ubuntu = c(
      "sudo apt-get update",
      "sudo apt-get install -y libcurl4-openssl-dev",
      "sudo add-apt-repository ppa:ubuntu-toolchain-r/test",
      "sudo apt-get install --only-upgrade libstdc++6"
    ),
    macos = c("brew install curl")
  )
)

## End(Not run)

---

workflow for calculating code coverage

Description

workflow for calculating code coverage

Usage

use_calc_coverage(
  workflow_name = "call-calc-coverage.yml",
  use_public_rspm = TRUE
)

Arguments

workflow_name

What to name the github action workflow locally. Must have the file extension .yml

use_public_rspm

Use posit package manager instead of CRAN to install dependencies? The advantage here is that dependencies are precompiled, so install should be much quicker. In rare situations (like packages with TMB dependencies), using use_public_rspm = FALSE may be a better option. Note a setting only needs to be specified in the yml if use_public_rspm is FALSE, so there will be no setting added if use_public_rspm is TRUE.

---

Use workflow in current pkg to automate documenting and styling

Description

Style your R package components automatically by running devtools::document(), styler::style_pkg(), and usethis::use_tidy_description().

Usage

use_doc_and_style_r(
  workflow_name = "call-doc-and-style-r.yml",
  use_rm_dollar_sign = FALSE,
  how_to_commit = c("pull_request", "directly"),
  build_trigger = c("push_to_main", "pull_request", "manually", "weekly"),
  use_pat = FALSE,
  pat_name = "PAT"
)

Arguments

workflow_name	What to name the github action workflow locally. Must have the file extension .yml
use_rm_dollar_sign	in addition to devtools::document and styler::style_pkg, should ghactions4r::rm_dollar_sign be run? Defaults to FALSE.
how_to_commit	Where should changes made to style and documentation be committed? Options are 1) in a pull request to the branch ("pull_request") where the workflow started; or 2) directly to the branch ("directly") where the workflow started.
build_trigger	Select the build trigger. Options are to run on pushing commits to main ("push_to_main", the default); run when a pull request is opened, reopened, or updated ("pull_request"); run manually with the workflow_dispatch trigger ("manually"); run on the default branch (usually main) once a week ("weekly").
use_pat	Should a personal access token (PAT) stored as a github secret be used? This is only necessary if you want the pull request generated by the doc and style workflow to be able to start other github action runs.
pat_name	Name of the personal access token (PAT), as stored in secrets. Only used if use_pat = TRUE. After generating the personal access token, See how to add it as a secret.

Details

Note that allow the pull request created from this workflow can be used to trigger github action runs, by using a personal access token to provide the right permissions. The PAT is first generated on a user account, then added to the repository or organization as a secret. Using a PAT can cause recursive runs, so should be used with caution. See github documentation on triggering a workflow from a workflow for more information.

Examples

# set up running the doc and style workflow on each push to main, opening a
# pull request to main when changes are found.
## Not run: 
use_doc_and_style_r()

## End(Not run)
# the same as
## Not run: 
use_doc_and_style_r(
  how_to_commit = "pull_request",
  build_trigger = "push_to_main"
)

## End(Not run)
# Set up running doc and style on each pull request, commiting directly to
# the pull request branch
## Not run: 
use_doc_and_style_r(
  how_to_commit = "directly",
  build_trigger = "pull_request"
)

## End(Not run)
# Set up the workflow to use a personal access token (PAT)
## Not run: 
use_doc_and_style_r(use_pat = TRUE, pat_name = "PAT")

## End(Not run)

---

Use workflow to run r cmd check on Linux, Mac, and Windows GitHub Actions

Description

Use workflow to run r cmd check on Linux, Mac, and Windows GitHub Actions

Usage

use_r_cmd_check(
  workflow_name = "call-r-cmd-check.yml",
  use_full_build_matrix = FALSE,
  depends_on_tmb = FALSE,
  additional_args = NULL
)

Arguments

workflow_name	What to name the github action workflow locally. Must have the file extension .yml
use_full_build_matrix	Run R cmd check with two older versions of R in addition to the three runs that use the release version.
depends_on_tmb	An option that install Matrix from source for windows and Mac builds to solved a nuanced issue for packages dependent on TMB. See this google groups thread for more information.
additional_args	A named list of additional command line arguments to be passed to the workflow. The names of the list represent the platforms (windows, macos, or ubuntu), and the values are character vectors of arguments. These additional arguments are executed after the step that checks out the repository and before the step that sets up R.

Examples

## Not run: 
use_r_cmd_check(
  additional_args = list(
    ubuntu = c(
      "sudo apt-get update",
      "sudo apt-get install -y libcurl4-openssl-dev",
      "sudo add-apt-repository ppa:ubuntu-toolchain-r/test",
      "sudo apt-get install --only-upgrade libstdc++6"
    ),
    macos = c("brew install curl")
  )
)

## End(Not run)

---

use workflow to run spelling::spell_check_package()

Description

use workflow to run spelling::spell_check_package()

Usage

use_spell_check(workflow_name = "call-spell-check.yml")

Arguments

workflow_name

What to name the github action workflow locally. Must have the file extension .yml

Value

The path to the new github action file.

---

use workflow in current pkg to update pkg down, where the site is deployed to a branch called gh-pages

Description

use workflow in current pkg to update pkg down, where the site is deployed to a branch called gh-pages

Usage

use_update_pkgdown(
  workflow_name = "call-update-pkgdown.yml",
  additional_args = NULL
)

Arguments

workflow_name	What to name the github action workflow locally. Must have the file extension .yml
additional_args	A named list of additional command line arguments to be passed to the workflow. The names of the list represent the platforms (windows, macos, or ubuntu), and the values are character vectors of arguments. These additional arguments are executed after the step that checks out the repository and before the step that sets up R.

Examples

## Not run: 
use_update_pkgdown(
  additional_args = list(
    ubuntu = c(
      "sudo apt-get update",
      "sudo apt-get install -y libcurl4-openssl-dev",
      "sudo add-apt-repository ppa:ubuntu-toolchain-r/test",
      "sudo apt-get install --only-upgrade libstdc++6"
    ),
    macos = c("brew install curl")
  )
)

## End(Not run)

---

Validate additional arguments for R functions

Description

Validate additional arguments for R functions

Usage

validate_additional_args(additional_args)

Arguments

additional_args

A named list of additional command line arguments to be passed to the workflow. The names of the list represent the platforms (windows, macos, or ubuntu), and the values are character vectors of arguments. These additional arguments are executed after the step that checks out the repository and before the step that sets up R.

---