Commits

Nikhil Marathe committed 6ee8aa1

Updated Part 2 to add v8 types explanation

Comments (0)

Files changed (2)

articles/c_in_my_javascript/c_in_javascript_part_2.html

 <h1>There&#8217;s a C in my JavaScript: Part 2</h1>
 <span id="author">Nikhil Marathe</span><br />
 <span id="email"><tt>&lt;<a href="mailto:nsm.nikhil@gmail.com">nsm.nikhil@gmail.com</a>&gt;</tt></span><br />
-<span id="revnumber">version 1.0,</span>
-<span id="revdate">March 2010</span>
+<span id="revnumber">version 1.0.0,</span>
+<span id="revdate">May 2010</span>
 <div id="toc">
   <div id="toctitle">Table of Contents</div>
   <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph"><p>This article is part 2, you might want to read
-<a href="c_in_javascript_part_2.html">Part 1</a> first.</p></div>
+<a href="c_in_javascript_part_1.html">Part 1</a> first.</p></div>
 </div>
 </div>
 <h2 id="_v8_types">v8 Types</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>int, string etc.
-How to use Maps and Arrays</p></div>
+<div class="paragraph"><p>The V8 engine provides implementations of many standard types to allow inter-operatability with JavaScript. The following types are present:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+Primitives
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>String</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Boolean</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Number</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Integer</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Int32</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Uint32</tt>
+</p>
+</li>
+</ul></div>
+</li>
+<li>
+<p>
+<tt>Object</tt>
+</p>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>Object</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Array</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Function</tt>
+</p>
+</li>
+</ul></div>
+</li>
+</ul></div>
+<div class="paragraph"><p>Besides this there are a few types which aren&#8217;t directly exposed to JavaScript such as <tt>FunctionTemplate</tt>, or <tt>External</tt>.</p></div>
+<h3 id="_c_to_javascript">C++ to JavaScript</h3><div style="clear:left"></div>
+<div class="paragraph"><p>All of the primitive types have a <tt>New()</tt> method which usually takes the C++ equivalent type and returns a wrapped type which you can put anywhere a <tt>Value</tt> is expected. In addition certain types like <tt>String</tt> have additional New overloads, which can be seen in the V8 documentation.</p></div>
+<div class="paragraph"><p>For example in Part 1, we converted a <tt>char</tt> array to <tt>v8::String</tt> using <tt>String::New( const char *, int length )</tt>.</p></div>
+<h3 id="_javascript_to_c">JavaScript to C++</h3><div style="clear:left"></div>
+<div class="paragraph"><p>To convert v8 types to the C++ types, it is recommended to first check if the conversion is possible and then convert it. If you receive a <tt>v8::Value</tt> ( or any subclass ), they have:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>IsArray()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsBoolean()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsDate()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsExternal()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsFalse()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsFunction()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsInt32()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsNull()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsNumber()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsObject()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsString()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsTrue()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsUint32()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>IsUndefined()</tt>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>after which you can call:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>bool BooleanValue()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>int32_t Int32Value()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>int64_t IntegerValue()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>double NumberValue()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Boolean&gt; ToBoolean()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;String&gt; ToString()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Int32&gt; ToInt32()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Integer&gt; ToInteger()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Number&gt; ToNumber()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Object&gt; ToObject()</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Uint32&gt; ToUint32()</tt>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>In addition each of these primitive types have a <tt>Value()</tt> method which returns the appropriate C\++ type.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>// obj is some type ( Handle&lt;Value&gt; ) received from JavaScript
+// see handling arguments below.
+
+if( obj-&gt;IsBoolean() ) {
+    // convert it
+    bool doOperation = obj-&gt;IsTrue();
+    // OR
+    bool doOperation = obj-&gt;ToBoolean()-&gt;Value();
+}</tt></pre>
+</div></div>
+<h3 id="_strings">Strings</h3><div style="clear:left"></div>
+<div class="paragraph"><p>v8 has two kinds of Strings, <tt>AsciiValue</tt> and <tt>Utf8Value</tt>. UTF-8 encoded strings are useful for user-displayed strings and places where non-ASCII characters are possible, while you will generally use <tt>AsciiValue</tt> when you want to use the string as an option or internal library use in your C/C++ library ( ie. passing as parameters etc. ).</p></div>
+<div class="paragraph"><p>To convert a <tt>v8::String</tt> to the right type, just pass the appropriate constructor the String object.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>String::AsciiValue name(String::New("foo"));</tt></pre>
+</div></div>
+<div class="paragraph"><p>Both <tt>AsciiValue</tt> and <tt>Utf8Value</tt> overload the <tt>*</tt> operator so that dereferencing them gets the value of the string as a <tt>char *</tt> or <tt>const char *</tt>.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>std::cerr &lt;&lt; "Name is " &lt;&lt; *name;</tt></pre>
+</div></div>
+<h3 id="_objects_and_arrays">Objects and Arrays</h3><div style="clear:left"></div>
+<div class="paragraph"><p><tt>Array`s are just `v8::Object`s with integer based access and a `Length()</tt> method. <tt>Object</tt> can have any wrapped <tt>Value</tt> as a key. It provides the following operations with regard to accessing keys and values:</p></div>
+<div class="ulist"><ul>
+<li>
+<p>
+<tt>bool Has( Handle&lt;String&gt; )</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>bool Has( uint32_t )</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Value&gt; Get( Handle&lt;Value&gt; key )</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>Local&lt;Value&gt; Get( uint32_t key )</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>void Set( Handle&lt;Value&gt; key, Handle&lt;Value&gt; value, PropertyAttribute = None )</tt>
+</p>
+</li>
+<li>
+<p>
+<tt>void Set( uint32_t index, Handle&lt;Value&gt; value )</tt>
+</p>
+</li>
+</ul></div>
+<div class="paragraph"><p>The first <tt>Set()</tt> accepts the PropertyAttribute to set advanced attributes of the property such as whether it is enumerated, read-only or deletable.</p></div>
+<div class="paragraph"><p><tt>Object</tt> also has additional properties, to allow callbacks on accessors, named properties, to support prototypal inheritance and for internal v8 details not exposed to JavaScript, such as memory management. Some of which will be covered in this document.</p></div>
 </div>
 <h2 id="_handling_arguments">Handling arguments</h2>
 <div class="sectionbody">
+<div class="paragraph"><p>With all the type related information out of the way, we can get back to writing useful code. Part 1 covered only how to get functions to be invoked, but functions without arguments are pretty useless. So now I&#8217;ll explain how we can extract arguments in our C\++ code and use them.</p></div>
 </div>
 <h2 id="_node_utilities">Node utilities</h2>
 <div class="sectionbody">
 </div>
 <h2 id="_time_for_objects">Time for Objects</h2>
 <div class="sectionbody">
+<div class="paragraph"><p>Wrapping C++ objects, static methods, unwrapping</p></div>
 </div>
 <h2 id="_ping_you_got_an_event">Ping, you got an event</h2>
 <div class="sectionbody">
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Version 1.0<br />
-Last updated 2010-03-22 14:47:44 IST
+Version 1.0.0<br />
+Last updated 2010-05-03 12:02:30 IST
 </div>
 </div>
 </body>

articles/c_in_my_javascript/v8_bindings_2.txt

 There's a C in my JavaScript: Part 2
 ====================================
 Nikhil Marathe <nsm.nikhil@gmail.com>
-v1.0, March 2010
+v1.0.0, May 2010
 
 This article is part 2, you might want to read
-link:c_in_javascript_part_2.html[Part 1] first.
+link:c_in_javascript_part_1.html[Part 1] first.
 
 v8 Types
 --------
 
-int, string etc.
-How to use Maps and Arrays
+The V8 engine provides implementations of many standard types to allow inter-operatability with JavaScript. The following types are present:
+
+* Primitives
+ ** `String`
+ ** `Boolean`
+ ** `Number`
+ ** `Integer`
+ ** `Int32`
+ ** `Uint32`
+* `Object`
+ ** `Object`
+ ** `Array`
+ ** `Function`
+ 
+Besides this there are a few types which aren't directly exposed to JavaScript such as `FunctionTemplate`, or `External`.
+
+C++ to JavaScript
+~~~~~~~~~~~~~~~~~
+
+All of the primitive types have a `New()` method which usually takes the C++ equivalent type and returns a wrapped type which you can put anywhere a `Value` is expected. In addition certain types like `String` have additional New overloads, which can be seen in the V8 documentation.
+
+For example in Part 1, we converted a `char` array to `v8::String` using `String::New( const char *, int length )`.
+
+JavaScript to C++
+~~~~~~~~~~~~~~~~~
+To convert v8 types to the C++ types, it is recommended to first check if the conversion is possible and then convert it. If you receive a `v8::Value` ( or any subclass ), they have:
+
+* `IsArray()`
+* `IsBoolean()`
+* `IsDate()`
+* `IsExternal()`
+* `IsFalse()`
+* `IsFunction()`
+* `IsInt32()`
+* `IsNull()`
+* `IsNumber()`
+* `IsObject()`
+* `IsString()`
+* `IsTrue()`
+* `IsUint32()`
+* `IsUndefined()`
+
+after which you can call:
+
+* `bool BooleanValue()`
+* `int32_t Int32Value()`
+* `int64_t IntegerValue()`
+* `double NumberValue()`
+* `Local<Boolean> ToBoolean()`
+* `Local<String> ToString()`
+* `Local<Int32> ToInt32()`
+* `Local<Integer> ToInteger()`
+* `Local<Number> ToNumber()`
+* `Local<Object> ToObject()`
+* `Local<Uint32> ToUint32()`
+
+In addition each of these primitive types have a `Value()` method which returns the appropriate C\++ type.
+
+----
+// obj is some type ( Handle<Value> ) received from JavaScript
+// see handling arguments below.
+
+if( obj->IsBoolean() ) {
+    // convert it
+    bool doOperation = obj->IsTrue();
+    // OR
+    bool doOperation = obj->ToBoolean()->Value();
+}
+----
+
+Strings
+~~~~~~~
+
+v8 has two kinds of Strings, `AsciiValue` and `Utf8Value`. UTF-8 encoded strings are useful for user-displayed strings and places where non-ASCII characters are possible, while you will generally use `AsciiValue` when you want to use the string as an option or internal library use in your C/C++ library ( ie. passing as parameters etc. ).
+
+To convert a `v8::String` to the right type, just pass the appropriate constructor the String object.
+
+----
+String::AsciiValue name(String::New("foo"));
+----
+
+Both `AsciiValue` and `Utf8Value` overload the `*` operator so that dereferencing them gets the value of the string as a `char *` or `const char *`.
+
+----
+std::cerr << "Name is " << *name;
+----
+
+ 
+Objects and Arrays
+~~~~~~~~~~~~~~~~~~
+
+`Array`s are just `v8::Object`s with integer based access and a `Length()` method. `Object` can have any wrapped `Value` as a key. It provides the following operations with regard to accessing keys and values:
+
+* `bool Has( Handle<String> )`
+* `bool Has( uint32_t )`
+* `Local<Value> Get( Handle<Value> key )`
+* `Local<Value> Get( uint32_t key )`
+* `void Set( Handle<Value> key, Handle<Value> value, PropertyAttribute = None )`
+* `void Set( uint32_t index, Handle<Value> value )`
+
+The first `Set()` accepts the PropertyAttribute to set advanced attributes of the property such as whether it is enumerated, read-only or deletable.
+
+`Object` also has additional properties, to allow callbacks on accessors, named properties, to support prototypal inheritance and for internal v8 details not exposed to JavaScript, such as memory management. Some of which will be covered in this document.
 
 Handling arguments
 ------------------
 
+With all the type related information out of the way, we can get back to writing useful code. Part 1 covered only how to get functions to be invoked, but functions without arguments are pretty useless. So now I'll explain how we can extract arguments in our C\++ code and use them.
+
 Node utilities
 --------------
 
 Time for Objects
 ----------------
 
+Wrapping C++ objects, static methods, unwrapping
+
 Ping, you got an event
 ----------------------