Native input specification

This document is for developers' reference and/or curious eyes who'd like an early-bird preview of new input specifications.

Rationale: old inputs suck because they differ from native R classes. Instead of rolling our own inventions, why not embrace the (implicit) conventions from R ecosystem and build/define inputs according to them? Writing templates should be straightforward and rapport should make you warm and fuzzy inside.

Native input specification

Native input specification takes leverage or R base classes, thus not relying on custom "inventions" when defining template inputs. Following specifications are to depict the current state of implementation along with conventions used in it. Unlike old input specification that relied on rather cumbersome custom syntax, new input specification is 100% pure YAML, with some custom (but graspable) attributes.

Inputs can be divided into two categories:

• dataset inputs (non-standalone) - inputs that match the named element in the object provided in data formal argument in rapport call. This is usually a data.frame object, but can/should be any object that allows subsetting by name. Dataset inputs cannot have the default value, so they always require user input. Note that this is not the same as required input attribute.
• standalone inputs don't depend on object passed in data. They accept (default) value attribute in the template definition, and user can override that value by passing an appropriate object (of matching class) in the rapport call.

General input options

All inputs can accept following options:

• name (character string) - input name. Cannot be blank, as mapped inputs will be assigned to that name in evaluation environment.

• label (character string) - input label. Can be blank, but it's useful to have something in there in order to get pretty output in a report (e.g. Number of hours is by far more descriptive than nwhours). Defaults to empty string.

• description (character string) - input description. It can be blank, but sometimes it's convenient to have a lengthy description of provided input. Defaults to empty string.

• required (logical value) - is input required (defaults to FALSE). If TRUE, input must match the subset of object provided in data argument (for dataset inputs) or user has to provide a value for that input/default value has to be defined in the template (if standalone).

• standalone (logical value) - does input depend on provided data. Defaults to FALSE.

• length - provides set of rules for input's length restriction. It can accept various attributes, e.g.

  • if integer value is provided, it refers to exactly N inputs:

length: 10

which is equivalent to (and will be parsed as):

length:
  exactly: 10

• from and to attributes can be passed to define a range that input's length must fall into:

length:
  from: 1
  to: 10

from or to can be omitted, and the sane defaults will be set implicitly. For instance, by omitting to, it will default to Inf, and if omitting from it will be set to 1.

length:
  from: 1

is identical to:

length:
  from: 1
  to: Inf

or:

length:
  to: 10

is equivalent to:

length:
  from: 1
  to: 10