Implement specify_fct()

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: hrmn
 Title: Harmonize Datasets
-Version: 0.0.0.9000
+Version: 0.0.0.9001
 Authors@R:
     person("Jon", "Harmon", , "jonthegeek@gmail.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-4781-4346"))
@@ -20,4 +20,6 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 Language: en-US
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.3.3
+RoxygenNote: 7.3.3
+Imports:
+    S7

NAMESPACE

@@ -1,2 +1,4 @@
 # Generated by roxygen2: do not edit by hand
 
+export(specify_fct)
+if (getRversion() < "4.3.0") importFrom("S7", "@")

R/specify_fct.R

@@ -0,0 +1,34 @@
+# Developer note: `specify_fct()` is designed to create a data-less
+# "specification" object. It defines the target state (the levels) for a factor
+# but doesn't hold any actual factor data itself. This is why the constructor
+# internally provides `integer()` as the data component to `S7::new_object()`.
+#
+# In the future, we might use the `hrmn_fct` class to represent actual,
+# harmonized factor data. In that scenario, we would likely create a separate
+# `class_hrmn_fct` object and have `specify_fct()` be a wrapper function that
+# calls the constructor with the empty data. For now, since we don't need the
+# full factor-like class, we are directly defining the `hrmn_fct` class in
+# `specify_fct()`
+
+#' Specify a factor harmonization
+#'
+#' Create a `hrmn_fct` object that specifies the desired levels for a factor
+#' variable. This 'specification' object does not contain any data itself, only
+#' the rules for harmonization.
+#'
+#' @param levels (`character`) The allowed values of the factor.
+#' @returns A factor specification, an S7 object of class `hrmn::hrmn_fct`.
+#' @export
+specify_fct <- S7::new_class(
+  "hrmn_fct",
+  parent = S7::class_factor,
+  properties = list(
+    levels = S7::class_character
+  ),
+  constructor = function(levels = character()) {
+    S7::new_object(
+      integer(),
+      levels = levels
+    )
+  }
+)

R/zzz.R

@@ -0,0 +1,3 @@
+# enable usage of <S7_object>@name in package code
+#' @rawNamespace if (getRversion() < "4.3.0") importFrom("S7", "@")
+NULL

tests/testthat/test-specify_fct.R

@@ -0,0 +1,14 @@
+test_that("specify_fct() returns an object with the correct class", {
+  spec <- specify_fct()
+  expect_s3_class(
+    spec,
+    c("hrmn::hrmn_fct", "factor", "S7_object"),
+    exact = TRUE
+  )
+})
+
+test_that("specify_fct() stores the levels", {
+  lvls <- c("a", "b", "c")
+  spec <- specify_fct(levels = lvls)
+  expect_equal(spec@levels, lvls)
+})