| Title: | Runtime Type System |
|---|---|
| Description: | Provides a runtime type system, allowing users to define and implement interfaces, enums, typed data.frame/data.table, as well as typed functions. This package enables stricter type checking and validation, improving code structure, robustness and reliability. |
| Authors: | Dereck Mezquita [aut, cre]
|
| Maintainer: | Dereck Mezquita <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.2 |
| Built: | 2025-01-09 06:58:23 UTC |
| Source: | CRAN |
Allows modifying a typed data frame using the [ ] operator, with validation checks.
## S3 replacement method for class 'typed_frame' x[i, j] <- value## S3 replacement method for class 'typed_frame' x[i, j] <- value
x |
A typed data frame. |
i |
Row index. |
j |
Column index or name. |
value |
The new value to assign. |
The modified typed data frame.
Compares two enum objects or an enum object with a character value.
## S3 method for class 'enum' e1 == e2## S3 method for class 'enum' e1 == e2
e1 |
First enum object |
e2 |
Second enum object or a character value |
Logical value indicating whether the two objects are equal
Retrieves the value of an enum object.
## S3 method for class 'enum' x$name## S3 method for class 'enum' x$name
x |
An enum object |
name |
The name of the field to access (should be "value") |
The value of the enum object
Get a property from an interface object
## S3 method for class 'interface_object' x$name## S3 method for class 'interface_object' x$name
x |
An interface object |
name |
The name of the property to get |
The value of the specified property. The class of the returned value depends on the property's type as defined in the interface.
Sets the value of an enum object. The new value must be one of the valid enum values.
## S3 replacement method for class 'enum' x$name <- value## S3 replacement method for class 'enum' x$name <- value
x |
An enum object |
name |
The name of the field to set (should be "value") |
value |
The new value to set |
The updated enum object
Set a property in an interface object
## S3 replacement method for class 'interface_object' x$name <- value## S3 replacement method for class 'interface_object' x$name <- value
x |
An interface object |
name |
The name of the property to set |
value |
The new value for the property |
The modified interface object, invisibly.
Allows modifying a typed data frame using the $ operator, with validation checks.
## S3 replacement method for class 'typed_frame' x$col_name <- value## S3 replacement method for class 'typed_frame' x$col_name <- value
x |
A typed data frame. |
col_name |
The name of the column to modify or add. |
value |
The new value to assign. |
The modified typed data frame.
Creates an enumerated type with a fixed set of possible values. This function returns an enum generator, which can be used to create enum objects with values restricted to the specified set.
enum(...)enum(...)
... |
The possible values for the enumerated type. These should be unique character strings. |
A function (enum generator) of class 'enum_generator' that creates enum objects of the defined type. The returned function takes a single argument and returns an object of class 'enum'.
interface for using enums in interfaces
# Create an enum type for colors Colors <- enum("red", "green", "blue") # Create enum objects my_color <- Colors("red") print(my_color) # Output: Enum: red # Trying to create an enum with an invalid value will raise an error try(Colors("yellow")) # Enums can be used in interfaces ColoredShape <- interface( shape = character, color = Colors ) my_shape <- ColoredShape(shape = "circle", color = "red") # Modifying enum values my_shape$color$value <- "blue" # This is valid try(my_shape$color$value <- "yellow") # This will raise an error# Create an enum type for colors Colors <- enum("red", "green", "blue") # Create enum objects my_color <- Colors("red") print(my_color) # Output: Enum: red # Trying to create an enum with an invalid value will raise an error try(Colors("yellow")) # Enums can be used in interfaces ColoredShape <- interface( shape = character, color = Colors ) my_shape <- ColoredShape(shape = "circle", color = "red") # Modifying enum values my_shape$color$value <- "blue" # This is valid try(my_shape$color$value <- "yellow") # This will raise an error
Defines a function with specified parameter types and return type. Ensures that the function's arguments and return value adhere to the specified types.
fun(...)fun(...)
... |
Named arguments defining the function parameters and their types, including 'return' for the expected return type(s) and 'impl' for the function implementation. |
The 'fun' function allows you to define a function with strict type checking for its parameters and return value. This ensures that the function receives arguments of the correct types and returns a value of the expected type. The 'return' and 'impl' arguments should be included in the ... parameter list.
A function of class 'typed_function' that enforces type constraints on its parameters and return value. The returned function has the same signature as the implementation function provided in the 'impl' argument.
# Define a typed function that adds two numbers add_numbers <- fun( x = numeric, y = numeric, return = numeric, impl = function(x, y) { return(x + y) } ) # Valid call print(add_numbers(1, 2)) # [1] 3 # Invalid call (throws error) try(add_numbers("a", 2)) # Define a typed function with multiple return types concat_or_add <- fun( x = c(numeric, character), y = numeric, return = c(numeric, character), impl = function(x, y) { if (is.numeric(x)) { return(x + y) } else { return(paste(x, y)) } } ) # Valid calls print(concat_or_add(1, 2)) # [1] 3 print(concat_or_add("a", 2)) # [1] "a 2"# Define a typed function that adds two numbers add_numbers <- fun( x = numeric, y = numeric, return = numeric, impl = function(x, y) { return(x + y) } ) # Valid call print(add_numbers(1, 2)) # [1] 3 # Invalid call (throws error) try(add_numbers("a", 2)) # Define a typed function with multiple return types concat_or_add <- fun( x = c(numeric, character), y = numeric, return = c(numeric, character), impl = function(x, y) { if (is.numeric(x)) { return(x + y) } else { return(paste(x, y)) } } ) # Valid calls print(concat_or_add(1, 2)) # [1] 3 print(concat_or_add("a", 2)) # [1] "a 2"
Handles violations by either throwing an error, issuing a warning, or doing nothing, depending on the specified action.
handle_violation(message, action)handle_violation(message, action)
message |
The error message to be handled. |
action |
The action to take: "error", "warning", or "silent". |
An interface defines a structure with specified properties and their types or validation functions. This is useful for ensuring that objects adhere to a particular format and type constraints.
interface(..., validate_on_access = FALSE, extends = list())interface(..., validate_on_access = FALSE, extends = list())
... |
Named arguments defining the properties and their types or validation functions. |
validate_on_access |
Logical, whether to validate properties on access (default: FALSE). |
extends |
A list of interfaces that this interface extends. |
A function of class 'interface' that creates objects implementing the defined interface. The returned function takes named arguments corresponding to the interface properties and returns an object of class 'interface_object'.
# Define an interface for a person Person <- interface( name = character, age = numeric, email = character ) # Create an object that implements the Person interface john <- Person( name = "John Doe", age = 30, email = "[email protected]" ) # Using enum in an interface Colors <- enum("red", "green", "blue") ColoredShape <- interface( shape = character, color = Colors ) my_shape <- ColoredShape(shape = "circle", color = "red") # In-place enum declaration Car <- interface( make = character, model = character, color = enum("red", "green", "blue") ) my_car <- Car(make = "Toyota", model = "Corolla", color = "red")# Define an interface for a person Person <- interface( name = character, age = numeric, email = character ) # Create an object that implements the Person interface john <- Person( name = "John Doe", age = 30, email = "[email protected]" ) # Using enum in an interface Colors <- enum("red", "green", "blue") ColoredShape <- interface( shape = character, color = Colors ) my_shape <- ColoredShape(shape = "circle", color = "red") # In-place enum declaration Car <- interface( make = character, model = character, color = enum("red", "green", "blue") ) my_car <- Car(make = "Toyota", model = "Corolla", color = "red")
Prints a human-readable representation of an enum object.
## S3 method for class 'enum' print(x, ...)## S3 method for class 'enum' print(x, ...)
x |
An enum object |
... |
Additional arguments (not used) |
No return value, called for side effects. Prints a string representation of the enum object to the console.
Prints a human-readable representation of an enum generator, showing all possible values.
## S3 method for class 'enum_generator' print(x, ...)## S3 method for class 'enum_generator' print(x, ...)
x |
An enum generator function |
... |
Additional arguments (not used) |
No return value, called for side effects. Prints a string representation of the enum generator to the console.
Print method for interface objects
## S3 method for class 'interface_object' print(x, ...)## S3 method for class 'interface_object' print(x, ...)
x |
An object implementing an interface |
... |
Additional arguments (not used) |
No return value, called for side effects. Prints a human-readable representation of the interface object to the console.
Provides a custom print method for typed data frames, displaying their properties and validation status.
## S3 method for class 'typed_frame' print(x, ...)## S3 method for class 'typed_frame' print(x, ...)
x |
A typed data frame. |
... |
Additional arguments passed to print. |
No return value, called for side effects. Prints a summary of the typed data frame to the console, including its dimensions, column specifications, frame properties, and a preview of the data.
Provides a custom print method for typed functions, displaying their parameter types and return type.
## S3 method for class 'typed_function' print(x, ...)## S3 method for class 'typed_function' print(x, ...)
x |
A typed function. |
... |
Additional arguments (not used). |
No return value, called for side effects. Prints a human-readable representation of the typed function to the console, showing the argument types and return type.
This function combines multiple typed data frames row-wise, ensuring type consistency and applying row validation rules.
It extends the base rbind function by adding type checks and row validation based on the specified rules for typed data frames.
## S3 method for class 'typed_frame' rbind(..., deparse.level = 1)## S3 method for class 'typed_frame' rbind(..., deparse.level = 1)
... |
Typed data frames to combine. |
deparse.level |
See |
This version of rbind for typed_frame performs extra type checking and row validation to ensure consistency and adherence to specified rules.
Refer to the base rbind documentation for additional details on combining data frames: rbind.
The combined typed data frame. The returned object is of class 'typed_frame' and inherits all properties (column types, validation rules, etc.) from the first data frame in the list.
Creates a data frame with specified column types and validation rules. Ensures that the data frame adheres to the specified structure and validation rules during creation and modification.
type.frame( frame, col_types, freeze_n_cols = TRUE, row_callback = NULL, allow_na = TRUE, on_violation = c("error", "warning", "silent") )type.frame( frame, col_types, freeze_n_cols = TRUE, row_callback = NULL, allow_na = TRUE, on_violation = c("error", "warning", "silent") )
frame |
The base data structure (e.g., data.frame, data.table). |
col_types |
A list of column types and validators. |
freeze_n_cols |
Logical, whether to freeze the number of columns (default: TRUE). |
row_callback |
A function to validate and process each row (optional). |
allow_na |
Logical, whether to allow NA values (default: TRUE). |
on_violation |
Action to take on violation: "error", "warning", or "silent" (default: "error"). |
The 'type.frame' function defines a blueprint for a data frame, specifying the types of its columns and optional validation rules for its rows. When a data frame is created or modified using this blueprint, it ensures that all data adheres to the specified rules.
A function that creates typed data frames. When called, this function returns an object of class 'typed_frame' (which also inherits from the base frame class used, i.e. data.frame, data.table).
# Define a typed data frame PersonFrame <- type.frame( frame = data.frame, col_types = list( id = integer, name = character, age = numeric, is_student = logical ) ) # Create a data frame persons <- PersonFrame( id = 1:3, name = c("Alice", "Bob", "Charlie"), age = c(25, 30, 35), is_student = c(TRUE, FALSE, TRUE) ) print(persons) # Invalid modification (throws error) try(persons$id <- letters[1:3]) # Adding a column (throws error if freeze_n_cols is TRUE) try(persons$yeet <- letters[1:3])# Define a typed data frame PersonFrame <- type.frame( frame = data.frame, col_types = list( id = integer, name = character, age = numeric, is_student = logical ) ) # Create a data frame persons <- PersonFrame( id = 1:3, name = c("Alice", "Bob", "Charlie"), age = c(25, 30, 35), is_student = c(TRUE, FALSE, TRUE) ) print(persons) # Invalid modification (throws error) try(persons$id <- letters[1:3]) # Adding a column (throws error if freeze_n_cols is TRUE) try(persons$yeet <- letters[1:3])
Validates a property to ensure it matches the expected type or satisfies the given validation function.
validate_property(name, value, validator)validate_property(name, value, validator)
name |
The name of the property being validated. |
value |
The value of the property. |
validator |
The expected type or a custom validation function. |
This function supports various types of validators: - Enum generators - Lists of multiple allowed types - Interface objects - Built-in R types (character, numeric, logical, integer, double, complex) - data.table and data.frame types - Custom validation functions
Returns NULL if the validation passes, otherwise returns a character string containing an error message describing why the validation failed.
Modifies a user-defined function to wrap its body in an all() call, ensuring that it returns a single logical value instead of a vector.
It uses bquote() to create a new body for the function. The .() inside bquote() inserts the original body of the function. The all() function wraps around the original body.
wrap_fun_in_all(user_fun)wrap_fun_in_all(user_fun)
user_fun |
A user-defined function. |
The modified function.