pub enum RCondition {
Error {
message: String,
class: Vec<String>,
data: Option<ConditionData>,
call: ConditionCall,
},
Warning {
message: String,
class: Vec<String>,
data: Option<ConditionData>,
call: ConditionCall,
},
Message {
message: String,
class: Vec<String>,
data: Option<ConditionData>,
call: ConditionCall,
},
Condition {
message: String,
class: Vec<String>,
data: Option<ConditionData>,
call: ConditionCall,
},
Conversion {
message: String,
class: Vec<String>,
data: Option<ConditionData>,
call: ConditionCall,
},
}Expand description
Owned payload for structured R conditions.
#[derive(RCondition)] gives a struct or enum a conversion into this
payload. Its #[condition(kind = warning)] (or error / message /
condition) chooses the signal; an enum variant can override the kind.
Convert with RCondition::from(value), then call defer
to accompany a return value, or raise to leave Rust.
Raised by the error!(), warning!(), message!(), and condition!()
macros via std::panic::panic_any. Caught by with_r_unwind_protect
before the generic panic→string path and forwarded to R as a tagged SEXP
with rust_* class layering. The defer_* family
(crate::deferred_condition) queues the same payloads instead of
panicking, so the call still returns its value.
Every variant carries the same four parts: the message, the user classes
(prepended to the rust_* layering, empty for none), the optional data
fields and the ConditionCall choice. All four are owned and Send, so
the payload can travel through panic_any. Each variant is one kind of the
tagged condition value (crate::error_value::kind).
Variants§
Error
Raised by error!(...) / error!(class = "...", ...), and by the
Result<T, E> Err arm once reconstructed across a package boundary.
Fields
data: Option<ConditionData>Named fields attached to the R condition.
call: ConditionCallCall attribution policy; messages always omit the call.
Warning
Raised by warning!(...) / warning!(class = "...", ...).
Fields
data: Option<ConditionData>Named fields attached to the R condition.
call: ConditionCallCall attribution policy; messages always omit the call.
Message
Raised by message!(...), and queued by crate::defer_message(). Only
the typed-payload path fills class (the macro has no class = form);
the R helper layers it in front of rust_message like the other kinds.
A message never reports a call, whatever call says.
Fields
data: Option<ConditionData>Named fields attached to the R condition.
call: ConditionCallCall attribution policy; messages always omit the call.
Condition
Raised by condition!(...) / condition!(class = "...", ...).
Fields
data: Option<ConditionData>Named fields attached to the R condition.
call: ConditionCallCall attribution policy; messages always omit the call.
Conversion
An argument error, kind = "conversion": raised by
crate::arg_error! / ArgError::raise (built by
RCondition::arg_error), and a failed argument conversion once
reconstructed across a package boundary.
Fields
data: Option<ConditionData>Named fields attached to the R condition.
call: ConditionCallCall attribution policy; messages always omit the call.
Implementations§
Source§impl RCondition
impl RCondition
Sourcepub fn raise(self) -> !
pub fn raise(self) -> !
Leave the current Rust body with this condition.
The enclosing miniextendr guard forwards it to R with its kind and
metadata intact. Like warning!, raising a warning still exits Rust:
muffling it in R does not resume this Rust body. Use defer
to keep computing and return a value.
Sourcepub fn defer(self)
pub fn defer(self)
Queue this condition until the current guarded call returns.
Preserves its declared kind, classes, fields and call policy, including for a mixed-kind enum. Errors queued here stop R at that boundary.
From another thread it goes to R’s main thread over a channel; see Threads and boundaries.
Sourcepub fn from_data<E: RConditionData + ?Sized>(e: &E) -> RCondition
pub fn from_data<E: RConditionData + ?Sized>(e: &E) -> RCondition
The error condition of a classed error value: its
message, class,
data fields and
call choice, as a Result return raises it.
For raising a typed error by hand where no Result reaches the
generated code, such as a helper deep inside a body:
let model = load(path).unwrap_or_else(|e| RCondition::from_data(&e).raise());Raised, it is kind = "error"; returned as Err it would be
"result_err". Both are R errors with the same classes and fields.
A data() field with a reserved name (message, call, kind)
panics here, as in a generated Err arm.
Source#[doc(hidden)]pub fn into_parts(self) -> (&'static str, ErrParts)
#[doc(hidden)]pub fn into_parts(self) -> (&'static str, ErrParts)
Split into the kind (one of crate::error_value::kind) and the
ErrParts (message, class, data, call choice) that
crate::error_value::condition_parts_value builds the tagged value
from.
Sourcepub fn message(&self) -> &str
pub fn message(&self) -> &str
The condition message, as conditionMessage() would read it in R.
Use it on a condition catch_condition caught or
capture collected, for example
to put a cause’s text into a new message.
Sourcepub fn with_parent(self, parent: RCondition) -> Self
pub fn with_parent(self, parent: RCondition) -> Self
This condition with parent as its cause, as rlang::abort(parent = )
chains conditions.
R gets the cause as the field e$parent: a condition object with its
own classes, message and fields (and its own parent, if it has one),
built like the condition itself but not signalled. The cause’s classes
stay out of this condition’s class vector, so a handler written for
the cause’s class does not catch this condition; code that wants the
cause branches on it: inherits(e$parent, "pkg_error_config").
The cause reports the same call as this condition, or none when it was
raised with call = none. A second with_parent replaces the first,
and the cause replaces a data field this condition names parent.
match catch_condition(|| load_config(path)) {
Ok(value) => value,
Err(cause) => RCondition::Error {
message: format!("could not load the model: {}", cause.message()),
class: vec!["pkg_error_load".into()],
data: None,
call: ConditionCall::Inherit,
}
.with_parent(cause)
.raise(),
}Sourcefn into_tagged_rvalue(self) -> RValue
fn into_tagged_rvalue(self) -> RValue
The condition as the tagged value the R raise helper reads (error,
kind, class, call, data), in RValue form so
it can travel inside another condition’s data (Self::with_parent).
Sourcepub fn call(&self) -> ConditionCall
pub fn call(&self) -> ConditionCall
Which call the condition reports when R raises it: see
ConditionCall.
Sourcefn class_and_data(&self) -> (&[String], &Option<ConditionData>)
fn class_and_data(&self) -> (&[String], &Option<ConditionData>)
The user classes and the fields, whatever the variant.
Source#[doc(hidden)]pub fn arg_error(
param: impl Into<String>,
message: String,
call: ConditionCall,
) -> Self
#[doc(hidden)]pub fn arg_error(
param: impl Into<String>,
message: String,
call: ConditionCall,
) -> Self
The payload of crate::arg_error! and ArgError::raise: the
argument error of parameter param (its R name) with message.
kind = "conversion", e$param as the only data field, and the class
CONVERSION_ERROR_CLASS_MARKER, which the generated R replaces with
the crate’s conversion_error_class: the condition the wrapper’s own
argument checks raise (.miniextendr_arg_error).
Source§impl RCondition
impl RCondition
Sourcepub unsafe fn from_tagged_sexp(sexp: SEXP) -> Option<Self>
pub unsafe fn from_tagged_sexp(sexp: SEXP) -> Option<Self>
Reconstruct an RCondition::Error from a tagged SEXP produced by
crate::error_value::make_rust_condition_value.
Returns Some(RCondition) when sexp has class "rust_condition_value" AND
the "__rust_condition__" attribute is TRUE. Returns None for all other
SEXPs (normal return values, R_NilValue, etc.).
Reconstructs the matching variant for each kind: "error"/"panic"/
"result_err"/"none_err"/"other_rust_error" →
RCondition::Error (class, message, data and a ConditionCall::None
choice kept; the kind itself is not carried by the variant);
"conversion" → RCondition::Conversion, so an argument error keeps
kind = "conversion" across a package boundary (and an
crate::arg_error! its class marker, which the consumer’s wrapper
resolves); "warning" → RCondition::Warning; "message" →
RCondition::Message; "condition" → RCondition::Condition.
Unknown kinds degrade to RCondition::Error with the kind string
prefixed to the message.
§Safety
Must be called from R’s main thread.
Trait Implementations§
Source§impl Clone for RCondition
impl Clone for RCondition
Source§impl Debug for RCondition
impl Debug for RCondition
Source§impl RConditionData for RCondition
An RCondition returned as an Err (#2217): from a
#[miniextendr] function or method returning Result<T, RCondition>.
Its message, classes, fields and call choice reach R as given. Like any Err, it is an
R error whatever its variant: the kind is read only where the condition is
raised or deferred (RCondition::raise, RCondition::defer). A cause
attached with RCondition::with_parent, as a caught refusal of a
restored object carries one, stays its e$parent, also through the
SexpError it converts into.
impl RConditionData for RCondition
An RCondition returned as an Err (#2217): from a
#[miniextendr] function or method returning Result<T, RCondition>.
Its message, classes, fields and call choice reach R as given. Like any Err, it is an
R error whatever its variant: the kind is read only where the condition is
raised or deferred (RCondition::raise, RCondition::defer). A cause
attached with RCondition::with_parent, as a caught refusal of a
restored object carries one, stays its e$parent, also through the
SexpError it converts into.
It is how a body hands on a condition catch_condition caught, or one
built by serde_condition!:
#[miniextendr]
pub fn load(path: &str) -> Result<Model, RCondition> {
let config = catch_condition(|| read_config(path))?;
Ok(Model::new(config))
}Source§fn __mx_keeps_internal_fields(&self) -> bool
fn __mx_keeps_internal_fields(&self) -> bool
A .mx_parent field is the cause RCondition::with_parent
attached (a refusal catch_condition caught carries one), a
.mx_errors field the failed elements of an
IntoRError it was built from.
Source§fn data(&self) -> Option<ConditionData>
fn data(&self) -> Option<ConditionData>
e$<name>).Source§fn call(&self) -> ConditionCall
fn call(&self) -> ConditionCall
ConditionCall::None makes
conditionCall() NULL, like R’s call. = FALSE, for a condition
about the data rather than the call; the default keeps the call the
transport captured. Honoured by defer_* and by Result returns;
an argument-conversion error always keeps the call (see
conversion_err_parts). #[condition(call = none)] on a derived
type or variant overrides this.Auto Trait Implementations§
impl Forget for RCondition
impl Freeze for RCondition
impl RefUnwindSafe for RCondition
impl Send for RCondition
impl Sync for RCondition
impl Unpin for RCondition
impl UnsafeUnpin for RCondition
impl UnwindSafe for RCondition
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> ConsumingFallible for Twhere
T: Clone,
Source§impl<E> ConversionArgMessageClassed for Ewhere
E: RConditionData,
impl<E> ConversionArgMessageClassed for Ewhere
E: RConditionData,
Source§impl<E> ConversionErrClassed for Ewhere
E: RConditionData,
impl<E> ConversionErrClassed for Ewhere
E: RConditionData,
fn __mx_conversion_parts(&self, _expected_known: bool) -> ErrParts
Source§impl<E> ErrPartsClassed for Ewhere
E: RConditionData,
impl<E> ErrPartsClassed for Ewhere
E: RConditionData,
fn __mx_classed_parts(&self) -> Option<ErrParts>
Source§impl<T> RDebug for Twhere
T: Debug,
impl<T> RDebug for Twhere
T: Debug,
Source§impl<T> SizeHint for Twhere
T: ?Sized,
impl<T> SizeHint for Twhere
T: ?Sized,
Source§default fn lower_bound(&self) -> usize
default fn lower_bound(&self) -> usize
core_io_internals)[u8; 12] could return any value between 0 and
12 inclusively as a correct implementation. Read moreSource§impl<T> SizedTypeProperties for T
impl<T> SizedTypeProperties for T
Source§#[doc(hidden)]const SIZE: usize
#[doc(hidden)]const SIZE: usize
sized_type_properties)Source§#[doc(hidden)]const ALIGN: usize
#[doc(hidden)]const ALIGN: usize
sized_type_properties)Source§#[doc(hidden)]const ALIGNMENT: Alignment
#[doc(hidden)]const ALIGNMENT: Alignment
ptr_alignment_type)Source§#[doc(hidden)]const IS_ZST: bool
#[doc(hidden)]const IS_ZST: bool
sized_type_properties)Source§#[doc(hidden)]const LAYOUT: Layout
#[doc(hidden)]const LAYOUT: Layout
sized_type_properties)Source§#[doc(hidden)]const MAX_SLICE_LEN: usize
#[doc(hidden)]const MAX_SLICE_LEN: usize
sized_type_properties)[Self]. Read moreLayout§
Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.
Size: 80 bytes
Size for each variant:
Error: 79 bytesWarning: 79 bytesMessage: 79 bytesCondition: 79 bytesConversion: 79 bytes