Context: Rename insert_with_data to insert and the original insert to insert_env

crates/indicator/src/context/layer/mod.rs

@@ -77,7 +77,9 @@ where
 
     /// Add a [`Insert`] layer with the given [`RefOperator`] constructor
     /// (i.e. a function that returns a [`RefOperator`]).
-    fn insert<R, Out, F>(self, f: F) -> Stack<Self, Insert<F>>
+    ///
+    /// We use this method to add the output of the operator to the `env` context.
+    fn insert_env<R, Out, F>(self, f: F) -> Stack<Self, Insert<F>>
     where
         F: Fn() -> R,
         R: for<'a> RefOperator<'a, In, Output = Out>,
@@ -89,6 +91,8 @@ where
 
     /// Add a [`InsertData`] layer with the given [`RefOperator`] constructor.
     /// (i.e. a function that returns a [`RefOperator`]).
+    ///
+    /// We use this method to add the output of the operator to the `data` context.
     fn insert_data<R, Out, F>(self, f: F) -> Stack<Self, InsertData<F>>
     where
         F: Fn() -> R,
@@ -101,7 +105,9 @@ where
 
     /// Add a [`InsertWithData`] layer with the given [`RefOperator`] constructor.
     /// (i.e. a function that returns a [`RefOperator`]).
-    fn insert_with_data<R, Env, Data, F>(self, f: F) -> Stack<Self, InsertWithData<F>>
+    ///
+    /// We use this method to add the output of the operator to the `env` and `data` context simultaneously.
+    fn insert<R, Env, Data, F>(self, f: F) -> Stack<Self, InsertWithData<F>>
     where
         F: Fn() -> R,
         R: for<'a> RefOperator<'a, In, Output = (Env, Option<Data>)>,

crates/indicator/src/context/mod.rs

@@ -103,7 +103,9 @@ pub trait ContextOperatorExt<In>: ContextOperator<In> {
 
     /// Add a [`Insert`] layer with the given [`RefOperator`] constructor
     /// (i.e. a function that returns a [`RefOperator`]).
-    fn insert<R, Out>(self, f: impl Fn() -> R) -> InsertOperator<Self, R>
+    ///
+    /// We use this method to add the output of the operator to the `env` context.
+    fn insert_env<R, Out>(self, f: impl Fn() -> R) -> InsertOperator<Self, R>
     where
         R: for<'a> RefOperator<'a, In, Output = Out>,
         Out: Send + Sync + 'static,
@@ -114,6 +116,8 @@ pub trait ContextOperatorExt<In>: ContextOperator<In> {
 
     /// Add a [`InsertData`] layer with the given [`RefOperator`] constructor.
     /// (i.e. a function that returns a [`RefOperator`]).
+    ///
+    /// We use this method to add the output of the operator to the `data` context.
     fn insert_data<R, Out>(self, f: impl Fn() -> R) -> InsertDataOperator<Self, R>
     where
         R: for<'a> RefOperator<'a, In, Output = Option<Out>>,
@@ -125,7 +129,9 @@ pub trait ContextOperatorExt<In>: ContextOperator<In> {
 
     /// Add a [`InsertWithData`] layer with the given [`RefOperator`] constructor.
     /// (i.e. a function that returns a [`RefOperator`]).
-    fn insert_with_data<R, Env, Data>(self, f: impl Fn() -> R) -> InsertWithDataOperator<Self, R>
+    ///
+    /// We use this method to add the output of the operator to the `env` and `data` context simultaneously.
+    fn insert<R, Env, Data>(self, f: impl Fn() -> R) -> InsertWithDataOperator<Self, R>
     where
         R: for<'a> RefOperator<'a, In, Output = (Env, Option<Data>)>,
         Env: Send + Sync + 'static,

crates/indicator/src/lib.rs

@@ -105,6 +105,7 @@ pub mod prelude {
     #[cfg(feature = "context")]
     pub use crate::context::{
         extractor::{Data, Env, In, Prev},
+        input,
         layer::{layer_fn, stack::id_layer, Layer, LayerExt},
         output, output_with, ContextOperator, ContextOperatorExt, Value, ValueRef,
     };

crates/indicator_derive/Cargo.toml

@@ -18,3 +18,7 @@ proc-macro2 = "1.0.67"
 quote = "1.0.33"
 syn = { version = "2.0.37", features = ["full"] }
 convert_case = "0.6.0"
+
+[dev-dependencies]
+indicator = { path = "../indicator", features = ["context"] }
+num = "0.4.1"

crates/indicator_derive/src/lib.rs

@@ -19,6 +19,66 @@ fn indicator() -> TokenStream2 {
 }
 
 /// Create a `RefOperator` from a function.
+///
+/// ## Note
+/// - When using with the `generate_out` flag, the output type will be converted to the same
+/// as `generate_out_with_data`, i.e. `(OutTy, Option<DataTy>)` where `DataTy = ()`
+/// is this case. So that it can be used in `insert` method (but not the `insert_env` method).
+/// - But when using with the `generate_data` flag, the output type is kept as `Option<DataTy>`,
+/// so that it can be used in `insert_data` method.
+///
+/// ## Example
+/// The following example is a basic usage of `#[operator]` attribute.
+/// We use `#[operator]` to create a `RefOperator` that just add two to the input.
+/// ```rust
+/// use indicator::prelude::*;
+/// use num::Num;
+///
+/// struct AddTwo<T>(T);
+///
+/// /// An operator that just add two to the input.
+/// #[operator(input = T)]
+/// fn add_two<T>(In(value): In<&T>) -> AddTwo<T>
+/// where
+///     T: Num + Clone,
+///     T: Send + Sync + 'static,
+/// {
+///     let two = T::one() + T::one();
+///     AddTwo(value.clone() + two)
+/// }
+///
+/// let op = input::<i32>().insert_env(add_two).finish();
+/// ```
+///
+/// We notice that the above example requires us to define a struct `AddTwo` to wrap the output.
+/// The same operator can also be created with the following code but in a more generic way.
+/// ```rust
+/// use indicator::prelude::*;
+/// use num::Num;
+///
+/// /// An operator that just add two to the input.
+/// #[operator(input = I, generate_out)]
+/// fn add_two<T>(#[input] value: &T) -> T
+/// where
+///    T: Num + Clone,
+/// {
+///    let two = T::one() + T::one();
+///   value.clone() + two
+/// }
+///
+/// let op = input::<i32>().insert(add_two::<_, _, i32>).finish();
+/// ```
+/// Here we use the `#[input]` attribute and the `generate_out` to achieve our goal.
+/// - The `#[input]` attribute is used to mark the input parameter.
+/// It will replace the `value: &T` parameter with `In(value): In<&I>` in the generated code,
+/// and introduce a bound `I: Borrow<T>` so that it can be converted back to `&T` before calling.
+/// - The `generate_out` flag in the `#[operator]` attribute is used to generate a generic output type.
+/// Like what the `#[input]` attribute does, it will introduce a bound `OutTy: From<T>`
+/// (here the `OutTy` is the generated output type) so that the output can be converted from `T`.
+///
+/// Also note that the operator generated with `generate_out` flag is meant to be used with `insert` method,
+/// because the output type is wrapped in a tuple `(OutTy, Option<DataTy>)` where `DataTy = ()` is this case.
+/// If you want to costomize the `DataTy`, you can use the `generate_out_with_data` flag instead.
 #[proc_macro_attribute]
 pub fn operator(args: TokenStream, input: TokenStream) -> TokenStream {
     match self::operator::generate_operator(args, input) {

crates/indicator_derive/src/operator/operator_fn.rs

@@ -178,7 +178,7 @@ impl OperatorFn {
         match self.out {
             Some(GenerateOut::Out) => {
                 quote! {
-                    #call_name (#extractors).into()
+                    ((#call_name (#extractors)).into(), None)
                 }
             }
             Some(GenerateOut::Data) => {
@@ -226,7 +226,7 @@ impl OutputTy {
         match options.generate_out {
             Some(GenerateOut::Out) => {
                 generics.push(syn::parse2(quote!(OutTy: From<#ty>))?);
-                ty = syn::parse2(quote!(OutTy))?;
+                ty = syn::parse2(quote!((OutTy, Option<()>)))?;
             }
             Some(GenerateOut::Data) => {
                 let data_ty = get_type_inside_option(&ty)?;

examples/context/context.rs

@@ -23,14 +23,14 @@ struct Ma<T>(T);
 /// An operator that does the following:
 /// `x => (x + prev(x)) / 2`
 #[operator(input = T)]
-fn ma<T>(Env(x): Env<&T>, Prev(prev): Prev<&Ma<T>>) -> Ma<T>
+fn ma<T>(Env(x): Env<&AddTwo<T>>, Prev(prev): Prev<&Ma<T>>) -> Ma<T>
 where
     T: Num + Clone,
     T: Send + Sync + 'static,
 {
     let two = T::one() + T::one();
     let prev = prev.map(|v| v.0.clone()).unwrap_or(T::zero());
-    Ma((x.clone() + prev) / two)
+    Ma((x.0.clone() + prev) / two)
 }
 
 fn main() -> anyhow::Result<()> {
@@ -41,7 +41,7 @@ fn main() -> anyhow::Result<()> {
                 println!("AddTwo: {x}");
             }
         })
-        .insert(add_two)
+        .insert_env(add_two)
         .cache(1)
         .finish();
     let data = [dec!(1), dec!(2), dec!(3)];

examples/context/data.rs

@@ -52,7 +52,7 @@ fn main() -> anyhow::Result<()> {
         .from_context::<&str>() // Asserting that the context has a `&str` data.
         .provide("This is my data!")
         .insert_data(odds_counter)
-        .insert_with_data(even_signal::<bool, EvenCount>)
+        .insert(even_signal::<bool, EvenCount>)
         .cache(1)
         .finish();
     let data = [1, 2, 3];

examples/context/stack.rs

@@ -11,7 +11,9 @@ where
     T: Num + Clone,
     P: ContextOperator<T>,
 {
-    id_layer().insert(ma::<_, N>).provide(Alpha::<_, N>(alhpa))
+    id_layer()
+        .insert_env(ma::<_, N>)
+        .provide(Alpha::<_, N>(alhpa))
 }
 
 /// Config for `ma` operator.