Skip to content

document namespace #1915

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 23, 2017
Merged

document namespace #1915

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 76 additions & 5 deletions docs/Manual.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -488,7 +488,7 @@
<h1><a href="https://github.com/bucklescript/bucklescript">BuckleScript</a> User Manual</h1>
<div class="details">
<span id="author" class="author">Hongbo Zhang</span><br>
<span id="revnumber">version 1.7.0</span>
<span id="revnumber">version 1.9.0</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
Expand Down Expand Up @@ -679,6 +679,8 @@ <h1><a href="https://github.com/bucklescript/bucklescript">BuckleScript</a> User
</ul>
</li>
<li><a href="#_a_real_world_example_of_using_code_bsb_code">A real world example of using <code>bsb</code></a></li>
<li><a href="#_namespace_support_since_1_9_0">namespace support (@since 1.9.0)</a></li>
<li><a href="#_in_source_build_support_since_1_9_0">In source build support (@since 1.9.0)</a></li>
<li><a href="#_build_using_make">Build using Make</a></li>
<li><a href="#_customize_rules_generators_support_since_1_7_4">Customize rules (generators support, @since 1.7.4)</a></li>
</ul>
Expand Down Expand Up @@ -3535,8 +3537,10 @@ <h3 id="_return_value_checking_since_1_5_1"><a class="anchor" href="#_return_val
</div>
</div>
<div class="paragraph">
<p>Currently 3 directives are supported: <code>null_to_opt</code>, <code>undefined_to_opt</code>,
<code>nullable</code> and <code>identity</code>.</p>
<p>Currently 4 directives are supported: <code>null_to_opt</code>, <code>undefined_to_opt</code>,
<code>nullable</code>(introduced in @1.9.0) and <code>identity</code>.
<code>null_undefined_to_opt</code> works the same as <code>nullable</code>,
but it is deprecated, <code>nullable</code> is encouraged</p>
</div>
<div class="admonitionblock note">
<table>
Expand Down Expand Up @@ -4692,7 +4696,7 @@ <h3 id="_bucklescript_build_system_code_bsb_code"><a class="anchor" href="#_buck
It is designed for a fast feedback loop (typically 100ms feedback loop) and works cross platform.</p>
</div>
<div class="paragraph">
<p><code>bsb</code> can be running in any subdirectory. It is a schema based build tool and the schema is
<p><code>bsb</code> is a schema based build tool. The schema is
<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>
after you finish reading the tutorials below.</p>
</div>
Expand Down Expand Up @@ -5044,6 +5048,73 @@ <h3 id="_a_real_world_example_of_using_code_bsb_code"><a class="anchor" href="#_
</div>
</div>
<div class="sect2">
<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>
<div class="paragraph">
<p>OCaml treat file names as modules, so that users can only have unique file names in a project, BuckleScript solves
the problem by scoping all modules by package.</p>
</div>
<div class="paragraph">
<p>Below is the <code>bsconfig.json</code> for <code>liba</code>, <code>libb</code> (they share the same configuration in this example)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
<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>
<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>
<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>
<span class="tok-s2">&quot;namespace&quot;</span><span class="tok-o">:</span> <span class="tok-kc">true</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you have a library to use them</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="js"><span class="tok-p">{</span>
<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>
<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>
<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>
<span class="tok-s2">&quot;bs-dependencies&quot;</span><span class="tok-o">:</span> <span class="tok-p">[</span>
<span class="tok-s2">&quot;liba&quot;</span><span class="tok-p">,</span>
<span class="tok-s2">&quot;libb&quot;</span>
<span class="tok-p">]</span>
<span class="tok-p">}</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>Since <code>liba</code> and <code>libb</code> is configured using namespace, to use them in source code, it would be like</p>
</div>
<div class="listingblock">
<div class="content">
<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>
<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>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>In the same package, everything works the same whether it uses namespace or not, it only affect
people who use your library</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<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>
<div class="paragraph">
<p>When user has an existing JS project, it makes sense to output the JS file in the same directory as vanilla JS,
the schema added a key called <code>in-source</code> so that generate JS file next to ML file.</p>
</div>
</div>
<div class="sect2">
<h3 id="_build_using_make"><a class="anchor" href="#_build_using_make"></a>Build using Make</h3>
<div class="admonitionblock warning">
<table>
Expand Down Expand Up @@ -6357,7 +6428,7 @@ <h3 id="_1_0"><a class="anchor" href="#_1_0"></a>1.0</h3>
</div>
<div id="footer">
<div id="footer-text">
Version 1.7.0<br>
Version 1.9.0<br>
</div>
</div>
</body>
Expand Down
63 changes: 54 additions & 9 deletions site/docsource/Build-system-support.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,10 @@ inlining, arity inference and other information.
BuckleScript provides a native build tool on top of Google's https://github.com/ninja-build/ninja/releases[ninja-build].
It is designed for a fast feedback loop (typically 100ms feedback loop) and works cross platform.

// [INFO]
// ======
// Currently for non-Windows users, they need to install ninja first (version >= 1.7.1).
// Please don't be confused with the npm ninja,
// we are using Google's https://github.com/ninja-build/ninja/releases[ninja-build].
// ======

`bsb` can be running in any subdirectory. It is a schema based build tool and the schema is
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]**


`bsb` is a schema based build tool. The schema is
{schema}[available]. It is strongly recommended to **check out the {schema}[schema]**
after you finish reading the tutorials below.

If your editor supports JSON schema validation and auto-completion like https://code.visualstudio.com/docs/languages/json[VSCode],
Expand Down Expand Up @@ -284,6 +279,56 @@ bsb -clean-world -make-world
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!


=== namespace support (@since 1.9.0)

OCaml treat file names as modules, so that users can only have unique file names in a project, BuckleScript solves
the problem by scoping all modules by package.

Below is the `bsconfig.json` for `liba`, `libb` (they share the same configuration in this example)

[source,js]
-----------
{
"name": "liba",
"version": "0.1.0",
"sources": "src",
"namespace": true
}
-----------

Now you have a library to use them

[source,js]
-----------
{
"name": "namespace",
"version": "0.1.0",
"sources": "src",
"bs-dependencies": [
"liba",
"libb"
]
}
-----------

Since `liba` and `libb` is configured using namespace, to use them in source code, it would be like

[source,ocaml]
--------------
let v =
(Liba.Demo.v + Libb.Demo.v)
--------------

[NOTE]
======
In the same package, everything works the same whether it uses namespace or not, it only affect
people who use your library
======

=== In source build support (@since 1.9.0)

When user has an existing JS project, it makes sense to output the JS file in the same directory as vanilla JS,
the schema added a key called `in-source` so that generate JS file next to ML file.

=== Build using Make
[WARNING]
Expand Down
3 changes: 2 additions & 1 deletion site/docsource/Manual.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# https://github.com/bucklescript/bucklescript[BuckleScript] User Manual
Hongbo Zhang
v1.7.0
v1.9.0
:toc: left
:toclevels: 4
:source-highlighter: pygments
Expand All @@ -16,6 +16,7 @@ v1.7.0
:name-mangling: https://en.wikipedia.org/wiki/Name_mangling
:npm: https://www.npmjs.com
:issues: https://github.com/bucklescript/bucklescript/issues
:schema: http://bucklescript.github.io/bucklescript/docson/#build-schema.json
:sectanchors:
:sectlinks:

Expand Down
6 changes: 4 additions & 2 deletions site/docsource/OCaml-call-JS.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1550,8 +1550,10 @@ function test(dom) {
-------------


Currently 3 directives are supported: `null_to_opt`, `undefined_to_opt`,
`nullable` and `identity`.
Currently 4 directives are supported: `null_to_opt`, `undefined_to_opt`,
`nullable`(introduced in @1.9.0) and `identity`.
`null_undefined_to_opt` works the same as `nullable`,
but it is deprecated, `nullable` is encouraged

[NOTE]
======
Expand Down