bea/cpp/README.md

Bea tools for C++

Purpose

	The purpose of Bea C++ is to provide a 'glue' between the code generated by the Bea C++ to V8 Converter and native C++ library/application.
	It is a single .h file which provides all the APIs needed by the converter.
	A short description of the API is found in this file.


Building
	You must have the boost libraries installed. Although it bothers me to have this dependency, it is the easiest way to do cross-platform filesystem operations (required by beascript, which loads scripts and resolves includes).
	On MacOS X, use
		
		brew install -v boost 2>&1

	You must build v8 and link your app against it. See the examples for a demo project.



Convert<T>

	Specialize this with a custom type to define conversions from/to Javascript.
	Bea provides specializations for most basic C++ types: int, double, bool, std::string, std::vector, but custom 
	types can be easily converted.
	
		//C++ : Converting a Point object from/to javascript
		template<> struct Convert<cv::Point> {
			static bool Is(v8::Handle<v8::Value> v) {
				return !v.IsEmpty() && v->IsObject();
			}
			
			static cv::Point FromJS(v8::Handle<v8::Value> v, int nArg) {
				const char* msg = "Object with the following properties expected: x, y. This will be cast to 'cv::Point'";
				if (!Is(v)) BEATHROW();
				v8::HandleScope scope;
				v8::Local<v8::Object> obj = v->ToObject();
				cv::Point ret;
				ret.x = bea::Convert<int>::FromJS(obj->Get(v8::String::NewSymbol("x")), nArg);
				ret.y = bea::Convert<int>::FromJS(obj->Get(v8::String::NewSymbol("y")), nArg);
				return ret;
			}
			
			static v8::Handle<v8::Value> ToJS(cv::Point const& v) {
				v8::HandleScope scope;
				v8::Local<v8::Object> obj = v8::Object::New();
				obj->Set(v8::String::NewSymbol("x"), bea::Convert<int>::ToJS(v.x));
				obj->Set(v8::String::NewSymbol("y"), bea::Convert<int>::ToJS(v.y));
				return scope.Close(obj);
			}
		};
		
	If there is an exposed C++ class which takes a cv::Point as a parameter, the following javascript can be used:
		//Javascript: Passing a cv::Point from Javascript to the native function
		myobject.myfunction({x: 100, y: 100});	//Use familiar Javascript object notation
		
	
ExposedClass<T>

	This class is used to expose a C++ class to Javascript. 
	The term 'Class' means 'a function template which can be instantiated from Javascript with operator new.'
	The class must be specialized for the desired type and instantiated. Then the methods *exposeMethod()*, *exposeProperty()*, *setConstructor()* can be called.
	Here is an example:
	
		//C++: Using ExposedClass
		bea::ExposedClass<cv::Mat>* obj = EXPOSE_CLASS(cv::Mat, "Mat");
		//Destructor
		obj->setDestructor(__destructor);
		//Exposed Methods
		obj->setPostAllocator(__postAllocator);
		obj->setConstructor(__constructor);
		obj->exposeMethod("row", row);
		obj->exposeMethod("col", col);
		//Accessors
		obj->exposeProperty("width", accGet_width, accSet_width);
		obj->exposeProperty("height", accGet_height, accSet_height);
		
	This allows us to execute this script:
		//Javascript
		var mat = new Mat();
		mat.row()
		mat.col()
		log(mat.width)
		log(mat.height)
		
DECLARE_EXPOSED_CLASS(ClassName)	

	Helper macros which creates a static variable bea::ExposedClass<ClassName>* bea::ExposedClass<ClassName>::Instance = NULL;
	
EXPOSE_CLASS(typeName, jsName)

	Helper macros which creates an instance of ExposedClass<typeName> and exposes it as jsName
	
ExposedStatic<T>

	This is an object exposed to Javascript, which cannot be instantiated. 
	The term 'Static' means 'an object which can be accessed from Javascript'.
	The class must be specialized for the desired type. Then the method *exposeMethod()*, can be used.
	The functions exposed by ExposedStatic don't have a 'this' pointer (eg. static C++ or C functions).