Skip to content

Commit 959e3d5

Browse files
bobzhangbobzhang
committed
add docs
1 parent 359b590 commit 959e3d5

File tree

3 files changed

+394
-4
lines changed

3 files changed

+394
-4
lines changed

‎docs/Manual.html

+215-2
Original file line numberDiff line numberDiff line change
@@ -488,7 +488,7 @@
488488
<h1><a href="https://github.com/bucklescript/bucklescript">BuckleScript</a> User Manual</h1>
489489
<div class="details">
490490
<span id="author" class="author">Hongbo Zhang</span><br>
491-
<span id="revnumber">version 2.0.1</span>
491+
<span id="revnumber">version 2.1.0</span>
492492
</div>
493493
<div id="toc" class="toc2">
494494
<div id="toctitle">Table of Contents</div>
@@ -586,6 +586,13 @@ <h1><a href="https://github.com/bucklescript/bucklescript">BuckleScript</a> User
586586
</ul>
587587
</li>
588588
<li><a href="#_return_value_checking_since_1_5_1">Return value checking (@since 1.5.1)</a></li>
589+
<li><a href="#_mapping_between_js_values_and_ocaml_values_since_2_1_0">Mapping between JS values and OCaml values (@since 2.1.0)</a>
590+
<ul class="sectlevel3">
591+
<li><a href="#_mapping_js_int_enums_to_ocaml_enums_since_2_1_0">Mapping JS Int enums to OCaml enums (@since 2.1.0)</a></li>
592+
<li><a href="#_mapping_js_string_enums_to_ocaml_enums_since_2_1_0">Mapping JS string enums to OCaml enums (@since 2.1.0)</a></li>
593+
<li><a href="#_mapping_js_int_enums_to_ocaml_enums_since_2_1_0_2">Mapping JS Int enums to OCaml enums (@since 2.1.0)</a></li>
594+
</ul>
595+
</li>
589596
<li><a href="#_embedding_untyped_javascript_code">Embedding untyped Javascript code</a>
590597
<ul class="sectlevel3">
591598
<li><a href="#_detect_global_variable_existence_code_bs_external_code_since_1_5_1">Detect global variable existence <code>bs.external</code> (@since 1.5.1)</a></li>
@@ -3532,6 +3539,212 @@ <h3 id="_return_value_checking_since_1_5_1"><a class="anchor" href="#_return_val
35323539
</div>
35333540
</div>
35343541
<div class="sect2">
3542+
<h3 id="_mapping_between_js_values_and_ocaml_values_since_2_1_0"><a class="anchor" href="#_mapping_between_js_values_and_ocaml_values_since_2_1_0"></a>Mapping between JS values and OCaml values (@since 2.1.0)</h3>
3543+
<div class="paragraph">
3544+
<p>BuckleScript already maps basic OCaml primitive types into JS primitive types,
3545+
however, there are some cases where such direct mapping is technically challenging,
3546+
we automate such process by providing a function to convert back and forth between
3547+
idiomatic JS values and idiomatic OCaml values, the generated code is optimized for
3548+
both performance and code size.</p>
3549+
</div>
3550+
<div class="sect3">
3551+
<h4 id="_mapping_js_int_enums_to_ocaml_enums_since_2_1_0"><a class="anchor" href="#_mapping_js_int_enums_to_ocaml_enums_since_2_1_0"></a>Mapping JS Int enums to OCaml enums (@since 2.1.0)</h4>
3552+
<div class="listingblock">
3553+
<div class="content">
3554+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
3555+
<span class="tok-o">|</span> <span class="tok-nc">A0</span>
3556+
<span class="tok-o">|</span> <span class="tok-nc">A1</span>
3557+
<span class="tok-o">|</span> <span class="tok-nc">A2</span>
3558+
<span class="tok-o">|</span> <span class="tok-nc">A3</span>
3559+
<span class="tok-o">|</span> <span class="tok-nc">A4</span>
3560+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-n">jsMapper</span><span class="tok-o">]</span></code></pre>
3561+
</div>
3562+
</div>
3563+
<div class="paragraph">
3564+
<p>This will derive two functions</p>
3565+
</div>
3566+
<div class="listingblock">
3567+
<div class="content">
3568+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">int</span>
3569+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span> <span class="tok-n">option</span></code></pre>
3570+
</div>
3571+
</div>
3572+
<div class="paragraph">
3573+
<p>Note here by default <code>Ai</code> is mapped into <code>i</code>, but we can customie it
3574+
as follows:</p>
3575+
</div>
3576+
<div class="listingblock">
3577+
<div class="content">
3578+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
3579+
<span class="tok-o">|</span> <span class="tok-nc">A0</span>
3580+
<span class="tok-o">|</span> <span class="tok-nc">A1</span> <span class="tok-o">[@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">as</span> <span class="tok-mi">3</span><span class="tok-o">]</span>
3581+
<span class="tok-o">|</span> <span class="tok-nc">A2</span>
3582+
<span class="tok-o">|</span> <span class="tok-nc">A3</span> <span class="tok-o">[@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">as</span> <span class="tok-mi">7</span><span class="tok-o">]</span>
3583+
<span class="tok-o">|</span> <span class="tok-nc">A4</span>
3584+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-n">jsMapper</span><span class="tok-o">]</span></code></pre>
3585+
</div>
3586+
</div>
3587+
<div class="paragraph">
3588+
<p>In this case, <code>A0</code> is 0, <code>A1</code> is 3, <code>A2</code> is 4, <code>A3</code> is 7, <code>A4</code> is 8.</p>
3589+
</div>
3590+
<div class="paragraph">
3591+
<p>Note the above derived js type is transparent: <code>int</code>, if we want to
3592+
provide more type safety, we can annotate it as below:</p>
3593+
</div>
3594+
<div class="listingblock">
3595+
<div class="content">
3596+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
3597+
<span class="tok-o">|</span> <span class="tok-nc">A0</span>
3598+
<span class="tok-o">|</span> <span class="tok-nc">A1</span>
3599+
<span class="tok-o">|</span> <span class="tok-nc">A2</span>
3600+
<span class="tok-o">|</span> <span class="tok-nc">A3</span>
3601+
<span class="tok-o">|</span> <span class="tok-nc">A4</span>
3602+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-o">{</span><span class="tok-n">jsMapper</span> <span class="tok-o">=</span> <span class="tok-n">jsType</span><span class="tok-o">}</span> <span class="tok-o">]</span></code></pre>
3603+
</div>
3604+
</div>
3605+
<div class="paragraph">
3606+
<p>In this case, it would generate two functions of such type:</p>
3607+
</div>
3608+
<div class="listingblock">
3609+
<div class="content">
3610+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">abs_t</span>
3611+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-n">abs_t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span></code></pre>
3612+
</div>
3613+
</div>
3614+
<div class="paragraph">
3615+
<p>Note the derived type is slightly different, since <code>abs_t</code> is abstrac type,
3616+
we assume it is well structured value, so it should always return value of type <code>t</code>
3617+
instead of <code>t option</code>.</p>
3618+
</div>
3619+
<div class="paragraph">
3620+
<p>The <code>bs.deriving</code> also applies to the signature file, so that users don&#8217;t have to
3621+
write generate functions manually</p>
3622+
</div>
3623+
</div>
3624+
<div class="sect3">
3625+
<h4 id="_mapping_js_string_enums_to_ocaml_enums_since_2_1_0"><a class="anchor" href="#_mapping_js_string_enums_to_ocaml_enums_since_2_1_0"></a>Mapping JS string enums to OCaml enums (@since 2.1.0)</h4>
3626+
<div class="listingblock">
3627+
<div class="content">
3628+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span> <span class="tok-o">[</span>
3629+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A0</span>
3630+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A1</span>
3631+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A2</span>
3632+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A3</span>
3633+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A4</span>
3634+
<span class="tok-o">]</span>
3635+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-n">jsMapper</span><span class="tok-o">]</span></code></pre>
3636+
</div>
3637+
</div>
3638+
<div class="paragraph">
3639+
<p>This will derive two functions</p>
3640+
</div>
3641+
<div class="listingblock">
3642+
<div class="content">
3643+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">string</span>
3644+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-kt">string</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span> <span class="tok-n">option</span></code></pre>
3645+
</div>
3646+
</div>
3647+
<div class="paragraph">
3648+
<p>Note here by default <code>Ai</code> is mapped into <code>"Ai"</code>, but we can customie it
3649+
as follows:</p>
3650+
</div>
3651+
<div class="listingblock">
3652+
<div class="content">
3653+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span> <span class="tok-o">[</span>
3654+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A0</span>
3655+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A1</span> <span class="tok-o">[@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">as</span> <span class="tok-s2">&quot;c&quot;</span><span class="tok-o">]</span>
3656+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A2</span>
3657+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A3</span> <span class="tok-o">[@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">as</span> <span class="tok-s2">&quot;d&quot;</span><span class="tok-o">]</span>
3658+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A4</span>
3659+
<span class="tok-o">]</span>
3660+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-n">jsMapper</span><span class="tok-o">]</span></code></pre>
3661+
</div>
3662+
</div>
3663+
<div class="paragraph">
3664+
<p>Note the above derived js type is transparent: <code>string</code>, if we want to
3665+
provide more type safety, we can annotate it as below:</p>
3666+
</div>
3667+
<div class="listingblock">
3668+
<div class="content">
3669+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span> <span class="tok-o">[</span>
3670+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A0</span>
3671+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A1</span>
3672+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A2</span>
3673+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A3</span>
3674+
<span class="tok-o">|</span> <span class="tok-o">`</span><span class="tok-nc">A4</span>
3675+
<span class="tok-o">]</span>
3676+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-o">{</span><span class="tok-n">jsMapper</span> <span class="tok-o">=</span> <span class="tok-n">jsType</span><span class="tok-o">}</span> <span class="tok-o">]</span></code></pre>
3677+
</div>
3678+
</div>
3679+
<div class="paragraph">
3680+
<p>In this case, it would generate two functions of such type:</p>
3681+
</div>
3682+
<div class="listingblock">
3683+
<div class="content">
3684+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">abs_t</span>
3685+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-n">abs_t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span></code></pre>
3686+
</div>
3687+
</div>
3688+
<div class="paragraph">
3689+
<p>Note the derived type is slightly different, since <code>abs_t</code> is abstrac type,
3690+
we assume it is well structured value, so it should always return value of type
3691+
<code>t</code> instead of type <code>t option</code>.</p>
3692+
</div>
3693+
<div class="paragraph">
3694+
<p>The <code>bs.deriving</code> also applies to the signature file, so that users don&#8217;t have to
3695+
write generate functions manually</p>
3696+
</div>
3697+
</div>
3698+
<div class="sect3">
3699+
<h4 id="_mapping_js_int_enums_to_ocaml_enums_since_2_1_0_2"><a class="anchor" href="#_mapping_js_int_enums_to_ocaml_enums_since_2_1_0_2"></a>Mapping JS Int enums to OCaml enums (@since 2.1.0)</h4>
3700+
<div class="listingblock">
3701+
<div class="content">
3702+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
3703+
<span class="tok-o">{</span>
3704+
<span class="tok-n">x</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">;</span>
3705+
<span class="tok-n">y</span> <span class="tok-o">:</span> <span class="tok-kt">int</span>
3706+
<span class="tok-o">}</span>
3707+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-n">jsMapper</span><span class="tok-o">]</span></code></pre>
3708+
</div>
3709+
</div>
3710+
<div class="paragraph">
3711+
<p>This will derive two functions:</p>
3712+
</div>
3713+
<div class="listingblock">
3714+
<div class="content">
3715+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-o">&lt;</span><span class="tok-n">x</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">;</span> <span class="tok-n">y</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">&gt;</span> <span class="tok-nn">Js</span><span class="tok-p">.</span><span class="tok-n">t</span>
3716+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-o">&lt;</span> <span class="tok-n">x</span><span class="tok-o">;</span> <span class="tok-kt">int</span> <span class="tok-o">;</span> <span class="tok-n">y</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">;</span> <span class="tok-o">..</span> <span class="tok-o">&gt;</span> <span class="tok-nn">Js</span><span class="tok-p">.</span><span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span></code></pre>
3717+
</div>
3718+
</div>
3719+
<div class="paragraph">
3720+
<p>Note that the input of <code>tFromJs</code> is open type so that it is more permissive.</p>
3721+
</div>
3722+
<div class="paragraph">
3723+
<p>Note the above derived js type is transparent, if we want to
3724+
provide more type safety, we can annotate it as below:</p>
3725+
</div>
3726+
<div class="listingblock">
3727+
<div class="content">
3728+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">t</span> <span class="tok-o">=</span>
3729+
<span class="tok-o">{</span>
3730+
<span class="tok-n">x</span> <span class="tok-o">:</span> <span class="tok-kt">int</span> <span class="tok-o">;</span>
3731+
<span class="tok-n">y</span> <span class="tok-o">:</span> <span class="tok-kt">int</span>
3732+
<span class="tok-o">}</span>
3733+
<span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">deriving</span> <span class="tok-o">{</span><span class="tok-n">jsMapper</span><span class="tok-o">=</span> <span class="tok-n">jsType</span><span class="tok-o">}]</span></code></pre>
3734+
</div>
3735+
</div>
3736+
<div class="paragraph">
3737+
<p>This will derive two functions:</p>
3738+
</div>
3739+
<div class="listingblock">
3740+
<div class="content">
3741+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">val</span> <span class="tok-n">tToJs</span> <span class="tok-o">:</span> <span class="tok-n">t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">abs_t</span>
3742+
<span class="tok-k">val</span> <span class="tok-n">tFromJs</span> <span class="tok-o">:</span> <span class="tok-n">abs_t</span> <span class="tok-o">-&gt;</span> <span class="tok-n">t</span></code></pre>
3743+
</div>
3744+
</div>
3745+
</div>
3746+
</div>
3747+
<div class="sect2">
35353748
<h3 id="_embedding_untyped_javascript_code"><a class="anchor" href="#_embedding_untyped_javascript_code"></a>Embedding untyped Javascript code</h3>
35363749
<div class="admonitionblock warning">
35373750
<table>
@@ -6242,7 +6455,7 @@ <h3 id="_1_0"><a class="anchor" href="#_1_0"></a>1.0</h3>
62426455
</div>
62436456
<div id="footer">
62446457
<div id="footer-text">
6245-
Version 2.0.1<br>
6458+
Version 2.1.0<br>
62466459
</div>
62476460
</div>
62486461
</body>

‎site/docsource/Manual.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# https://github.com/bucklescript/bucklescript[BuckleScript] User Manual
22
Hongbo Zhang
3-
v2.0.1
3+
v2.1.0
44
:toc: left
55
:toclevels: 4
66
:source-highlighter: pygments

0 commit comments

Comments
 (0)