fusen v0.5: Gotta inflate ’em all !

You can read the original post in its original format on Rtask website by ThinkR here: fusen v0.5: Gotta inflate ’em all !

No more amnesia for {fusen}! With v0.5, it now has “memory”, allowing you to inflate all your flat files simultaneously. The aim of this latest version of {fusen} is to provide an ever smoother package development experience, for both novice and experiences users.

{fusen} continues to make life easier for package creators. One of the main changes in this new version is the appearance of a configuration file to list the links between a “parent” flat file (in the dev/ directory) and its “child” files (in the R/, tests/ and vignettes/ directories). This file provides {fusen} with memory, and is the cornerstone of a major v0.5 feature: the ability to automatically run an inflate_all() on all your flat files at the same time!

For less experienced {fusen} users, please feel free to consult our previous articles, and for the more experienced, please read on.

Our previous articles :

• How to get started with {fusen}
• Tip and tricks of the v0.4

Installation

{fusen} is available on CRAN and developed on GitHub. You can access the full documentation website on this page: https://thinkr-open.github.io/fusen/. It also appears on the page ThinkR r-universe if you want to install the development version without GitHub API constraints.

Install CRAN version

install.packages("fusen")

Install development version

install.packages('fusen', repos = c('https://thinkr-open.r-universe.dev', 'https://cloud.r-project.org'))

{fusen} lists all the files in your package

On packages developed with {fusen} >= v0.5, we note the appearance of a dev/config_fusen.yaml configuration file. This file introduces the notion of “memory” into {fusen}. The configuration file lists the links between a “parent” flat file and its “child” files. It is updated each time the inflate() function is called on a given flat file. The parameters used to configure the inflate() call are also stored here.

This will enable you to keep track of the link between flat files, and all files in the R/, tests/ and vignettes/ directories. The configuration file also lists all files not originating from a flat file, which may give you an opportunity to clean up your package if necessary.

I am developing a new package with {fusen} v0.5.1, what should I do?

Nothing special, apart from taking advantage of the new features straight away! The configuration file will appear after the first call to inflate() and will be updated with each new call.

I have started a package with a version of {fusen} prior to v0.5.1, what should I do?

The easiest way is to run a fusen::inflate_all_no_check() and follow the instructions returned by the function.

It is likely that you will have to:

1. Run an inflate() of each of your flat files with this version of {fusen}.
2. Run fusen::check_not_registered_files() to list files not listed in the configuration file.
3. Check the contents of the dev/config_not_registered.csv file.
4. Clean your package of the files listed in step 3, if necessary.
5. Register all remaining unregistered files with fusen::register_all_to_config().

Retry a call to fusen::inflate_all_no_check() or fusen::inflate_all() and you should be able to continue your package development serenely.

I have started a package without {fusen}, what should I do?

To continue your package with {fusen}, you’ll need to implement your new functionalities in a first flat file. Once this is done, you can follow the procedure described in the previous section.

What does the configuration file look like?

The configuration file, found in dev/config_fusen.yaml, lists all flat files that have been inflated, the files created during this operation and the parameters used to call the inflate() function.
Other files, not originating from flat files, are also listed, under a section called “keep”.

Below is an example of a configuration file:

flat_file1.Rmd:
  path: dev/flat_file1.Rmd
  R:
  - R/function1.R
  - R/function2.R
  tests:
  - tests/testthat/test-function1.R
  - tests/testthat/test-function2.R
  vignettes: vignettes/How-to-use-these-2-awesome-functions.Rmd
  inflate:
    flat_file: dev/flat_file1.Rmd
    vignette_name: First vignette to read
    open_vignette: false
    check: false
    document: true
    overwrite: 'yes'  
flat_file2.Rmd:
  path: dev/flat_file2.Rmd
  R:
  - R/function3.R
  - R/function4.R
  tests:
  - tests/testthat/test-function3.R
  - tests/testthat/test-function4.R
  vignettes: vignettes/Yet-another-vignette-to-read.Rmd
  inflate:
    flat_file: dev/flat_file2.Rmd
    vignette_name: Yet another vignette to read
    open_vignette: false
    check: false
    document: true
    overwrite: 'yes'
keep:
  path: keep
  R:
  - R/my_R_file1_from_my_previous_work.R
  - R/my_R_file2_from_my_previous_work.R
  tests:
  - tests/testthat/test-my_previous_work.R
  vignettes: vignettes/my_vignette_from_my_previous_work.Rmd

This configuration file tells us that the package contains 2 flat files: flat_file1.Rmd and flat_file2.Rmd. These are associated with 2 files in the R/ directory, 2 files in the tests/ directory and 1 file in the vignettes/ directory, respectively. These 2 files have been inflated with the latest version of {fusen}, as the parameters used to call the inflate() function are also listed.
Finally, in the “keep” section, you’ll find files from previous developments made for this package, prior to the use of {fusen}.

For more information ?

Go to the dedicated vignette.

How do I inflate all my flat files at once?

Is your package starting to include a lot of flat files, and you’re getting tired of having to inflate each one by hand on a regular basis? With this version of {fusen} comes the inflate_all() function!

Each call to inflate() now stores the function’s call parameters in the aforementioned configuration file. The inflate_all() function will reuse these parameters to serially inflate all your files. This means that a flat file must be manually inflated with inflate() before it can be used via inflate_all().

I have started a package with a version of {fusen} prior to v0.5.0, what should I do?

The configuration file is absent from your project, so calling an inflate() on each of your flat files will create the configuration file and fill it in.

I already knew about the configuration file but I have started a package with a development version of {fusen} prior to v0.5.1, what should I do?

The configuration file exists in your project, and lists the links between the flat files and the files in R/, tests/ and vignettes/, but the section relating to inflate() parameters is empty! To fill it in, you’ll need to make a manual call to inflate() for each flat file.

For more information ?

Go to the dedicated vignette.

In the end, is it hard to upgrade to the new version of {fusen}?

Not at all!

• If you start a new package with this version of {fusen}, everything will be crystal clear.
• If you’re starting from an old package developed without {fusen} or with an older version of {fusen}, it will only take a few minutes to make your project compatible with this version and take advantage of all the new features!

With {fusen} v0.5.1, you now have:

• A summary of the links between your package files in the configuration file: this makes for a cleaner, more readable project.
• The ability to inflate all your flat files at once: this saves time and eliminates the possibility of forgetting to inflate some flat file.

{fusen} and {attachment}

The purpose of the {attachment} package is to help you manage dependencies during the development of your package. {attachment} is used by {fusen} when calling an inflate() to update package documentation and dependencies.

With {attachment} v0.4.0, a configuration file also appears, similar to the one used by {fusen}. For optimum cooperation between these two packages, we recommend that you also use this version of {attachment}.

To find out more about this latest version and the collaboration between {fusen} and {attachment}, please consult these resources:

• {attachment} v0.4.0: Breaking changes and configuration file for a better experience
• Package dev with {fusen} & {attachment}: load all functions of a flat, manage qmd and auto-fill Remotes field

NEWS content (v0.5.0 + v0.5.1)

New features

Inflate all active flat file

• inflate_all() uses the configuration file to inflate all your flat files at once. document and check options are thus only run once for all flat files. (#204, @ymansiaux)
• This requires to run inflate() at least once for each flat file.
• This also requires to register all other files, that were present in the package before this version of {fusen} with register_all_to_config().

List all files created with an inflate() in a config file with parameters

• inflate() creates a configuration file dev/config_fusen.yaml to register all files created while inflating the corresponding flat file, along with inflate parameters. (#198, @ymansiaux)

Publish your package website on GitHub

• Publish your {fusen} project on a GitHub website with one command: init_share_on_github()

List all files created with an inflate() in a config file

• inflate() creates a “dev/config_fusen.yaml” file to register all files created while inflating the corresponding flat file (First steps in #24)
• Migrate from a non-fusen package or a previous version of ‘fusen’ with register_all_to_config()
• Create or update the config file from a data.frame with df_to_config() to list legitimate scripts (even if not associated with a flat file)

Others

• Allow multiple examples for the same function (#149)

Breaking changes

• Arguments rmd and name in function inflate() now lead to errors (Deprecated since v0.3.0).
• add_dev_history() was deprecated since v0.3.0 in favor of add_flat_template(). Now add_dev_history() only adds a “dev_history.Rmd” file in the “dev/” directory.
• add_flat_template(template = "minimal") no longer exists to avoid confusion between minimal package or minimal flat file. Indeed, now there are add_flat_template(template = "minimal_package") (also add_minimal_package()) or add_flat_template(template = "minimal_flat") (also add_minimal_flat()). The latter doing exactly the same as add_additional() (#187)
• create_fusen() still uses minimal as minimal_package

Major changes

• create_fusen() and the RStudio gui interface now accept flat_file parameter to name the first flat file as well as the first function (when using ‘minimal’ template).
• The tips and tricks vignette shortly presents how to combine {fusen} and {golem} (#187)
• Incorrect function names issued from addins or add_flat_template() are cleaned before being included in the flat file to follow underscore rule.

Minor changes

• Update CONTRIBUTING to speak about flat file in {fusen} itself
• replace the maintainer’s name from fill_description() in examples, templates and tests (#155, @FlorenceMounier)
• create_fusen() vaccinates created git project (#171)
• Examples under function roxygen documentation are cleaned from extra spaces after empty #' to avoid git diff against code linters / stylers.

Bug fixes

• Fix using line break after function name in flat files (#142, @FlorenceMounier)
• If project directory is renamed by “my.package (Copy)”, inflate() still works, even if this name is not a proper package name. What is important is that DESCRIPTION Package name is correct.
• Fix for when using word “function(” in documentation (#174, @FlorenceMounier)

This post is better presented on its original ThinkR website here: fusen v0.5: Gotta inflate ’em all !