Fix CRAN docs and harden FFI codegen

Author: sounkou-bioinfo

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: Rtinycc
 Title: Builds the 'TinyCC' Command-Line Interface and Library for 'C' Scripting in 'R'
-Version: 0.1.6
+Version: 0.1.7
 Authors@R: c(
     person(given = "Sounkou Mahamane", family = "Toure", 
     email = "sounkoutoure@gmail.com", role = c("aut", "cre")),

NEWS.md

@@ -1,3 +1,13 @@
+# Rtinycc 0.1.7
+
+- Add missing return-value documentation across exported helpers and print
+  methods so generated reference pages consistently describe result class,
+  meaning, or side-effect-only behavior.
+
+- Update vignettes to ensure each article executes ordinary R code during
+  builds, and correct conservative type-mapping docs so `const char *`
+  examples reflect the default `ptr` mapping.
+
 # Rtinycc 0.1.6
 
 - Exclude the top-level `scripts/` directory more explicitly from package

R/aaa.R

@@ -9,4 +9,9 @@
 NULL
 
 #' we are using .Call directly, this is to make R CMD check happy
+#'
+#' @return The result returned by the invoked native routine. This alias is
+#'   package-internal and exists to satisfy `R CMD check` native routine
+#'   registration requirements.
+#' @keywords internal
 .RtinyccCall <- base::.Call

R/callbacks.R

@@ -119,6 +119,9 @@ tcc_callback_ptr <- function(callback) {
 #'
 #' @param x A tcc_callback object
 #' @param ... Ignored
+#' @return The input `tcc_callback` object, invisibly. Called for its
+#'   side effect of printing the callback signature, thread-safety flag,
+#'   and validity status.
 #' @export
 print.tcc_callback <- function(x, ...) {
   sig <- attr(x, "signature")

R/ffi.R

@@ -1811,6 +1811,9 @@ make_callable <- function(fn_ptr, sym, state) {
 #'
 #' @param x A tcc_ffi object
 #' @param ... Ignored
+#' @return The input `tcc_ffi` object, invisibly. Called for its side
+#'   effect of printing the configured output mode, registered symbols,
+#'   and selected libraries/include paths.
 #' @export
 print.tcc_ffi <- function(x, ...) {
   cat("<tcc_ffi>\n")
@@ -1836,6 +1839,9 @@ print.tcc_ffi <- function(x, ...) {
 #'
 #' @param x A tcc_compiled object
 #' @param ... Ignored
+#' @return The input `tcc_compiled` object, invisibly. Called for its side
+#'   effect of printing the compilation output mode and the status of
+#'   compiled callable symbols.
 #' @export
 print.tcc_compiled <- function(x, ...) {
   cat("<tcc_compiled>\n")
@@ -2226,6 +2232,13 @@ tcc_cstring_object <- function(ptr, clone = TRUE, owned = FALSE) {
   obj
 }
 
+#' Convert a `tcc_cstring` object to an R string
+#'
+#' @param x A `tcc_cstring` object.
+#' @param ... Ignored.
+#' @return A character scalar containing the string value. Returns the
+#'   cached R copy when available; otherwise reads the current NUL-terminated
+#'   C string from `x$ptr`.
 #' @export
 as.character.tcc_cstring <- function(x, ...) {
   if (!is.null(x$cached_string)) {
@@ -2234,6 +2247,12 @@ as.character.tcc_cstring <- function(x, ...) {
   tcc_read_cstring(x$ptr)
 }
 
+#' Print a `tcc_cstring` object
+#'
+#' @param x A `tcc_cstring` object.
+#' @param ... Ignored.
+#' @return The input `tcc_cstring` object, invisibly. Called for its side
+#'   effect of printing the current string value.
 #' @export
 print.tcc_cstring <- function(x, ...) {
   str <- as.character(x)

R/ffi_codegen.R

@@ -1088,8 +1088,51 @@ union_field_setter_lines <- function(type_name, mem_name, size) {
   union_field_setter_rule(type_name, mem_name, size)
 }
 
+ffi_input_array_check_rule <- function(ffi_type, arg_name, r_name) {
+  check_line <- switch(
+    ffi_type,
+    raw = sprintf(
+      "  if (TYPEOF(%s) != RAWSXP) Rf_error(\"expected raw vector for argument '%s'\");",
+      r_name,
+      arg_name
+    ),
+    integer_array = sprintf(
+      "  if (TYPEOF(%s) != INTSXP) Rf_error(\"expected integer vector for argument '%s'\");",
+      r_name,
+      arg_name
+    ),
+    numeric_array = sprintf(
+      "  if (TYPEOF(%s) != REALSXP) Rf_error(\"expected numeric vector for argument '%s'\");",
+      r_name,
+      arg_name
+    ),
+    logical_array = sprintf(
+      "  if (TYPEOF(%s) != LGLSXP) Rf_error(\"expected logical vector for argument '%s'\");",
+      r_name,
+      arg_name
+    ),
+    character_array = sprintf(
+      "  if (!Rf_isString(%s)) Rf_error(\"expected character vector for argument '%s'\");",
+      r_name,
+      arg_name
+    ),
+    NULL
+  )
+
+  if (is.null(check_line)) {
+    return(NULL)
+  }
+
+  paste(c(check_line, ffi_input_rule(ffi_type, arg_name, r_name)), collapse = "\n")
+}
+
 ffi_input_special_rule <- function(ffi_type, arg_name, r_name) {
   special_map <- list(
+    raw = function() ffi_input_array_check_rule(ffi_type, arg_name, r_name),
+    integer_array = function() ffi_input_array_check_rule(ffi_type, arg_name, r_name),
+    numeric_array = function() ffi_input_array_check_rule(ffi_type, arg_name, r_name),
+    logical_array = function() ffi_input_array_check_rule(ffi_type, arg_name, r_name),
+    character_array = function() ffi_input_array_check_rule(ffi_type, arg_name, r_name),
     "enum:" = function() ffi_input_enum_rule(ffi_type, arg_name, r_name),
     "callback" = function() ffi_input_callback_rule(ffi_type, arg_name, r_name)
   )

R/tcc_ptr_utils.R

@@ -8,6 +8,8 @@
 #' These utilities handle pointer creation, buffer management, and memory operations
 #' that are commonly needed when working with external libraries.
 #'
+#' @return No return value. This is a documentation topic that groups the
+#'   pointer and buffer utility functions described below.
 #' @name tcc_ptr_utils
 NULL
 
@@ -274,62 +276,80 @@ tcc_write_i8 <- function(ptr, offset, value) {
 
 #' Write an unsigned 8-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   unsigned 8-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_u8 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_u8, ptr, offset, value))
 }
 
 #' Write a signed 16-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   signed 16-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_i16 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_i16, ptr, offset, value))
 }
 
 #' Write an unsigned 16-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   unsigned 16-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_u16 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_u16, ptr, offset, value))
 }
 
 #' Write a signed 32-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   signed 32-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_i32 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_i32, ptr, offset, value))
 }
 
 #' Write an unsigned 32-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   unsigned 32-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_u32 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_u32, ptr, offset, value))
 }
 
 #' Write a signed 64-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   signed 64-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_i64 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_i64, ptr, offset, value))
 }
 
 #' Write an unsigned 64-bit integer
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   unsigned 64-bit value into native memory at `ptr + offset`.
 #' @export
 tcc_write_u64 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_u64, ptr, offset, value))
 }
 
 #' Write a 32-bit float
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   32-bit floating-point value into native memory at `ptr + offset`.
 #' @export
 tcc_write_f32 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_f32, ptr, offset, value))
 }
 
 #' Write a 64-bit double
 #' @inheritParams tcc_write_i8
+#' @return `NULL` (invisibly). Called for its side effect of writing one
+#'   64-bit floating-point value into native memory at `ptr + offset`.
 #' @export
 tcc_write_f64 <- function(ptr, offset, value) {
   invisible(.Call(RC_write_f64, ptr, offset, value))

R/treesitter_helpers.R

@@ -249,6 +249,9 @@ tcc_map_c_type_to_ffi <- function(c_type) {
       return(type_str)
     }
     last <- parts[length(parts)]
+    if (last %in% c("*", "**") || grepl("^\\*+", last)) {
+      return(type_str)
+    }
     type_tokens <- c(
       "void",
       "bool",

inst/tinytest/test_codegen_soundness.R

@@ -350,6 +350,47 @@ expect_equal(
   info = "logical_array round-trip preserves all values"
 )
 
+# Array input wrappers reject wrong SEXPTYPE before borrowing vector storage.
+ffi <- tcc_ffi() |>
+  tcc_source(
+    "
+    void touch_raw(unsigned char* buf) { (void) buf; }
+    void touch_ints(int* x) { (void) x; }
+    void touch_nums(double* x) { (void) x; }
+    void touch_lgl(int* x) { (void) x; }
+    void touch_chars(SEXP* x) { (void) x; }
+  "
+  ) |>
+  tcc_bind(
+    touch_raw = list(args = list("raw"), returns = "void"),
+    touch_ints = list(args = list("integer_array"), returns = "void"),
+    touch_nums = list(args = list("numeric_array"), returns = "void"),
+    touch_lgl = list(args = list("logical_array"), returns = "void"),
+    touch_chars = list(args = list("character_array"), returns = "void")
+  ) |>
+  tcc_compile()
+
+expect_error(
+  ffi$touch_raw(1:3),
+  info = "raw input rejects non-raw vectors before borrowing"
+)
+expect_error(
+  ffi$touch_ints(c(1, 2, 3)),
+  info = "integer_array input rejects non-integer vectors before borrowing"
+)
+expect_error(
+  ffi$touch_nums(1:3),
+  info = "numeric_array input rejects non-numeric vectors before borrowing"
+)
+expect_error(
+  ffi$touch_lgl(c(1L, 0L, 1L)),
+  info = "logical_array input rejects non-logical vectors before borrowing"
+)
+expect_error(
+  ffi$touch_chars(list("a", "b")),
+  info = "character_array input rejects non-character vectors before borrowing"
+)
+
 # NULL array return -> R_NilValue
 ffi <- tcc_ffi() |>
   tcc_source(
@@ -369,6 +410,32 @@ expect_true(
   info = "NULL array return gives R NULL"
 )
 
+# Zero-length array returns still round-trip as empty R vectors when C returns
+# a non-NULL buffer. This guards the wrapper path used in the benchmark
+# vignette, where length 0 should yield numeric(0) rather than NULL.
+ffi <- tcc_ffi() |>
+  tcc_source(
+    "
+    #include <stdlib.h>
+    double* zero_vec(int n) {
+      if (n != 0) return NULL;
+      return (double*) malloc(sizeof(double));
+    }
+  "
+  ) |>
+  tcc_bind(
+    zero_vec = list(
+      args = list("i32"),
+      returns = list(type = "numeric_array", length_arg = 1, free = TRUE)
+    )
+  ) |>
+  tcc_compile()
+expect_equal(
+  ffi$zero_vec(0L),
+  numeric(0),
+  info = "zero-length array return with non-NULL buffer yields empty R vector"
+)
+
 # ===========================================================================
 # 4. STRUCT FIELD ROUND-TRIPS: set field, read it back for each type
 # ===========================================================================
@@ -1086,6 +1153,23 @@ expect_equal(
 )
 expect_equal(r, "hello", info = "cstring return: correct value")
 
+# Regression: const-qualified char* returns must compile and box correctly.
+ffi <- tcc_ffi() |>
+  tcc_source(
+    "
+    const char* const_message(void) {
+      return \"const-ok\";
+    }
+  "
+  ) |>
+  tcc_bind(const_message = list(args = list(), returns = "cstring")) |>
+  tcc_compile()
+expect_equal(
+  ffi$const_message(),
+  "const-ok",
+  info = "const char* return compiles and boxes into an R string"
+)
+
 # wrapper argument single-eval
 ffi <- tcc_ffi() |>
   tcc_source("int add3(int a, int b, int c) { return a + b + c; }") |>

inst/tinytest/test_ffi_codegen.R

@@ -20,15 +20,23 @@ expect_true(grepl("bool flag = (bool)(_flag != 0)", code, fixed = TRUE))
 
 # Test 2: Generate C input for array types
 code <- Rtinycc:::generate_c_input("buf", "arg1_", "raw")
+expect_true(grepl("TYPEOF\\(arg1_\\) != RAWSXP", code))
 expect_true(grepl("uint8_t[*] buf = RAW", code))
 
 code <- Rtinycc:::generate_c_input("arr", "arg1_", "integer_array")
+expect_true(grepl("TYPEOF\\(arg1_\\) != INTSXP", code))
 expect_true(grepl("int32_t[*] arr = INTEGER", code))
 
 code <- Rtinycc:::generate_c_input("nums", "arg1_", "numeric_array")
+expect_true(grepl("TYPEOF\\(arg1_\\) != REALSXP", code))
 expect_true(grepl("double[*] nums = REAL", code))
 
+code <- Rtinycc:::generate_c_input("flags", "arg1_", "logical_array")
+expect_true(grepl("TYPEOF\\(arg1_\\) != LGLSXP", code))
+expect_true(grepl("int[*] flags = LOGICAL", code))
+
 code <- Rtinycc:::generate_c_input("chars", "arg1_", "character_array")
+expect_true(grepl("Rf_isString\\(arg1_\\)", code))
 expect_true(grepl("STRING_PTR_RO", code, fixed = TRUE))
 
 # Test 3: Generate C return code