Package 'blaseRtemplates'

Description

cache a single package

Usage

cache_fun(
  package,
  cache_loc = fs::path(Sys.getenv("BLASERTEMPLATES_CACHE_ROOT"), "library"),
  permissions
)

Description

Make sure you are in a properly-formatted blaseRtemplates project.

Usage

catch_blasertemplates_root()

Description

This function sets up a directory structure that is designed to work well with blaseRtemplates functions. It will create directories where indicated, write a standard .Rprofile document, and modify the user .Renviron file to configure R properly. The function will not overwrite existing directories and will fail when an existing installation is already present in the same location. The only modification outside of the existing directory is to the .Renviron file. If you have existing configurations in your .Renviron file, they will only be changed if they are conflicting. If this is problematic, then you should archive your .Renviron file before running. The new .Renviron file will cause R to use the new .Rprofile in the cache directory and skip existing user- and project-level .Rprofiles.

For the individual user: Identify the location for your blaseRtemplates cache and your R projects. For convenience, these can be within the same parent directory. The cache will hold versioned and hashed binary package files in the library directory. These are the actual instructions used by R when you call up functions. The version/hash structure is tracked by your projects and allows reproducibility. The user_project directory holds symlinks to the specific version/hash packages being used. A new directory is created for each new project. The source directory is used by the package installer, pak, to archive the source files for each package. You should rarely need to look in there. The logs directory holds .Rhistory files. One is created for each R session you open. The .tsv files catalog the entire collection of packages in your cache with their dependencies. The .Rprofile is what sets up your R session to use the proper user_package directory, ensures you are working in a valid project, generates startup messages and sets some helpful options.

This function will create 1 project, called baseproject, in the projects directory which will ensure you are always operating in a project environment. Working outside of a project can have dangerous/unintended consequences.

For the system administrator: the directory structure will work equally well for a multiuser system (e.g. rstudio server) with minor modifications. The .Rprofile generated by the function can be used as Rprofile.site and will apply to all users of that R installation. Each user should have their own project directories with a baseproject on the system. The .Renviron file should be modified for each user to point to this directory and saved in the home directory. There should be a subdirectory in user_projects with each user's ID for their project libraries. Ownership should be given to the user/group and permissions set accordingly, e.g. 755.

Upgrading R versions: since package binaries don't work across minor version changes in R, e.g. 4.2 -> 4.3, you will have to create a new cache directory each time this changes.

Usage

establish_new_bt(cache_path, project_path)

Arguments

See Also

cli_alert create, copy, path_package, path, file_access, dir_ls, path_file str_detect, str_replace proj_utils

Examples

## Not run: 
if(interactive()){
  establish_new_bt(cache_path = "<some_directory>/r_4_2_cache", project_path = "<some_directory>/projects")
 }

## End(Not run)

Description

Find Unlinked Packages

Usage

find_unlinked_packages(lib_path)

Description

Sometimes, the user_project library can break. This can happen if there are failures in the upstream install functions. Or if the links are deleted for some reason. If everything is broken, you may need to repair the user project library. To do this, exit the project and enter a working project. Delete the links in the offending user project library. Then run this function to relink. Use either the library catalog file from the project itself, or if this is also corrupted with bad information, run an older version that worked or a version from another project that worked. If you can identify the problematic package in the course of these fixes, then you should probably delete it from your cache entirely.

Usage

fix_another_library(file, dir)

Arguments

Value

Nothing

See Also

path_math, create, path, path_file read_delim pull

Description

get all package dependencies

Usage

get_all_deps(package)

Description

Use this to replace the current symlinked library with a new version. By default, the function will link to the newest version of all packages available in the cache. Alternatively, identify another project library catalog to replace the current version.

Usage

get_new_library(newest_or_file = "newest")

Arguments

Value

Uninstalled packages hashes.

Description

Supply this function with a branch name. If the branch exists it will switch to the branch. If not, it will pull any changes from remote and then create the branch. Any uncommitted work will be carried over to the new branch in the same state. Avoid repeatedly switching branches with work in different states of completion since this may cause conflicts

Usage

git_easy_branch(branch)

Arguments

Value

nothing git_branch

Description

This uses gert to look up all active remotes and then runs gert::git_push() to each.

Usage

git_push_all()

Value

nothing

Description

This function uses git revert to rewind history to a prior commit. First make sure all of your changes have been committed. Then run gert::git_log() to identify the "good" commit you want to rewind to. Supply this as the argument to this function. A new commit will be made with a helpful message. Commit history is not changed so you can always rewind the rewind etc....

Usage

git_rewind_to(commit)

Arguments

Value

a tibble with the new git commit log after rewinding

See Also

git_commit

Description

This function updates default branch (usually "main") from remote. This pulls in any changes from other contributors. Then it merges the working branch into the upstream branch.

Usage

git_safe_merge(branch = NULL, upstream = "main")

Arguments

Value

nothing

See Also

git-default-branch git_branch,git_commit

Description

This function updates a git branch via rebase from a default upstream branch (default is "main"). You can explicitly provide the names of your working branch and the default upstream branch.

Usage

git_update_branch(branch = NULL, upstream = "main")

Arguments

Value

nothing

See Also

git-default-branch git_branch,git_stash

Description

This wraps gitcreds::gitcreds_set() and adds a system call to edit the user global git config to set the cache timeout to 1 billion seconds if running a Linux system.

Usage

gitcreds_set()

Value

nothing

See Also

gitcreds_get

Description

Hash a single package

Usage

hash_fun(package)

Description

hash one or more functions and then cache them and update the catalogs. Default permissions are set to 777.

Usage

hash_n_cache(
  lib_loc = .libPaths()[1],
  cache_loc = fs::path(Sys.getenv("BLASERTEMPLATES_CACHE_ROOT"), "library"),
  verbose = TRUE,
  permissions = "777"
)

Description

This function wraps usethis::create_from_github, making some useful default choices. Because this function forks the project, git will set up the originator as an upstream remote. Using blaseRtemplates::git_push_all will push to both the originator and the collaborator's github.

Usage

initialize_github(repo, dest = NULL, open = TRUE)

Arguments

Value

nothing

Description

This wraps usethis::create_package() and adds a few additional templates.

Usage

initialize_package(
  path,
  fields = list(),
  roxygen = TRUE,
  check_name = TRUE,
  rstudio = rstudioapi::isAvailable(),
  open = rlang::is_interactive(),
  fresh_install = FALSE,
  path_to_cache_root = Sys.getenv("BLASERTEMPLATES_CACHE_ROOT")
)

Arguments

See Also

isAvailable is_interactive use_template defer

Description

These functions create an R project:

• create_project() creates a non-package project, i.e. a data analysis project

Both functions can be called on an existing project; you will be asked before any existing files are changed.

This function is a modification of usethis::create_project

Usage

initialize_project(
  path,
  rstudio = rstudioapi::isAvailable(),
  open = rlang::is_interactive(),
  fresh_install = FALSE,
  path_to_cache_root = Sys.getenv("BLASERTEMPLATES_CACHE_ROOT")
)

Arguments

Value

Path to the newly created project or package, invisibly.

Description

Use this to install a new package. Choosing "new_or_update" will go to the package repository, get the latest version of the software, install into your cache and link to your project library. Choosing "link_from_cache" will get you the latest version in the cache Also, use this option with either "which_version" or "which_hash" to install specific versions.

Usage

install_one_package(
  package,
  how = c("link_from_cache", "new_or_update", "tarball"),
  which_version = NULL,
  which_hash = NULL
)

Arguments

Value

nothing

Description

link package dependencies

Usage

link_deps(package)

Description

link one new package

Usage

link_one_new_package(package, version = NULL, hash = NULL)

Description

Calling function to get recursive dependencies

Usage

rec_get_deps(
  needed,
  checked = character(0),
  deps = character(0),
  catalog = fs::path(Sys.getenv("BLASERTEMPLATES_CACHE_ROOT"), "dependency_catalog.tsv")
)

Description

recursively get package dependencies

Usage

rec_get_deps_internal(needed, checked, deps, catalog)

Description

If you have deleted or otherwise broken your .Rprofile or .Renviron files, you may have difficulty connecting to the package cache. This function will regenerate both for you. The existing .Rprofile must be deleted manually. You can choose to archive the old version if you wish. It will be replaced with the standard .Rprofile from blaseRtemplates. The .Renviron file will be modified by removing the damaged lines and replacing them with the correct ones. You must supply the correct file path locations to your cache directory and project directory, otherwise your R installation will be configured incorrectly.

Usage

regenerate_bt_configs(cache_path, project_path)

Arguments

Value

nothing

See Also

file_access, path, copy, path_package cli_abort, cli_alert str_detect, str_replace

Description

Since this file is ignored by git, you will have to regenerate it when forking a repository. This function writes the template file to your R directory as "regenerated_git_commands.R".

Usage

regenerate_git_commands()

Value

nothing

Description

Shortcut function to save the blaseRtemplates report template in Rmd format within an Rmd folder.

Usage

report_template_rmd(report_name = NULL)

Arguments

Details

Makes a new Rmd file with the supplied file name

Value

Returns nothing

See Also

str_detect cli_alert create, path use_template

Description

The prompt package adds a nice feature but has some limitations, namely, that it does not respect changing git branches and has to be manually re-called. This defeats the purpose. Blasertemplates git functions automoatically call prompt to change the prompt label when switching branches, but this will not happen if you change branches using the terminal, the git panel or other git branching functions. Therefore this function is provided to manually reset your prompt to the current branch.

Usage

reset_prompt()

Value

nothing

See Also

set_prompt,prompt_git

Description

update the dependency catalog

Usage

update_dependency_catalog()

Description

rewrite/update the package catalog

Usage

update_package_catalog()

Description

In the current version of blaseRtemplates, the package library is cached at the location designated by the environment variable "BLASERTEMPLATES_CACHE_ROOT". There is a single cache for all users and projects. The cache holds the binary software used by each package. The packages for each project are connected to the cache by symlinks. The cache is versioned so that different projects can use different versions if desired. Use this function to write a tab-delimited file listing the packages used by each project.

This file will be written to the "library_catalogs" directory within each project. The filename incorporates the user name so everyone working on the project will have their own. Use get_new_library() to adopt a new version of all packages

Usage

write_project_library_catalog()

Value

returns nothing