Remove .call(), .construct(), .call_with(), and `.construct_wit…

…h()` from docs
neon-bindings · Sep 28, 2024 · 942fb50 · 942fb50
1 parent 39eaada
commit 942fb50
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 69 deletions.
diff --git a/crates/neon/src/context/mod.rs b/crates/neon/src/context/mod.rs
@@ -113,9 +113,9 @@
 //!     while !done {
 //!         done = cx.execute_scoped(|mut cx| {                   // temporary scope
 //!             let obj: Handle<JsObject> = next                  // temporary object
-//!                 .call_with(&cx)
-//!                 .this(iterator)
-//!                 .apply(&mut cx)?;
+//!                 .bind(&mut cx)
+//!                 .this(iterator)?
+//!                 .call()?;
 //!             numbers.push(obj.prop(&mut cx, "value").get()?);  // temporary number
 //!             obj.prop(&mut cx, "done").get()                   // temporary boolean
 //!         })?;

diff --git a/crates/neon/src/event/channel.rs b/crates/neon/src/event/channel.rs
@@ -75,13 +75,12 @@ type Callback = Box<dyn FnOnce(sys::Env) + Send + 'static>;
 ///         // loop. This _will_ block the event loop while executing.
 ///         channel.send(move |mut cx| {
 ///             let callback = callback.into_inner(&mut cx);
-///             let this = cx.undefined();
-///             let args = vec![
-///                 cx.null().upcast::<JsValue>(),
-///                 cx.number(result).upcast(),
-///             ];
+///             let null = cx.null();
 ///
-///             callback.call(&mut cx, this, args)?;
+///             callback
+///                 .bind(&mut cx)
+///                 .args((null, result))?
+///                 .exec()?;
 ///
 ///             Ok(())
 ///         });

diff --git a/crates/neon/src/event/mod.rs b/crates/neon/src/event/mod.rs
@@ -78,27 +78,28 @@
 //!     // loop. This _will_ block the event loop while executing.
 //!     channel.send(move |mut cx| {
 //!         let callback = callback.into_inner(&mut cx);
-//!         let this = cx.undefined();
-//!         let args = match result {
+//!
+//!         match result {
 //!             Ok(psd) => {
 //!                 // Extract data from the parsed file.
-//!                 let obj = cx.empty_object();
-//!                 obj.prop(&mut cx, "width").set(psd.width())?;
-//!                 obj.prop(&mut cx, "height").set(psd.height())?;
-//!                 vec![
-//!                     cx.null().upcast::<JsValue>(),
-//!                     obj.upcast(),
-//!                 ]
+//!                 let obj = cx.empty_object()
+//!                     .prop(&mut cx, "width").set(psd.width())?
+//!                     .prop("height").set(psd.height())?
+//!                     .this();
+//!                 let null = cx.null();
+//!
+//!                 callback
+//!                     .bind(&mut cx)
+//!                     .args((null, obj))?
+//!                     .exec()?;
 //!             }
 //!             Err(err) => {
-//!                 let err = cx.string(err.to_string());
-//!                 vec![
-//!                     err.upcast::<JsValue>(),
-//!                 ]
+//!                 callback
+//!                     .bind(&mut cx)
+//!                     .arg(err.to_string())?
+//!                     .exec()?;
 //!             }
-//!         };
-//!
-//!         callback.call(&mut cx, this, args)?;
+//!         }
 //!
 //!         Ok(())
 //!     });

diff --git a/crates/neon/src/thread/mod.rs b/crates/neon/src/thread/mod.rs
@@ -16,9 +16,10 @@
 //! pub fn thread_id(cx: &mut Cx) -> NeonResult<u32> {
 //!     THREAD_ID.get_or_try_init(cx, |cx| {
 //!         let require: Handle<JsFunction> = cx.global("require")?;
-//!         let worker: Handle<JsObject> = require.call_with(cx)
-//!             .arg(cx.string("node:worker_threads"))
-//!             .apply(cx)?;
+//!         let worker: Handle<JsObject> = require
+//!             .bind(cx)
+//!             .arg("node:worker_threads")?
+//!             .call()?;
 //!         let thread_id: f64 = worker.prop(cx, "threadId").get()?;
 //!         Ok(thread_id as u32)
 //!     }).cloned()

diff --git a/crates/neon/src/types_impl/boxed.rs b/crates/neon/src/types_impl/boxed.rs
@@ -293,19 +293,10 @@ impl<T: 'static> Deref for JsBox<T> {
 ///
 /// impl Finalize for Point {
 ///     fn finalize<'a, C: Context<'a>>(self, cx: &mut C) {
-///         let global = cx.global_object();
-///         let emit: Handle<JsFunction> = global
-///             .prop(cx.cx_mut(), "emit")
-///             .get()
-///             .unwrap();
-///
-///         let args = vec![
-///             cx.string("gc_point").upcast::<JsValue>(),
-///             cx.number(self.0).upcast(),
-///             cx.number(self.1).upcast(),
-///         ];
-///
-///         emit.call(cx, global, args).unwrap();
+///         cx.global_object()
+///             .method(cx.cx_mut(), "emit").unwrap()
+///             .args(("gc_point", self.0, self.1)).unwrap()
+///             .exec().unwrap();
 ///     }
 /// }
 /// ```

diff --git a/crates/neon/src/types_impl/function/mod.rs b/crates/neon/src/types_impl/function/mod.rs
@@ -117,6 +117,7 @@ impl<'a, 'cx: 'a> BindOptions<'a, 'cx> {
 /// # Ok(x)
 /// # }
 /// ```
+#[deprecated(since = "TBD", note = "use `JsFunction::bind()` instead")]
 #[derive(Clone)]
 pub struct CallOptions<'a> {
     pub(crate) callee: Handle<'a, JsFunction>,
@@ -175,6 +176,7 @@ impl<'a> CallOptions<'a> {
 /// # Ok(obj)
 /// # }
 /// ```
+#[deprecated(since = "TBD", note = "use `JsFunction::bind()` instead")]
 #[derive(Clone)]
 pub struct ConstructOptions<'a> {
     pub(crate) callee: Handle<'a, JsFunction>,

diff --git a/crates/neon/src/types_impl/mod.rs b/crates/neon/src/types_impl/mod.rs
@@ -342,16 +342,12 @@ impl ValueInternal for JsNull {
 /// ```
 /// # use neon::prelude::*;
 /// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
-/// // Extract the console.log function:
-/// let console: Handle<JsObject> = cx.global("console")?;
-/// let log: Handle<JsFunction> = console.prop(&mut cx, "log").get()?;
-///
 /// // The two Boolean values:
 /// let t = cx.boolean(true);
 /// let f = cx.boolean(false);
 ///
 /// // Call console.log(true, false):
-/// log.call_with(&cx).arg(t).arg(f).exec(&mut cx)?;
+/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.args((t, f))?.exec()?;
 /// # Ok(cx.undefined())
 /// # }
 /// ```
@@ -419,15 +415,11 @@ impl ValueInternal for JsBoolean {
 /// ```
 /// # use neon::prelude::*;
 /// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
-/// // Extract the console.log function:
-/// let console: Handle<JsObject> = cx.global("console")?;
-/// let log: Handle<JsFunction> = console.prop(&mut cx, "log").get()?;
-///
 /// // Create a string:
 /// let s = cx.string("hello 🥹");
 ///
 /// // Call console.log(s):
-/// log.call_with(&cx).arg(s).exec(&mut cx)?;
+/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(s)?.exec()?;
 /// # Ok(cx.undefined())
 /// # }
 /// ```
@@ -696,15 +688,11 @@ impl JsString {
 /// ```
 /// # use neon::prelude::*;
 /// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
-/// // Extract the console.log function:
-/// let console: Handle<JsObject> = cx.global("console")?;
-/// let log: Handle<JsFunction> = console.prop(&mut cx, "log").get()?;
-///
 /// // Create a number:
 /// let n = cx.number(17.0);
 ///
 /// // Call console.log(n):
-/// log.call_with(&cx).arg(n).exec(&mut cx)?;
+/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(n)?.exec()?;
 /// # Ok(cx.undefined())
 /// # }
 /// ```
@@ -772,10 +760,6 @@ impl ValueInternal for JsNumber {
 /// ```
 /// # use neon::prelude::*;
 /// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
-/// // Extract the console.log function:
-/// let console: Handle<JsObject> = cx.global("console")?;
-/// let log: Handle<JsFunction> = console.prop(&mut cx, "log").get()?;
-///
 /// // Create an object:
 /// let obj = cx.empty_object()
 ///     .prop(&mut cx, "name")
@@ -785,7 +769,7 @@ impl ValueInternal for JsNumber {
 ///     .this();
 ///
 /// // Call console.log(obj):
-/// log.call_with(&cx).arg(obj).exec(&mut cx)?;
+/// cx.global::<JsObject>("console")?.method(&mut cx, "log")?.arg(obj)?.exec()?;
 /// # Ok(cx.undefined())
 /// # }
 /// ```
@@ -975,7 +959,7 @@ impl Object for JsArray {}
 /// ## Calling functions
 ///
 /// Neon provides a convenient syntax for calling JavaScript functions with the
-/// [`call_with()`](JsFunction::call_with) method, which produces a [`CallOptions`](CallOptions)
+/// [`bind()`](JsFunction::bind) method, which produces a [`BindOptions`](BindOptions)
 /// struct that can be used to provide the function arguments (and optionally, the binding for
 /// `this`) before calling the function:
 /// ```
@@ -986,9 +970,9 @@ impl Object for JsArray {}
 ///
 /// // Call parseInt("42")
 /// let x: Handle<JsNumber> = parse_int
-///     .call_with(&mut cx)
-///     .arg(cx.string("42"))
-///     .apply(&mut cx)?;
+///     .bind(&mut cx)
+///     .arg("42")?
+///     .call()?;
 /// # Ok(x)
 /// # }
 /// ```
@@ -997,7 +981,7 @@ impl Object for JsArray {}
 ///
 /// A `JsFunction` can be called as a constructor (like `new Array(16)` or
 /// `new URL("https://neon-bindings.com")`) with the
-/// [`construct_with()`](JsFunction::construct_with) method:
+/// [`construct()`](BindOptions::construct) method:
 /// ```
 /// # use neon::prelude::*;
 /// # fn foo(mut cx: FunctionContext) -> JsResult<JsObject> {
@@ -1006,9 +990,9 @@ impl Object for JsArray {}
 ///
 /// // Call new URL("https://neon-bindings.com")
 /// let obj = url
-///     .construct_with(&cx)
-///     .arg(cx.string("https://neon-bindings.com"))
-///     .apply(&mut cx)?;
+///     .bind(&mut cx)
+///     .arg("https://neon-bindings.com")?
+///     .construct()?;
 /// # Ok(obj)
 /// # }
 /// ```