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
| 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())?;
}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ยง
- Eval
Args ๐ - 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.
- REval
Error - 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), andtry_eval_with_handlers/RCall::try_eval_with_handlers. - RSymbol
- A safe wrapper around R symbols (SYMSXP).
- TryEval
Data ๐ - What
catch_errorshares 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_classesleaves out: Rโs base error layers, and therust_errorlayer a miniextendr function adds.error!and aResultreturn add them again. - EXIT_
MESSAGE ๐ - The message of the
simpleErrorthat stands for an evaluation that jumped to the top level without an error condition.
Functionsยง
- catch_
error ๐ โ - Run a
TryEvalDataโs body witherrorconditions caught (R_tryCatchError), and store its value, or the caught condition, in its slot. ReturnsR_tryCatchErrorโs value: the bodyโs, orNULLafter an error (TryEvalData::outcometells them apart). - condition_
call ๐ โ conditionCall(cond), orNULLif the method fails or the call is thetryCatch()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โsmessagefield, 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 thetryCatch()frame, over no Rust frame holding anything to drop. - eval_
with_ โhandlers - Evaluate
exprinenvin the callerโs R context, the way R code callingeval(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
callisdoTryCatch(return(expr), name, parentenv, handler), the frame of RโstryCatch(), whichR_tryCatchErrorevaluates 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, soREvalError::callreportsNonethere. Base Rโstry()recognises the frame by the samedoTryCatchhead. - needs_
root ๐ - Whether
valueneeds a GC root while Rust holds it across an allocation. - quote ๐ โ
quote(<value>), unprotected.valueis 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 (
NAas"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), witherrorconditions caught (catch_error). - try_
eval ๐ โ try_eval_rawwith a caught error as anREvalError. The value is unprotected.- try_
eval_ ๐ โraw - Evaluate
exprinenvastry_call_rawcalls a body. - try_
eval_ ๐ โunwinding - Evaluate
exprinenvin the callerโs R context, witherrorconditions caught (catch_error): the callerโs handlers and restarts stay in place, and any other R exit leaves as a Rust unwind (call_unwinding). NeverCaught::Exit. - try_
eval_ โwith_ handlers - Evaluate
exprinenvin the callerโs R context, aseval_with_handlersdoes, but return an R error asErrinstead of letting it unwind. - without_
try_ ๐ โcatch_ frame_ call cond, or a shallow copy of it whosecallelement isNULLwhen that element is thetryCatch()frameโs call: the conditionREvalError::reraisesignals, with the callREvalError::callreports.
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.