Module expression 

Safe wrappers for R expression evaluation.

This module provides ergonomic types for building and evaluating R function calls from Rust, handling GC protection and error propagation automatically.

Types

Type	Purpose
RSymbol	Interned R symbol (SYMSXP)
RCall	Builder for R function calls (LANGSXP)
REnv	Well-known R environments
REvalError	An R error caught by RCall::eval / r_eval_str / try_eval_with_handlers

Example

use miniextendr_api::expression::{RCall, REnv};

unsafe {
    // Call paste0("hello", " world") in the base environment
    let result = RCall::new("paste0")
        .arg(Rf_mkString(c"hello".as_ptr()))
        .arg(Rf_mkString(c" world".as_ptr()))
        .eval(REnv::base().as_sexp())?;
}

Structs

EvalArgs 🔒

An R expression and the environment to evaluate it in: eval_body’s data.

RCall

Builder for constructing and evaluating R function calls.

REnv

Handle to a well-known R environment.

REvalError

An R error caught by RCall::eval / RCall::eval_base, r_eval_str, the helpers built on them (REnv::package_namespace, RCall::namespaced, dollar_extract), and try_eval_with_handlers / RCall::try_eval_with_handlers.

RSymbol

A safe wrapper around R symbols (SYMSXP).

TryEvalData 🔒

What catch_error shares with its callbacks.

Enums

Caught 🔒

How an evaluation with R errors caught ended. The SEXPs are unprotected.

Constants

BASE_ERROR_CLASSES 🔒

The trailing classes REvalError::specific_classes leaves out: R’s base error layers, and the rust_error layer a miniextendr function adds. error! and a Result return add them again.

EXIT_MESSAGE 🔒

The message of the simpleError that stands for an evaluation that jumped to the top level without an error condition.

Functions

catch_error 🔒 ^⚠

Run a TryEvalData’s body with error conditions caught (R_tryCatchError), and store its value, or the caught condition, in its slot. Returns R_tryCatchError’s value: the body’s, or NULL after an error (TryEvalData::outcome tells them apart).

condition_call 🔒 ^⚠

conditionCall(cond), or NULL if the method fails or the call is the tryCatch() frame’s (is_try_catch_frame_call). Unprotected.

condition_message 🔒 ^⚠

conditionMessage(cond), through S3 dispatch, so a class with its own method (rlang’s errors, say) words its message. If the method fails or returns no string: the condition’s message field, then a placeholder.

dollar_extract^⚠

Build and evaluate target$name — the R $ extraction operator.

dots_symbol 🔒 ^⚠

The symbol ....

eval_body 🔒 ^⚠

Evaluate an EvalArgs. An R error jumps from here to the tryCatch() frame, over no Rust frame holding anything to drop.

eval_with_handlers^⚠

Evaluate expr in env in the caller’s R context, the way R code calling eval(expr, env) does.

into_result 🔒 ^⚠

An evaluation’s outcome with a caught error as an REvalError. The value is unprotected.

is_try_catch_frame_call 🔒

Whether call is doTryCatch(return(expr), name, parentenv, handler), the frame of R’s tryCatch(), which R_tryCatchError evaluates in. An error raised at the top of the evaluated expression (stop() called directly, not from a function) takes that frame’s call as its own; it is no call of the user’s code, so REvalError::call reports None there. Base R’s try() recognises the frame by the same doTryCatch head.

needs_root 🔒

Whether value needs a GC root while Rust holds it across an allocation.

quote 🔒 ^⚠

quote(<value>), unprotected. value is rooted across the allocation unless it is a symbol (needs_root).

r_eval_str^⚠

Parse a string of R source and evaluate it in env.

r_eval_str_global^⚠

Parse and evaluate a string of R source in R_GlobalEnv.

string_vector 🔒 ^⚠

The elements of a character vector (NA as "NA"); empty for anything else. Does not allocate.

try_call_raw 🔒 ^⚠

Call body(body_data), hidden from the caller’s handlers and restarts (a new top-level context, R_ToplevelExec), with error conditions caught (catch_error).

try_eval 🔒 ^⚠

try_eval_raw with a caught error as an REvalError. The value is unprotected.

try_eval_raw 🔒 ^⚠

Evaluate expr in env as try_call_raw calls a body.

try_eval_unwinding 🔒 ^⚠

Evaluate expr in env in the caller’s R context, with error conditions caught (catch_error): the caller’s handlers and restarts stay in place, and any other R exit leaves as a Rust unwind (call_unwinding). Never Caught::Exit.

try_eval_with_handlers^⚠

Evaluate expr in env in the caller’s R context, as eval_with_handlers does, but return an R error as Err instead of letting it unwind.

without_try_catch_frame_call 🔒 ^⚠

cond, or a shallow copy of it whose call element is NULL when that element is the tryCatch() frame’s call: the condition REvalError::reraise signals, with the call REvalError::call reports.

Type Aliases

TryBody 🔒

A C callback run with R errors caught, given the caller’s data. An R error jumps out of it, so it holds nothing to drop.