Before input file data can be accessed, it must first be verified by calling the verify()
method of the top-level Inlet
object. This will return a bool
indicating whether the provided input conformed to the schema and specific violations of the schema are logged via SLIC by default. If you would like to suppress the SLIC warnings and process the list of verification errors instead, you can pass a std::vector<inlet::VerificationError>
to the verify()
method as follows:
You can then iterate over the list of errors, each of which contains the path within the input file of the offending Container
, Field
, or Function
and the corresponding message.
This section describes the verification rules that apply to each possible element of the Inlet hierarchy, namely, Container
, Field
, and Function
.
If a Container
is marked as required (via the required()
) method, then the Container
must have a Field
or Function
that was present in the input or contain a sub-Container
that does. This does not apply to a Container
that corresponds to an array or dictionary, as empty collections provided by the user are considered valid. Consider the following definition and input file:
foo = { }
Inlet verification will succeed for the above snippets.
If a Container
corresponds to an array or dictionary, the elements of the array must all be of the requested type, if any were provided. This restriction applies even if the array/dictionary was not marked as required
.
If a verification function was provided via the registerVerifier()
method, this function must return true
when passed the corresponding Container
object.
Note
Since a Container
represents internal nodes in the Inlet hierarchy, its verification status is dependent on that of its child objects. A Container
is only considered valid if all of its child Container
, Field
, and Function
objects are also valid.
If a Field
is marked as required (via the required()
) method, then a value must be provided in the input.
Providing a value of the wrong type will result in verification failure, even if the field was not marked as required
.
If a range (inclusive upper/lower bounds) of valid values is specified with the range()
method, both the provided value (if applicable) and default value (if specified with defaultValue()
) must fall within the range.
If a set of valid values is specified with the validValues()
method, both the provided value (if applicable) and default value (if specified with defaultValue()
) must be included in the set.
If a verification function was provided via the registerVerifier()
method, this function must return true
when passed the corresponding Field
object.
If a Function
is marked as required (via the required()
) method, then a function must be provided in the input.
If a verification function was provided via the registerVerifier()
method, this function must return true
when passed the corresponding Function
object.
In order to better detect user error, e.g., misspelled names, Inlet provides a method to retrieve the names of entries in the input file that were not requested in the schema definition phase. Consider the following input:
../../examples/verification.cpp
The full set of unexpected names across the entire input file can be retrieved from the top-level Inlet
object as follows:
../../examples/verification.cpp
The list of unexpected names can also be retrieved relative to an individual Container
- that is, anywhere within/below that container:
../../examples/verification.cpp
../../examples/verification.cpp
These lists of unexpected names can be useful if you'd like to implement custom/targeted error messages - in the example above, one might wish to provide a message indicating that dimension
should be used instead of just dim
. In other cases, it may be sufficient to just require that all or part of the input file have no unexpected entries. This is supported via the strict()
method, which will cause a Container
to fail verification if it contains any unexpected entries:
../../examples/verification.cpp