Chapter 8 Rules in text files

This Chapter is about importing and exporting rules from and to file, both in free-form text and in YAML. We also discuss some more advanced features like how to have one rule file include another file.

  • Importing from free-form text files was discussed in @ref{sect:readfromfile}
  • Importing from simple YAML files was discussed in @ref{sect:yamlfiles}

8.1 Setting options

Both free-form and YAML files can optionally start with a header section where options or file inclusions can be set. The header section is enclosed by lines that contain three dashes (---) at the beginning of the line.

For example, in the following rule file we make sure that errors are not caught but raised to run-time level, and we set the tolerance for checking linear equalities and inequalities to zero.

---
options:
  raise: errors
  lin.eq.eps: 0
  lin.ineq.eps: 0
---

turnover >= 0

staff >= 0

total.rev - profit == total.costs

The options you set here will be part of the validator object, that is created once you read in the file. The options are valid for every confrontation you use this validator for, unless they are overwritten during the call to confront().

The header section is interpreted as a block of YAML, so options and file inclusions must be specified in that format.

8.2 Including other rule files

In validate, rule files can include each other recursively. So file A can include file B, which may inclide file C. This is useful for example in surveys where the first part of the questionnaire goes to all respondents, and for the second part, the contents of the questionnaire (and hence its variables) depend on the respondent type. One could create a files with specific rules for the second part: one for each respondent group, and have each specific rule file include the general rules that must hold for every respondent. It can also be useful when different persons are responsible for different rule sets.

File inclusion can be set through the include option in the YAML header.

---
include:
  - petes_rules.yaml
  - nancys_rules.yaml
options:
  raise: errors
---
# start rule definitions here

8.3 Exporting validator objects

There are three ways to do that. You can either write to a yaml file immediately as follows

or you can get the yaml text string using as_yaml

cat(as_yaml(v))

Finally, you can convert a rule set to data frame and then export it to a database.