Skip to content

Commit 471ce17

Browse files
bobzhangbobzhang
committed
finish docs and implementation of auto-conversion of return value, need more refinement and testing
1 parent a577032 commit 471ce17

40 files changed

+23104
-22669
lines changed

‎docs/Manual.html

+110-2
Original file line numberDiff line numberDiff line change
@@ -529,7 +529,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
529529
<li><a href="#_js_calling_ocaml">JS Calling OCaml</a></li>
530530
<li><a href="#_bucklescritp_annotations_for_unicode_and_js_ffi_support">BuckleScritp annotations for Unicode and JS FFI support</a>
531531
<ul class="sectlevel2">
532-
<li><a href="#_unicode_support">Unicode support</a></li>
532+
<li><a href="#_unicode_support_since_1_5_1">Unicode support (@since 1.5.1)</a></li>
533533
<li><a href="#_ffi">FFI</a></li>
534534
<li><a href="#_binding_to_simple_js_functions_values">Binding to simple JS functions values</a>
535535
<ul class="sectlevel3">
@@ -583,6 +583,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
583583
<li><a href="#_object_label_translation_convention">Object label translation convention</a></li>
584584
</ul>
585585
</li>
586+
<li><a href="#_return_value_checking_since_1_5_1">Return value checking (@since 1.5.1)</a></li>
586587
<li><a href="#_embedding_raw_javascript_code">Embedding raw Javascript code</a>
587588
<ul class="sectlevel3">
588589
<li><a href="#_embedding_raw_js_code_as_an_expression">Embedding raw JS code as an expression</a></li>
@@ -1390,7 +1391,7 @@ <h2 id="_bucklescritp_annotations_for_unicode_and_js_ffi_support"><a class="anch
13901391
improve the generated code.</p>
13911392
</div>
13921393
<div class="sect2">
1393-
<h3 id="_unicode_support"><a class="anchor" href="#_unicode_support"></a>Unicode support</h3>
1394+
<h3 id="_unicode_support_since_1_5_1"><a class="anchor" href="#_unicode_support_since_1_5_1"></a>Unicode support (@since 1.5.1)</h3>
13941395
<div class="admonitionblock warning">
13951396
<table>
13961397
<tr>
@@ -3230,6 +3231,113 @@ <h4 id="_object_label_translation_convention"><a class="anchor" href="#_object_l
32303231
</div>
32313232
</div>
32323233
<div class="sect2">
3234+
<h3 id="_return_value_checking_since_1_5_1"><a class="anchor" href="#_return_value_checking_since_1_5_1"></a>Return value checking (@since 1.5.1)</h3>
3235+
<div class="paragraph">
3236+
<p>In general, the FFI code is error prone, and potentially will leak in
3237+
<code>undefined</code> or <code>null</code> values.</p>
3238+
</div>
3239+
<div class="paragraph">
3240+
<p>So we introduced auto coercion for return values for two benefits:</p>
3241+
</div>
3242+
<div class="olist arabic">
3243+
<ol class="arabic">
3244+
<li>
3245+
<p>More safety for FFI code without performance cost(explained later)</p>
3246+
</li>
3247+
<li>
3248+
<p>More idiomatic OCaml code for users to consume the FFI.</p>
3249+
</li>
3250+
</ol>
3251+
</div>
3252+
<div class="paragraph">
3253+
<p>Below is a contrived core example:</p>
3254+
</div>
3255+
<div class="listingblock">
3256+
<div class="content">
3257+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">element</span>
3258+
<span class="tok-k">type</span> <span class="tok-n">dom</span>
3259+
<span class="tok-k">external</span> <span class="tok-n">getElementById</span> <span class="tok-o">:</span> <span class="tok-kt">string</span> <span class="tok-o">-&gt;</span> <span class="tok-n">element</span> <span class="tok-n">option</span> <span class="tok-o">=</span> <span class="tok-s2">&quot;&quot;</span>
3260+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">send</span><span class="tok-o">.</span><span class="tok-n">pipe</span><span class="tok-o">:</span><span class="tok-n">dom</span><span class="tok-o">]</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">return</span> <span class="tok-o">{</span><span class="tok-n">null_to_opt</span><span class="tok-o">}]</span> <b class="conum">(1)</b>
3261+
3262+
<span class="tok-k">let</span> <span class="tok-n">test</span> <span class="tok-n">dom</span> <span class="tok-o">=</span>
3263+
<span class="tok-k">let</span> <span class="tok-n">elem</span> <span class="tok-o">=</span> <span class="tok-n">dom</span> <span class="tok-o">|&gt;</span> <span class="tok-n">getElementById</span> <span class="tok-s2">&quot;haha&quot;</span> <span class="tok-k">in</span>
3264+
<span class="tok-k">match</span> <span class="tok-n">elem</span> <span class="tok-k">with</span>
3265+
<span class="tok-o">|</span> <span class="tok-nc">None</span> <span class="tok-o">-&gt;</span> <span class="tok-mi">1</span>
3266+
<span class="tok-o">|</span> <span class="tok-nc">Some</span> <span class="tok-n">ui</span> <span class="tok-o">-&gt;</span> <span class="tok-nn">Js</span><span class="tok-p">.</span><span class="tok-n">log</span> <span class="tok-n">ui</span> <span class="tok-o">;</span> <span class="tok-mi">2</span></code></pre>
3267+
</div>
3268+
</div>
3269+
<div class="colist arabic">
3270+
<ol>
3271+
<li>
3272+
<p><code>null_to_opt</code> attriute will automatically convert null to <code>option</code></p>
3273+
</li>
3274+
</ol>
3275+
</div>
3276+
<div class="listingblock">
3277+
<div class="title">Output</div>
3278+
<div class="content">
3279+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-kd">function</span> <span class="tok-nx">test</span><span class="tok-p">(</span><span class="tok-nx">dom</span><span class="tok-p">)</span> <span class="tok-p">{</span>
3280+
<span class="tok-kd">var</span> <span class="tok-nx">elem</span> <span class="tok-o">=</span> <span class="tok-nx">dom</span><span class="tok-p">.</span><span class="tok-nx">getElementById</span><span class="tok-p">(</span><span class="tok-s2">&quot;haha&quot;</span><span class="tok-p">);</span>
3281+
<span class="tok-k">if</span> <span class="tok-p">(</span><span class="tok-nx">elem</span> <span class="tok-o">!==</span> <span class="tok-kc">null</span><span class="tok-p">)</span> <span class="tok-p">{</span> <b class="conum">(1)</b>
3282+
<span class="tok-nx">console</span><span class="tok-p">.</span><span class="tok-nx">log</span><span class="tok-p">(</span><span class="tok-nx">elem</span><span class="tok-p">);</span>
3283+
<span class="tok-k">return</span> <span class="tok-mi">2</span><span class="tok-p">;</span>
3284+
<span class="tok-p">}</span>
3285+
<span class="tok-k">else</span> <span class="tok-p">{</span>
3286+
<span class="tok-k">return</span> <span class="tok-mi">1</span><span class="tok-p">;</span>
3287+
<span class="tok-p">}</span>
3288+
<span class="tok-p">}</span></code></pre>
3289+
</div>
3290+
</div>
3291+
<div class="colist arabic">
3292+
<ol>
3293+
<li>
3294+
<p>nullable checking without boxing due to compiler optimizations</p>
3295+
</li>
3296+
</ol>
3297+
</div>
3298+
<div class="paragraph">
3299+
<p>Currently, 4 directives are supported: <code>null_to_opt</code>, <code>undefined_to_opt</code>,
3300+
, <code>null_undefined_to_opt</code> and <code>identity</code>.</p>
3301+
</div>
3302+
<div class="admonitionblock note">
3303+
<table>
3304+
<tr>
3305+
<td class="icon">
3306+
<div class="title">Note</div>
3307+
</td>
3308+
<td class="content">
3309+
<div class="paragraph">
3310+
<p><code>null_to_opt</code>, <code>undefined_to_opt</code> and <code>null_undefined_to_opt</code> will <strong>semantically</strong>
3311+
convert nullable value to <code>option</code> which is a boxed value, but the compiler will
3312+
do smart optimizations to <strong>remove such boxing overhead</strong> when the returned value is destructed
3313+
in the same routine.</p>
3314+
</div>
3315+
<div class="paragraph">
3316+
<p>The three directives above require users to write literally <code>_ option</code>, it is
3317+
in theory not necessary, but it is required to reduce user errors.</p>
3318+
</div>
3319+
<div class="paragraph">
3320+
<p>When return type is <code>unit</code>: the compiler will append its return value
3321+
with an OCaml <code>unit</code> literal to make sure it does return <code>unit</code>, its main purpose
3322+
is to make user consume FFI in idiomatic OCaml code, the cost is <strong>very very small</strong> and
3323+
the compiler will do smart optimizations to remove it when the returned value is not used (mostly likely)</p>
3324+
</div>
3325+
<div class="paragraph">
3326+
<p>When return type is <code>bool</code>, the compiler will coerce its return value from
3327+
JS boolean to OCaml boolean. The cost is also <strong>very small</strong> and compiler will remove
3328+
such coercison when it is not needed. Note even if your external FFI does return OCaml <code>bool</code> or <code>unit</code>,
3329+
such implicit coercion will <strong>cause no harm</strong>.</p>
3330+
</div>
3331+
<div class="paragraph">
3332+
<p><code>identity</code> will make sure that compiler will do nothing about returned value, it
3333+
is rarely used but introduced here for debugging purpose.</p>
3334+
</div>
3335+
</td>
3336+
</tr>
3337+
</table>
3338+
</div>
3339+
</div>
3340+
<div class="sect2">
32333341
<h3 id="_embedding_raw_javascript_code"><a class="anchor" href="#_embedding_raw_javascript_code"></a>Embedding raw Javascript code</h3>
32343342
<div class="admonitionblock warning">
32353343
<table>

‎jscomp/all.depend

+4-6
Original file line numberDiff line numberDiff line change
@@ -222,8 +222,7 @@ syntax/ast_derive_dyn.cmi :
222222
syntax/ast_derive_projector.cmi :
223223
syntax/ast_ffi_types.cmi : syntax/ast_core_type.cmi
224224
syntax/ast_external_attributes.cmi : common/bs_loc.cmi \
225-
syntax/ast_ffi_types.cmi syntax/ast_core_type.cmi \
226-
syntax/ast_attributes.cmi
225+
syntax/ast_core_type.cmi syntax/ast_attributes.cmi
227226
syntax/ast_util.cmi : syntax/ast_payload.cmi
228227
syntax/ppx_entry.cmi :
229228
depends/depends_post_process.cmi :
@@ -246,7 +245,7 @@ core/ocaml_parse.cmi :
246245
core/lam_module_ident.cmi : core/js_op.cmx common/js_config.cmi core/j.cmx \
247246
ext/hashtbl_gen.cmx ext/hash_set_gen.cmx
248247
core/lam.cmi : core/lam_module_ident.cmi ext/ident_set.cmi \
249-
syntax/ast_ffi_types.cmi syntax/ast_external_attributes.cmi
248+
syntax/ast_ffi_types.cmi
250249
core/lam_print.cmi : core/lam.cmi
251250
core/lam_beta_reduce_util.cmi : core/lam.cmi
252251
core/lam_inline_util.cmi : core/lam.cmi
@@ -349,8 +348,7 @@ core/lam.cmx : ext/ordered_hash_map_local_ident.cmx \
349348
common/js_config.cmx ext/int_vec_vec.cmx ext/int_vec_util.cmx \
350349
ext/int_vec.cmx ext/ident_set.cmx ext/ident_hashtbl.cmx \
351350
ext/ident_hash_set.cmx ext/hash_set_ident_mask.cmx ext/ext_string.cmx \
352-
ext/ext_scc.cmx ext/ext_list.cmx syntax/ast_ffi_types.cmx \
353-
syntax/ast_external_attributes.cmx core/lam.cmi
351+
ext/ext_scc.cmx ext/ext_list.cmx syntax/ast_ffi_types.cmx core/lam.cmi
354352
core/lam_print.cmx : core/lam.cmx core/lam_print.cmi
355353
core/lam_beta_reduce_util.cmx : core/lam.cmx ext/ident_hashtbl.cmx \
356354
core/lam_beta_reduce_util.cmi
@@ -519,7 +517,7 @@ core/lam_compile_primitive.cmx : core/lam_util.cmx \
519517
core/js_of_lam_exception.cmx core/js_of_lam_block.cmx \
520518
core/js_of_lam_array.cmx core/js_long.cmx core/js_exp_make.cmx \
521519
common/js_config.cmx core/j.cmx common/ext_log.cmx \
522-
syntax/ast_ffi_types.cmx core/lam_compile_primitive.cmi
520+
core/lam_compile_primitive.cmi
523521
core/lam_compile.cmx : ext/literals.cmx core/lam_util.cmx \
524522
common/lam_methname.cmx core/lam_exit_code.cmx \
525523
core/lam_eta_conversion.cmx core/lam_compile_primitive.cmx \

0 commit comments

Comments
 (0)