Package 'devforge'

Title: Development tooling for the bixverse family of R packages
Description: Dev-time tooling, not a runtime dependency. Generates the parameter wrapper constructors and their paired checkmate extensions from a declarative spec, and lints the things the house style asks for but cannot enforce: roxygen that has drifted away from the formals it documents, function inputs that never reach a checkmate assertion, and rextendr bindings without an R wrapper.
Authors: Gregor Lueg [aut, cre]
Maintainer: Gregor Lueg <[email protected]>
License: MIT + file LICENSE
Version: 0.0.7
Built: 2026-10-07 06:02:40 UTC
Source: https://github.com/GregorLueg/devforge

Help Index

Generate the parameter wrappers and their checkmate extensions

Description

Reads every spec under ⁠inst/params/⁠, writes the three generated files under ⁠R/⁠ and formats them with air. The generated files are meant to be committed.

Usage

forge_params(pkg = ".", .verbose = TRUE)

Arguments

pkg

String. Path to the package root. Defaults to ".".
.verbose

Boolean. Report what was written. Defaults to TRUE.

Value

Character vector of the paths written, invisibly.

Collect the specs defined in a package's spec directory

Description

Sources every .R file under ⁠inst/params/⁠ in a fresh environment and returns the devforge_spec objects it finds, in file then definition order.

Usage

load_specs(pkg = ".")

Arguments

pkg

String. Path to the package root. Defaults to ".".

Value

A named list of devforge_spec objects, named by their name.

Choice field

Description

Emits match.arg() plus checkmate::assertChoice() in the constructor and a apply_choice_rules() entry in the checker, which is what the packages already do by hand. default is moved to the front of choices so the generated formal reads method = c("default", ...).

Usage

p_choice(default, choices, doc = NULL)

Arguments

default

String. The default value. Must be one of choices.
choices

Character vector. The allowed values.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

String field

Description

String field

Usage

p_chr(default, null_ok = FALSE, len = 1L, doc = NULL)

Arguments

default

String or NULL. The default value. Leave it out for a formal the caller must supply.
null_ok

Boolean. Whether NULL is permitted. Defaults to FALSE.
len

Integer or string. 1L for a scalar, "+" for one or more. Defaults to 1L.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Numeric field

Description

Numeric field

Usage

p_dbl(
  default,
  range = NULL,
  null_ok = FALSE,
  len = 1L,
  strict = FALSE,
  doc = NULL
)

Arguments

default

Numeric or NULL. The default value. Leave it out for a formal the caller must supply.
range

String or NULL. Checkmate range suffix, for example "(0, 1]".
null_ok

Boolean. Whether NULL is permitted. Defaults to FALSE.
len

Integer or string. 1L for a scalar, "+" for one or more. Defaults to 1L.
strict

Boolean. TRUE demands a double ("R") rather than any number ("N"). Defaults to FALSE.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Unvalidated field

Description

For anything a qassert pattern cannot express. The field contributes a formal, a default and its roxygen, but no assertion and no rule table entry. Pair it with extra_ctor / extra_check on the spec.

Usage

p_free(default, doc = NULL)

Arguments

default

Any. The default value. Leave it out for a formal the caller must supply.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Integer field

Description

Integer field

Usage

p_int(
  default,
  range = NULL,
  null_ok = FALSE,
  len = 1L,
  integerish = FALSE,
  check_as = NULL,
  doc = NULL
)

Arguments

default

Integer or NULL. The default value. Leave it out for a formal the caller must supply.
range

String or NULL. Checkmate range suffix, for example "[1,)".
null_ok

Boolean. Whether NULL is permitted. Defaults to FALSE.
len

Integer or string. 1L for a scalar, "+" for one or more. Defaults to 1L.
integerish

Boolean. Accept whole doubles such as 1000 as well ("X" rather than "I"). Pair it with an as.integer() in extra_ctor when downstream code needs a real integer. Defaults to FALSE.
check_as

Character vector or NULL. Overrides the checker's pattern, for a field the constructor resolves before returning it.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Boolean field

Description

Boolean field

Usage

p_lgl(default, null_ok = FALSE, doc = NULL)

Arguments

default

Boolean or NULL. The default value. Leave it out for a formal the caller must supply.
null_ok

Boolean. Whether NULL is permitted. Defaults to FALSE.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Merged sub-list field

Description

For the constructors that take a list of overrides for a shared defaults block, e.g. knn = list(k = 25L) on top of params_knn_defaults(). The constructor merges the caller's list into the base with modifyList(keep.null = TRUE) and splices the result flat into the returned list at this field's position. When from names another spec, the checker requires the spliced elements and validates them with that spec's rules.

Usage

p_merge(
  from,
  default = list(),
  overrides = NULL,
  drop = NULL,
  strict = FALSE,
  doc = NULL
)

Arguments

from

String or language object. The name of a spec in the same package ("knn_defaults" merges into params_knn_defaults()), or an expression evaluated inside the constructor, for a base that depends on the other arguments. A language from contributes nothing to the checker.
default

List or language object. The formal default. Defaults to list().
overrides

List, language object or NULL. Constructor-specific defaults applied over from before the caller's list. A language object may reference the other formals, e.g. quote(list(k = neighbours_within_batch * 2L)). Defaults to NULL.
drop

Character vector or NULL. Elements removed from the base before the merge, for a constructor that sets them itself or has no use for them. They drop out of the checker too. Defaults to NULL.
strict

Boolean. The constructor rejects caller elements that are not in the base (after drop) instead of splicing them through unchecked. Defaults to FALSE.
doc

String or NULL. Roxygen prose for this field.

Value

A devforge_field.

Defaults block specification

Description

A zero-argument ⁠params_*_defaults()⁠ helper. Same fields as a param_spec(), but the generated function takes no arguments, runs no assertions and simply returns the defaults. These exist to be embedded in other constructors.

Usage

param_defaults(
  name,
  title,
  fields,
  description = NULL,
  details = NULL,
  references = NULL,
  checker = NULL,
  label = NULL,
  hint = NULL,
  export = TRUE
)

Arguments

name

String. Snake case stem. "knn_defaults" gives params_knn_defaults().
title

String. The roxygen title line.
fields

Named list of p_int() and friends.
description

String or NULL. Roxygen ⁠@description⁠ prose.
details

String or NULL. Roxygen ⁠@details⁠ prose.
references

String or NULL. Roxygen ⁠@references⁠ prose.
checker

String or NULL. PascalCase stem for a checker over this block, for the defaults blocks that are validated on their own. Defaults to NULL.
label

String or NULL. Label used in the checker's error messages.
hint

String or NULL. Appended to the checker's error messages.
export

Boolean. Whether the helper gets ⁠@export⁠. Defaults to TRUE.

Value

A list of class devforge_spec.

Parameter wrapper specification

Description

The declarative description of one ⁠params_*()⁠ constructor and its paired checkmate extension. Everything the generator emits comes from here.

Usage

param_spec(
  name,
  title,
  fields,
  description = NULL,
  details = NULL,
  references = NULL,
  return_order = NULL,
  checker = to_pascal_case(name),
  checker_args = list(),
  extra_ctor = NULL,
  extra_check = NULL,
  class_tag = NULL,
  strict_names = FALSE,
  label = NULL,
  hint = NULL,
  test_fn = FALSE,
  export = TRUE
)

Arguments

name

String. Snake case stem. "ica_general" gives params_ica_general().
title

String. The roxygen title line for the constructor.
fields

Named list of p_int() and friends. Order is the order of the formals and of the returned list.
description

String or NULL. Roxygen ⁠@description⁠ prose. Defaults to NULL.
details

String or NULL. Roxygen ⁠@details⁠ prose. Line breaks are kept so it can carry its own ⁠\itemize{}⁠, and lines over the width are wrapped. Defaults to NULL.
references

String or NULL. Roxygen ⁠@references⁠ prose. Defaults to NULL.
return_order

Character vector or NULL. The order of the returned list, when it differs from the order of the formals. Must be a permutation of names(fields). Defaults to NULL, meaning the order of the formals.
checker

String or NULL. PascalCase stem for the checkmate extension, giving ⁠check<stem>Params()⁠ and ⁠assert<stem>Params()⁠. Two specs may share a stem, in which case the checker is emitted once and the field sets must agree. NULL emits no checker. Defaults to the PascalCase form of name.
checker_args

A list made with base::alist(). Extra formals for the checker beyond x, for the checkers that cross-reference an outside object. Defaults to an empty list.
extra_ctor

Language object or NULL. Emitted verbatim into the constructor after the per-field assertions. For cross-field rules.
extra_check

Language object or NULL. Emitted verbatim into the checker before its final return. Must return() an error string on failure.
class_tag

String or NULL. When set, the returned list is tagged c(class_tag, "list"). Only for the params objects that are dispatched on with inherits(). Defaults to NULL.
strict_names

Boolean. TRUE demands exactly the declared names, FALSE uses must.include and tolerates extras. Defaults to FALSE.
label

String or NULL. Human readable label used in the checker's error messages. Defaults to name with underscores replaced by spaces, followed by "params".
hint

String or NULL. Appended to the checker's error messages to describe the expected types and ranges.
test_fn

Boolean. Also emit ⁠test<stem>Params()⁠ via checkmate::makeTestFunction(). Defaults to FALSE.
export

Boolean. Whether the constructor gets ⁠@export⁠. Defaults to TRUE.

Value

A list of class devforge_spec.

Check whether the generated files match the specs

Description

Regenerates into a temporary directory and compares. Meant for CI, so that a hand-edit of a generated file or a spec change that was never regenerated fails the build.

Usage

params_up_to_date(pkg = ".")

Arguments

pkg

String. Path to the package root. Defaults to ".".

Value

TRUE when everything matches, otherwise a character vector of the paths that are out of date.

Add the params drift workflow to a package

Description

Copies a GitHub Actions workflow into .github/workflows/params-drift.yml that installs devforge and fails the build when params_up_to_date() reports stale generated files. Also adds ⁠^\.github$⁠ to .Rbuildignore if it is not there yet.

Usage

use_drift_ci(
  pkg = ".",
  runner = "macos-latest",
  overwrite = FALSE,
  .verbose = TRUE
)

Arguments

pkg

String. Path to the package root. Defaults to ".".
runner

String. The GitHub Actions runner. Has to match the platform the specs are forged on: macOS arm64 R has no extended long double, so literals like 1e-300 deparse differently than on Linux and every file reads as stale. Defaults to "macos-latest".
overwrite

Boolean. Replace an existing workflow file. Defaults to FALSE.
.verbose

Boolean. Report what was written. Defaults to TRUE.

Value

The path of the workflow file, invisibly.