Skip to contents

Record a local file that a corpus was built from, such as a database snapshot, an institutional export, a publication tracker or an affiliation dictionary, together with its SHA-256 hash. sm_certificate() lists the registered files in its local_inputs block, and sm_verify_certificate() checks that each of them still has the hash recorded here. sm_corpus_from_tables() registers the files given as its inputs.

Usage

sm_register_input(
  corpus,
  path,
  role = NULL,
  builder = NULL,
  call = rlang::caller_env()
)

Arguments

corpus

An sm_corpus object. A locked corpus (sm_lock()) cannot be changed.

path

Path of the file.

role

NULL or a string: what the file is.

builder

NULL or a string: the code that read the file.

call

Caller environment for error reporting.

Value

The corpus with the file recorded in corpus$metadata$local_inputs.

Details

The file is hashed as a stream (digest::digest(path, algo = "sha256", file = TRUE)), so large snapshots are not read into memory. The function adds one row to corpus$metadata$local_inputs, a tibble with these columns:

ColumnTypeContent
pathcharacterThe path, relative or as given (see below)
path_abscharacterThe absolute path of the file
rootcharacterThe working directory at registration
basenamecharacterThe file name
sha256characterSHA-256 hash of the content
bytesdoubleSize in bytes
rolecharacterWhat the file is, such as "dictionary"
buildercharacterThe code that read it
registered_atPOSIXctWhen it was registered (UTC, whole seconds)

path is relative to the working directory when the file lies below it, and as given otherwise. role names the file's part in the corpus, such as "source database" or "publication tracker", and builder the code that read it, such as "R/02_corpus.R::build_corpus".

Registering the same file again replaces its row; paths are compared after they are made absolute, so "data/x.csv" and "./data/x.csv" name the same file. A corpus without registered files has no such element; sm_certificate() then writes an empty block.

Local inputs are metadata: they do not enter the corpus hash (sm_hash_corpus()), and sm_rebuild_from_cert() cannot replay them. A certificate records path_abs and root as well as path, so that sm_verify_certificate() finds the files on the same computer from any folder; these absolute paths show the folder names of that computer.

Examples

corpus <- sm_example_corpus(n_works = 10)
tracker <- tempfile(fileext = ".csv")
writeLines(c("doi,unit", "10.9999/example.1,Unit A"), tracker)
corpus <- sm_register_input(corpus, tracker,
                            role = "publication tracker",
                            builder = "R/01_import.R::read_tracker")
corpus$metadata$local_inputs
#> # A tibble: 1 × 9
#>   path    path_abs root  basename sha256 bytes role  builder registered_at      
#>   <chr>   <chr>    <chr> <chr>    <chr>  <dbl> <chr> <chr>   <dttm>             
#> 1 /tmp/R… /tmp/Rt… /hom… file1c5… 721a6…    34 publ… R/01_i… 2026-11-22 06:04:18