<commit_before>
## Doxygen docs available here: http://xaxxon.github.io/v8-class-wrapper/docs/html/index.html

## Tutorial for using this library

#### Building V8

Building V8 is not a simple process.

First, you need git:   https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Second, you need "depot tools", a collection of google build tools: http://dev.chromium.org/developers/how-tos/install-depot-tools
You git clone this then set your path (I've been able to just type in the whole path when I want to use them instead of setting my PATH)

(following the instructions here: https://github.com/v8/v8/wiki/Using%20Git)

Third, run `gclient`,(assuming you put depot-tools in your path, otherwise type out the full path to gclient) a tool in depot-tools 
which will make sure the tools are up to date (not sure how important this is)

Fourth, run `fetch v8`.  fetch is another tool in depot-tools.  This will put the code in a directory called v8.

For OS X, you need to tell V8 to build with libc++ (instead of libstdc++).  The following environment variables must be set.  They can
either be set on the command line or put in your ~/.bash_profile (if you put them in your .bash_profile, you must either start a new
shell or `source` your .bash_rc like `. ~/.bash_rc` to get the environment variables in your current shell)

export CXX="`which clang++` -std=c++11 -stdlib=libc++"
export CC="`which clang`"
export CPP="`which clang` -E"
export LINK="`which clang++` -std=c++11 -stdlib=libc++"
export CXX_host="`which clang++`"
export CC_host="`which clang`"
export CPP_host="`which clang` -E"
export LINK_host="`which clang++`"
export GYP_DEFINES="clang=1 mac_deployment_target=10.7"

Again, the above lines are ONLY for OS X builds.



Fifth, go into the v8 directory and type "make native".   This will build V8 for the computer you are on.   If you do a `make all`, it will
attempt to build for x86, x64, as well as ARM and can lead to errors if your computer isn't set up for cross compiling and it takes a LOT longer.

Once this finishes, from the v8 directory, you can `cd out/native` and then run `./d8` which is a javascript shell. (ctrl-d to quit d8)  In this directory
you should see a large number of .a files (but sometimes they seem to be buried in subdirectories).   These are how you will link your application against V8.
The include files are located back off the base v8 directory in the v8/includes directory, but your -I option to your compiler cannot include the "/includes" 
portion of the path as the V8 .h files expect to find themselves in "includes/FILENAME.h"


#### Building/installing Boost

V8 doesn't use Boost, but v8toolkit has additional, desirable features when boost is present. 

With apt-get:  `sudo apt-get install libboost-all-dev`

OS X with brew: `brew install boost --c++11`

From source:

Get boost: http://www.boost.org/doc/libs/1_60_0/more/getting_started/unix-variants.html#get-boost

Install boost: 

Short version: untar, go into boost directory, `./bootstrap.sh`, `./b2` (this can take a while), `./b2 install` (this will install with the prefix /usr/local/include)

More detailed install information: http://www.boost.org/doc/libs/1_60_0/more/getting_started/unix-variants.html

NOTE: If you plan on using the boost libraries that have to be compiled (as opposed to header-only ones), you'll need to build boost with libc++.  Here is an example
on how to do that: https://gist.github.com/jimporter/10442880



#### Build v8toolkit

clone v8toolkit:  git clone https://github.com/xaxxon/v8-class-wrapper.git 

go into the v8-class-wrapper directory (this name will be changed soon)

edit the Makefile so that V8_DIR=\<PATH_TO_V8_BASE_DIRECTORY> (under LINUX if compiling on Linux or in the `else` section if compiling on OS X)

To build the libray, on OS X, type `make`, on Linux, type "make LINUX=1"

The library and some sample programs should build.   To confirm everything is working, `make run` will run the sample programs.



#### Your First V8 program

Here is the simplest program you can write to execute some javascript using the v8toolkit library:

    #include "javascript.h"
    using v8toolkit;
    
    int main(int argc, char ** argv) {
        // any v8-specific command-line arguments will be stripped out
        PlatformHelper::init(argc, argv); 
        
        // creates an isolate helper which can manage some number of contexts
        auto isolate_helper = PlatformHelper::create_isolate();
        
        // javascript doesn't have any way to print to stdout, so this exposes some handy functions to javascript
        isolate_helper->add_print(); 
        
        // a context represents an actual javascript environment in which code is executed
        auto context_helper = isolate_helper->create_context(); 
        
        // Prints to the screen using the print helper function we added above
        context_helper->run("println('Hello JavaScript World!');"); 
    }

Working backwards, a context is the container in which JavaScript code actually runs.   Any changes made to globally accessible objects in a context persist 
and will be seen any other JavaScript run within that same context.

An isolate contains the necessary state for any number of related context objects.  An isolate can also be customized so that all contexts created after the customization share that customization.   In the example above, if we made another context by calling isolate_helper->create_context() a second time, this second context would also have access to println().  However, if a second isolate were made, contexts created from it would not have the print helpers unless add_print() were also to be called on the second isolate.  Lastly, regardless of how many contexts exist within an isolate, only one of them can be active at a time.   If you want multiple threads running JavaScript, you must have multiple isolates.

PlatformHelper manages the per-process configuration for V8 and is used to create isolates.  It has no interaction with your JavaScript execution.  Simply call the static ::init() method on it once and V8 is ready to go.

#### Compiler options to build your program

Here are some example command lines for building an application using V8.  In it are some things that will need to be replaced with the actual location on the 
computer being used:

\<PATH_TO_V8_BASE_DIRECTORY> - the directory containing the v8 include directory.   This cannot include the "include/" directory.

\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR> - location where boost/format.hpp is located.  This is likely /usr/local/include and cannot include the "boost/" directory

\<YOUR_PROGRAM_CPP> - your source code

\<PATH_TO_V8TOOLKIT> - path where this library is installed and built and the file libv8toolkit.a exists

Successfully running the commands below will build your program as `./a.out`

On OS X (command line - unknown how/if xcode works):

    clang++ -std=c++14 -g -I./ -I\<PATH_TO_V8_BASE_DIRECTORY> -g -I\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR>  -Wall -Werror  YOUR_PROGRAM_CPP  
    -L\<PATH_TO_V8_BASE_DIRECTORY>/out/native/  -I\<PATH_TO_V8TOOLKIT> \<PATH_TO_V8TOOLKIT>/libv8toolkit.a -lv8_base -lv8_libbase -lv8_base -lv8_libplatform -lv8_nosnapshot -licudata -licuuc -licui18n  
    
On Linux (tested on Ubuntu Desktop 15.10)

    g++ -std=c++14 -g -I\<PATH_TO_V8TOOLKIT> -I\<PATH_TO_V8_BASE_DIRECTORY>  -I\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR>  -Wall -Werror  \<YOUR_PROGRAM_CPP>
    -L\<PATH_TO_V8_BASE_DIRECTORY>/native/obj.target/tools/gyp/ -L\<PATH_TO_V8_BASE_DIRECTORY>/out/native/obj.target/third_party/icu/  -I\<PATH_TO_V8TOOLKIT>
    \<PATH_TO_V8TOOLKIT>/libv8toolkit.a -lv8_base -lv8_libbase -lv8_base -lv8_libplatform -lv8_nosnapshot -licudata -licuuc -licui18n  -lpthread -licuuc -licudata -ldl
    
Currently no information on windows builds using either MinGW or MSVC++


#### Exposing C++ functions to JavaScript

Simply running pure javascript as in the previous example just isn't interesting, though.  We want to cross the boundary between JavaScript and C++ seemlessly.  
Skipping some of the boilerplate in the previous example, here's how to call a custom C++ function from JavaScript.

    // just a normal function, nothing special about it
    int add_numbers(int x, int y) 
    { 
        return x + y; 
    }
    
    auto i = PlatformHelper::create_isolate();
    i->add_print();
    
    // adds a function named "js_add_numbers" to each context created from this isolate that calls 
    //   the C++ function add_numbers
    i->add_function("js_add_numbers", add_numbers);
    auto c = i->create_context();
    
    // prints 9
    c->run("println(js_add_numbers(4,5));");

This example introduces add_function() method which takes a name and "something to be called". This "something" can be a function, a functor 
(a class with an overloaded operator() method), a lambda (capturing or not), or anything else that std::function can hold.   The magic here is 
that this library knows what the parameter types and return type of the function you're calling are and tries its best to convert the javascript 
values passed in to match the types the function wants.  All the standard C++ types are supported and 
conversion happens using the same mechanism used when converting types in javascript.  User-defined types as well as many common STL containers are
supported as well and are described in detail below.


#### Exposing global C++ variables to JavaScript

Global variables (as well as class public static variables) can be exposed to javascript, as well.   

    int x = 0;
    i->expose_variable("x", x);
    ...
    c->run("x = 4; println(x);"); // prints 4
    printf("%d\n", x); // also prints 4

This works very similarly to the add_function method above.  Give it a name and the variable to expose and JavaScript now has access to it.


#### Using STL containers 

Many common STL containers are supported and behave in a fairly intuitive manner.   If the container acts mostly like an array, it is turned into
an array when passed back to JavaScript.   If the container acts more like an associatie array (key/value pairs), it is turned into a javascript 
object.

    std::vector<int> make_three_element_vector(int i, int j, int k) {
        return std::vector{i,j,k};
    }
    
    // name mismatch, but each describes what they do from the user's perspective
    i->add_function("make_three_element_array", make_three_element_vector); 
    ...
    c->run("a=make_three_element_array(2,3,5); println(a[1]);"); // prints 3

This example shows a C++ function returning a vector which is turned into a JavaScript array.   During that conversion, the std::vector is converted
to an array and then each element inside the vector is converted, so vectors containing any other supported type are supported.   This includes 
containers of containers of containers...  The add_function() method does not support funtions taking a variable number of arguments, but if you're 
willing to learn more about the V8 API, you can write a function taking a variable number of arguments without too much additional work and there's 
an example on this later.

Currently there is no support for passing a JavaScript array or object to a C++ function and having it turned into a STL container as an input
parameter.   This is not believed to be a technical limitation, just a missing featuer.


#### Exposing your C++ class to javascript

Now things really start to get interesting: user-defined types.   Most of the commonly-used features of a C++ class are supported, though there are some limitations, and other
concepts don't map directly, but are still accessible.

Let's first define a type to work with:

    class Person {
    private:
        std::string name;
        int age;
        
    public:
        Animal(std::string name, int age) : name(name), age(age) {}
        virtual speak() {printf("Hi.");}
        
        // people are very impressionable on what their favorite color is.
        std::string favorite_color = "purple";
        
        std::string get_name(){return name;}
        int get_age(){return age;}
    }

To make Person available in javascript, first tell the library it's a class it should know about.  Then tell it what parts of that class it should make 
available to javascript.  There's no requirement to make everything available, and unfortunately there's no introspection in C++ to look at the class
and make everything available automatically.

    auto person_wrapper = i->wrap_class<Person>;
    
    // adds a constructor function in JavaScript called "Person"
    person_wrapper.add_constructor<std::string, int>("Person");
    
    // If you weren't familiar with the syntax for getting a method pointer, now you are.
    person_wrapper.add_method("speak", &Person::speak);
    
    // If you weren't familiar with the syntax for getting a data-member pointer, now you are.
    person_wrapper.add_member("favorite_color", &Person::favorite_color);
    
    // you can chain calls while wrapping your class
    person_wrapper.add_method("get_name", &Person::get_name).add_method("get_age", &Person::get_age);
    
    // It's very important to make the context AFTER wrapping the class.  Only contexts made from the same isolate
    //   after the class is wrapped will see your class.
    c = i->create_context();
    c->run("p = new Person();  p.speak(); println(p.get_name(), ' is ', p.get_age(), ' years old'); println('Favorite color: ', p.favorite_color);  ");

If there was also a default constructor for Person that made "<NAME>" age 18, that could be added with an additional call to add_constructor(), 
but a different JavaScript function name would have to be used, like "PersonDefault".   This is a limitation of the C++ type system and how constructors 
must be called.   `add_constructor<>("PersonNoParams");` would be the syntax to add a default Person constructor if it were present.

The same limitation exists for overloaded plain functions and methods.  They can each be exposed to JavaScript, but they must have different names.

After wrapping your class, you can use your class just as any other primitive type.   On its own, as a paramter to a function, as a return type from
a function, or in an STL container.   

#### Introducing the ScriptHelper

There's one more "helper" type we haven't talked about, since it's not needed for simple examples shown so far.  It's likely in a real-world project
the same code will be run multiple times and compiling it each time is a huge waste.   That's where the ScriptHelper type comes in.

    // returns a compiled script that can be run multiple times without re-compiling
    auto script = context->compile("println('Hello Javascript World!');");
    
    script->run();
    script->run();

That compiled script always runs in the context it was created in.   If you need to run the same code in another context, you will need to recompile it.


#### *Helper object lifetimes

In the following sections, *Helper refers to all of IsolateHelper, ContextHelper, and ScriptHelper

In V8, a context is invalid if the isolate it was created in has been cleaned up.   Similarly, a compiled script isn't valid if its context is
destroyed or invalid.  To help manage these object dependencies, each IsolateHelper, ContextHelper, and ScriptHelper track their dependencies and make
sure those dependencies are not destroyed until they are no longer needed.

If you've noticed in all the examples, the variable storing all the *Helper objects is always set as "auto".  The actual type
returned when creating these types is a std::shared_ptr\<>.  In addition, when a ContextHelper is created from an IsolateHelper or a ScriptHelper from a 
ContextHelper, the newly created object has a shared_ptr to it's parent object.  This ensures an IsolateHelper will not be destroyed while a ContextHelper 
is depending on it or a ContextHelper destroyed while a ScriptHelper is depending on it.  This means that even if your variable storing your IsolateHelper 
goes out of scope, if you've created a ContextHelper from it and still have that object around, the associated IsolateHelper will stick around.  This 
guarantees that as long as you can make the call to run some JavaScript code, the necessary state information will be available for it to succeed.   

To illustrate this:

    {
        std::shared_ptr<ScriptHelper> s;
        {
            // PlatformHelper is a singleton and never goes away
            auto i = PlatformHelper::create_context(); // i reference count is 1
            auto c = i->create_context(); // c reference count is 1, i reference count is now 2
        
            s = c->compile("4;"); // s reference count is 1, c reference count is now 2, i is still 2
        } // i and c variables go out of scope, dropping the reference count to both their objects from 2 to 1
    
        s->run(); // this is fine, i and c still exist and are not leaked
    } 
    // s goes out of scope, dropping s's reference count from 1 to 0 causing it to be destroyed.   Destroying s
    // destroys it's shared_ptr to c, dropping c's reference count to 0 causing c to be destroyed.  Destroying
    // c destroys its shared_ptr to i, dropping i's reference count to 0 causing i to be destroyed  

This behavior means you never have to worry about having your *Helper objects being cleaned up too soon and leaving your compiled scripts unrunnable or
making sure you manually clean up the *Helpers in order to not have a memory leak.   If you can possibly use a *Helper again, it will be there for you
and if you can't, it is destroyed automatically.


#### Running JavaScript in a separate thread

This section is intentionally after the Helper Object Lifetime section because it's important to understand how the *Helper objects maintain their
dependencies.  The description of the dependency mechanism is expanded on in this section, so if you didn't read Helper Object Lifetime (or it didn't 
make sense the first time), go back and read it (again) before continuing with this section.

In all our examples so far, the JavaScript has been executed on the current thread: context->run() or script->run() is called, the JavaScript executes immediately
and when it's done, execution resumes in your code.   However, it's quite easy to run javascript in a separate thread.  There are 3 options provided for running background
Javascript, std::async/std::future, std::thread (joinable), and std::thread(detached) and each of maintains a shared_ptr to the ScriptHelper they are run from
so nothing you do while it is running can cause the objects it depends on to be destroyed.  Note that even if you don't explicitly create a ScriptHelper 
and simply call context->run(some_code), a ScriptHelper is created behind the scenes for you.



##### run_threaded()

Calling run_threaded() creates a new thread running the requested JavaScript and returns the std::thread object associated with that thread to the caller.  
This allows the caller to do some work and then call thread.join() to wait for the thread to complete if it hasn't already.  

The std::thread library is pretty bare compared to native threading libraries in modern OSs, but std::thread gives you access to the underlying 
implementation via thread.native_handle(), so you can use all the advanced pthreads or Windows threads functionality you want to control your
thread.

Remember, if the std::thread object returned by run_threaded() goes out of scope before you call detach() or join() on it, your program will exit 
immediately.   This is part of the C++ standard, so be careful.


##### run_detached()

Calling run_detached() is completely fire and forget.   It kicks off your javascript on a new thread and returns.   You don't get
anything back.   You cannot  find out if the thread has finished.  The code you're executing could potentially set variables to note its progress or completion, but run_detached() 
doesn't provide anything for you directly.  The detached thread will hold open the *Helpers it needs until it completes.   

The implementation of run_detached literally calls run_threaded(), then thread.detach(); and returns void to the caller. 




##### run_async()

Running javascript in a std::async behaves exactly like running any other code in a std::async.   The work is put in the async, and
a std::future object is returned.   At any later time, the execution path calls future.get() and the result of the completed
async is returned.  If the async has not completed, get() will block until it has completed.  Note, future.get() does not directly return the result
of your JavaScript, it returns a `std::pair<v8::Global<v8::Value>`, `std::shared_ptr<ScriptHelper>>`.  This means that even if you lost all your handles
to your isolate, context, and script, you can still use the results in the future, since the shared_ptr in the future is keeping everything alive
for you.

    auto script = context->compile("4");
    {
        auto future = script->run_async();
        ... do some other work here...
        auto result = future.get(); // if the async hasn't completed, this call blocks until the async completes
        // do something with result->first (if you aren't going to use the result, you should use run_threaded instead of async)
    } 
    // the future goes out of scope, so it's no longer keeping your ScriptHelper so if you use the result after here
    //   you have to be careful that it's still valid (ensure neither the associated context or isolate have been destroyed)


It's important to note that only one context per isolate can be executing on a thread at a time.   This means if you spawn off a thread to run in the 
background, and then try to do something in another context in the same isolate, one of the two will block (whichever doesn't get to the internal V8 
lock in the v8::Isolate object first) until the other completes.  This means it is possible to create a deadlock if your background thread is caught 
in an infinite loop and your main thread then tries to do something requiring the lock.   


#### Writing more complicated C++ functions using the V8 API

Earlier, in the section about using STL containers, a function taking 3 ints and returning a vector with those values in it was shown.   While a function with any
number of arguments could have been made, it had to be a fixed number.   Here, we will learn how to write a function in C++ that can take any number of parameters
from javascript and decide how to act on them.

This will require delving a little bit into the V8 API however.   The API is complex, not particularly straightforward, and the documentation is hit or miss.   

The most up-to-date documentation lives here:  http://v8.paulfryzel.com/docs/master/

With the power to write more flexible functions comes the responsibility of doing this work manually.

First, a function wanting to handle the javascript parameter directly must have the following signature: a single input paramter of type 
`const v8::FunctionCallbackInfo<v8::Value> &` and a `void` return type. Only for functions with exactly this signature will the raw data will be passed through 
to the function with no "magic" behind the scenes.

Second, the function must manipulate its `FunctionCallbackInfo<T>` object which represents the javascript function invocation.  There three important parts of 
`FunctionCallbackInfo<T>`` for this are:

`Length()` - the number of parameters passed in from JavaScript.
`operator[N]` - returns the javascript parameter at position N (N must be \< Length())
`GetReturnValue()` - Used for returning a v8::Value back to the JavaScript caller

Lastly, the types must be marshalled from their JavaScript types to traditional C++ types and then back to a JavaScrit value for the return value.  There are two 
functors for doing these conversions - they are called `CastToNative<T>` and `CastToJS<T>`.  T always refers to the native
type as the JavaScript type is always v8::Value.


With this information, here is an example of a function taking an arbitrary number of parameters and returning a `std::vector<int>` with all the parameters in it:

    void make_vector(const v8::FunctionCallbackInfo<v8::Value> info &) {
        std::vector<int> v;
        for(int i = 0; i < info.Length(); i++) {
            v.push_back(CastToNative<int>(info[i]));
        }
        info.GetReturnValue.Set(CastToJS<std::vector<int>>(v));
    }

That's it.   It loops through each parameter passed in from JavaScript, runs `CastToNative<int>` on each JavaScript value to coerce it into an int
(how good that coercion is depends on how integer-y the JavaScript values are), and pushes that int onto the end of the vector. Then, to return
the result back to the JavaScript caller, it takes the vector and turns it into a v8::Value appropriate for returning back to the JavaScript caller.

If the type you want to cast to or from isn't supported, more V8 API work is in store, but fortunately the next section is:

#### Extending CastToNative and CastToJS

The two functors `CastToNative<T>` and `CastToJS<T>` are responsible for converting back and forth between v8::Value (which can represent any JavaScript type)
and a specific native type.  Most of the casts are in casts.hpp.  There are a large number of specializations - all the native C++ types as well as many 
types from std::.

The casts missing from casts.hpp are the ones responsible for handling user-defined types.  These are located in v8_class_wrapper.h.   There should be 
no need to change these.  They are only selected when no exact match is found.

There should be enough examples of how to use the V8 API for wrapping types in the existig casts for other types.   For example, to wrap a new STL 
container, look at the existing casts for STL containers: std::vector is quite simple, std::map is more complex, and std::multimap is fairly complex 
as it creates an object with vectors for values.


#### Exceptions

##### The ignorance-is-bliss short version:

Exceptions work just like you'd expect.  Exceptions thrown in a C++ function called from JavaScript will immediately stop
JavaScript execution and bubble up to your script->run() call where you should catch and handle them.   There are also a few exception types 
thrown by the system: V8CompilationException and V8ExecutionException.   These override std::exception and provide the what() method which returns 
a const char * string description of what happened.  If you are going to be using the *Helper objects for all your V8 interactions, you can stop 
here and be happy.  No need to read any more of this section.

##### The long version:

The V8 JavaScript engine is not exception safe (and is compiled with -fno-exceptions).  Any exception making it into actual V8 library code will 
cause your application to immediately exit.  To add to the confusion, V8 has "exceptions" but they are not related, in any way, to C++ exceptions.

Knowing this, then, how can "the short version" be true?  Well, exceptions thrown in C++ code called from ScriptHelper->run() (remember, a ScriptHelper
is created behind the scenes if you call context->run()) are wrapped in a V8 
Exception before re-entering V8 code and then re-thrown once execution leaves the V8 library stack.  This re-thrown exception is the same exception 
as the one thrown inside the callbacks (using std::current_exception and std::exception_ptr to accomplish this).  Code not using *Helper objects, must 
deal with any thrown C++ exceptions on their own to make sure they don't reach any V8 code.  To throw a V8 exception, use v8::Isolate::ThrowException 
and to catch a V8 exception, declare a v8::TryCatch object on the stack where you want to catch V8 exceptions and you can test TryCatch::HasCaught() 
to see if it "has caught" and exception.  Also, often the return value of the V8 call in which the V8 exception was thrown will be a Maybe or a 
MaybeLocal which will contain no value.   That's a sign to check the TryCatch object for an Exception.   TryCatch::Exception() returns the actual v8::Value 
passed to v8::Isolate::ThrowException().  



#### Lifetime rules for wrapped objects
DO NOT READ THIS SECTION
In the process of JavaScript creating, using, and destroying JavaScript objects backed by C++ objects (like custom-wrapped user-defined classes),
it's not always clear when the underlying C++ object should be destroyed versus when it should remain.   Take object creation, for example: There
are many situations in which a user-class C++ object may be instantiated.   JavaScript calls the registered constructor (new Person()), a registered
C++ function returns a newly created object with C++'s new (a factory method, for instance, returning a Person * or Pereson &), a registered C++ 
function returning an r-value.  What about a user-defined class containing another user-defined object with an accessor to return that contained type.

How to determine the correct behavior is an ongoing process for this library.  The rest of this section is a bit of a brain-dump.   Usually the time
when it's known best what the right thing to do 
OK TO START READING AGAIN


For full example use that's guaranteed to be up to date, please see sample.cpp, toolbox_sample.cpp, and javascript_sample.cpp.  Also see threaded_smaple.cpp for examples of how to do multithreaded calls.


# Behaviors:
If a wrapped class type r-value is returned from a function, a default copy will be made and the underlying object will be deleted when the javascript object is garbage collected.
Subsequent calls to that function will return different javascript objects backed by different c++ objects.

If a wrapped class type reference or pointer value is returned from a function, the first time it will create a new javascript object for the object.   Subsequent calls will return the same javascript object (not different javascript objects wrapping the same c++ object).   This means you can customize the object in javascript outside of the c++ interactions and get it again later.

<commit_msg>fixed indentation on a section<commit_after>
## Doxygen docs available here: http://xaxxon.github.io/v8-class-wrapper/docs/html/index.html

## Tutorial for using this library

#### Building V8

Building V8 is not a simple process.

First, you need git:   https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Second, you need "depot tools", a collection of google build tools: http://dev.chromium.org/developers/how-tos/install-depot-tools
You git clone this then set your path (I've been able to just type in the whole path when I want to use them instead of setting my PATH)

(following the instructions here: https://github.com/v8/v8/wiki/Using%20Git)

Third, run `gclient`,(assuming you put depot-tools in your path, otherwise type out the full path to gclient) a tool in depot-tools 
which will make sure the tools are up to date (not sure how important this is)

Fourth, run `fetch v8`.  fetch is another tool in depot-tools.  This will put the code in a directory called v8.

For OS X, you need to tell V8 to build with libc++ (instead of libstdc++).  The following environment variables must be set.  They can
either be set on the command line or put in your ~/.bash_profile (if you put them in your .bash_profile, you must either start a new
shell or `source` your .bash_rc like `. ~/.bash_rc` to get the environment variables in your current shell)

    export CXX="`which clang++` -std=c++11 -stdlib=libc++"
    export CC="`which clang`"
    export CPP="`which clang` -E"
    export LINK="`which clang++` -std=c++11 -stdlib=libc++"
    export CXX_host="`which clang++`"
    export CC_host="`which clang`"
    export CPP_host="`which clang` -E"
    export LINK_host="`which clang++`"
    export GYP_DEFINES="clang=1 mac_deployment_target=10.7"

Again, the above lines are ONLY for OS X builds.



Fifth, go into the v8 directory and type "make native".   This will build V8 for the computer you are on.   If you do a `make all`, it will
attempt to build for x86, x64, as well as ARM and can lead to errors if your computer isn't set up for cross compiling and it takes a LOT longer.

Once this finishes, from the v8 directory, you can `cd out/native` and then run `./d8` which is a javascript shell. (ctrl-d to quit d8)  In this directory
you should see a large number of .a files (but sometimes they seem to be buried in subdirectories).   These are how you will link your application against V8.
The include files are located back off the base v8 directory in the v8/includes directory, but your -I option to your compiler cannot include the "/includes" 
portion of the path as the V8 .h files expect to find themselves in "includes/FILENAME.h"


#### Building/installing Boost

V8 doesn't use Boost, but v8toolkit has additional, desirable features when boost is present. 

With apt-get:  `sudo apt-get install libboost-all-dev`

OS X with brew: `brew install boost --c++11`

From source:

Get boost: http://www.boost.org/doc/libs/1_60_0/more/getting_started/unix-variants.html#get-boost

Install boost: 

Short version: untar, go into boost directory, `./bootstrap.sh`, `./b2` (this can take a while), `./b2 install` (this will install with the prefix /usr/local/include)

More detailed install information: http://www.boost.org/doc/libs/1_60_0/more/getting_started/unix-variants.html

NOTE: If you plan on using the boost libraries that have to be compiled (as opposed to header-only ones), you'll need to build boost with libc++.  Here is an example
on how to do that: https://gist.github.com/jimporter/10442880



#### Build v8toolkit

clone v8toolkit:  git clone https://github.com/xaxxon/v8-class-wrapper.git 

go into the v8-class-wrapper directory (this name will be changed soon)

edit the Makefile so that V8_DIR=\<PATH_TO_V8_BASE_DIRECTORY> (under LINUX if compiling on Linux or in the `else` section if compiling on OS X)

To build the libray, on OS X, type `make`, on Linux, type "make LINUX=1"

The library and some sample programs should build.   To confirm everything is working, `make run` will run the sample programs.



#### Your First V8 program

Here is the simplest program you can write to execute some javascript using the v8toolkit library:

    #include "javascript.h"
    using v8toolkit;
    
    int main(int argc, char ** argv) {
        // any v8-specific command-line arguments will be stripped out
        PlatformHelper::init(argc, argv); 
        
        // creates an isolate helper which can manage some number of contexts
        auto isolate_helper = PlatformHelper::create_isolate();
        
        // javascript doesn't have any way to print to stdout, so this exposes some handy functions to javascript
        isolate_helper->add_print(); 
        
        // a context represents an actual javascript environment in which code is executed
        auto context_helper = isolate_helper->create_context(); 
        
        // Prints to the screen using the print helper function we added above
        context_helper->run("println('Hello JavaScript World!');"); 
    }

Working backwards, a context is the container in which JavaScript code actually runs.   Any changes made to globally accessible objects in a context persist 
and will be seen any other JavaScript run within that same context.

An isolate contains the necessary state for any number of related context objects.  An isolate can also be customized so that all contexts created after the customization share that customization.   In the example above, if we made another context by calling isolate_helper->create_context() a second time, this second context would also have access to println().  However, if a second isolate were made, contexts created from it would not have the print helpers unless add_print() were also to be called on the second isolate.  Lastly, regardless of how many contexts exist within an isolate, only one of them can be active at a time.   If you want multiple threads running JavaScript, you must have multiple isolates.

PlatformHelper manages the per-process configuration for V8 and is used to create isolates.  It has no interaction with your JavaScript execution.  Simply call the static ::init() method on it once and V8 is ready to go.

#### Compiler options to build your program

Here are some example command lines for building an application using V8.  In it are some things that will need to be replaced with the actual location on the 
computer being used:

\<PATH_TO_V8_BASE_DIRECTORY> - the directory containing the v8 include directory.   This cannot include the "include/" directory.

\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR> - location where boost/format.hpp is located.  This is likely /usr/local/include and cannot include the "boost/" directory

\<YOUR_PROGRAM_CPP> - your source code

\<PATH_TO_V8TOOLKIT> - path where this library is installed and built and the file libv8toolkit.a exists

Successfully running the commands below will build your program as `./a.out`

On OS X (command line - unknown how/if xcode works):

    clang++ -std=c++14 -g -I./ -I\<PATH_TO_V8_BASE_DIRECTORY> -g -I\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR>  -Wall -Werror  YOUR_PROGRAM_CPP  
    -L\<PATH_TO_V8_BASE_DIRECTORY>/out/native/  -I\<PATH_TO_V8TOOLKIT> \<PATH_TO_V8TOOLKIT>/libv8toolkit.a -lv8_base -lv8_libbase -lv8_base -lv8_libplatform -lv8_nosnapshot -licudata -licuuc -licui18n  
    
On Linux (tested on Ubuntu Desktop 15.10)

    g++ -std=c++14 -g -I\<PATH_TO_V8TOOLKIT> -I\<PATH_TO_V8_BASE_DIRECTORY>  -I\<PATH_TO_DIRECTORY_WITH_BOOST_INCLUDE_DIR>  -Wall -Werror  \<YOUR_PROGRAM_CPP>
    -L\<PATH_TO_V8_BASE_DIRECTORY>/native/obj.target/tools/gyp/ -L\<PATH_TO_V8_BASE_DIRECTORY>/out/native/obj.target/third_party/icu/  -I\<PATH_TO_V8TOOLKIT>
    \<PATH_TO_V8TOOLKIT>/libv8toolkit.a -lv8_base -lv8_libbase -lv8_base -lv8_libplatform -lv8_nosnapshot -licudata -licuuc -licui18n  -lpthread -licuuc -licudata -ldl
    
Currently no information on windows builds using either MinGW or MSVC++


#### Exposing C++ functions to JavaScript

Simply running pure javascript as in the previous example just isn't interesting, though.  We want to cross the boundary between JavaScript and C++ seemlessly.  
Skipping some of the boilerplate in the previous example, here's how to call a custom C++ function from JavaScript.

    // just a normal function, nothing special about it
    int add_numbers(int x, int y) 
    { 
        return x + y; 
    }
    
    auto i = PlatformHelper::create_isolate();
    i->add_print();
    
    // adds a function named "js_add_numbers" to each context created from this isolate that calls 
    //   the C++ function add_numbers
    i->add_function("js_add_numbers", add_numbers);
    auto c = i->create_context();
    
    // prints 9
    c->run("println(js_add_numbers(4,5));");

This example introduces add_function() method which takes a name and "something to be called". This "something" can be a function, a functor 
(a class with an overloaded operator() method), a lambda (capturing or not), or anything else that std::function can hold.   The magic here is 
that this library knows what the parameter types and return type of the function you're calling are and tries its best to convert the javascript 
values passed in to match the types the function wants.  All the standard C++ types are supported and 
conversion happens using the same mechanism used when converting types in javascript.  User-defined types as well as many common STL containers are
supported as well and are described in detail below.


#### Exposing global C++ variables to JavaScript

Global variables (as well as class public static variables) can be exposed to javascript, as well.   

    int x = 0;
    i->expose_variable("x", x);
    ...
    c->run("x = 4; println(x);"); // prints 4
    printf("%d\n", x); // also prints 4

This works very similarly to the add_function method above.  Give it a name and the variable to expose and JavaScript now has access to it.


#### Using STL containers 

Many common STL containers are supported and behave in a fairly intuitive manner.   If the container acts mostly like an array, it is turned into
an array when passed back to JavaScript.   If the container acts more like an associatie array (key/value pairs), it is turned into a javascript 
object.

    std::vector<int> make_three_element_vector(int i, int j, int k) {
        return std::vector{i,j,k};
    }
    
    // name mismatch, but each describes what they do from the user's perspective
    i->add_function("make_three_element_array", make_three_element_vector); 
    ...
    c->run("a=make_three_element_array(2,3,5); println(a[1]);"); // prints 3

This example shows a C++ function returning a vector which is turned into a JavaScript array.   During that conversion, the std::vector is converted
to an array and then each element inside the vector is converted, so vectors containing any other supported type are supported.   This includes 
containers of containers of containers...  The add_function() method does not support funtions taking a variable number of arguments, but if you're 
willing to learn more about the V8 API, you can write a function taking a variable number of arguments without too much additional work and there's 
an example on this later.

Currently there is no support for passing a JavaScript array or object to a C++ function and having it turned into a STL container as an input
parameter.   This is not believed to be a technical limitation, just a missing featuer.


#### Exposing your C++ class to javascript

Now things really start to get interesting: user-defined types.   Most of the commonly-used features of a C++ class are supported, though there are some limitations, and other
concepts don't map directly, but are still accessible.

Let's first define a type to work with:

    class Person {
    private:
        std::string name;
        int age;
        
    public:
        Animal(std::string name, int age) : name(name), age(age) {}
        virtual speak() {printf("Hi.");}
        
        // people are very impressionable on what their favorite color is.
        std::string favorite_color = "purple";
        
        std::string get_name(){return name;}
        int get_age(){return age;}
    }

To make Person available in javascript, first tell the library it's a class it should know about.  Then tell it what parts of that class it should make 
available to javascript.  There's no requirement to make everything available, and unfortunately there's no introspection in C++ to look at the class
and make everything available automatically.

    auto person_wrapper = i->wrap_class<Person>;
    
    // adds a constructor function in JavaScript called "Person"
    person_wrapper.add_constructor<std::string, int>("Person");
    
    // If you weren't familiar with the syntax for getting a method pointer, now you are.
    person_wrapper.add_method("speak", &Person::speak);
    
    // If you weren't familiar with the syntax for getting a data-member pointer, now you are.
    person_wrapper.add_member("favorite_color", &Person::favorite_color);
    
    // you can chain calls while wrapping your class
    person_wrapper.add_method("get_name", &Person::get_name).add_method("get_age", &Person::get_age);
    
    // It's very important to make the context AFTER wrapping the class.  Only contexts made from the same isolate
    //   after the class is wrapped will see your class.
    c = i->create_context();
    c->run("p = new Person();  p.speak(); println(p.get_name(), ' is ', p.get_age(), ' years old'); println('Favorite color: ', p.favorite_color);  ");

If there was also a default constructor for Person that made "<NAME>" age 18, that could be added with an additional call to add_constructor(), 
but a different JavaScript function name would have to be used, like "PersonDefault".   This is a limitation of the C++ type system and how constructors 
must be called.   `add_constructor<>("PersonNoParams");` would be the syntax to add a default Person constructor if it were present.

The same limitation exists for overloaded plain functions and methods.  They can each be exposed to JavaScript, but they must have different names.

After wrapping your class, you can use your class just as any other primitive type.   On its own, as a paramter to a function, as a return type from
a function, or in an STL container.   

#### Introducing the ScriptHelper

There's one more "helper" type we haven't talked about, since it's not needed for simple examples shown so far.  It's likely in a real-world project
the same code will be run multiple times and compiling it each time is a huge waste.   That's where the ScriptHelper type comes in.

    // returns a compiled script that can be run multiple times without re-compiling
    auto script = context->compile("println('Hello Javascript World!');");
    
    script->run();
    script->run();

That compiled script always runs in the context it was created in.   If you need to run the same code in another context, you will need to recompile it.


#### *Helper object lifetimes

In the following sections, *Helper refers to all of IsolateHelper, ContextHelper, and ScriptHelper

In V8, a context is invalid if the isolate it was created in has been cleaned up.   Similarly, a compiled script isn't valid if its context is
destroyed or invalid.  To help manage these object dependencies, each IsolateHelper, ContextHelper, and ScriptHelper track their dependencies and make
sure those dependencies are not destroyed until they are no longer needed.

If you've noticed in all the examples, the variable storing all the *Helper objects is always set as "auto".  The actual type
returned when creating these types is a std::shared_ptr\<>.  In addition, when a ContextHelper is created from an IsolateHelper or a ScriptHelper from a 
ContextHelper, the newly created object has a shared_ptr to it's parent object.  This ensures an IsolateHelper will not be destroyed while a ContextHelper 
is depending on it or a ContextHelper destroyed while a ScriptHelper is depending on it.  This means that even if your variable storing your IsolateHelper 
goes out of scope, if you've created a ContextHelper from it and still have that object around, the associated IsolateHelper will stick around.  This 
guarantees that as long as you can make the call to run some JavaScript code, the necessary state information will be available for it to succeed.   

To illustrate this:

    {
        std::shared_ptr<ScriptHelper> s;
        {
            // PlatformHelper is a singleton and never goes away
            auto i = PlatformHelper::create_context(); // i reference count is 1
            auto c = i->create_context(); // c reference count is 1, i reference count is now 2
        
            s = c->compile("4;"); // s reference count is 1, c reference count is now 2, i is still 2
        } // i and c variables go out of scope, dropping the reference count to both their objects from 2 to 1
    
        s->run(); // this is fine, i and c still exist and are not leaked
    } 
    // s goes out of scope, dropping s's reference count from 1 to 0 causing it to be destroyed.   Destroying s
    // destroys it's shared_ptr to c, dropping c's reference count to 0 causing c to be destroyed.  Destroying
    // c destroys its shared_ptr to i, dropping i's reference count to 0 causing i to be destroyed  

This behavior means you never have to worry about having your *Helper objects being cleaned up too soon and leaving your compiled scripts unrunnable or
making sure you manually clean up the *Helpers in order to not have a memory leak.   If you can possibly use a *Helper again, it will be there for you
and if you can't, it is destroyed automatically.


#### Running JavaScript in a separate thread

This section is intentionally after the Helper Object Lifetime section because it's important to understand how the *Helper objects maintain their
dependencies.  The description of the dependency mechanism is expanded on in this section, so if you didn't read Helper Object Lifetime (or it didn't 
make sense the first time), go back and read it (again) before continuing with this section.

In all our examples so far, the JavaScript has been executed on the current thread: context->run() or script->run() is called, the JavaScript executes immediately
and when it's done, execution resumes in your code.   However, it's quite easy to run javascript in a separate thread.  There are 3 options provided for running background
Javascript, std::async/std::future, std::thread (joinable), and std::thread(detached) and each of maintains a shared_ptr to the ScriptHelper they are run from
so nothing you do while it is running can cause the objects it depends on to be destroyed.  Note that even if you don't explicitly create a ScriptHelper 
and simply call context->run(some_code), a ScriptHelper is created behind the scenes for you.



##### run_threaded()

Calling run_threaded() creates a new thread running the requested JavaScript and returns the std::thread object associated with that thread to the caller.  
This allows the caller to do some work and then call thread.join() to wait for the thread to complete if it hasn't already.  

The std::thread library is pretty bare compared to native threading libraries in modern OSs, but std::thread gives you access to the underlying 
implementation via thread.native_handle(), so you can use all the advanced pthreads or Windows threads functionality you want to control your
thread.

Remember, if the std::thread object returned by run_threaded() goes out of scope before you call detach() or join() on it, your program will exit 
immediately.   This is part of the C++ standard, so be careful.


##### run_detached()

Calling run_detached() is completely fire and forget.   It kicks off your javascript on a new thread and returns.   You don't get
anything back.   You cannot  find out if the thread has finished.  The code you're executing could potentially set variables to note its progress or completion, but run_detached() 
doesn't provide anything for you directly.  The detached thread will hold open the *Helpers it needs until it completes.   

The implementation of run_detached literally calls run_threaded(), then thread.detach(); and returns void to the caller. 




##### run_async()

Running javascript in a std::async behaves exactly like running any other code in a std::async.   The work is put in the async, and
a std::future object is returned.   At any later time, the execution path calls future.get() and the result of the completed
async is returned.  If the async has not completed, get() will block until it has completed.  Note, future.get() does not directly return the result
of your JavaScript, it returns a `std::pair<v8::Global<v8::Value>`, `std::shared_ptr<ScriptHelper>>`.  This means that even if you lost all your handles
to your isolate, context, and script, you can still use the results in the future, since the shared_ptr in the future is keeping everything alive
for you.

    auto script = context->compile("4");
    {
        auto future = script->run_async();
        ... do some other work here...
        auto result = future.get(); // if the async hasn't completed, this call blocks until the async completes
        // do something with result->first (if you aren't going to use the result, you should use run_threaded instead of async)
    } 
    // the future goes out of scope, so it's no longer keeping your ScriptHelper so if you use the result after here
    //   you have to be careful that it's still valid (ensure neither the associated context or isolate have been destroyed)


It's important to note that only one context per isolate can be executing on a thread at a time.   This means if you spawn off a thread to run in the 
background, and then try to do something in another context in the same isolate, one of the two will block (whichever doesn't get to the internal V8 
lock in the v8::Isolate object first) until the other completes.  This means it is possible to create a deadlock if your background thread is caught 
in an infinite loop and your main thread then tries to do something requiring the lock.   


#### Writing more complicated C++ functions using the V8 API

Earlier, in the section about using STL containers, a function taking 3 ints and returning a vector with those values in it was shown.   While a function with any
number of arguments could have been made, it had to be a fixed number.   Here, we will learn how to write a function in C++ that can take any number of parameters
from javascript and decide how to act on them.

This will require delving a little bit into the V8 API however.   The API is complex, not particularly straightforward, and the documentation is hit or miss.   

The most up-to-date documentation lives here:  http://v8.paulfryzel.com/docs/master/

With the power to write more flexible functions comes the responsibility of doing this work manually.

First, a function wanting to handle the javascript parameter directly must have the following signature: a single input paramter of type 
`const v8::FunctionCallbackInfo<v8::Value> &` and a `void` return type. Only for functions with exactly this signature will the raw data will be passed through 
to the function with no "magic" behind the scenes.

Second, the function must manipulate its `FunctionCallbackInfo<T>` object which represents the javascript function invocation.  There three important parts of 
`FunctionCallbackInfo<T>`` for this are:

`Length()` - the number of parameters passed in from JavaScript.
`operator[N]` - returns the javascript parameter at position N (N must be \< Length())
`GetReturnValue()` - Used for returning a v8::Value back to the JavaScript caller

Lastly, the types must be marshalled from their JavaScript types to traditional C++ types and then back to a JavaScrit value for the return value.  There are two 
functors for doing these conversions - they are called `CastToNative<T>` and `CastToJS<T>`.  T always refers to the native
type as the JavaScript type is always v8::Value.


With this information, here is an example of a function taking an arbitrary number of parameters and returning a `std::vector<int>` with all the parameters in it:

    void make_vector(const v8::FunctionCallbackInfo<v8::Value> info &) {
        std::vector<int> v;
        for(int i = 0; i < info.Length(); i++) {
            v.push_back(CastToNative<int>(info[i]));
        }
        info.GetReturnValue.Set(CastToJS<std::vector<int>>(v));
    }

That's it.   It loops through each parameter passed in from JavaScript, runs `CastToNative<int>` on each JavaScript value to coerce it into an int
(how good that coercion is depends on how integer-y the JavaScript values are), and pushes that int onto the end of the vector. Then, to return
the result back to the JavaScript caller, it takes the vector and turns it into a v8::Value appropriate for returning back to the JavaScript caller.

If the type you want to cast to or from isn't supported, more V8 API work is in store, but fortunately the next section is:

#### Extending CastToNative and CastToJS

The two functors `CastToNative<T>` and `CastToJS<T>` are responsible for converting back and forth between v8::Value (which can represent any JavaScript type)
and a specific native type.  Most of the casts are in casts.hpp.  There are a large number of specializations - all the native C++ types as well as many 
types from std::.

The casts missing from casts.hpp are the ones responsible for handling user-defined types.  These are located in v8_class_wrapper.h.   There should be 
no need to change these.  They are only selected when no exact match is found.

There should be enough examples of how to use the V8 API for wrapping types in the existig casts for other types.   For example, to wrap a new STL 
container, look at the existing casts for STL containers: std::vector is quite simple, std::map is more complex, and std::multimap is fairly complex 
as it creates an object with vectors for values.


#### Exceptions

##### The ignorance-is-bliss short version:

Exceptions work just like you'd expect.  Exceptions thrown in a C++ function called from JavaScript will immediately stop
JavaScript execution and bubble up to your script->run() call where you should catch and handle them.   There are also a few exception types 
thrown by the system: V8CompilationException and V8ExecutionException.   These override std::exception and provide the what() method which returns 
a const char * string description of what happened.  If you are going to be using the *Helper objects for all your V8 interactions, you can stop 
here and be happy.  No need to read any more of this section.

##### The long version:

The V8 JavaScript engine is not exception safe (and is compiled with -fno-exceptions).  Any exception making it into actual V8 library code will 
cause your application to immediately exit.  To add to the confusion, V8 has "exceptions" but they are not related, in any way, to C++ exceptions.

Knowing this, then, how can "the short version" be true?  Well, exceptions thrown in C++ code called from ScriptHelper->run() (remember, a ScriptHelper
is created behind the scenes if you call context->run()) are wrapped in a V8 
Exception before re-entering V8 code and then re-thrown once execution leaves the V8 library stack.  This re-thrown exception is the same exception 
as the one thrown inside the callbacks (using std::current_exception and std::exception_ptr to accomplish this).  Code not using *Helper objects, must 
deal with any thrown C++ exceptions on their own to make sure they don't reach any V8 code.  To throw a V8 exception, use v8::Isolate::ThrowException 
and to catch a V8 exception, declare a v8::TryCatch object on the stack where you want to catch V8 exceptions and you can test TryCatch::HasCaught() 
to see if it "has caught" and exception.  Also, often the return value of the V8 call in which the V8 exception was thrown will be a Maybe or a 
MaybeLocal which will contain no value.   That's a sign to check the TryCatch object for an Exception.   TryCatch::Exception() returns the actual v8::Value 
passed to v8::Isolate::ThrowException().  



#### Lifetime rules for wrapped objects
DO NOT READ THIS SECTION
In the process of JavaScript creating, using, and destroying JavaScript objects backed by C++ objects (like custom-wrapped user-defined classes),
it's not always clear when the underlying C++ object should be destroyed versus when it should remain.   Take object creation, for example: There
are many situations in which a user-class C++ object may be instantiated.   JavaScript calls the registered constructor (new Person()), a registered
C++ function returns a newly created object with C++'s new (a factory method, for instance, returning a Person * or Pereson &), a registered C++ 
function returning an r-value.  What about a user-defined class containing another user-defined object with an accessor to return that contained type.

How to determine the correct behavior is an ongoing process for this library.  The rest of this section is a bit of a brain-dump.   Usually the time
when it's known best what the right thing to do 
OK TO START READING AGAIN


For full example use that's guaranteed to be up to date, please see sample.cpp, toolbox_sample.cpp, and javascript_sample.cpp.  Also see threaded_smaple.cpp for examples of how to do multithreaded calls.


# Behaviors:
If a wrapped class type r-value is returned from a function, a default copy will be made and the underlying object will be deleted when the javascript object is garbage collected.
Subsequent calls to that function will return different javascript objects backed by different c++ objects.

If a wrapped class type reference or pointer value is returned from a function, the first time it will create a new javascript object for the object.   Subsequent calls will return the same javascript object (not different javascript objects wrapping the same c++ object).   This means you can customize the object in javascript outside of the c++ interactions and get it again later.


{'fraction_non_alphanumeric': 0.06408920211094016, 'fraction_numerical': 0.005823283206776184, 'mean_word_length': 3.9132731854019345, 'pattern_counts': {'":': 0, '<': 91, '<?xml version=': 0, '>': 147, 'https://': 8, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5227339', 'n_tokens_mistral': 16305, 'n_tokens_neox': 15432, 'n_words': 8602}