runCrunchAutomation: Run a crunch automation script

Description

Crunch Automation is a custom scripting language that allows you to execute common Crunch commands. The syntax is described in the Crunch API documentation.

Usage

runCrunchAutomation(
  x,
  script,
  is_file = string_is_file_like(script),
  encoding = "UTF-8",
  ...
)
showScriptErrors()

Value

For runCrunchAutomation(): an updated dataset/project folder (invisibly), For showScriptErrors(), when run after a failure, a list with two items: script: that contains the script string sent to the server and errors which is a data.frame with details about the errors sent from the server.

Arguments

x: A crunch dataset or project folder (for backwards compatibility, dataset is also accepted)
script: A path to a text file containing a Crunch Automation script or a character vector of length 1 or more with Crunch Automation commands (see Details)
is_file: The default guesses whether a file or string was used in the script argument, but you can override the heuristics by specifying TRUE for a file, and FALSE for a string.
encoding: Optional encoding to convert from, defaults to UTF-8. The API accepts only UTF-8, so all text will be converted to UTF-8 before being sent to the server.
...: Additional options, such as dry_run = TRUE, passed on to the API if x is a dataset (if x is a project folder, an error is thrown)

Details

If a character vector with length bigger than 1 is passed to script, it's converted to a string by concatenating its elements together using line breaks.

Examples

Run this code

if (FALSE) {
# Can use a path to a file:
script_file <- "crunch_automation.txt"
ds <- runCrunchAutomation(ds, script_file)

# Or a string directly:
ds <- runCrunchAutomation(ds, "RENAME v1 TO age;")

# A "dry run" that validates the script but does not run it:
runCrunchAutomation(ds, "RENAME V1 TO age;", dry_run = TRUE)

# After a failed run, some error information prints to console,
# But more details are available with function:
showScriptErrors()

# After a successful run, can look at scripts:
scripts(ds)

# Run Crunch Automation on a folder:
my_folder <- cd(projects(), "folder1")
runCrunchAutomation(my_folder, 'CREATE FOLDER "folder2";')
}