add more docs [skip ci]

bobzhang · bobzhang · commit 3bd14783fccc · 2017-01-24T11:54:22.000-05:00
diff --git a/docs/Manual.html b/docs/Manual.html
@@ -541,13 +541,14 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
 </ul>
 </li>
 <li><a href="#_splice_calling_convention_bs_splice">Splice calling convention: bs.splice</a></li>
-<li><a href="#_special_types_on_external_declarations_bs_string_bs_int_bs_ignore">Special types on external declarations: bs.string, bs.int, bs.ignore</a>
+<li><a href="#_special_types_on_external_declarations_bs_string_bs_int_bs_ignore_bs_as">Special types on external declarations: bs.string, bs.int, bs.ignore, bs.as</a>
 <ul class="sectlevel3">
 <li><a href="#_using_polymorphic_variant_to_model_enums_and_string_types">Using polymorphic variant to model enums and string types</a></li>
 <li><a href="#_using_polymorphic_variant_to_model_event_listener">Using polymorphic variant to model event listener</a></li>
 <li><a href="#_phantom_arguments_and_ad_hoc_polyrmophism">Phantom Arguments and ad-hoc polyrmophism</a></li>
 </ul>
 </li>
+<li><a href="#_fixed_arguments">Fixed Arguments</a></li>
 <li><a href="#_binding_to_nodejs_special_variables_bs_node">Binding to NodeJS special variables: bs.node</a></li>
 <li><a href="#_binding_to_callbacks_high_order_function">Binding to callbacks (high-order function)</a>
 <ul class="sectlevel3">
@@ -1717,7 +1718,7 @@ <h3 id="_splice_calling_convention_bs_splice"><a class="anchor" href="#_splice_c
 </div>
 </div>
 <div class="sect2">
-<h3 id="_special_types_on_external_declarations_bs_string_bs_int_bs_ignore"><a class="anchor" href="#_special_types_on_external_declarations_bs_string_bs_int_bs_ignore"></a>Special types on external declarations: bs.string, bs.int, bs.ignore</h3>
+<h3 id="_special_types_on_external_declarations_bs_string_bs_int_bs_ignore_bs_as"><a class="anchor" href="#_special_types_on_external_declarations_bs_string_bs_int_bs_ignore_bs_as"></a>Special types on external declarations: bs.string, bs.int, bs.ignore, bs.as</h3>
 <div class="sect3">
 <h4 id="_using_polymorphic_variant_to_model_enums_and_string_types"><a class="anchor" href="#_using_polymorphic_variant_to_model_enums_and_string_types"></a>Using polymorphic variant to model enums and string types</h4>
 <div class="paragraph">
@@ -1921,6 +1922,85 @@ <h4 id="_phantom_arguments_and_ad_hoc_polyrmophism"><a class="anchor" href="#_ph
 </div>
 </div>
 <div class="sect2">
+<h3 id="_fixed_arguments"><a class="anchor" href="#_fixed_arguments"></a>Fixed Arguments</h3>
+<div class="paragraph">
+<p>Contrary to the Phantom arguments, <code>_[@bs.as]</code> is introduced to attach the const
+data.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">external</span> <span class="tok-n">process_on_exit</span> <span class="tok-o">:</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-k">as</span> <span class="tok-s2">&quot;exit&quot;</span><span class="tok-o">])</span> <span class="tok-o">-&gt;</span> <span class="tok-o">(</span><span class="tok-kt">int</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span><span class="tok-o">)</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span> <span class="tok-o">=</span>
+  <span class="tok-s2">&quot;process.on&quot;</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-k">val</span><span class="tok-o">]</span>
+
+<span class="tok-k">let</span> <span class="tok-bp">()</span> <span class="tok-o">=</span>
+    <span class="tok-n">process_on_exit</span> <span class="tok-o">(</span><span class="tok-k">fun</span> <span class="tok-n">exit_code</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-o">(</span> <span class="tok-s2">&quot;error code: &quot;</span> <span class="tok-o">^</span> <span class="tok-n">string_of_int</span> <span class="tok-n">exit_code</span> <span class="tok-o">))</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Output</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="js"><span class="tok-nx">process</span><span class="tok-p">.</span><span class="tok-nx">on</span><span class="tok-p">(</span><span class="tok-s2">&quot;exit&quot;</span><span class="tok-p">,</span> <span class="tok-kd">function</span> <span class="tok-p">(</span><span class="tok-nx">exit_code</span><span class="tok-p">)</span> <span class="tok-p">{</span>
+      <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-s2">&quot;error code: &quot;</span> <span class="tok-o">+</span> <span class="tok-nx">exit_code</span><span class="tok-p">);</span>
+      <span class="tok-k">return</span> <span class="tok-cm">/* () */</span><span class="tok-mi">0</span><span class="tok-p">;</span>
+    <span class="tok-p">});</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>It can also be used in combination with other attributes, for example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">type</span> <span class="tok-n">process</span>
+
+<span class="tok-k">external</span> <span class="tok-n">on_exit</span> <span class="tok-o">:</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-k">as</span> <span class="tok-s2">&quot;exit&quot;</span><span class="tok-o">])</span> <span class="tok-o">-&gt;</span> <span class="tok-o">(</span><span class="tok-kt">int</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span><span class="tok-o">)</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span> <span class="tok-o">=</span>
+    <span class="tok-s2">&quot;on&quot;</span> <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">process</span><span class="tok-o">]</span>
+<span class="tok-k">let</span> <span class="tok-n">register</span> <span class="tok-o">(</span><span class="tok-n">p</span> <span class="tok-o">:</span> <span class="tok-n">process</span><span class="tok-o">)</span> <span class="tok-o">=</span>
+        <span class="tok-n">p</span> <span class="tok-o">|&gt;</span> <span class="tok-n">on_exit</span> <span class="tok-o">(</span><span class="tok-k">fun</span> <span class="tok-n">i</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">i</span> <span class="tok-o">)</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Output</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="js"><span class="tok-kd">function</span> <span class="tok-nx">register</span><span class="tok-p">(</span><span class="tok-nx">p</span><span class="tok-p">)</span> <span class="tok-p">{</span>
+  <span class="tok-k">return</span> <span class="tok-nx">p</span><span class="tok-p">.</span><span class="tok-nx">on</span><span class="tok-p">(</span><span class="tok-s2">&quot;exit&quot;</span><span class="tok-p">,</span> <span class="tok-kd">function</span> <span class="tok-p">(</span><span class="tok-nx">i</span><span class="tok-p">)</span> <span class="tok-p">{</span>
+              <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">i</span><span class="tok-p">);</span>
+              <span class="tok-k">return</span> <span class="tok-cm">/* () */</span><span class="tok-mi">0</span><span class="tok-p">;</span>
+            <span class="tok-p">});</span>
+<span class="tok-p">}</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Input</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">external</span> <span class="tok-n">io_config</span> <span class="tok-o">:</span>
+    <span class="tok-n">stdio</span><span class="tok-o">:(</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-k">as</span> <span class="tok-s2">&quot;inherit&quot;</span><span class="tok-o">])</span> <span class="tok-o">-&gt;</span> <span class="tok-n">cwd</span><span class="tok-o">:</span><span class="tok-kt">string</span> <span class="tok-o">-&gt;</span> <span class="tok-kt">unit</span> <span class="tok-o">-&gt;</span> <span class="tok-o">_</span>  <span class="tok-o">=</span> <span class="tok-s2">&quot;&quot;</span> <span class="tok-o">[@@</span><span class="tok-n">bs</span><span class="tok-o">.</span><span class="tok-n">obj</span><span class="tok-o">]</span>
+
+<span class="tok-k">let</span> <span class="tok-n">config</span> <span class="tok-o">=</span> <span class="tok-n">io_config</span> <span class="tok-o">~</span><span class="tok-n">cwd</span><span class="tok-o">:</span><span class="tok-s2">&quot;.&quot;</span> <span class="tok-bp">()</span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Output</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="js"><span class="tok-kd">var</span> <span class="tok-nx">config</span> <span class="tok-o">=</span> <span class="tok-p">{</span>
+  <span class="tok-nx">stdio</span><span class="tok-o">:</span> <span class="tok-s2">&quot;inherit&quot;</span><span class="tok-p">,</span>
+  <span class="tok-nx">cwd</span><span class="tok-o">:</span> <span class="tok-s2">&quot;.&quot;</span>
+<span class="tok-p">};</span></code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
 <h3 id="_binding_to_nodejs_special_variables_bs_node"><a class="anchor" href="#_binding_to_nodejs_special_variables_bs_node"></a>Binding to NodeJS special variables: bs.node</h3>
 <div class="paragraph">
 <p>NodeJS has several file local variables: <code><em>dirname</code>, <code></em>filename</code>, <code>module_</code>, and <code>require</code>,
diff --git a/jscomp/test/prepend_data_ffi.js b/jscomp/test/prepend_data_ffi.js
@@ -30,21 +30,41 @@ process.on(function (i) {
 xx(3, 3, "xxx", "a", "b");
 
 function f(x) {
-  x.xx(91, /* int array */[
+  x.xx(104, /* int array */[
         1,
         2,
         3
       ]);
-  x.xx(92, 3, "xxx", /* int array */[
+  x.xx(105, 3, "xxx", /* int array */[
         1,
         2,
         3
       ]);
-  x.xx(93, 3, "xxx", 1, 2, 3);
-  return x.xx(94, 3, "xxx", 0, "b", 1, 2, 3, 4, 5);
+  x.xx(106, 3, "xxx", 1, 2, 3);
+  x.xx(107, 3, "xxx", 0, "b", 1, 2, 3, 4, 5);
+  return x.xx(108, 3, "xxx", 0, "yyy", "b", 1, 2, 3, 4, 5);
 }
 
-exports.v1 = v1;
-exports.v2 = v2;
-exports.f  = f;
+process.on("exit", function (exit_code) {
+      console.log("error code: " + exit_code);
+      return /* () */0;
+    });
+
+function register(p) {
+  return p.on("exit", function (i) {
+              console.log(i);
+              return /* () */0;
+            });
+}
+
+var config = {
+  stdio: "inherit",
+  cwd: "."
+};
+
+exports.v1       = v1;
+exports.v2       = v2;
+exports.f        = f;
+exports.register = register;
+exports.config   = config;
 /* v1 Not a pure module */
diff --git a/jscomp/test/prepend_data_ffi.ml b/jscomp/test/prepend_data_ffi.ml
@@ -84,11 +84,46 @@ external on_exit_slice4 :
     "xx" [@@bs.send.pipe: t] [@@bs.splice]
 
 
+external on_exit_slice5 : 
+    int 
+    -> (_ [@bs.as 3]) 
+    -> (_ [@bs.as "xxx"]) 
+    -> ([`a|`b|`c] [@bs.int])
+    -> (_ [@bs.as "yyy"]) 
+    -> ([`a|`b|`c] [@bs.string])
+    -> int array
+    -> unit 
+    = 
+    "xx" [@@bs.send.pipe: t] [@@bs.splice]
+
+
 (**
  TODO: bs.send conflicts with bs.val: better error message
 *)
 let f (x : t) = 
     x |> on_exit_slice1 __LINE__ [|1;2;3|];
     x |> on_exit_slice2 __LINE__ [|1;2;3|];
     x |> on_exit_slice3 __LINE__ [|1;2;3|];
-    x |> on_exit_slice4 __LINE__ `a `b [|1;2;3;4;5|]
+    x |> on_exit_slice4 __LINE__ `a `b [|1;2;3;4;5|];
+    x |> on_exit_slice5 __LINE__ `a `b [|1;2;3;4;5|]
+
+external process_on_exit : (_ [@bs.as "exit"]) -> (int -> unit) -> unit =
+  "process.on" [@@bs.val]
+
+let () = 
+    process_on_exit (fun exit_code -> 
+        Js.log( "error code: " ^ string_of_int exit_code ))      
+
+
+type process
+
+external on_exit :  (_ [@bs.as "exit"]) -> (int -> unit) -> unit = 
+    "on" [@@bs.send.pipe: process]
+let register (p : process) = 
+        p |> on_exit (fun i -> Js.log i )
+
+
+external io_config : 
+    stdio:( _ [@bs.as "inherit"]) -> cwd:string -> unit -> _  = "" [@@bs.obj]
+
+let config = io_config ~cwd:"." ()   
diff --git a/site/docsource/OCaml-call-JS.adoc b/site/docsource/OCaml-call-JS.adoc
@@ -241,7 +241,7 @@ the compiler will emit an error message
 ======
 
 
-### Special types on external declarations: bs.string, bs.int, bs.ignore
+### Special types on external declarations: bs.string, bs.int, bs.ignore, bs.as
 
 #### Using polymorphic variant to model enums and string types
 There are several patterns heavily used in existing JavaScript codebase, for example,
@@ -380,6 +380,74 @@ let add2 k x y =
   add_dyn k (string_of_kind k) x y
 -------------
 
+### Fixed Arguments
+
+Contrary to the Phantom arguments, `_[@bs.as]` is introduced to attach the const 
+data.
+
+For example:
+
+[source,ocaml]
+--------------
+external process_on_exit : (_ [@bs.as "exit"]) -> (int -> unit) -> unit =
+  "process.on" [@@bs.val]
+
+let () = 
+    process_on_exit (fun exit_code -> 
+        Js.log( "error code: " ^ string_of_int exit_code ))      
+--------------
+
+Output
+[source,js]
+-----------
+process.on("exit", function (exit_code) {
+      console.log("error code: " + exit_code);
+      return /* () */0;
+    });
+-----------
+
+It can also be used in combination with other attributes, for example:
+
+[source,ocaml]
+--------------
+type process
+
+external on_exit :  (_ [@bs.as "exit"]) -> (int -> unit) -> unit = 
+    "on" [@@bs.send.pipe: process]
+let register (p : process) = 
+        p |> on_exit (fun i -> Js.log i )
+
+--------------
+
+Output
+[source,js]
+-----------
+function register(p) {
+  return p.on("exit", function (i) {
+              console.log(i);
+              return /* () */0;
+            });
+}
+-----------
+
+Input
+[source,ocaml]
+--------------
+external io_config : 
+    stdio:( _ [@bs.as "inherit"]) -> cwd:string -> unit -> _  = "" [@@bs.obj]
+
+let config = io_config ~cwd:"." ()   
+--------------
+
+Output
+[source,js]
+-----------
+var config = {
+  stdio: "inherit",
+  cwd: "."
+};
+-----------
+
 ### Binding to NodeJS special variables: bs.node
 
 NodeJS has several file local variables: `__dirname`, `__filename`, `module_`, and `require`,
