validateHumdrum: Validate humdrum files

In Computational-Cognitive-Musicology-Lab/humdrumR: humdrumR

Validate humdrum files

Description

This function checks files on your local machine for violations of the humdrum syntax. Detailed error reports can be generated, pointing to specific problematic records in files.

Usage

validateHumdrum(..., errorReport.path = NULL)

Arguments

...	Arguments passed to findHumdrum(). Used to identify files on the local machine to test for humdrum validity. This is mainly used to pass regex file-path search patterns, but may also be used to pass the recursive and/or contains arguments to findHumdrum().
errorReport.path	A directory path where to write error report files. Defaults to NULL. Must be a single character string. If NULL (the default), no error report files are written.

Details

Only violations of the general humdrum syntax are identified. For example, missing exclusive interpretations, ⁠*-⁠ spine enders, or null data tokens. The validateHumdrum function does not check for ill-formed data content—for example, a ⁠**kern⁠ spine containing the token "Lsharp" will not be rejected. Note that validateHumdrum is quite picky about details! "Hanging white space," even in global records, will be marked as invalid files!

validateHumdrum is called in the same manner as readHumdrum(), by providing one or more regex search patterns to match files on your machine. (The ..., recursive, and contains arguments are all simply passed to findHumdrum().) When called, validateHumdrum prints basic messages informing you about the result of the file matching and validity testing.

Value

validateHumdrum() returns a "error frame" data.table object, invisibly (to "see" the output, you must save it to a variable, then look at it). The error frame is a data.table with three columns:

• Filepath: The file name.

• Record: Which record contains the error.

• Message: A description of the error.

Valid files will have no rows in the error frame.

Error reports

If desired, the contents of the validateHumdrum "error frame" can be written into text files. This allows us to print the errors tagged right alongside the original raw data. To write an error report, set the errorReport.path argument to a non-NULL string, pointing to a directory path on your machine. If the directory doesn't exist, R will (attempt to) create it.

In the errorReport.path directory, the complete error report(s) for all the files (same as in the returned "fileFrame", see above) are written into a single file named 'humdrumR_syntaxErrorReport_DATE.txt' (with the date coming from Sys.Date⁠). In addition, a sub directory called ⁠AnnotatedFiles⁠is created. In this directory, copies of all the files which contain errors are written, with⁠_errorAnnotations' appended to their names. In each file, individual errors are directly indicated in the record where they occur. The output looks like this:

                                             | **whatever
                                             | =
                                             | The original records from the input file
                                             | appear on the right side.
                                             | =
Error message for record six printed here.   | Exactly as they did
                                             | in the input file.
                                             | *-

Examples

validateHumdrum(humdrumRroot, "HumdrumData/BeethovenVariations/B.*.krn")

errorFrame <- validateHumdrum(humdrumRroot, "HumdrumData/InvalidFile.krn")
errorFrame

Computational-Cognitive-Musicology-Lab/humdrumR documentation built on Oct. 22, 2024, 9:28 a.m.