8  The global state in {sandpaper}

8.1 When {sandpaper} is loaded

When {sandpaper} is loaded (either by attatchment with library() or invocation with ::, a function called .onLoad() (which lives in R/zzz.R) is evaluated:

sandpaper:::.onLoad

function (libname, pkgname) 
{
    ns <- asNamespace(pkgname)
    delayedAssign("GITIGNORED", gitignore_items(), eval.env = ns, 
        assign.env = ns)
    op <- getOption("sandpaper.use_renv")
    if (is.null(op)) {
        try_use_renv()
    }
    establish_translation_vars()
    invisible()
}
<bytecode: 0x5567f6f01958>
<environment: namespace:sandpaper>

This does a few things:

1. establishes a GITIGNORED vector that is used to check the .gitignore file to validate that we are working in a lesson that The Workbench can work with.

   

   GITIGNORED is a list of items required to be in the lesson’s .gitignore

2. attempts to determine if the user has provided consent to use {renv} with try_use_renv(). This will set the internal sandpaper.use_renv environment variable.

3. The establish_translation_vars() will establish the internal list of translation strings inside the internal environment called these$translations for use with set_language(), which can be fetched with the tr_src(), and tr_get() functions. See establish_translation_vars() for details

8.2 Building the lesson

All functions that build a lesson go through build_lesson():

sandpaper::build_lesson

function (path = ".", rebuild = FALSE, quiet = !interactive(), 
    preview = TRUE, override = list()) 
{
    check_pandoc()
    slugpath <- get_build_slug(path, quiet = quiet)
    slug <- slugpath$slug
    path <- slugpath$path
    on.exit({
        reset_build_paths()
    })
    validate_lesson(path, quiet = quiet)
    built <- build_markdown(path = path, rebuild = rebuild, quiet = quiet, 
        slug = slug)
    build_site(path = path, quiet = quiet, preview = preview, 
        override = override, slug = slug, built = built)
}
<bytecode: 0x5567fad2b008>
<environment: namespace:sandpaper>

8.2.1 Step 1: set an anchor

Because all of the lesson functions need to understand where the lesson exists on the file system, we want to record the root path while a lesson is being deployed. When build_lesson() is run, it calls the set_source_path() function, which records the root of the lesson (as determined by the presence of an “episodes” directory, OR a “site” directory, OR a “learners” directory, OR an “instructors” directory, OR a “profiles” directory) in a global envioronment called .build_paths$source:

sandpaper:::set_source_path

function (path) 
{
    .build_paths$source <- root_path(path) %||% .build_paths$source
    invisible(.build_paths$source)
}
<bytecode: 0x5567f90628e0>
<environment: namespace:sandpaper>

time elapsed: 11.04602 secs

set_source_path() establishes the root of the lesson

When the function exits, the reset_build_paths() function is called to reset the build path to NULL so that it could be used for a new lesson.

sandpaper:::reset_build_paths

function () 
{
    .build_paths$source <- NULL
}
<bytecode: 0x5567f990dd78>
<environment: namespace:sandpaper>

time elapsed: 1.096219 secs

reset_build_paths() establishes the root of the lesson

8.2.2 Step 2: Validate and setup global variables

When validate_lesson() is called, it kicks off a cascade that stores lesson-specific variables and strings for {varnish} into the language of the lesson. This process is described in The Data Flow vingette for {sandpaper}