Skip to contents

CandidatePath: a directory with multiple candidate locations

Source: R/r6_candidate_path.R
CandidatePath.Rd

Holds a priority-ordered list of candidate paths for a directory that may live at different filesystem locations on different hosts (e.g. a shared drive mounted at different points under Linux vs Windows). $resolve() returns the first candidate that exists, caching the result so subsequent calls are free. If no candidate exists but a candidate's parent directory does, $resolve() creates the candidate and returns it – this is how "first run on a fresh host" gets a directory automatically.

CandidatePath is the single type used by swereg R6 classes (RegistryStudy, TTEPlan) to own their multi-host directory knowledge. Both classes hold CandidatePath instances as public fields, so their resolution behavior is structurally identical – it cannot drift.

The cache is host-specific and must not persist across a save/load cycle. Containing classes call invalidate_candidate_paths() from their $save() methods before serialization to clear it.

Methods

$new(candidates, label = NULL)

Construct from a character vector of candidate paths.

$resolve()

Return the cached resolved path; otherwise walk the candidate list and pick the first that exists (or create the first whose parent exists), cache, and return.

$invalidate()

Clear the cache. The next $resolve() call re-walks the candidate list.

$is_resolved()

TRUE if the cache is populated and the cached path still exists; FALSE otherwise.

$print()

Show the candidate list, marking the cached-resolved entry with >.

See also

first_existing_path() for the stateless primitive used by $resolve(); invalidate_candidate_paths() for the save-time cache clearer; RegistryStudy and TTEPlan for the R6 classes that own CandidatePath instances.

Other multi_host_paths: first_existing_path(), invalidate_candidate_paths()

Public fields

candidates

Character vector of candidate paths, in priority order. Read-only after construction (modify via a new instance).

label

Short human-readable label used in error messages and $print() output.

Methods

Public methods

CandidatePath$new()

Construct a CandidatePath.

Usage

CandidatePath$new(candidates, label = NULL)

Arguments

candidates

Character vector of candidate paths. Must be non-empty.

label

Optional label for error messages and printing.

CandidatePath$resolve()

Resolve the candidate list to a concrete path on the current host. Returns the cached value if valid; otherwise walks the candidates and caches the first that exists (or is creatable).

Usage

CandidatePath$resolve()

Returns

A single character path.

CandidatePath$invalidate()

Clear the cached resolved path. The next $resolve() call will re-walk the candidate list.

Usage

CandidatePath$invalidate()

Returns

invisible(self).

CandidatePath$is_resolved()

Check whether a cached path exists and is still valid.

Usage

CandidatePath$is_resolved()

Returns

TRUE if cached and the cached directory still exists, FALSE otherwise.

CandidatePath$print()

Print the candidate list, marking the cached-resolved entry with >.

Usage

CandidatePath$print(...)

Arguments

...

Ignored.

CandidatePath$clone()

The objects of this class are cloneable with this method.

Usage

CandidatePath$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

d <- tempfile()
dir.create(d)
cp <- CandidatePath$new(c("/definitely/not/there", d), "my_dir")
cp$resolve()
#> [1] "/tmp/RtmpKg4QzZ/file1d1256a20c1b"
cp$is_resolved()
#> [1] TRUE
print(cp)
#> <CandidatePath: my_dir>
#>     /definitely/not/there
#>   > /tmp/RtmpKg4QzZ/file1d1256a20c1b
cp$invalidate()
cp$is_resolved()
#> [1] FALSE