X-Git-Url: https://git.josue.xyz/?p=VSoRC%2F.git;a=blobdiff_plain;f=node_modules%2Fnode-pty%2Fnode_modules%2Fnan%2Fdoc%2Fobject_wrappers.md;fp=node_modules%2Fnode-pty%2Fnode_modules%2Fnan%2Fdoc%2Fobject_wrappers.md;h=08dd6b5529824646bcf9febe4b94c8f7022d15b9;hp=0000000000000000000000000000000000000000;hb=e79e4a5a87f3e84f7c1777f10a954453a69bf540;hpb=4339da12467b75fb8b6ca831f4bf0081c485ed2c

diff --git a/node_modules/node-pty/node_modules/nan/doc/object_wrappers.md b/node_modules/node-pty/node_modules/nan/doc/object_wrappers.md
new file mode 100644
index 0000000..08dd6b5
--- /dev/null
+++ b/node_modules/node-pty/node_modules/nan/doc/object_wrappers.md
@@ -0,0 +1,263 @@
+## Object Wrappers
+
+The `ObjectWrap` class can be used to make wrapped C++ objects and a factory of wrapped objects.
+
+ - <a href="#api_nan_object_wrap"><b><code>Nan::ObjectWrap</code></b></a>
+
+
+<a name="api_nan_object_wrap"></a>
+### Nan::ObjectWrap()
+
+A reimplementation of `node::ObjectWrap` that adds some API not present in older versions of Node. Should be preferred over `node::ObjectWrap` in all cases for consistency.
+
+Definition:
+
+```c++
+class ObjectWrap {
+ public:
+  ObjectWrap();
+
+  virtual ~ObjectWrap();
+
+  template <class T>
+  static inline T* Unwrap(v8::Local<v8::Object> handle);
+
+  inline v8::Local<v8::Object> handle();
+
+  inline Nan::Persistent<v8::Object>& persistent();
+
+ protected:
+  inline void Wrap(v8::Local<v8::Object> handle);
+
+  inline void MakeWeak();
+
+  /* Ref() marks the object as being attached to an event loop.
+   * Refed objects will not be garbage collected, even if
+   * all references are lost.
+   */
+  virtual void Ref();
+
+  /* Unref() marks an object as detached from the event loop.  This is its
+   * default state.  When an object with a "weak" reference changes from
+   * attached to detached state it will be freed. Be careful not to access
+   * the object after making this call as it might be gone!
+   * (A "weak reference" means an object that only has a
+   * persistant handle.)
+   *
+   * DO NOT CALL THIS FROM DESTRUCTOR
+   */
+  virtual void Unref();
+
+  int refs_;  // ro
+};
+```
+
+See the Node documentation on [Wrapping C++ Objects](https://nodejs.org/api/addons.html#addons_wrapping_c_objects) for more details.
+
+### This vs. Holder
+
+When calling `Unwrap`, it is important that the argument is indeed some JavaScript object which got wrapped by a `Wrap` call for this class or any derived class.
+The `Signature` installed by [`Nan::SetPrototypeMethod()`](methods.md#api_nan_set_prototype_method) does ensure that `info.Holder()` is just such an instance.
+In Node 0.12 and later, `info.This()` will also be of such a type, since otherwise the invocation will get rejected.
+However, in Node 0.10 and before it was possible to invoke a method on a JavaScript object which just had the extension type in its prototype chain.
+In such a situation, calling `Unwrap` on `info.This()` will likely lead to a failed assertion causing a crash, but could lead to even more serious corruption.
+
+On the other hand, calling `Unwrap` in an [accessor](methods.md#api_nan_set_accessor) should not use `Holder()` if the accessor is defined on the prototype.
+So either define your accessors on the instance template,
+or use `This()` after verifying that it is indeed a valid object.
+
+### Examples
+
+#### Basic
+
+```c++
+class MyObject : public Nan::ObjectWrap {
+ public:
+  static NAN_MODULE_INIT(Init) {
+    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
+    tpl->SetClassName(Nan::New("MyObject").ToLocalChecked());
+    tpl->InstanceTemplate()->SetInternalFieldCount(1);
+
+    Nan::SetPrototypeMethod(tpl, "getHandle", GetHandle);
+    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);
+
+    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
+    Nan::Set(target, Nan::New("MyObject").ToLocalChecked(),
+      Nan::GetFunction(tpl).ToLocalChecked());
+  }
+
+ private:
+  explicit MyObject(double value = 0) : value_(value) {}
+  ~MyObject() {}
+
+  static NAN_METHOD(New) {
+    if (info.IsConstructCall()) {
+      double value = info[0]->IsUndefined() ? 0 : Nan::To<double>(info[0]).FromJust();
+      MyObject *obj = new MyObject(value);
+      obj->Wrap(info.This());
+      info.GetReturnValue().Set(info.This());
+    } else {
+      const int argc = 1;
+      v8::Local<v8::Value> argv[argc] = {info[0]};
+      v8::Local<v8::Function> cons = Nan::New(constructor());
+      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
+    }
+  }
+
+  static NAN_METHOD(GetHandle) {
+    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
+    info.GetReturnValue().Set(obj->handle());
+  }
+
+  static NAN_METHOD(GetValue) {
+    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
+    info.GetReturnValue().Set(obj->value_);
+  }
+
+  static inline Nan::Persistent<v8::Function> & constructor() {
+    static Nan::Persistent<v8::Function> my_constructor;
+    return my_constructor;
+  }
+
+  double value_;
+};
+
+NODE_MODULE(objectwrapper, MyObject::Init)
+```
+
+To use in Javascript:
+
+```Javascript
+var objectwrapper = require('bindings')('objectwrapper');
+
+var obj = new objectwrapper.MyObject(5);
+console.log('Should be 5: ' + obj.getValue());
+```
+
+#### Factory of wrapped objects
+
+```c++
+class MyFactoryObject : public Nan::ObjectWrap {
+ public:
+  static NAN_MODULE_INIT(Init) {
+    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
+    tpl->InstanceTemplate()->SetInternalFieldCount(1);
+
+    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);
+
+    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
+  }
+
+  static NAN_METHOD(NewInstance) {
+    v8::Local<v8::Function> cons = Nan::New(constructor());
+    double value = info[0]->IsNumber() ? Nan::To<double>(info[0]).FromJust() : 0;
+    const int argc = 1;
+    v8::Local<v8::Value> argv[1] = {Nan::New(value)};
+    info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
+  }
+
+  // Needed for the next example:
+  inline double value() const {
+    return value_;
+  }
+
+ private:
+  explicit MyFactoryObject(double value = 0) : value_(value) {}
+  ~MyFactoryObject() {}
+
+  static NAN_METHOD(New) {
+    if (info.IsConstructCall()) {
+      double value = info[0]->IsNumber() ? Nan::To<double>(info[0]).FromJust() : 0;
+      MyFactoryObject * obj = new MyFactoryObject(value);
+      obj->Wrap(info.This());
+      info.GetReturnValue().Set(info.This());
+    } else {
+      const int argc = 1;
+      v8::Local<v8::Value> argv[argc] = {info[0]};
+      v8::Local<v8::Function> cons = Nan::New(constructor());
+      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
+    }
+  }
+
+  static NAN_METHOD(GetValue) {
+    MyFactoryObject* obj = ObjectWrap::Unwrap<MyFactoryObject>(info.Holder());
+    info.GetReturnValue().Set(obj->value_);
+  }
+
+  static inline Nan::Persistent<v8::Function> & constructor() {
+    static Nan::Persistent<v8::Function> my_constructor;
+    return my_constructor;
+  }
+
+  double value_;
+};
+
+NAN_MODULE_INIT(Init) {
+  MyFactoryObject::Init(target);
+  Nan::Set(target,
+    Nan::New<v8::String>("newFactoryObjectInstance").ToLocalChecked(),
+    Nan::GetFunction(
+      Nan::New<v8::FunctionTemplate>(MyFactoryObject::NewInstance)).ToLocalChecked()
+  );
+}
+
+NODE_MODULE(wrappedobjectfactory, Init)
+```
+
+To use in Javascript:
+
+```Javascript
+var wrappedobjectfactory = require('bindings')('wrappedobjectfactory');
+
+var obj = wrappedobjectfactory.newFactoryObjectInstance(10);
+console.log('Should be 10: ' + obj.getValue());
+```
+
+#### Passing wrapped objects around
+
+Use the `MyFactoryObject` class above along with the following:
+
+```c++
+static NAN_METHOD(Sum) {
+  Nan::MaybeLocal<v8::Object> maybe1 = Nan::To<v8::Object>(info[0]);
+  Nan::MaybeLocal<v8::Object> maybe2 = Nan::To<v8::Object>(info[1]);
+
+  // Quick check:
+  if (maybe1.IsEmpty() || maybe2.IsEmpty()) {
+    // return value is undefined by default
+    return;
+  }
+
+  MyFactoryObject* obj1 =
+    Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe1.ToLocalChecked());
+  MyFactoryObject* obj2 =
+    Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe2.ToLocalChecked());
+
+  info.GetReturnValue().Set(Nan::New<v8::Number>(obj1->value() + obj2->value()));
+}
+
+NAN_MODULE_INIT(Init) {
+  MyFactoryObject::Init(target);
+  Nan::Set(target,
+    Nan::New<v8::String>("newFactoryObjectInstance").ToLocalChecked(),
+    Nan::GetFunction(
+      Nan::New<v8::FunctionTemplate>(MyFactoryObject::NewInstance)).ToLocalChecked()
+  );
+  Nan::Set(target,
+    Nan::New<v8::String>("sum").ToLocalChecked(),
+    Nan::GetFunction(Nan::New<v8::FunctionTemplate>(Sum)).ToLocalChecked()
+  );
+}
+
+NODE_MODULE(myaddon, Init)
+```
+
+To use in Javascript:
+
+```Javascript
+var myaddon = require('bindings')('myaddon');
+
+var obj1 = myaddon.newFactoryObjectInstance(5);
+var obj2 = myaddon.newFactoryObjectInstance(10);
+console.log('sum of object values: ' + myaddon.sum(obj1, obj2));
+```