From {fusen} >=0.5, a “config_fusen.yaml” file registers all files created from a specific “flat” file as soon as you inflate it. Hence, you can keep track on where to find the source of your functions and tests. One of its major functionnality is to help you clean your package files in case you decide to change a function name, delete a function or change a vignette name.
To make this work properly, you will have to register all files that
were not created from a flat file. add_files_to_config()
will help you do so (See below: “Register some specific files, even with
regex”).
If you use this version of {fusen} in an existing project, you will
want to register all existing files to avoid a too strong clean up:
register_all_to_config() will help you do so (See below:
“How to migrate from previous {fusen} versions?”).
{fusen} inflates your flat files to script files with pre-defined
names stored in the correct place, so that you do not have to think
about it. If you do not change the default behavior, scripts names are
created from the name of each function created.
Until version 0.4, if you decided to change the name of your function,
or a function was obsolete, you had to clean it all manually.
This time is over with {fusen} version >0.5!
Now, {fusen} keeps track of files created with an
inflate(), in a yaml configuration file. It also allows you
to register all extra files that you decide are legitimate. Hence,
{fusen} will be able to clean all files that are not necessary anymore
in your package.
To make this work properly, all R, test and vignettes files will need
to be registered in the “dev/config_fusen.yaml” file.
{fusen} will try to guess the source flat file of each script. This will
only be possible if you used {fusen} >= 0.4 before. Otherwise, you
may want to follow the detailed process below.
TODO - clean_fusen_files
You may not want to register each new file that does not come during
an inflate process. For instance, with {golem}, there are module
(^mod_*) files, which need to be protected. You can add
this regular expression directly in the yaml file with
add_files_to_config(c("R" = "^mod_*"))
If your practice of {fusen} is to inflate it once, and then continue
development in the R, test and vignette files directly, then you may
want to properly deprecated the flat file.
We recommend to use deprecate_flat_file() to clean your
script files (remove “do not edit”), update the config file and move the
flat file in a “dev/dev_history” directory.
TODO
This vignette shows tools that are used internally to {fusen} to keep
track of all files created during the inflate() process.
They are visible to users as soon as they start using {fusen} >= 0.5,
even if the package was built without {fusen}, or with an earlier
version of {fusen}.
The recommended process for a migration is:
register_all_to_config() in your current package to
create the “dev/config_fusen.yaml” that registers all your existing
files.If you used earlier versions of {fusen}, it is possible that you have some remaining “.R” or test files. You may want to detect which scripts are linked to a flat file. If you are more familiar with “.csv” file than with the “.yaml” file above, or if you want a quick edit of multiple sources, you can run these intermediate steps:
check_not_registered_files() on your packageorigin = "keep" for files to keep, that are not
coming from a flat filedf_to_config()
You can continue reading if you are interesting in the functioning of these config file manipulations.
If all files of the current state are legitimate, then, you can register everything in the config file.
Run register_all_to_config() in your current package to
create the “dev/config_fusen.yaml” that registers all your files. You
will note a “keep” section, which lists all files for which the source
was not guessed.
#' \dontrun{
# Usually run this one inside the current project
# Note: running this will write "dev/config_fusen.yaml" in your working directory
register_all_to_config()
#' }
# Or you can try on the reproducible example
dummypackage <- tempfile("register")
dir.create(dummypackage)
# {fusen} steps
fill_description(pkg = dummypackage, fields = list(Title = "Dummy Package"))
dev_file <- suppressMessages(add_flat_template(pkg = dummypackage, overwrite = TRUE, open = FALSE))
flat_file <- dev_file[grepl("flat_", dev_file)]
# Inflate once
usethis::with_project(dummypackage, {
suppressMessages(
inflate(
pkg = dummypackage, flat_file = flat_file,
vignette_name = "Get started", check = FALSE,
open_vignette = FALSE
)
)
out_path <- register_all_to_config(dummypackage)
# Look at the output
yaml::read_yaml(out_path)
})df_to_config() allows to add your own list of files that
you want to keep in your package, despite not being created
with a flat file.
This is important if you started to develop without {fusen}, and start
using a flat file from now on, so that {fusen} does not delete your
existing files.
# Add your own list of files to "keep",
# if they are not in a flat file.
# Otherwise, they may be deleted with your next `inflate()`
my_files_to_protect <- tibble::tribble(
~type, ~path,
"R", "R/zaza.R",
"R", "R/zozo.R",
"test", "tests/testthat/test-zaza.R",
"vignette", "vignettes/my-zaza-vignette.Rmd"
)
#' \dontrun{
df_to_config(my_files_to_protect)
#' }
# Provide a list of `inflate()` parameters if you wish them
# to be added in the dev/config_fusen.yaml file
#' \dontrun{
df_to_config(my_files_to_protect,
inflate_parameters = list(
pkg = ".",
flat_file = "dev/my_flat.Rmd",
vignette_name = "My new vignette",
open_vignette = FALSE,
check = FALSE,
document = TRUE,
overwrite = "yes"
)
)
#' }{fusen} now registers all files created during
inflate(). This allows to clean the packages directories in
case some functions do not exist anymore and were renamed.
However, this also requires to register all existing files if you
started your package without {fusen} or with an earlier version of
{fusen}.check_not_registered_files() shows files that are not
already registered in the yaml config file. The output is consistent
with what is needed for df_to_config() to register them if
wanted.
Note that check_not_registered_files() will try to guess
the source flat template, if you used {fusen} >= 0.4 before.
#' \dontrun{
# Run this on the current package in development
out_csv <- check_not_registered_files()
out_csv
#' }
# Or you can try on the reproducible example
dummypackage <- tempfile("clean")
dir.create(dummypackage)
# {fusen} steps
fill_description(pkg = dummypackage, fields = list(Title = "Dummy Package"))
dev_file <- suppressMessages(add_flat_template(pkg = dummypackage, overwrite = TRUE, open = FALSE))
flat_file <- dev_file[grepl("flat_", dev_file)]
# Inflate once
usethis::with_project(dummypackage, {
suppressMessages(
inflate(
pkg = dummypackage, flat_file = flat_file,
vignette_name = "Get started", check = FALSE,
open_vignette = FALSE
)
)
# Add a not registered file to the package
cat("# test R file", file = file.path(dummypackage, "R", "to_keep.R"))
# Use the fonction to check the list of files
out_csv <- check_not_registered_files(dummypackage)
out_csv
# Open the csv to modify manually the list of files in the csv created
# Indeed, the "to_keep.R" file will be registered as
# "No existing source path found."
# Manually change this line with "keep"
content_csv <- read.csv(out_csv, stringsAsFactors = FALSE)
# Here I change the line to simulate what you manually did above
content_csv[content_csv[["path"]] == "R/to_keep.R", "origin"] <- "keep"
write.csv(content_csv, out_csv)
out_config <- df_to_config(
df_files = out_csv,
inflate_parameters = list(
pkg = dummypackage, flat_file = flat_file,
vignette_name = "Get started", check = FALSE,
open_vignette = FALSE
)
)
out_config
# Open the out_config file to see what's going on
yaml::read_yaml(out_config)
})
unlink(dummypackage, recursive = TRUE)