Plugin API Reference
v8r exports two classes: BasePlugin and Document. v8r plugins extend the BasePlugin class. Parsing a file should return a Document object. Additionally, validating a document yields a ValidationResult object.
BasePlugin
class BasePlugin
Base class for all v8r plugins.
Properties
name
Name of the plugin. All plugins must declare a name starting with v8r-plugin-.
Type: string
Methods
registerInputFileParsers
Use the registerInputFileParsers hook to tell v8r about additional file formats that can be parsed. Any parsers registered with this hook become valid values for the parser property in custom schemas.
Returns: Array<string>
- File parsers to register
parseInputFile
Use the parseInputFile hook to tell v8r how to parse files. If parseInputFile returns anything other than undefined, that return value will be used and no further plugins will be invoked. If parseInputFile returns undefined, v8r will move on to the next plugin in the stack. The result of successfully parsing a file can either be a single Document object or an array of Document objects.
Returns: Document | Array<Document> | undefined
- Parsed file contents
| PARAMETER | TYPE | OPTIONAL | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| contents | string | The unparsed file content. | ||
| fileLocation | string | The file path. Filenames are resolved and normalised by glob using the dotRelative option. This means relative paths in the current directory will be prefixed with ./ (or .\ on Windows) even if this was not present in the input filename or pattern. | ||
| parser | string | undefined | If the user has specified a parser to use for this file in a custom schema, this will be passed to parseInputFile in the parser param. |
registerOutputFormats
Use the registerOutputFormats hook to tell v8r about additional output formats that can be generated. Any formats registered with this hook become valid values for the format property in the config file and the --format command line argument.
Returns: Array<string>
- Output formats to register
getSingleResultLogMessage
Use the getSingleResultLogMessage hook to provide a log message for v8r to output after processing a single file. If getSingleResultLogMessage returns anything other than undefined, that return value will be used and no further plugins will be invoked. If getSingleResultLogMessage returns undefined, v8r will move on to the next plugin in the stack. Any message returned from this function will be written to stdout.
Returns: string | undefined
- Log message
| PARAMETER | TYPE | OPTIONAL | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| result | ValidationResult | Result of attempting to validate this document. | ||
| fileLocation | string | The document file path. Filenames are resolved and normalised by glob using the dotRelative option. This means relative paths in the current directory will be prefixed with ./ (or .\ on Windows) even if this was not present in the input filename or pattern. | ||
| format | string | The user's requested output format as specified in the config file or via the --format command line argument. |
getAllResultsLogMessage
Use the getAllResultsLogMessage hook to provide a log message for v8r to output after processing all files. If getAllResultsLogMessage returns anything other than undefined, that return value will be used and no further plugins will be invoked. If getAllResultsLogMessage returns undefined, v8r will move on to the next plugin in the stack. Any message returned from this function will be written to stdout.
Returns: string | undefined
- Log message
| PARAMETER | TYPE | OPTIONAL | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| results | Array<ValidationResult> | Results of attempting to validate these documents. | ||
| format | string | The user's requested output format as specified in the config file or via the --format command line argument. |
Document
class Document
constructor
new Document(document)
Document is a thin wrapper class for a document we want to validate after parsing a file
| PARAMETER | TYPE | OPTIONAL | DEFAULT | DESCRIPTION |
|---|---|---|---|---|
| document | any | The object to be wrapped |
ValidationResult
Type: object
| PROPERTY | TYPE | DESCRIPTION |
|---|---|---|
| fileLocation | string | Path of the document that was validated. Filenames are resolved and normalised by glob using the dotRelative option. This means relative paths in the current directory will be prefixed with ./ (or .\ on Windows) even if this was not present in the input filename or pattern. |
| documentIndex | number | null | Some file formats allow multiple documents to be embedded in one file (e.g: yaml). In these cases, documentIndex identifies is used to identify the sub document within the file. documentIndex will be null when there is a one-to-one relationship between file and document. |
| schemaLocation | string | null | Location of the schema used to validate this file if one could be found. null if no schema was found. |
| valid | boolean | null | Result of the validation (true/false) if a schema was found. null if no schema was found and no validation could be performed. |
| errors | Array<ErrorObject> | An array of AJV Error Objects describing any errors encountered when validating this document. |