Maybe Types

The Nan::MaybeLocal and Nan::Maybe types are monads that encapsulate v8::Local handles that may be empty.

• Maybe Types

  • Nan::MaybeLocal

  • Nan::Maybe

  • Nan::Nothing

  • Nan::Just

• Maybe Helpers

  • Nan::Call()

  • Nan::ToDetailString()

  • Nan::ToArrayIndex()

  • Nan::Equals()

  • Nan::NewInstance()

  • Nan::GetFunction()

  • Nan::Set()

  • Nan::ForceSet()

  • Nan::Get()

  • Nan::GetPropertyAttributes()

  • Nan::Has()

  • Nan::Delete()

  • Nan::GetPropertyNames()

  • Nan::GetOwnPropertyNames()

  • Nan::SetPrototype()

  • Nan::ObjectProtoToString()

  • Nan::HasOwnProperty()

  • Nan::HasRealNamedProperty()

  • Nan::HasRealIndexedProperty()

  • Nan::HasRealNamedCallbackProperty()

  • Nan::GetRealNamedPropertyInPrototypeChain()

  • Nan::GetRealNamedProperty()

  • Nan::CallAsFunction()

  • Nan::CallAsConstructor()

  • Nan::GetSourceLine()

  • Nan::GetLineNumber()

  • Nan::GetStartColumn()

  • Nan::GetEndColumn()

  • Nan::CloneElementAt()

  • Nan::MakeMaybe()

Nan::MaybeLocal

A Nan::MaybeLocal<T> is a wrapper around v8::Local<T> that enforces a check that determines whether the v8::Local<T> is empty before it can be used.

If an API method returns a Nan::MaybeLocal, the API method can potentially fail either because an exception is thrown, or because an exception is pending, e.g. because a previous API call threw an exception that hasn't been caught yet, or because a v8::TerminateExecution exception was thrown. In that case, an empty Nan::MaybeLocal is returned.

Definition:

template<typename T> class Nan::MaybeLocal {
 public:
  MaybeLocal();

  template<typename S> MaybeLocal(v8::Local<S> that);

  bool IsEmpty() const;

  template<typename S> bool ToLocal(v8::Local<S> *out);

  // Will crash if the MaybeLocal<> is empty.
  v8::Local<T> ToLocalChecked();

  template<typename S> v8::Local<S> FromMaybe(v8::Local<S> default_value) const;
};

See the documentation for v8::MaybeLocal for further details.

Nan::Maybe

A simple Nan::Maybe type, representing an object which may or may not have a value, see https://hackage.haskell.org/package/base/docs/Data-Maybe.html.

If an API method returns a Nan::Maybe<>, the API method can potentially fail either because an exception is thrown, or because an exception is pending, e.g. because a previous API call threw an exception that hasn't been caught yet, or because a v8::TerminateExecution exception was thrown. In that case, a "Nothing" value is returned.

Definition:

template<typename T> class Nan::Maybe {
 public:
  bool IsNothing() const;
  bool IsJust() const;

  // Will crash if the Maybe<> is nothing.
  T FromJust();

  T FromMaybe(const T& default_value);

  bool operator==(const Maybe &other);

  bool operator!=(const Maybe &other);
};

See the documentation for v8::Maybe for further details.

Nan::Nothing

Construct an empty Nan::Maybe type representing nothing.

template<typename T> Nan::Maybe<T> Nan::Nothing();

Nan::Just

Construct a Nan::Maybe type representing just a value.

template<typename T> Nan::Maybe<T> Nan::Just(const T &t);

Nan::Call()

A helper method for calling v8::Function#Call() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::Call(v8::Local<v8::Function> fun, v8::Local<v8::Object> recv, int argc, v8::Local<v8::Value> argv[]);

Nan::ToDetailString()

A helper method for calling v8::Value#ToDetailString() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::String> Nan::ToDetailString(v8::Local<v8::Value> val);

Nan::ToArrayIndex()

A helper method for calling v8::Value#ToArrayIndex() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Uint32> Nan::ToArrayIndex(v8::Local<v8::Value> val);

Nan::Equals()

A helper method for calling v8::Value#Equals() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::Equals(v8::Local<v8::Value> a, v8::Local<v8::Value>(b));

Nan::NewInstance()

A helper method for calling v8::Function#NewInstance() and v8::ObjectTemplate#NewInstance() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h, int argc, v8::Local<v8::Value> argv[]);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::ObjectTemplate> h);

Nan::GetFunction()

A helper method for calling v8::FunctionTemplate#GetFunction() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Function> Nan::GetFunction(v8::Local<v8::FunctionTemplate> t);

Nan::Set()

A helper method for calling v8::Object#Set() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::Set(v8::Local<v8::Object> obj,
                          v8::Local<v8::Value> key,
                          v8::Local<v8::Value> value)
Nan::Maybe<bool> Nan::Set(v8::Local<v8::Object> obj,
                          uint32_t index,
                          v8::Local<v8::Value> value);

Nan::ForceSet()

A helper method for calling v8::Object#ForceSet() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::ForceSet(v8::Local<v8::Object> obj,
                               v8::Local<v8::Value> key,
                               v8::Local<v8::Value> value,
                               v8::PropertyAttribute attribs = v8::None);

Nan::Get()

A helper method for calling v8::Object#Get() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::Get(v8::Local<v8::Object> obj,
                                    v8::Local<v8::Value> key);
Nan::MaybeLocal<v8::Value> Nan::Get(v8::Local<v8::Object> obj, uint32_t index);

Nan::GetPropertyAttributes()

A helper method for calling v8::Object#GetPropertyAttributes() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<v8::PropertyAttribute> Nan::GetPropertyAttributes(
    v8::Local<v8::Object> obj,
    v8::Local<v8::Value> key);

Nan::Has()

A helper method for calling v8::Object#Has() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::Has(v8::Local<v8::Object> obj, v8::Local<v8::String> key);
Nan::Maybe<bool> Nan::Has(v8::Local<v8::Object> obj, uint32_t index);

Nan::Delete()

A helper method for calling v8::Object#Delete() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::Delete(v8::Local<v8::Object> obj,
                             v8::Local<v8::String> key);
Nan::Maybe<bool> Nan::Delete(v8::Local<v8::Object> obj, uint32_t index);

Nan::GetPropertyNames()

A helper method for calling v8::Object#GetPropertyNames() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Array> Nan::GetPropertyNames(v8::Local<v8::Object> obj);

Nan::GetOwnPropertyNames()

A helper method for calling v8::Object#GetOwnPropertyNames() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Array> Nan::GetOwnPropertyNames(v8::Local<v8::Object> obj);

Nan::SetPrototype()

A helper method for calling v8::Object#SetPrototype() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::SetPrototype(v8::Local<v8::Object> obj,
                                   v8::Local<v8::Value> prototype);

Nan::ObjectProtoToString()

A helper method for calling v8::Object#ObjectProtoToString() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::String> Nan::ObjectProtoToString(v8::Local<v8::Object> obj);

Nan::HasOwnProperty()

A helper method for calling v8::Object#HasOwnProperty() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::HasOwnProperty(v8::Local<v8::Object> obj,
                                     v8::Local<v8::String> key);

Nan::HasRealNamedProperty()

A helper method for calling v8::Object#HasRealNamedProperty() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::HasRealNamedProperty(v8::Local<v8::Object> obj,
                                           v8::Local<v8::String> key);

Nan::HasRealIndexedProperty()

A helper method for calling v8::Object#HasRealIndexedProperty() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::HasRealIndexedProperty(v8::Local<v8::Object> obj,
                                             uint32_t index);

Nan::HasRealNamedCallbackProperty()

A helper method for calling v8::Object#HasRealNamedCallbackProperty() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<bool> Nan::HasRealNamedCallbackProperty(
    v8::Local<v8::Object> obj,
    v8::Local<v8::String> key);

Nan::GetRealNamedPropertyInPrototypeChain()

A helper method for calling v8::Object#GetRealNamedPropertyInPrototypeChain() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::GetRealNamedPropertyInPrototypeChain(
    v8::Local<v8::Object> obj,
    v8::Local<v8::String> key);

Nan::GetRealNamedProperty()

A helper method for calling v8::Object#GetRealNamedProperty() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::GetRealNamedProperty(v8::Local<v8::Object> obj,
                                                     v8::Local<v8::String> key);

Nan::CallAsFunction()

A helper method for calling v8::Object#CallAsFunction() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::CallAsFunction(v8::Local<v8::Object> obj,
                                               v8::Local<v8::Object> recv,
                                               int argc,
                                               v8::Local<v8::Value> argv[]);

Nan::CallAsConstructor()

A helper method for calling v8::Object#CallAsConstructor() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Value> Nan::CallAsConstructor(v8::Local<v8::Object> obj,
                                                  int argc,
                                                  v8::Local<v8::Value> argv[]);

Nan::GetSourceLine()

A helper method for calling v8::Message#GetSourceLine() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::String> Nan::GetSourceLine(v8::Local<v8::Message> msg);

Nan::GetLineNumber()

A helper method for calling v8::Message#GetLineNumber() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<int> Nan::GetLineNumber(v8::Local<v8::Message> msg);

Nan::GetStartColumn()

A helper method for calling v8::Message#GetStartColumn() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<int> Nan::GetStartColumn(v8::Local<v8::Message> msg);

Nan::GetEndColumn()

A helper method for calling v8::Message#GetEndColumn() in a way compatible across supported versions of V8.

Signature:

Nan::Maybe<int> Nan::GetEndColumn(v8::Local<v8::Message> msg);

Nan::CloneElementAt()

A helper method for calling v8::Array#CloneElementAt() in a way compatible across supported versions of V8.

Signature:

Nan::MaybeLocal<v8::Object> Nan::CloneElementAt(v8::Local<v8::Array> array, uint32_t index);

Nan::MakeMaybe()

Wraps a v8::Local<> in a Nan::MaybeLocal<>. When called with a Nan::MaybeLocal<> it just returns its argument. This is useful in generic template code that builds on NAN.

Synopsis:

  MaybeLocal<v8::Number> someNumber = MakeMaybe(New<v8::Number>(3.141592654));
  MaybeLocal<v8::String> someString = MakeMaybe(New<v8::String>("probably"));

Signature:

template <typename T, template <typename> class MaybeMaybe>
Nan::MaybeLocal<T> Nan::MakeMaybe(MaybeMaybe<T> v);