From ca2c98e8464b9225846b181395274dcd1acc94c9 Mon Sep 17 00:00:00 2001 From: Hongbo Zhang Date: Tue, 22 Aug 2017 13:57:28 +0800 Subject: [PATCH] document namespace --- docs/Manual.html | 81 ++++++++++++++++++++++-- site/docsource/Build-system-support.adoc | 63 +++++++++++++++--- site/docsource/Manual.adoc | 3 +- site/docsource/OCaml-call-JS.adoc | 6 +- 4 files changed, 136 insertions(+), 17 deletions(-) diff --git a/docs/Manual.html b/docs/Manual.html index b634f0ea2b..8595bcc889 100644 --- a/docs/Manual.html +++ b/docs/Manual.html @@ -488,7 +488,7 @@

BuckleScript User Manual

Hongbo Zhang
-version 1.7.0 +version 1.9.0
Table of Contents
@@ -679,6 +679,8 @@

BuckleScript User
  • A real world example of using bsb
    • +
  • namespace support (@since 1.9.0)
    • +
  • In source build support (@since 1.9.0)
  • Build using Make
  • Customize rules (generators support, @since 1.7.4)
    • @@ -3535,8 +3537,10 @@

    -

    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

    @@ -4692,7 +4696,7 @@

    -

    bsb can be running in any subdirectory. It is a schema based build tool and the schema is +

    bsb is a schema based build tool. The schema is available. It is strongly recommended to check out the schema after you finish reading the tutorials below.

    @@ -5044,6 +5048,73 @@

    +

    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)

    +
    +
    +
    +
    {
+  "name": "liba",
+  "version": "0.1.0",
+  "sources": "src",
+  "namespace": true
+}
    +
    +
    +
    +

    Now you have a library to use them

    +
    +
    +
    +
    {
+  "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

    +
    +
    +
    +
    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

    @@ -6357,7 +6428,7 @@

    1.0

    diff --git a/site/docsource/Build-system-support.adoc b/site/docsource/Build-system-support.adoc index 81616cea26..e7ee9a6551 100644 --- a/site/docsource/Build-system-support.adoc +++ b/site/docsource/Build-system-support.adoc @@ -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], @@ -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] diff --git a/site/docsource/Manual.adoc b/site/docsource/Manual.adoc index 5ee86cb995..60469f1e70 100644 --- a/site/docsource/Manual.adoc +++ b/site/docsource/Manual.adoc @@ -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 @@ -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: diff --git a/site/docsource/OCaml-call-JS.adoc b/site/docsource/OCaml-call-JS.adoc index 449adc6213..203860a37c 100644 --- a/site/docsource/OCaml-call-JS.adoc +++ b/site/docsource/OCaml-call-JS.adoc @@ -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] ======