Skip to content

Commit ca2c98e

Browse files
bobzhangbobzhang
committed
document namespace
1 parent 2ee4abe commit ca2c98e

File tree

4 files changed

+136
-17
lines changed

4 files changed

+136
-17
lines changed

‎docs/Manual.html

Lines changed: 76 additions & 5 deletions
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 1.7.0</span>
491+
<span id="revnumber">version 1.9.0</span>
492492
</div>
493493
<div id="toc" class="toc2">
494494
<div id="toctitle">Table of Contents</div>
@@ -679,6 +679,8 @@ <h1><a href="https://github.com/bucklescript/bucklescript">BuckleScript</a> User
679679
</ul>
680680
</li>
681681
<li><a href="#_a_real_world_example_of_using_code_bsb_code">A real world example of using <code>bsb</code></a></li>
682+
<li><a href="#_namespace_support_since_1_9_0">namespace support (@since 1.9.0)</a></li>
683+
<li><a href="#_in_source_build_support_since_1_9_0">In source build support (@since 1.9.0)</a></li>
682684
<li><a href="#_build_using_make">Build using Make</a></li>
683685
<li><a href="#_customize_rules_generators_support_since_1_7_4">Customize rules (generators support, @since 1.7.4)</a></li>
684686
</ul>
@@ -3535,8 +3537,10 @@ <h3 id="_return_value_checking_since_1_5_1"><a class="anchor" href="#_return_val
35353537
</div>
35363538
</div>
35373539
<div class="paragraph">
3538-
<p>Currently 3 directives are supported: <code>null_to_opt</code>, <code>undefined_to_opt</code>,
3539-
<code>nullable</code> and <code>identity</code>.</p>
3540+
<p>Currently 4 directives are supported: <code>null_to_opt</code>, <code>undefined_to_opt</code>,
3541+
<code>nullable</code>(introduced in @1.9.0) and <code>identity</code>.
3542+
<code>null_undefined_to_opt</code> works the same as <code>nullable</code>,
3543+
but it is deprecated, <code>nullable</code> is encouraged</p>
35403544
</div>
35413545
<div class="admonitionblock note">
35423546
<table>
@@ -4692,7 +4696,7 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
46924696
It is designed for a fast feedback loop (typically 100ms feedback loop) and works cross platform.</p>
46934697
</div>
46944698
<div class="paragraph">
4695-
<p><code>bsb</code> can be running in any subdirectory. It is a schema based build tool and the schema is
4699+
<p><code>bsb</code> is a schema based build tool. The schema is
46964700
<a href="http://bucklescript.github.io/bucklescript/docson/#build-schema.json">available</a>. It is strongly recommended to <strong>check out the <a href="http://bucklescript.github.io/bucklescript/docson/#build-schema.json">schema</a></strong>
46974701
after you finish reading the tutorials below.</p>
46984702
</div>
@@ -5044,6 +5048,73 @@ <h3 id="_a_real_world_example_of_using_code_bsb_code"><a class="anchor" href="#_
50445048
</div>
50455049
</div>
50465050
<div class="sect2">
5051+
<h3 id="_namespace_support_since_1_9_0"><a class="anchor" href="#_namespace_support_since_1_9_0"></a>namespace support (@since 1.9.0)</h3>
5052+
<div class="paragraph">
5053+
<p>OCaml treat file names as modules, so that users can only have unique file names in a project, BuckleScript solves
5054+
the problem by scoping all modules by package.</p>
5055+
</div>
5056+
<div class="paragraph">
5057+
<p>Below is the <code>bsconfig.json</code> for <code>liba</code>, <code>libb</code> (they share the same configuration in this example)</p>
5058+
</div>
5059+
<div class="listingblock">
5060+
<div class="content">
5061+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
5062+
<span class="tok-s2">&quot;name&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;liba&quot;</span><span class="tok-p">,</span>
5063+
<span class="tok-s2">&quot;version&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;0.1.0&quot;</span><span class="tok-p">,</span>
5064+
<span class="tok-s2">&quot;sources&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;src&quot;</span><span class="tok-p">,</span>
5065+
<span class="tok-s2">&quot;namespace&quot;</span><span class="tok-o">:</span> <span class="tok-kc">true</span>
5066+
<span class="tok-p">}</span></code></pre>
5067+
</div>
5068+
</div>
5069+
<div class="paragraph">
5070+
<p>Now you have a library to use them</p>
5071+
</div>
5072+
<div class="listingblock">
5073+
<div class="content">
5074+
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
5075+
<span class="tok-s2">&quot;name&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;namespace&quot;</span><span class="tok-p">,</span>
5076+
<span class="tok-s2">&quot;version&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;0.1.0&quot;</span><span class="tok-p">,</span>
5077+
<span class="tok-s2">&quot;sources&quot;</span><span class="tok-o">:</span> <span class="tok-s2">&quot;src&quot;</span><span class="tok-p">,</span>
5078+
<span class="tok-s2">&quot;bs-dependencies&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
5079+
<span class="tok-s2">&quot;liba&quot;</span><span class="tok-p">,</span>
5080+
<span class="tok-s2">&quot;libb&quot;</span>
5081+
<span class="tok-p">]</span>
5082+
<span class="tok-p">}</span></code></pre>
5083+
</div>
5084+
</div>
5085+
<div class="paragraph">
5086+
<p>Since <code>liba</code> and <code>libb</code> is configured using namespace, to use them in source code, it would be like</p>
5087+
</div>
5088+
<div class="listingblock">
5089+
<div class="content">
5090+
<pre class="pygments highlight"><code data-lang="ocaml"><span class="tok-k">let</span> <span class="tok-n">v</span> <span class="tok-o">=</span>
5091+
<span class="tok-o">(</span><span class="tok-nn">Liba</span><span class="tok-p">.</span><span class="tok-nn">Demo</span><span class="tok-p">.</span><span class="tok-n">v</span> <span class="tok-o">+</span> <span class="tok-nn">Libb</span><span class="tok-p">.</span><span class="tok-nn">Demo</span><span class="tok-p">.</span><span class="tok-n">v</span><span class="tok-o">)</span></code></pre>
5092+
</div>
5093+
</div>
5094+
<div class="admonitionblock note">
5095+
<table>
5096+
<tr>
5097+
<td class="icon">
5098+
<div class="title">Note</div>
5099+
</td>
5100+
<td class="content">
5101+
<div class="paragraph">
5102+
<p>In the same package, everything works the same whether it uses namespace or not, it only affect
5103+
people who use your library</p>
5104+
</div>
5105+
</td>
5106+
</tr>
5107+
</table>
5108+
</div>
5109+
</div>
5110+
<div class="sect2">
5111+
<h3 id="_in_source_build_support_since_1_9_0"><a class="anchor" href="#_in_source_build_support_since_1_9_0"></a>In source build support (@since 1.9.0)</h3>
5112+
<div class="paragraph">
5113+
<p>When user has an existing JS project, it makes sense to output the JS file in the same directory as vanilla JS,
5114+
the schema added a key called <code>in-source</code> so that generate JS file next to ML file.</p>
5115+
</div>
5116+
</div>
5117+
<div class="sect2">
50475118
<h3 id="_build_using_make"><a class="anchor" href="#_build_using_make"></a>Build using Make</h3>
50485119
<div class="admonitionblock warning">
50495120
<table>
@@ -6357,7 +6428,7 @@ <h3 id="_1_0"><a class="anchor" href="#_1_0"></a>1.0</h3>
63576428
</div>
63586429
<div id="footer">
63596430
<div id="footer-text">
6360-
Version 1.7.0<br>
6431+
Version 1.9.0<br>
63616432
</div>
63626433
</div>
63636434
</body>

‎site/docsource/Build-system-support.adoc

Lines changed: 54 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,10 @@ inlining, arity inference and other information.
1818
BuckleScript provides a native build tool on top of Google's https://github.com/ninja-build/ninja/releases[ninja-build].
1919
It is designed for a fast feedback loop (typically 100ms feedback loop) and works cross platform.
2020

21-
// [INFO]
22-
// ======
23-
// Currently for non-Windows users, they need to install ninja first (version >= 1.7.1).
24-
// Please don't be confused with the npm ninja,
25-
// we are using Google's https://github.com/ninja-build/ninja/releases[ninja-build].
26-
// ======
27-
28-
`bsb` can be running in any subdirectory. It is a schema based build tool and the schema is
29-
http://bucklescript.github.io/bucklescript/docson/#build-schema.json[available]. It is strongly recommended to **check out the http://bucklescript.github.io/bucklescript/docson/#build-schema.json[schema]**
21+
22+
23+
`bsb` is a schema based build tool. The schema is
24+
{schema}[available]. It is strongly recommended to **check out the {schema}[schema]**
3025
after you finish reading the tutorials below.
3126

3227
If your editor supports JSON schema validation and auto-completion like https://code.visualstudio.com/docs/languages/json[VSCode],
@@ -284,6 +279,56 @@ bsb -clean-world -make-world
284279
You will get both `commonjs` and `amdjs` support. In the end, we suggest you http://bucklescript.github.io/bucklescript/docson/#build-schema.json[check out the schema] and enjoy the build!
285280

286281

282+
=== namespace support (@since 1.9.0)
283+
284+
OCaml treat file names as modules, so that users can only have unique file names in a project, BuckleScript solves
285+
the problem by scoping all modules by package.
286+
287+
Below is the `bsconfig.json` for `liba`, `libb` (they share the same configuration in this example)
288+
289+
[source,js]
290+
-----------
291+
{
292+
"name": "liba",
293+
"version": "0.1.0",
294+
"sources": "src",
295+
"namespace": true
296+
}
297+
-----------
298+
299+
Now you have a library to use them
300+
301+
[source,js]
302+
-----------
303+
{
304+
"name": "namespace",
305+
"version": "0.1.0",
306+
"sources": "src",
307+
"bs-dependencies": [
308+
"liba",
309+
"libb"
310+
]
311+
}
312+
-----------
313+
314+
Since `liba` and `libb` is configured using namespace, to use them in source code, it would be like
315+
316+
[source,ocaml]
317+
--------------
318+
let v =
319+
(Liba.Demo.v + Libb.Demo.v)
320+
--------------
321+
322+
[NOTE]
323+
======
324+
In the same package, everything works the same whether it uses namespace or not, it only affect
325+
people who use your library
326+
======
327+
328+
=== In source build support (@since 1.9.0)
329+
330+
When user has an existing JS project, it makes sense to output the JS file in the same directory as vanilla JS,
331+
the schema added a key called `in-source` so that generate JS file next to ML file.
287332

288333
=== Build using Make
289334
[WARNING]

‎site/docsource/Manual.adoc

Lines changed: 2 additions & 1 deletion
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-
v1.7.0
3+
v1.9.0
44
:toc: left
55
:toclevels: 4
66
:source-highlighter: pygments
@@ -16,6 +16,7 @@ v1.7.0
1616
:name-mangling: https://en.wikipedia.org/wiki/Name_mangling
1717
:npm: https://www.npmjs.com
1818
:issues: https://github.com/bucklescript/bucklescript/issues
19+
:schema: http://bucklescript.github.io/bucklescript/docson/#build-schema.json
1920
:sectanchors:
2021
:sectlinks:
2122

‎site/docsource/OCaml-call-JS.adoc

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1550,8 +1550,10 @@ function test(dom) {
15501550
-------------
15511551
15521552
1553-
Currently 3 directives are supported: `null_to_opt`, `undefined_to_opt`,
1554-
`nullable` and `identity`.
1553+
Currently 4 directives are supported: `null_to_opt`, `undefined_to_opt`,
1554+
`nullable`(introduced in @1.9.0) and `identity`.
1555+
`null_undefined_to_opt` works the same as `nullable`,
1556+
but it is deprecated, `nullable` is encouraged
15551557
15561558
[NOTE]
15571559
======

0 commit comments

Comments
 (0)