s7x provides utility extensions to the {S7} type system.
It fills the void of features I’ve long wanted in S7 (and R) to help make R packages more type safe(ish) with less boilerplate.
Notably s7x provides:
- an extensible
Enumclass for speficying enumerations - scalar properties
- arrays of S7 classes
- range propeties (discrete and continuous)
- property intersections
See Enums in R: towards type safe R for the motivation behind this package.
Installation
You can install the development version of s7x like so:
pak::pak("josiahparry/s7x")[!NOTE]
s7xis built on the development version ofS7. Install it withpak::pak("RConsortium/S7").
Enum(eration)s
In R, we use enumerations all the time, though in formally. For example, stats::cor()’s argument method = c("pearson", "kendall", "spearman") is an enumeration in that method can be only one of three possible values. In R, enums are typically strings and validated via arg.match() or the equivalent rlang::arg_match().
In s7x, enums are formalized through the s7x::Enum class.
library(s7x)
# create a new enum
CorMethod <- new_enum("CorMethod", c("pearson", "kendall", "spearman"))
# instantiate the enum
x <- CorMethod("pearson")
x
#> <CorMethod>
#> @ value : chr "pearson"
#> @ variants: chr [1:3] "pearson" "kendall" "spearman"
#> @ allow_na: logi TRUENote that all s7x::Enums can be cast as character vectors.
as.character(x)
#> [1] "pearson"Thus, we can use the Enum to enforce variants, but when we need the underlying value we can as.character() or extract it’s value via x@value.
Scalar properties
A longtime wish list item of mine is scalar properties. A scalar in R is a length one vector. These are useful for arguments such as n_components = 5—where it wouldn’t make sense for the value to be c(5, 1), for example.
S7 has built-in classes for the vector types in R (double, integer, character, list) but not for their scalar variants.
s7x introduces the property_scalar() function which lets you create scalar variants.
For example:
library(S7)
NComponents := new_class(
properties = list(n = property_scalar(S7::class_integer))
)
n_comps <- NComponents(5L)
n_comps
#> <NComponents>
#> @ n: int 5Providing a non-length 1 value creates an error:
NComponents(c(5L, 1L))
#> Error in `NComponents()`:
#> ! <NComponents> object properties are invalid:
#> - @n must be a scalar atomicRanges
For example, if you wanted to model a chess board:
Rank := new_class(
properties = list(number = property_range_discrete(1, 8, allow_na = FALSE))
)
File := new_class(
properties = list(number = property_range_discrete(1, 8, allow_na = FALSE))
)We can combine this with an enum and a normal S7 object to define the position of a chess piece.
Piece := new_enum(
c("Pawn", "Bishop", "Knight", "Rook", "Queen", "King"),
allow_na = FALSE,
default = "Pawn"
)
Square := new_class(
properties = list(
piece = Piece,
rank = Rank,
file = File
)
)
queen_start <- Square(
Piece("Queen"),
Rank(1L),
File(4L)
)
queen_start
#> <Square>
#> @ piece: <Piece>
#> .. @ value : chr "Queen"
#> .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" "Queen" "King"
#> .. @ allow_na: logi FALSE
#> @ rank : <Rank>
#> .. @ number: int 1
#> @ file : <File>
#> .. @ number: int 4Arrays
Often, you may want to contain an array of S7 objects.
The property_array() gives us strongly typed arrays of S7 objects. If we wanted to record the position of all of each player’s pieces at on turn we could create a new type that contains an array of Squares.
PlayerPieces := new_class(
properties = list(pieces = property_array(Square))
)
white <- PlayerPieces(
list(
queen_start,
Square(
Piece("King"),
Rank(1L),
File(5L)
)
)
)
white
#> <PlayerPieces>
#> @ pieces: List of 2
#> .. $ : <Square>
#> .. ..@ piece: <Piece>
#> .. .. .. @ value : chr "Queen"
#> .. .. .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" ...
#> .. .. .. @ allow_na: logi FALSE
#> .. ..@ rank : <Rank>
#> .. .. .. @ number: int 1
#> .. ..@ file : <File>
#> .. .. .. @ number: int 4
#> .. $ : <Square>
#> .. ..@ piece: <Piece>
#> .. .. .. @ value : chr "King"
#> .. .. .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" ...
#> .. .. .. @ allow_na: logi FALSE
#> .. ..@ rank : <Rank>
#> .. .. .. @ number: int 1
#> .. ..@ file : <File>
#> .. .. .. @ number: int 5Conversion to vectors
The s7x package introduces the generics as_vector() and from_vector() to provide conversion methods from base S3 vectors types such as a list, or character vector, etc.
The defualt implementation does the following:
-
S7objects: creates a named list of each property and value -
Enums: converts to a character vector -
Ranges: converts to a double or integer
You can create your own bespoke methods as well.
For example, we can use as_vector() to convert our Square() to a list.
queen_list <- as_vector(queen_start)
queen_list
#> $piece
#> [1] "Queen"
#>
#> $rank
#> $rank$number
#> [1] 1
#>
#>
#> $file
#> $file$number
#> [1] 4Additionally, if your data comes in the format of a list or another type, we can parse that into the correct S7 type using from_vector(object, S7_class).
round_tripped <- from_vector(queen_list, Square)
round_tripped
#> <Square>
#> @ piece: <Piece>
#> .. @ value : chr "Queen"
#> .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" "Queen" "King"
#> .. @ allow_na: logi FALSE
#> @ rank : <Rank>
#> .. @ number: int 1
#> @ file : <File>
#> .. @ number: int 4
# verify no differences
waldo::compare(queen_start, round_tripped)
#> ✔ No differencesJson conversion
Inspired by serde and serde_json in the rust ecosystem, s7x provides generics from_json() and to_json(). These use yyjsonr under the hood for fast performance.
to_json(white, pretty = TRUE) |>
cat()
#> {
#> "pieces": [
#> {
#> "piece": "Queen",
#> "rank": {
#> "number": 1
#> },
#> "file": {
#> "number": 4
#> }
#> },
#> {
#> "piece": "King",
#> "rank": {
#> "number": 1
#> },
#> "file": {
#> "number": 5
#> }
#> }
#> ]
#> }Now, we can call from_json() to parse this back into the correct type. This is particularly useful when you have a property_array() that you want to have as a list of your S7 class:
# round trip the json conversion
to_json(white) |>
from_json(PlayerPieces)
#> <PlayerPieces>
#> @ pieces: List of 2
#> .. $ : <Square>
#> .. ..@ piece: <Piece>
#> .. .. .. @ value : chr "Queen"
#> .. .. .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" ...
#> .. .. .. @ allow_na: logi FALSE
#> .. ..@ rank : <Rank>
#> .. .. .. @ number: int 1
#> .. ..@ file : <File>
#> .. .. .. @ number: int 4
#> .. $ : <Square>
#> .. ..@ piece: <Piece>
#> .. .. .. @ value : chr "King"
#> .. .. .. @ variants: chr [1:6] "Pawn" "Bishop" "Knight" "Rook" ...
#> .. .. .. @ allow_na: logi FALSE
#> .. ..@ rank : <Rank>
#> .. .. .. @ number: int 1
#> .. ..@ file : <File>
#> .. .. .. @ number: int 5Package Development
If using an Enum from s7x, call s7x::use_roxygen() so that you can use the @enum roclet to automatically generate variant level documentation.
For example: