man-roxygen/class_prototype.R

In jeanmathieupotvin/cargo: Data containers, schemas and prototypes

# class_prototype.R


#' @name Prototype-class
#'
#' @title
#' Prototype: a class to define prototypes of \R objects
#'
#' @description
#' A formal class to rigorously define prototypes of any \R objects.
#'
#' @section The Prototype class:
#' Class `Prototype` holds consistent prototypes of any \R object. A
#' *consistent prototype* theoretically has three components:
#'
#' 1. a representation in \R (here called an archetype);
#' 2. an enclosure (the environment holding the arechetype's class definition);
#' 3. a constructor function that generates the archetype.
#'
#' The third component is needed because two different functions defined in the
#' same enclosure can theoretically return two objects of the same class based
#' on two different class definitions. In practice, this never happens, because
#' it breaks \R usual method dispatching mechanisms.
#'
#' @section Using the class:
#' The API is intentionally kept minimal, since the class is mostly intended
#' to be used within class [`Schema`][Schema-class].
#'
#' * Create objects of class `Prototype` through the constructor function
#' [Prototype()].
#' * Validate instances of the class by using [valid_prototype()].
#' * Test objects for class `Prototype` with introspector function
#' [is_prototype()].
#' * Extract slots from instances of the class with functions [archetype()],
#' [enclosure()] and [constructor()].
#' * Set new values to slots with functions [`archetype<-()`][archetype()],
#' [`enclosure<-()`][enclosure()] and [`constructor<-()`][constructor()].
#' * Methods for class `Prototype` are implemented for generic functions
#' [format()] and [show()].
#'
#' @family Prototype