Conditional support for C++ exceptions (#52)

Enable using the N-API C++ wrapper classes with or without C++
exceptions. See the updated `Napi::Error` class documentation for an
overview of the developer experience.

 - Add a `NAPI_CPP_EXCEPTIONS` preprocessor symbol that is defined
   when C++ exceptions are enabled.
 - Add `Env::GetAndClearPendingException()` method.
 - Add `Value::IsEmpty()` method.
 - Update documentation on Error class to provide parallel
   explanation and examples for error-handling without C++ exceptions.
 - Update README to mention optional C++ exception support.
 - Define a `NAPI_THROW_IF_FAILED()` macro that throws either a C++
   or JS exception depending on whether `NAPI_CPP_EXCEPTIONS` is
   defined.
 - Define a `details::WrapCallback()` helper function that catches C++
   exceptions thrown from callbacks, only if `NAPI_CPP_EXCEPTIONS`
   is defined.
 - Update implementation of all methods to use `NAPI_THROW_IF_FAILED()`
   and `details::WrapCallback()` as appropriate.
 - Fix a bug in `Error::New()` when there was a pending exception but
   some different error status was reported by the last error info.
 - Update `test/binding.gyp` to build two separate modules, with and
   without C++ exceptions enabled.
 - Update test JS code to run the same tests against both modules.
 - Update test C++ code to throw JS exceptions (to be compatible with
   both modes).
 - Add some additional test cases to verify expected exceptions are
   observed from JS regardless of whether C++ exceptions are enabled
   or not.
 - Change CI config to ignore failures on nightly builds.

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 2

.travis.yml

@@ -19,6 +19,9 @@ env:
     - NODEJS_VERSION=chakracore-nightly
 matrix:
   fast_finish: true
+  allow_failures:
+    - env: NODEJS_VERSION=nightly
+    - env: NODEJS_VERSION=chakracore-nightly
 sudo: false
 cache:
   directories:
@@ -50,6 +53,9 @@ before_install:
 install:
   - npm install $NPMOPT
 script:
+  # Travis CI sets NVM_NODEJS_ORG_MIRROR, but it makes node-gyp fail to download headers for nightly builds.
+  - unset NVM_NODEJS_ORG_MIRROR
+
   - npm test $NPMOPT
 after_success:
   - cpp-coveralls --gcov-options '\-lp' --build-root test/build --exclude test

README.md

@@ -26,9 +26,12 @@ To use N-API in a native module:
   'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
 ```
 
-  3. Ensure C++ exceptions are enabled in `binding.gyp`.
-     The N-API C++ wrapper classes use exceptions for error-handling;
-     the base ABI-stable C APIs do not.
+  3. Decide whether the package will enable C++ exceptions in the N-API wrapper.
+     The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
+     N-API C++ wrapper classes may _optionally_
+     [integrate C++ and JavaScript exception-handling
+     ](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html).
+     To enable that capability, C++ exceptions must be enabled in `binding.gyp`:
 ```gyp
   'cflags!': [ '-fno-exceptions' ],
   'cflags_cc!': [ '-fno-exceptions' ],
@@ -41,6 +44,10 @@ To use N-API in a native module:
     'VCCLCompilerTool': { 'ExceptionHandling': 1 },
   },
 ```
+  Alternatively, disable use of C++ exceptions in N-API:
+```gyp
+  'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
+```
 
   4. Include `napi.h` in the native module code.
      To ensure only ABI-stable APIs are used, DO NOT include

appveyor.yml

@@ -9,6 +9,12 @@ environment:
     - NODEJS_VERSION: nightly
     - NODEJS_VERSION: chakracore-nightly
 
+matrix:
+  fast_finish: true
+  allow_failures:
+    - NODEJS_VERSION: nightly
+    - NODEJS_VERSION: chakracore-nightly
+
 platform:
   - x86
   - x64