Skip to contents

Define a ruleset

Source: R/research-rules.R
bg_ruleset.Rd

Validates a ruleset and returns it as a plain list. A ruleset collects raw rules under a dotted namespace and version, and can extend, disable, and override rules from other registered rulesets.

Usage

bg_ruleset(
  id,
  version,
  rules = list(),
  extends = character(),
  disable = character(),
  override = list(),
  vocabulary = NULL,
  title = NULL,
  description = NULL,
  references = NULL
)

Arguments

id

Dotted namespace, for example "lab.prereg".

version

MAJOR.MINOR.PATCH, optionally followed by -prerelease.

rules

List of raw rules, see bg_rule().

extends

References to other rulesets, "<id>@<major>" or "<id>@<version>", resolved in order.

disable

Qualified ids of inherited rules to drop.

override

Named list of partial rules, named by qualified rule id. Each supplied field replaces the inherited one whole. NULL removes an optional field.

vocabulary

Optional named list with utilities, goal_kinds, and checks. Utilities and goal kinds are lists of list(id, title, description, references). Checks are lists of list(id, title, utilities). A declared category must be non-empty; an absent category is unconstrained.

title, description

Optional documentation strings.

references

Optional source strings. They are never fetched.

Value

A validated ruleset (named list).

Details

Resolution is recursive. Each extends reference is resolved in order and the results are concatenated. Identical rules inherited along several paths collapse to one; any other duplicate is an error. disable and then override are applied to the inherited rules, and the ruleset's own rules are appended with qualified ids <id>/<rule id>. Overridden rules keep their source and gain overridden_by.

id@MAJOR selects the highest registered non-prerelease version with that major. An exact version selects only that version.

See also

bg_register_ruleset(), bg_ruleset_check(), bg_use_rules().

Examples

bg_ruleset(
  "lab.review",
  "1.0.0",
  rules = list(bg_rule(
    id = "review-ppc",
    on = "accept",
    require = list(type = "require_review", check = "ppc"),
    message = "Review the predictive check before accepting."
  ))
)
#> $id
#> [1] "lab.review"
#> 
#> $rules
#> $rules[[1]]
#> $rules[[1]]$id
#> [1] "review-ppc"
#> 
#> $rules[[1]]$message
#> [1] "Review the predictive check before accepting."
#> 
#> $rules[[1]]$on
#> $rules[[1]]$on[[1]]
#> [1] "accept"
#> 
#> 
#> $rules[[1]]$require
#> $rules[[1]]$require$check
#> [1] "ppc"
#> 
#> $rules[[1]]$require$type
#> [1] "require_review"
#> 
#> 
#> 
#> 
#> $version
#> [1] "1.0.0"
#>