Skip to main content

Module expression

Module expression 

Source
Expand description

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

TypePurpose
RSymbolInterned R symbol (SYMSXP)
RCallBuilder for R function calls (LANGSXP)
REnvWell-known R environments
REvalErrorAn 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())?;
}

Re-exportsยง

use crate::condition::ConditionClass; ๐Ÿ”’
use crate::from_r::TryFromSexp; ๐Ÿ”’
use crate::gc_protect::OwnedProtect; ๐Ÿ”’
use crate::gc_protect::ProtectScope; ๐Ÿ”’
use crate::into_r::IntoR; ๐Ÿ”’
use crate::protect_pool::ProtectPool; ๐Ÿ”’
use crate::sexp_ext::PairListExt; ๐Ÿ”’
use crate::sys; ๐Ÿ”’
use crate::sys::ParseStatus; ๐Ÿ”’
use crate::sys::R_BaseEnv; ๐Ÿ”’
use crate::sys::R_EmptyEnv; ๐Ÿ”’
use crate::sys::R_GlobalEnv; ๐Ÿ”’
use crate::sys::R_ParseVector; ๐Ÿ”’
use crate::sys::Rf_install; ๐Ÿ”’
use crate::SEXP; ๐Ÿ”’
use crate::SexpExt; ๐Ÿ”’
use std::ffi::CStr; ๐Ÿ”’
use std::ffi::CString; ๐Ÿ”’
use std::os::raw::c_void; ๐Ÿ”’

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.