Load DCT specifications from a file or multiple files

These function load DCT specifications from the YAML fragments in one (load_dct_specs) or multiple files (load_dct_dir).

load_dct_dir(
  path,
  recursive = TRUE,
  extension = "\\.rock|\\.dct\\.yaml|\\.yaml|\\.yml",
  regex,
  dctContainer = "dct",
  headingLevel = 2,
  delimiterRegEx = "^---$",
  ignoreOddDelimiters = FALSE,
  encoding = "UTF-8",
  sortDecreasing = FALSE,
  silent = TRUE
)

load_dct_specs(
  text,
  file,
  delimiterRegEx = "^---$",
  dctContainer = "dct",
  headingLevel = 2,
  ignoreOddDelimiters = FALSE,
  encoding = "UTF-8",
  silent = TRUE
)

# S3 method for dct_specs
print(x, ...)

# S3 method for dct_specs
plot(x, ...)

Arguments

path

The path containing the files to read.

recursive

Whether to also process subdirectories (TRUE) or not (FALSE).

extension

The extension of the files to read; files with other extensions will be ignored. Multiple extensions can be separated by a pipe (|).

regex

Instead of specifing an extension, it's also possible to specify a regular expression; only files matching this regular expression are read. If specified, regex takes precedece over extension,

dctContainer

The container of the DCT specifications in the YAML fragments. Because only DCT specifications are read that are stored in this container, the files can contain YAML fragments with other data, too, without interfering with the parsing of the DCT specifications.

headingLevel

The level of the Markdown headings that are produced.

delimiterRegEx

The regular expression used to locate YAML fragments

ignoreOddDelimiters

Whether to throw an error (FALSE) or delete the last delimiter (TRUE) if an odd number of delimiters is encountered.

encoding

The encoding to use when calling readLines(). Set to NULL to let readLines() guess.

sortDecreasing

Whether to sort the constructs in decreasing order (TRUE), in increasing order (FALSE), or not at all (NULL).

silent

Whether to be silent (TRUE) or informative (FALSE).

text, file

As text or file, you can specify a file to read with encoding encoding, which will then be read using base::readLines(). If the argument is named text, whether it is the path to an existing file is checked first, and if it is, that file is read. If the argument is named file, and it does not point to an existing file, an error is produced (useful if calling from other functions). A text should be a character vector where every element is a line of the original source (like provided by base::readLines()); although if a character vector of one element and including at least one newline character (\\n) is provided as text, it is split at the newline characters using base::strsplit(). Basically, this behavior means that the first argument can be either a character vector or the path to a file; and if you're specifying a file and you want to be certain that an error is thrown if it doesn't exist, make sure to name it file.

x

The parsed parsed_dct object.

...

Any other arguments are passed to the print command.

Value

An object with the DiagrammeR::DiagrammeR graph stored in output$basic_graph, a DiagrammeR::DiagrammeR graph with a summary of which specifications are provided for each construct in output$completeness_graph and the instructions in output$instr.

Details

load_dct_dir simply identifies all files and then calls load_dct_specs for each of them. load_dct_specs loads the YAML fragments containing the DCT specifications using yum::load_yaml_fragments() and then parses the DCT specifications into a visual representation as a DiagrammeR::DiagrammeR graph and Markdown documents with the instructions for creating measurement instruments or manipulations, and for coding measurement instruments, manipulations, or aspects of a construct.

Examples

exampleSpec <-
  system.file("extdata",
              "example.dct.yaml",
              package="psyverse");
dctObject <- load_dct_specs(exampleSpec);

if (FALSE) {
psyverse::load_dct_dir(path="A:/some/path");
}