From 8baa22dd523e4dd908cb31fbdaab79efec36cf46 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:04:40 +1100 Subject: [PATCH 01/61] Add get decorator syntax --- misc_docs/syntax/decorator_get.mdx | 35 ++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 misc_docs/syntax/decorator_get.mdx diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx new file mode 100644 index 000000000..8efc0dfd3 --- /dev/null +++ b/misc_docs/syntax/decorator_get.mdx @@ -0,0 +1,35 @@ +--- +id: "get-decorator" +keywords: ["get", "decorator", "property", "object", "bind"] +name: "@get" +summary: "This is the `@get` decorator." +category: "decorators" +--- + +The `@get` decorator is used to bind to a property of an object. + +For example: + + + +```res +type element + +@scope("document") @val +external createElement: string => element = "createElement" + +@get +external getScrollTop: element => unit = "scrollTop" + +let div = createElement("div") +let top = getScrollTop(div) +``` + +```js +var div = document.createElement("div") +var top = div.scrollTop +``` + + + + From 4987d0aab31c4ad22297bbaa7e91749688d58b84 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:06:38 +1100 Subject: [PATCH 02/61] Add set decorator syntax --- misc_docs/syntax/decorator_set.mdx | 36 ++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 misc_docs/syntax/decorator_set.mdx diff --git a/misc_docs/syntax/decorator_set.mdx b/misc_docs/syntax/decorator_set.mdx new file mode 100644 index 000000000..430608437 --- /dev/null +++ b/misc_docs/syntax/decorator_set.mdx @@ -0,0 +1,36 @@ +--- +id: "set-decorator" +keywords: ["set", "property", "object", "bind"] +name: "@set" +summary: "This is the `@set` decorator." +category: "decorators" +--- + +The `@set` decorator is used to set a property of an object. + +For example: + + + +```res +type element + +@scope("document") @val +external createElement: string => element = "createElement" + +@set +external setScrollTop: (element, int) => unit = "scrollTop" + +let div = createElement("div") +setScrollTop(div, 100) +``` + +```js +var div = document.createElement("div") + +div.scrollTop = 100 +``` + + + + From f1f36e83f87a765220bc3913257bcdce38741885 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:07:46 +1100 Subject: [PATCH 03/61] Add set index decorator syntax --- misc_docs/syntax/decorator_set_index.mdx | 72 ++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 misc_docs/syntax/decorator_set_index.mdx diff --git a/misc_docs/syntax/decorator_set_index.mdx b/misc_docs/syntax/decorator_set_index.mdx new file mode 100644 index 000000000..bc7f7d68b --- /dev/null +++ b/misc_docs/syntax/decorator_set_index.mdx @@ -0,0 +1,72 @@ +--- +id: "set-index-decorator" +keywords: ["set", "decorator", "array", "object"] +name: "@set_index" +summary: "This is the `@set_index` decorator." +category: "decorators" +--- + +The `@set_index` decorator is used to set a dynamic property or index. + +For example with an Array: + + + +```res +type t + +@new external create: int => t = "Array" +@set_index external set: (t, int, string) => unit = "" +@get_index external get: (t, int) => string = "" + +let a = create(3) +a->set(0, "zero") +a->set(1, "one") +a->set(2, "two") + +let value = a->get(1) +``` + +```js +var a = new Array(3); + +a[0] = "zero"; +a[1] = "one"; +a[2] = "two"; + +var value = a[1]; +``` + + + +And an example with an object: + + + +```res +type t + +@new external create: unit => t = "Object" +@set_index external set: (t, string, int) => unit = "" +@get_index external get: (t, string) => int = "" + +let o = create() +o->set("x", 1) +o->set("y", 3) +o->set("z", 5) + +let value = o->get("y") +``` + +```js +var o = new Object(); + +o["x"] = 1; +o["y"] = 3; +o["z"] = 5; + +var value = o["y"]; +``` + + + From 916b5d0a1883e341b7f5655a5bfc7e19b4f5ef1d Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:08:15 +1100 Subject: [PATCH 04/61] Add get index decorator syntax --- misc_docs/syntax/decorator_get_index.mdx | 72 ++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 misc_docs/syntax/decorator_get_index.mdx diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx new file mode 100644 index 000000000..9357d6959 --- /dev/null +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -0,0 +1,72 @@ +--- +id: "get-index-decorator" +keywords: ["get", "decorator", "array", "object"] +name: "@get_index" +summary: "This is the `@get_index` decorator." +category: "decorators" +--- + +The `@get_index` decorator is used to access a dynamic property or index. + +For example with an Array: + + + +```res +type t + +@new external create: int => t = "Array" +@set_index external set: (t, int, string) => unit = "" +@get_index external get: (t, int) => string = "" + +let a = create(3) +a->set(0, "zero") +a->set(1, "one") +a->set(2, "two") + +let value = a->get(1) +``` + +```js +var a = new Array(3); + +a[0] = "zero"; +a[1] = "one"; +a[2] = "two"; + +var value = a[1]; +``` + + + +And an example with an object: + + + +```res +type t + +@new external create: unit => t = "Object" +@set_index external set: (t, string, int) => unit = "" +@get_index external get: (t, string) => int = "" + +let o = create() +o->set("x", 1) +o->set("y", 3) +o->set("z", 5) + +let value = o->get("y") +``` + +```js +var o = new Object(); + +o["x"] = 1; +o["y"] = 3; +o["z"] = 5; + +var value = o["y"]; +``` + + + From f288353b1f30969b5bb2e7ba45b8a7cdb9c6e03c Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:09:20 +1100 Subject: [PATCH 05/61] Add val decorator syntax --- misc_docs/syntax/decorator_val.mdx | 34 ++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_val.mdx b/misc_docs/syntax/decorator_val.mdx index 434b0c25b..fa13595a5 100644 --- a/misc_docs/syntax/decorator_val.mdx +++ b/misc_docs/syntax/decorator_val.mdx @@ -1,3 +1,33 @@ -This decorator is used to bind to a value in global scope. +--- +id: "val-decorator" +keywords: ["val", "decorator", "bind", "global"] +name: "@val" +summary: "This is the `@val` decorator." +category: "decorators" +--- + +The `@val` decorator allows you to bind to JavaScript values that are on the global scope. + +For example: + + + +```res +type timeoutID + +@val +external setTimeout: (unit => unit, int) => timeoutID = "setTimeout" + +let timeoutID = setTimeout(() => Js.log("Hello"), 1000) +``` + +```js +var timeoutID = setTimeout(function (param) { + console.log("Hello") +}, 1000) +``` + + + +To access global values on another global object, such as `Date.now` or `location.origin.length` see the `@scope` decorator. -**Also see:** `@bs.val` From 622dd1201d146d3ba6e756df0b64be0dd4b04bca Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:09:45 +1100 Subject: [PATCH 06/61] Add new decorator syntax --- misc_docs/syntax/decorator_new.mdx | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/misc_docs/syntax/decorator_new.mdx b/misc_docs/syntax/decorator_new.mdx index 1a4ed55ee..aceb2400e 100644 --- a/misc_docs/syntax/decorator_new.mdx +++ b/misc_docs/syntax/decorator_new.mdx @@ -1,16 +1,25 @@ -This decorator is used whenever you need to bind to a JS class constructor that requires the `new` keword for instantiation. +--- +id: "new-decorator" +keywords: ["new", "decorator", "object"] +name: "@new" +summary: "This is the `@new` decorator." +category: "decorators" +--- + +The `@new` decorator is used whenever you need to bind to a JavaScript class constructor that requires the `new` keword for instantiation. -```res +```re type t -@bs.new external create: unit => t = "Date" -create(); +@new external create: unit => t = "Date" + +let now = create() ``` ```js -new Date(); +var now = new Date(); ``` @@ -20,10 +29,11 @@ When the object is not available on the global scope, combine it with `@module`: ```res -type t; -@module @bs.new external book: unit => t = "Book"; +type t + +@module @new external book: unit => t = "Book" -let myBook = book(); +let myBook = book() ``` ```js From dfe1cdab12e45014febd1e648b4db749468b0bb7 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:10:05 +1100 Subject: [PATCH 07/61] Add send decorator syntax --- misc_docs/syntax/decorator_send.mdx | 41 ++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_send.mdx b/misc_docs/syntax/decorator_send.mdx index b8eafdd7d..961f65362 100644 --- a/misc_docs/syntax/decorator_send.mdx +++ b/misc_docs/syntax/decorator_send.mdx @@ -1 +1,40 @@ -This decorator is used to "send a value" to an instance of an object. +--- +id: "send-decorator" +keywords: ["send", "decorator", "object"] +name: "@send" +summary: "This is the `@send` decorator." +category: "decorators" +--- + +The `@send` decorator is used to call a function on an object. + +For example: + + + +```res +type element + +@scope("document") @val +external createElement: string => element = "createElement" + +@send +external appendChild: (element, element) => element = "appendChild" + +let div = createElement("div") +let button = createElement("button") + +let _ = appendChild(div, button) +``` + +```js +var div = document.createElement("div"); + +var button = document.createElement("button"); + +div.appendChild(button); +``` + + + + From 33a73706b4ef65b478e0ec9966a00d7423ae7648 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:10:30 +1100 Subject: [PATCH 08/61] Add scope decorator syntax --- misc_docs/syntax/decorator_scope.mdx | 40 ++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 misc_docs/syntax/decorator_scope.mdx diff --git a/misc_docs/syntax/decorator_scope.mdx b/misc_docs/syntax/decorator_scope.mdx new file mode 100644 index 000000000..d354886a6 --- /dev/null +++ b/misc_docs/syntax/decorator_scope.mdx @@ -0,0 +1,40 @@ +--- +id: "scope-decorator" +keywords: ["scope", "decorator", "bind", "global"] +name: "@scope" +summary: "This is the `@scope` decorator." +category: "decorators" +--- + +The `@scope` decorator is used with other decorators such as `@val` and `@module` to declare a parent scope for the binding. + +For example: + + + +```res +@scope("Math") @val +external floor: float => int = "floor" + +@scope(("location", "origin")) @val +external originLength: string = "length" + +@module("MyModule") @scope("CONSTANTS") +external initialDays: int = "initialDays" + +Js.log(floor(3.4)) +Js.log(originLength) +Js.log(initialDays) +``` + +```js +var MyModule = require("MyModule") + +console.log(Math.floor(3.4)) +console.log(location.origin.length) +console.log(MyModule.CONSTANTS.initialDays) +``` + + + +Note that the order of the decorators doesn't matter. \ No newline at end of file From 46a97e837e42ea5963ecd26309aabcfb16939e44 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:11:10 +1100 Subject: [PATCH 09/61] Add string decorator syntax --- misc_docs/syntax/decorator_string.mdx | 29 +++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 misc_docs/syntax/decorator_string.mdx diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx new file mode 100644 index 000000000..cfed0974a --- /dev/null +++ b/misc_docs/syntax/decorator_string.mdx @@ -0,0 +1,29 @@ +--- +id: "string-decorator" +keywords: ["string", "decorator", "polymorphic", "variant", "as", "external"] +name: "@string" +summary: "This is the `@string` decorator." +category: "decorators" +--- + +The `@string` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the compiled JavaScript. + +For example: + + + +```res +@val external setStatus: @string[ + @as("NOT_STARTED") #NotStarted | + @as("STARTED") #Started | + @as("DONE") #Done +] => unit = "setStatus" + +setStatus(#NotStarted) +``` + +```js +setStatus("NOT_STARTED"); +``` + + From 1cb11a329e5db8b1785445b83b02a56e2fb30930 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:11:31 +1100 Subject: [PATCH 10/61] Add int decorator syntax --- misc_docs/syntax/decorator_int.mdx | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 misc_docs/syntax/decorator_int.mdx diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx new file mode 100644 index 000000000..191707fd1 --- /dev/null +++ b/misc_docs/syntax/decorator_int.mdx @@ -0,0 +1,29 @@ +--- +id: "int-decorator" +keywords: ["int", "decorator", "polymorphic", "variant", "as", "external"] +name: "@int" +summary: "This is the `@int` decorator." +category: "decorators" +--- + +The `@int` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the compiled JavaScript. + +For example: + + + +```res +@val external setStatus: @int[ + @as(0) #NotStarted | + @as(1) #Started | + @as(2) #Done +] => unit = "setStatus" + +setStatus(#Done) +``` + +```js +setStatus(2); +``` + + From 3557fa6d6ec1221b32ab857b1b6409a5f0ddaad4 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:12:25 +1100 Subject: [PATCH 11/61] Add unwrap decorator syntax --- misc_docs/syntax/decorator_unwrap.mdx | 48 +++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 misc_docs/syntax/decorator_unwrap.mdx diff --git a/misc_docs/syntax/decorator_unwrap.mdx b/misc_docs/syntax/decorator_unwrap.mdx new file mode 100644 index 000000000..a488daadf --- /dev/null +++ b/misc_docs/syntax/decorator_unwrap.mdx @@ -0,0 +1,48 @@ +--- +id: "unwrap-decorator" +keywords: ["unwrap", "decorator", "external"] +name: "@unwrap" +summary: "This is the `@unwrap` decorator." +category: "decorators" +--- + +The `@unwrap` decorator may be used when binding to external functions that accept multiple types for an argument. + +Consider the following JavaScript function: + +```js +function padLeft(padding, str) { + if (typeof padding === "number") { + return " ".repeat(padding) + str; + } + if (typeof padding === "string") { + return padding + str; + } + throw new Error("Expected padding to be number or string"); +} +``` +Note how `padding` can be either a number or a string. + +Here is how you'd bind to this function: + + + +```res +@val external padLeft: ( + @unwrap [#Int(int) | #Str(string)], + string +) => string = "padLeft"; + +let _ = padLeft(#Int(7), "eleven"); +let _ = padLeft(#Str("7"), "eleven"); +``` + +```js +padLeft(7, "eleven"); + +padLeft("7", "eleven"); +``` + + + +Review the JavaScript output and note how `@unwrap` simply unwraps the polymorphic variant constructor. From 49a7b7d8691602dfc7c869f90f1b1ea16c27b282 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:13:06 +1100 Subject: [PATCH 12/61] Add as decorator syntax --- misc_docs/syntax/decorator_as.mdx | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index 5926018cc..5c6030bfe 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -1,19 +1,25 @@ --- -test: "foo" +id: "as-decorator" +keywords: ["as", "decorator", "record", "alias", "object"] +name: "@as" +summary: "This is the `@as` decorator." +category: "decorators" --- -Use this decorator on record types to alias record names to a different JS attribute name. +The `@as` decorator may be used on record types to alias record names to a different JavaScript attribute name. -This is mostly useful to map to JS attribute names that cannot be expressed in ReScript (such as keywords). +This is mostly useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords). -### Example +For example -```reason +```re type action = { - [@bs.as "type"] _type: string, -}; + @as("type") type_: string +} + +let action = {type_: "ADD_USER"} ``` ```js @@ -21,6 +27,6 @@ var action = { type: "ADD_USER" }; ``` + -Refer to the [Records as Objects](/docs/manual/latest/bind-to-js-object#bind-using-rescript-record) section for a more detailed explanation. From 55d7ff3a95bc46da0a0959d2af1842cbda9505ea Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:13:32 +1100 Subject: [PATCH 13/61] Add module decorator syntax --- misc_docs/syntax/decorator_module.mdx | 31 ++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_module.mdx b/misc_docs/syntax/decorator_module.mdx index 4eba66db7..e0548a578 100644 --- a/misc_docs/syntax/decorator_module.mdx +++ b/misc_docs/syntax/decorator_module.mdx @@ -1 +1,30 @@ -used for [this](https://google.com) and [that](https://google.com) +--- +id: "module-decorator" +keywords: ["module", "decorator", "import", "require", "bind"] +name: "@module" +summary: "This is the `@module` decorator." +category: "decorators" +--- + +The `@module` decorator is used to bind to a JavaScript module. + +For example: + + + +```res +@module("path") +external dirname: string => string = "dirname" + +let root = dirname("/User/github") +``` + +```js +var Path = require("path"); + +var root = Path.dirname("/User/github"); +``` + + + +See the [Import from JavaScript](/docs/manual/latest/import-from-export-to-js#import-from-javascript) section for full details. From c5332f54ad5453d612cd54f81f9d21acca605dde Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:26:52 +1100 Subject: [PATCH 14/61] Tweak as decorator syntax --- misc_docs/syntax/decorator_as.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index 5c6030bfe..b3ce3386d 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -1,16 +1,16 @@ --- id: "as-decorator" -keywords: ["as", "decorator", "record", "alias", "object"] +keywords: ["as", "decorator", "record", "field", "alias", "object"] name: "@as" summary: "This is the `@as` decorator." category: "decorators" --- -The `@as` decorator may be used on record types to alias record names to a different JavaScript attribute name. +The `@as` decorator may be used on record types to alias record field names to a different JavaScript attribute name. This is mostly useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords). -For example +For example: From f9d4ea3ec920750198ec0bf855b15330a70e2acc Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:28:56 +1100 Subject: [PATCH 15/61] Tweak get decorator syntax --- misc_docs/syntax/decorator_get.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx index 8efc0dfd3..a5715fad6 100644 --- a/misc_docs/syntax/decorator_get.mdx +++ b/misc_docs/syntax/decorator_get.mdx @@ -12,7 +12,7 @@ For example: -```res +```re type element @scope("document") @val From c5bd2f92d7474532b595fbc9048939aba4587213 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:30:30 +1100 Subject: [PATCH 16/61] Tweak get index decorator syntax --- misc_docs/syntax/decorator_get_index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index 9357d6959..37d854921 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -1,6 +1,6 @@ --- id: "get-index-decorator" -keywords: ["get", "decorator", "array", "object"] +keywords: ["get", "decorator", "array", "object", "index"] name: "@get_index" summary: "This is the `@get_index` decorator." category: "decorators" From 37ca04ec585f8c7d3c4694299bacf04058c55785 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:33:50 +1100 Subject: [PATCH 17/61] Tweak get index decorator syntax --- misc_docs/syntax/decorator_get_index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index 37d854921..45e27f587 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -12,7 +12,7 @@ For example with an Array: -```res +```re type t @new external create: int => t = "Array" @@ -43,7 +43,7 @@ And an example with an object: -```res +```re type t @new external create: unit => t = "Object" From d60db1fac20b43fea2892221c82057c49a46275f Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:37:21 +1100 Subject: [PATCH 18/61] Tweak int decorator syntax --- misc_docs/syntax/decorator_int.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx index 191707fd1..6e83bc100 100644 --- a/misc_docs/syntax/decorator_int.mdx +++ b/misc_docs/syntax/decorator_int.mdx @@ -6,13 +6,13 @@ summary: "This is the `@int` decorator." category: "decorators" --- -The `@int` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the compiled JavaScript. +The `@int` decorator can be used with [polymorphic variants](/docs/manual/latest/polymorphic-variant) and the `@as` decorator on *externals* to modify the compiled JavaScript to use integers for the values instead of strings. For example: -```res +```re @val external setStatus: @int[ @as(0) #NotStarted | @as(1) #Started | From f24d471917391f6e0ae12c75ef578eb02a1c723a Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:38:24 +1100 Subject: [PATCH 19/61] Tweak string decorator syntax --- misc_docs/syntax/decorator_string.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx index cfed0974a..94b51d79e 100644 --- a/misc_docs/syntax/decorator_string.mdx +++ b/misc_docs/syntax/decorator_string.mdx @@ -6,13 +6,13 @@ summary: "This is the `@string` decorator." category: "decorators" --- -The `@string` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the compiled JavaScript. +The `@string` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the string values used for the variants in the compiled JavaScript. For example: -```res +```re @val external setStatus: @string[ @as("NOT_STARTED") #NotStarted | @as("STARTED") #Started | From f73643ecdb01d889cfd22b186c26f0ad84684a0e Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:40:02 +1100 Subject: [PATCH 20/61] Tweak module decorator syntax --- misc_docs/syntax/decorator_module.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_module.mdx b/misc_docs/syntax/decorator_module.mdx index e0548a578..56665fcae 100644 --- a/misc_docs/syntax/decorator_module.mdx +++ b/misc_docs/syntax/decorator_module.mdx @@ -12,7 +12,7 @@ For example: -```res +```re @module("path") external dirname: string => string = "dirname" @@ -27,4 +27,4 @@ var root = Path.dirname("/User/github"); -See the [Import from JavaScript](/docs/manual/latest/import-from-export-to-js#import-from-javascript) section for full details. +See the [Import from JavaScript](/docs/manual/latest/import-from-export-to-js#import-from-javascript) section for full details, including other variations of how this decorator may be used. From c674341b2a811057bb6ff3e65d6014df38729bfe Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:41:04 +1100 Subject: [PATCH 21/61] Tweak new decorator syntax --- misc_docs/syntax/decorator_new.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_new.mdx b/misc_docs/syntax/decorator_new.mdx index aceb2400e..d2d3f58c8 100644 --- a/misc_docs/syntax/decorator_new.mdx +++ b/misc_docs/syntax/decorator_new.mdx @@ -28,7 +28,7 @@ When the object is not available on the global scope, combine it with `@module`: -```res +```re type t @module @new external book: unit => t = "Book" From 43b6e344bf93c1380b70e5cd91a3cf80fc940fe2 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:41:50 +1100 Subject: [PATCH 22/61] Tweak scope decorator syntax --- misc_docs/syntax/decorator_scope.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_scope.mdx b/misc_docs/syntax/decorator_scope.mdx index d354886a6..ce2b8438c 100644 --- a/misc_docs/syntax/decorator_scope.mdx +++ b/misc_docs/syntax/decorator_scope.mdx @@ -12,7 +12,7 @@ For example: -```res +```re @scope("Math") @val external floor: float => int = "floor" From b6502fb1f74f56f0478a1bfe2ee1979ac407a5ed Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:44:19 +1100 Subject: [PATCH 23/61] Tweak send decorator syntax --- misc_docs/syntax/decorator_send.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_send.mdx b/misc_docs/syntax/decorator_send.mdx index 961f65362..e084931b9 100644 --- a/misc_docs/syntax/decorator_send.mdx +++ b/misc_docs/syntax/decorator_send.mdx @@ -12,7 +12,7 @@ For example: -```res +```re type element @scope("document") @val From 6f53ab3f01516c4fdface437480460fe032e2926 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:45:12 +1100 Subject: [PATCH 24/61] Tweak set index decorator syntax --- misc_docs/syntax/decorator_set_index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/misc_docs/syntax/decorator_set_index.mdx b/misc_docs/syntax/decorator_set_index.mdx index bc7f7d68b..3e1f2fc9b 100644 --- a/misc_docs/syntax/decorator_set_index.mdx +++ b/misc_docs/syntax/decorator_set_index.mdx @@ -1,6 +1,6 @@ --- id: "set-index-decorator" -keywords: ["set", "decorator", "array", "object"] +keywords: ["set", "decorator", "array", "object", "index"] name: "@set_index" summary: "This is the `@set_index` decorator." category: "decorators" @@ -12,7 +12,7 @@ For example with an Array: -```res +```re type t @new external create: int => t = "Array" @@ -43,7 +43,7 @@ And an example with an object: -```res +```re type t @new external create: unit => t = "Object" From ff5f05e0b94d3500a04f1cdf1de4b1b27e2bf213 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:45:36 +1100 Subject: [PATCH 25/61] Tweak set decorator syntax --- misc_docs/syntax/decorator_set.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_set.mdx b/misc_docs/syntax/decorator_set.mdx index 430608437..7815a0972 100644 --- a/misc_docs/syntax/decorator_set.mdx +++ b/misc_docs/syntax/decorator_set.mdx @@ -12,7 +12,7 @@ For example: -```res +```re type element @scope("document") @val From f424dd0806f575882a58f0317042e153e23b9554 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:45:59 +1100 Subject: [PATCH 26/61] Tweak unwrap decorator syntax --- misc_docs/syntax/decorator_unwrap.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_unwrap.mdx b/misc_docs/syntax/decorator_unwrap.mdx index a488daadf..3078913a4 100644 --- a/misc_docs/syntax/decorator_unwrap.mdx +++ b/misc_docs/syntax/decorator_unwrap.mdx @@ -27,7 +27,7 @@ Here is how you'd bind to this function: -```res +```re @val external padLeft: ( @unwrap [#Int(int) | #Str(string)], string From ae11d2a023a761e5e6f47b2d3d91ae91ae6d19b1 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 13:46:26 +1100 Subject: [PATCH 27/61] Tweak val decorator syntax --- misc_docs/syntax/decorator_val.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_val.mdx b/misc_docs/syntax/decorator_val.mdx index fa13595a5..be6b326c9 100644 --- a/misc_docs/syntax/decorator_val.mdx +++ b/misc_docs/syntax/decorator_val.mdx @@ -12,7 +12,7 @@ For example: -```res +```re type timeoutID @val From 3af0c983ee36bd5a5b4939a95c52b5fc9eda8c74 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 18:01:53 +1100 Subject: [PATCH 28/61] Add deriving decorator syntax --- misc_docs/syntax/decorator_deriving.mdx | 202 ++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 misc_docs/syntax/decorator_deriving.mdx diff --git a/misc_docs/syntax/decorator_deriving.mdx b/misc_docs/syntax/decorator_deriving.mdx new file mode 100644 index 000000000..7987beec3 --- /dev/null +++ b/misc_docs/syntax/decorator_deriving.mdx @@ -0,0 +1,202 @@ +--- +id: "deriving-decorator" +keywords: ["deriving", "decorator", "record", "variant"] +name: "@deriving" +summary: "This is the `@deriving` decorator." +category: "decorators" +--- + +The `@deriving(accessors)` decorator can be used to either: + +* Generate getter functions for a decorated **record** type, or +* Generate creator functions for constructors of a **variant** type. + +The `@deriving(abstract)` decorator creates: + +* An abstract type representing the "abstract record". +* A creator function for the new abstract type, where labeled arguments represent the attributes of the record. +* A set of setter / getter functions for each record attribute + +Note that when using the `@deriving(abstract)` decorator, the original record type will be removed. +You'll need to use the newly created functions to create / get / set values of this type. + +Example of **record** accessors: + + + +```re +@deriving(accessors) +type person = { + name: string, + age: int, +} + +// This generates functions with signatures: +// let name: (person) => string; +// let age: (person) => int; + +let toString = (person): string => { + name(person) ++ " " ++ Belt.Int.toString(age(person)) +} + +let misha = { + name: "Misha", + age: 20, +} + +let result = toString(misha) +``` + +```js +function name(param) { + return param.name; +} + +function age(param) { + return param.age; +} + +function toString(person) { + return person.name + " " + String(person.age); +} + +var misha = { + name: "Misha", + age: 20, +}; + +var result = toString(misha); +``` + + + +Example of **variant** accessors: + + + +```re +@deriving(accessors) +type action = + | SetName(string) + | SetAge(int) + | ClearAll + +// This generates functions with signatures: +// let setName: (string) => action; +// let age: (person) => int; + +let dispatch = action => { + switch action { + | SetName(name) => Js.log2("SetName", name) + | SetAge(age) => Js.log2("SetAge", age) + | ClearAll => Js.log("ClearAll") + } +} + +dispatch(setName("Hello")) +dispatch(setAge(123)) +dispatch(clearAll) +``` + +```js +function setName(param_0) { + return { + TAG: /* SetName */ 0, + _0: param_0, + } +} + +function setAge(param_0) { + return { + TAG: /* SetAge */ 1, + _0: param_0, + } +} + +function dispatch(action) { + if (typeof action === "number") { + console.log("ClearAll") + return + } + if (action.TAG === /* SetName */ 0) { + console.log("SetName", action._0) + return + } + console.log("SetAge", action._0) +} + +dispatch({ + TAG: /* SetName */ 0, + _0: "Hello", +}) + +dispatch({ + TAG: /* SetAge */ 1, + _0: 123, +}) + +dispatch(/* ClearAll */ 0) + +var clearAll = /* ClearAll */ 0 +``` + + + +Example of **abstract record** type: + + + +```re +@deriving(abstract) +type person = { + name: string, + mutable age: int, // Use the mutable keyword for generating setters +} + +// Generates the following: +// +// An abstract type, replacing the original type: +// +// type person +// +// A type constructor: +// +// let person: (~name: string, ~age: int) => person +// +// Getters: +// +// let nameGet: (person) => string; +// let ageGet: (person) => int +// +// Setters (only mutable attributes) +// +// let ageSet: (person, int) => unit + +let friend = person(~name="Misha", ~age=20) + +Js.log(friend->nameGet) // => "Misha" + +// Increase age by 1 via mutation +friend->ageSet(friend->ageGet + 1) + +Js.log(friend->ageGet) // => 21 + +// This will NOT be possible (original type has been removed) +// let misha = {name: "Misha", age: 20} + +``` + +```js +var friend = { + name: "Misha", + age: 20 +}; + +console.log(friend.name); + +friend.age = friend.age + 1 | 0; + +console.log(friend.age); +``` + + \ No newline at end of file From 00e08c88da292d6d3d59fd042b11a98de0f235c8 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 18:08:32 +1100 Subject: [PATCH 29/61] Tweak as decorator syntax --- misc_docs/syntax/decorator_as.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index b3ce3386d..8af24b1d9 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -30,3 +30,4 @@ var action = { +It may also be used when declaring external [polymorphic variants](/docs/manual/latest/polymorphic-variant). See the `@string` and `@int` decorators for more details. From ff607353b004be749e2bdb4eab2cad69e06acfbc Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 18:08:51 +1100 Subject: [PATCH 30/61] Tweak string decorator syntax --- misc_docs/syntax/decorator_string.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx index 94b51d79e..9dcfdb2e6 100644 --- a/misc_docs/syntax/decorator_string.mdx +++ b/misc_docs/syntax/decorator_string.mdx @@ -6,7 +6,7 @@ summary: "This is the `@string` decorator." category: "decorators" --- -The `@string` decorator can be used with polymorphic variants and the `@as` decorator on *externals* to modify the string values used for the variants in the compiled JavaScript. +The `@string` decorator can be used with [polymorphic variants](/docs/manual/latest/polymorphic-variant) and the `@as` decorator on *externals* to modify the string values used for the variants in the compiled JavaScript. For example: From 0f08e50ba1f2c23a68fa52c505403f9e434243fd Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 21:51:13 +1100 Subject: [PATCH 31/61] Add variadic decorator syntax --- misc_docs/syntax/decorator_variadic.mdx | 45 +++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 misc_docs/syntax/decorator_variadic.mdx diff --git a/misc_docs/syntax/decorator_variadic.mdx b/misc_docs/syntax/decorator_variadic.mdx new file mode 100644 index 000000000..115471acb --- /dev/null +++ b/misc_docs/syntax/decorator_variadic.mdx @@ -0,0 +1,45 @@ +--- +id: "variadic-decorator" +keywords: ["variadic", "decorator"] +name: "@variadic" +summary: "This is the `@variadic` decorator." +category: "decorators" +--- + +The `@variadic` decorator is used to model JavaScript functions that take a variable number of arguments, where all arguments are of the same type. + +For example: + + + +```re +@val @variadic @scope("Math") +external max: array => int = "max" + +let result = max([5, -2, 6, 1]) +``` + +```js +var result = Math.max(5, -2, 6, 1); +``` + + + +If your function has mandatory arguments, you can use the `@as` decorator to add them: + + + +```re +@val @variadic +external warn: (@as(404) _, @as("NOT_FOUND") _, array) => unit = "log" + +warn([]) +warn(["this", "page", "is", "not", "found"]) +``` + +```js +log(404, "NOT_FOUND"); +log(404, "NOT_FOUND", "this", "page", "is", "not", "found"); +``` + + From a225816b462601492a65101442fafc4175ebee6c Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 22:03:56 +1100 Subject: [PATCH 32/61] Add inline decorator syntax --- misc_docs/syntax/decorator_inline.mdx | 93 +++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 misc_docs/syntax/decorator_inline.mdx diff --git a/misc_docs/syntax/decorator_inline.mdx b/misc_docs/syntax/decorator_inline.mdx new file mode 100644 index 000000000..7d096a0bb --- /dev/null +++ b/misc_docs/syntax/decorator_inline.mdx @@ -0,0 +1,93 @@ +--- +id: "inline-decorator" +keywords: ["inline", "decorator", "constant"] +name: "@inline" +summary: "This is the `@inline` decorator." +category: "decorators" +--- + +The `@inline` decorator tells the compiler to copy (i.e. inline) its value in every place the binding is being used. This is especially useful for cases where string constants can't be used as variables, but need to be present as constant values. + +For example, consider the following code *without* the `@inline` decorator. + + + +```re +module Colors = { + let green = "green" + let red = "red" +} + +let allowedColors = [Colors.green, Colors.red] +``` + +```js +var green = "green"; +var red = "red"; + +var Colors = { + green: green, + red: red +}; + +var allowedColors = [ + green, + red +]; +``` + + + + +And compare *with* the `@inline` decorator. + + + +```re +module Colors = { + @inline + let green = "green" + + @inline + let red = "red" +} + +let allowedColors = [Colors.green, Colors.red] +``` + +```js +var allowedColors = [ + "green", + "red" +]; +``` + + + +A more advanced, but common use-case is to inline the `NODE_ENV` strings: + + + +```re +module NodeEnv = { + @val @scope("process.env") external env: string = "NODE_ENV" + + @inline + let development = "development" + + @inline + let production = "production" +} + +if NodeEnv.env === NodeEnv.development { + Js.log("development") +} +``` + +```js +if (process.env.NODE_ENV === "development") { + console.log("development"); +} +``` + + From 121831930f70d56bc12212a2933899a114de027d Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 22:17:14 +1100 Subject: [PATCH 33/61] Add meth decorator syntax --- misc_docs/syntax/decorator_meth.mdx | 45 +++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 misc_docs/syntax/decorator_meth.mdx diff --git a/misc_docs/syntax/decorator_meth.mdx b/misc_docs/syntax/decorator_meth.mdx new file mode 100644 index 000000000..6db851873 --- /dev/null +++ b/misc_docs/syntax/decorator_meth.mdx @@ -0,0 +1,45 @@ +--- +id: "meth-decorator" +keywords: ["meth", "decorator", "object", "function"] +name: "@meth" +summary: "This is the `@meth` decorator." +category: "decorators" +--- + +The `@meth` decorator is used to call a function on a JavaScript object, and avoid issues with currying. + +For example, consider the following JavaScript code: + +```js +function say (a, b) { + console.log(a, b); +}; + +var john = { + say +}; +``` + +The shape of the john object could be typed and accessed as follows: + + + +```re +type person = {@meth "say": (string, string) => unit} + +@val external john: person = "john" + +john["say"]("hey", "jude") +``` + +```js +john.say("hey", "jude"); +``` + + + +Note that we are using the object property notation to access the method. + +If you omit the `@meth` decorator in the function signature, the type checker will error, because it is ensured by the compiler to enforce only fully applied functions in JavaScript objects. + + From fc454f59ed3d90c9fc6ea0a95172ae06134cf055 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 22:50:12 +1100 Subject: [PATCH 34/61] Add return decorator syntax --- misc_docs/syntax/decorator_return.mdx | 87 +++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 misc_docs/syntax/decorator_return.mdx diff --git a/misc_docs/syntax/decorator_return.mdx b/misc_docs/syntax/decorator_return.mdx new file mode 100644 index 000000000..0e07ee8e5 --- /dev/null +++ b/misc_docs/syntax/decorator_return.mdx @@ -0,0 +1,87 @@ +--- +id: "return-decorator" +keywords: ["return", "decorator", "null", "undefined"] +name: "@return" +summary: "This is the `@return` decorator." +category: "decorators" +--- + +The `@return` decorator is used to control how `null` and `undefined` values are converted to `option` types in ReScript. + +Consider the following code *without* the `@return` decorator: + + + + +```re +type element +type dom + +@send +external getElementById: (dom, string) => option = "getElementById" + +let test = dom => { + let elem = dom->getElementById("haha") + switch elem { + | None => "None: Only when value is undefined" + | Some(_) => "Some: When value is not undefined or is null" + } +} +``` + +```js +function test(dom) { + var elem = dom.getElementById("haha"); + if (elem !== undefined) { + return "Some: When value is not undefined or is null"; + } else { + return "None: Only when value is undefined"; + } +} +``` + + + +Here, `Some` can include `null` values. + +The `@return` decorator can specify how `null` and `undefined` are handled. + +There are four versions of the decorator: + +1. `@return(nullable)` converts `null` and `undefined` to `None`. +2. `@return(null_to_opt)` converts `null` to `None`. +3. `@return(undefined_to_opt)` converts `undefined` to `None`. +4. `@return(identity)` has the same behaviour as omitting the decorator. It is rarely used, but introduced here for debugging purposes. + +Example with `@return(nullable)`: + + + +```re +type element +type dom + +@send @return(nullable) +external getElementById: (dom, string) => option = "getElementById" + +let test = dom => { + let elem = dom->getElementById("haha") + switch elem { + | None => "None: When value is undefined or null" + | Some(_) => "Some: When value is not undefined and not null" + } +} +``` + +```js +function test(dom) { + var elem = dom.getElementById("haha"); + if (elem == null) { + return "None: When value is undefined or null"; + } else { + return "Some: When value is not undefined and not null"; + } +} +``` + + From 1c4325554a1f27127532831438723d7e20579d69 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 23:06:23 +1100 Subject: [PATCH 35/61] Enable wrapping of tags --- src/components/SyntaxLookupWidget.js | 6 ++++-- src/components/SyntaxLookupWidget.res | 4 ++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/components/SyntaxLookupWidget.js b/src/components/SyntaxLookupWidget.js index d492d0f6f..7ce88606a 100644 --- a/src/components/SyntaxLookupWidget.js +++ b/src/components/SyntaxLookupWidget.js @@ -41,7 +41,9 @@ function SyntaxLookupWidget$Category(Props) { var children = Props.children; return React.createElement("div", undefined, React.createElement("h3", { className: "font-sans font-medium text-gray-100 tracking-wide text-14 uppercase mb-2" - }, title), React.createElement("div", undefined, children)); + }, title), React.createElement("div", { + className: "flex flex-wrap" + }, children)); } function toCategory(s) { @@ -275,7 +277,7 @@ function SyntaxLookupWidget(Props) { }; return React.createElement("span", { key: item.name, - className: "first:ml-0 ml-2 cursor-pointer", + className: "mr-2 mb-2 cursor-pointer", onMouseDown: onMouseDown }, React.createElement(SyntaxLookupWidget$Tag, { text: item.name diff --git a/src/components/SyntaxLookupWidget.res b/src/components/SyntaxLookupWidget.res index 7918f3938..ca5c8c3f3 100644 --- a/src/components/SyntaxLookupWidget.res +++ b/src/components/SyntaxLookupWidget.res @@ -49,7 +49,7 @@ module Category = {

{React.string(title)}

-
children
+
children
} } @@ -259,7 +259,7 @@ let make = () => { ReactEvent.Mouse.preventDefault(evt) setState(_ => ShowDetails(item)) } - + }) From 5e51a46b146a591d792ba022f3e8b32d106103dc Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 23:07:42 +1100 Subject: [PATCH 36/61] Update syntax lookup meta --- pages/syntax-lookup.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/syntax-lookup.mdx b/pages/syntax-lookup.mdx index a132ee277..39a5e8da7 100644 --- a/pages/syntax-lookup.mdx +++ b/pages/syntax-lookup.mdx @@ -1,7 +1,7 @@ --- title: "Syntax Lookup" -description: "Discover ReScript syntax constructs with our discovery tool" -canonical: "/docs/manual/latest/syntax-discovery" +description: "Discover ReScript syntax constructs with our lookup tool" +canonical: "/docs/manual/latest/syntax-lookup" --- import { make as SyntaxLookupWidget } from "src/components/SyntaxLookupWidget" From e8c8ba0dca01aa6d5742b5e1e23a768498e1d751 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Fri, 8 Jan 2021 23:54:50 +1100 Subject: [PATCH 37/61] Add unboxed decorator syntax --- misc_docs/syntax/decorator_unboxed.mdx | 58 ++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 misc_docs/syntax/decorator_unboxed.mdx diff --git a/misc_docs/syntax/decorator_unboxed.mdx b/misc_docs/syntax/decorator_unboxed.mdx new file mode 100644 index 000000000..bf49ae7bc --- /dev/null +++ b/misc_docs/syntax/decorator_unboxed.mdx @@ -0,0 +1,58 @@ +--- +id: "unboxed-decorator" +keywords: ["unboxed", "decorator"] +name: "@unboxed" +summary: "This is the `@unboxed` decorator." +category: "decorators" +--- + +The `@unboxed` decorator provides a way to unwrap **variant** constructors that have a *single* argument, or **record** objects that have a *single* field. + +For example, consider the following code: + + + +```re +type name = Name(string) +let studentName = Name("Joe") + +type greeting = {message: string} +let hi = {message: "hello!"} +``` + +```js +var studentName = /* Name */{ + _0: "Joe" +}; + +var hi = { + message: "hello!" +}; +``` + + + +When compiled to JavaScript, these values are represented as objects. + +If we now add the `@unboxed` decorator, the object wrappers are removed from the JavaScript output: + + + +```re +@unboxed +type name = Name(string) +let studentName = Name("Joe") + +@unboxed +type greeting = {message: string} +let hi = {message: "hello!"} +``` + +```js +var studentName = "Joe"; +var hi = "hello!"; +``` + + + +See the [Unboxed](/docs/manual/latest/unboxed) section for more details. From 520155f6234b8f80b4df44079ae29cb4957eb83b Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 07:23:34 +1100 Subject: [PATCH 38/61] Apply suggestions from code review Co-authored-by: Patrick Ecker --- misc_docs/syntax/decorator_as.mdx | 2 +- misc_docs/syntax/decorator_get.mdx | 2 ++ misc_docs/syntax/decorator_get_index.mdx | 3 ++- misc_docs/syntax/decorator_inline.mdx | 4 ++++ 4 files changed, 9 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index 8af24b1d9..cc4cf70ff 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -14,7 +14,7 @@ For example: -```re +```res type action = { @as("type") type_: string } diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx index a5715fad6..a1a9bbc5c 100644 --- a/misc_docs/syntax/decorator_get.mdx +++ b/misc_docs/syntax/decorator_get.mdx @@ -32,4 +32,6 @@ var top = div.scrollTop +### References +- [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index 45e27f587..dbcf21b6a 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -69,4 +69,5 @@ var value = o["y"]; ``` - +### References +- [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) diff --git a/misc_docs/syntax/decorator_inline.mdx b/misc_docs/syntax/decorator_inline.mdx index 7d096a0bb..541f46910 100644 --- a/misc_docs/syntax/decorator_inline.mdx +++ b/misc_docs/syntax/decorator_inline.mdx @@ -91,3 +91,7 @@ if (process.env.NODE_ENV === "development") { ``` + +### References + +- [Attribute (Decorator)](https://rescript-lang.org/docs/manual/latest/attribute) From 2bb206e04a20c5e90928f1a4ba5954ad146e8b6d Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 07:25:10 +1100 Subject: [PATCH 39/61] Replace "re" with "res" in code snippet types --- misc_docs/syntax/decorator_deriving.mdx | 6 +++--- misc_docs/syntax/decorator_get.mdx | 2 +- misc_docs/syntax/decorator_get_index.mdx | 4 ++-- misc_docs/syntax/decorator_inline.mdx | 6 +++--- misc_docs/syntax/decorator_int.mdx | 2 +- misc_docs/syntax/decorator_meth.mdx | 2 +- misc_docs/syntax/decorator_module.mdx | 2 +- misc_docs/syntax/decorator_new.mdx | 4 ++-- misc_docs/syntax/decorator_return.mdx | 4 ++-- misc_docs/syntax/decorator_scope.mdx | 2 +- misc_docs/syntax/decorator_send.mdx | 2 +- misc_docs/syntax/decorator_set.mdx | 2 +- misc_docs/syntax/decorator_set_index.mdx | 4 ++-- misc_docs/syntax/decorator_string.mdx | 2 +- misc_docs/syntax/decorator_unboxed.mdx | 4 ++-- misc_docs/syntax/decorator_unwrap.mdx | 2 +- misc_docs/syntax/decorator_val.mdx | 2 +- misc_docs/syntax/decorator_variadic.mdx | 4 ++-- 18 files changed, 28 insertions(+), 28 deletions(-) diff --git a/misc_docs/syntax/decorator_deriving.mdx b/misc_docs/syntax/decorator_deriving.mdx index 7987beec3..d32a60315 100644 --- a/misc_docs/syntax/decorator_deriving.mdx +++ b/misc_docs/syntax/decorator_deriving.mdx @@ -24,7 +24,7 @@ Example of **record** accessors: -```re +```res @deriving(accessors) type person = { name: string, @@ -74,7 +74,7 @@ Example of **variant** accessors: -```re +```res @deriving(accessors) type action = | SetName(string) @@ -146,7 +146,7 @@ Example of **abstract record** type: -```re +```res @deriving(abstract) type person = { name: string, diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx index a1a9bbc5c..26e204017 100644 --- a/misc_docs/syntax/decorator_get.mdx +++ b/misc_docs/syntax/decorator_get.mdx @@ -12,7 +12,7 @@ For example: -```re +```res type element @scope("document") @val diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index dbcf21b6a..ef48a6545 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -12,7 +12,7 @@ For example with an Array: -```re +```res type t @new external create: int => t = "Array" @@ -43,7 +43,7 @@ And an example with an object: -```re +```res type t @new external create: unit => t = "Object" diff --git a/misc_docs/syntax/decorator_inline.mdx b/misc_docs/syntax/decorator_inline.mdx index 541f46910..105231d49 100644 --- a/misc_docs/syntax/decorator_inline.mdx +++ b/misc_docs/syntax/decorator_inline.mdx @@ -12,7 +12,7 @@ For example, consider the following code *without* the `@inline` decorator. -```re +```res module Colors = { let green = "green" let red = "red" @@ -43,7 +43,7 @@ And compare *with* the `@inline` decorator. -```re +```res module Colors = { @inline let green = "green" @@ -68,7 +68,7 @@ A more advanced, but common use-case is to inline the `NODE_ENV` strings: -```re +```res module NodeEnv = { @val @scope("process.env") external env: string = "NODE_ENV" diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx index 6e83bc100..cc677a054 100644 --- a/misc_docs/syntax/decorator_int.mdx +++ b/misc_docs/syntax/decorator_int.mdx @@ -12,7 +12,7 @@ For example: -```re +```res @val external setStatus: @int[ @as(0) #NotStarted | @as(1) #Started | diff --git a/misc_docs/syntax/decorator_meth.mdx b/misc_docs/syntax/decorator_meth.mdx index 6db851873..4dadaa42c 100644 --- a/misc_docs/syntax/decorator_meth.mdx +++ b/misc_docs/syntax/decorator_meth.mdx @@ -24,7 +24,7 @@ The shape of the john object could be typed and accessed as follows: -```re +```res type person = {@meth "say": (string, string) => unit} @val external john: person = "john" diff --git a/misc_docs/syntax/decorator_module.mdx b/misc_docs/syntax/decorator_module.mdx index 56665fcae..d3fe1277b 100644 --- a/misc_docs/syntax/decorator_module.mdx +++ b/misc_docs/syntax/decorator_module.mdx @@ -12,7 +12,7 @@ For example: -```re +```res @module("path") external dirname: string => string = "dirname" diff --git a/misc_docs/syntax/decorator_new.mdx b/misc_docs/syntax/decorator_new.mdx index d2d3f58c8..a93a3b192 100644 --- a/misc_docs/syntax/decorator_new.mdx +++ b/misc_docs/syntax/decorator_new.mdx @@ -10,7 +10,7 @@ The `@new` decorator is used whenever you need to bind to a JavaScript class con -```re +```res type t @new external create: unit => t = "Date" @@ -28,7 +28,7 @@ When the object is not available on the global scope, combine it with `@module`: -```re +```res type t @module @new external book: unit => t = "Book" diff --git a/misc_docs/syntax/decorator_return.mdx b/misc_docs/syntax/decorator_return.mdx index 0e07ee8e5..ea9b77c48 100644 --- a/misc_docs/syntax/decorator_return.mdx +++ b/misc_docs/syntax/decorator_return.mdx @@ -13,7 +13,7 @@ Consider the following code *without* the `@return` decorator: -```re +```res type element type dom @@ -57,7 +57,7 @@ Example with `@return(nullable)`: -```re +```res type element type dom diff --git a/misc_docs/syntax/decorator_scope.mdx b/misc_docs/syntax/decorator_scope.mdx index ce2b8438c..d354886a6 100644 --- a/misc_docs/syntax/decorator_scope.mdx +++ b/misc_docs/syntax/decorator_scope.mdx @@ -12,7 +12,7 @@ For example: -```re +```res @scope("Math") @val external floor: float => int = "floor" diff --git a/misc_docs/syntax/decorator_send.mdx b/misc_docs/syntax/decorator_send.mdx index e084931b9..961f65362 100644 --- a/misc_docs/syntax/decorator_send.mdx +++ b/misc_docs/syntax/decorator_send.mdx @@ -12,7 +12,7 @@ For example: -```re +```res type element @scope("document") @val diff --git a/misc_docs/syntax/decorator_set.mdx b/misc_docs/syntax/decorator_set.mdx index 7815a0972..430608437 100644 --- a/misc_docs/syntax/decorator_set.mdx +++ b/misc_docs/syntax/decorator_set.mdx @@ -12,7 +12,7 @@ For example: -```re +```res type element @scope("document") @val diff --git a/misc_docs/syntax/decorator_set_index.mdx b/misc_docs/syntax/decorator_set_index.mdx index 3e1f2fc9b..c79e71dd2 100644 --- a/misc_docs/syntax/decorator_set_index.mdx +++ b/misc_docs/syntax/decorator_set_index.mdx @@ -12,7 +12,7 @@ For example with an Array: -```re +```res type t @new external create: int => t = "Array" @@ -43,7 +43,7 @@ And an example with an object: -```re +```res type t @new external create: unit => t = "Object" diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx index 9dcfdb2e6..6594b98c5 100644 --- a/misc_docs/syntax/decorator_string.mdx +++ b/misc_docs/syntax/decorator_string.mdx @@ -12,7 +12,7 @@ For example: -```re +```res @val external setStatus: @string[ @as("NOT_STARTED") #NotStarted | @as("STARTED") #Started | diff --git a/misc_docs/syntax/decorator_unboxed.mdx b/misc_docs/syntax/decorator_unboxed.mdx index bf49ae7bc..5efe495e0 100644 --- a/misc_docs/syntax/decorator_unboxed.mdx +++ b/misc_docs/syntax/decorator_unboxed.mdx @@ -12,7 +12,7 @@ For example, consider the following code: -```re +```res type name = Name(string) let studentName = Name("Joe") @@ -38,7 +38,7 @@ If we now add the `@unboxed` decorator, the object wrappers are removed from the -```re +```res @unboxed type name = Name(string) let studentName = Name("Joe") diff --git a/misc_docs/syntax/decorator_unwrap.mdx b/misc_docs/syntax/decorator_unwrap.mdx index 3078913a4..a488daadf 100644 --- a/misc_docs/syntax/decorator_unwrap.mdx +++ b/misc_docs/syntax/decorator_unwrap.mdx @@ -27,7 +27,7 @@ Here is how you'd bind to this function: -```re +```res @val external padLeft: ( @unwrap [#Int(int) | #Str(string)], string diff --git a/misc_docs/syntax/decorator_val.mdx b/misc_docs/syntax/decorator_val.mdx index be6b326c9..fa13595a5 100644 --- a/misc_docs/syntax/decorator_val.mdx +++ b/misc_docs/syntax/decorator_val.mdx @@ -12,7 +12,7 @@ For example: -```re +```res type timeoutID @val diff --git a/misc_docs/syntax/decorator_variadic.mdx b/misc_docs/syntax/decorator_variadic.mdx index 115471acb..4e9dcc1ae 100644 --- a/misc_docs/syntax/decorator_variadic.mdx +++ b/misc_docs/syntax/decorator_variadic.mdx @@ -12,7 +12,7 @@ For example: -```re +```res @val @variadic @scope("Math") external max: array => int = "max" @@ -29,7 +29,7 @@ If your function has mandatory arguments, you can use the `@as` decorator to add -```re +```res @val @variadic external warn: (@as(404) _, @as("NOT_FOUND") _, array) => unit = "log" From 6cc597eb2eb16ae19a43eb95af9404a9283193ab Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 13:55:14 +1100 Subject: [PATCH 40/61] Tweak as decorator --- misc_docs/syntax/decorator_as.mdx | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index cc4cf70ff..b888b00c9 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -6,9 +6,9 @@ summary: "This is the `@as` decorator." category: "decorators" --- -The `@as` decorator may be used on record types to alias record field names to a different JavaScript attribute name. +The `@as` decorator is commonly used on record types to alias record field names to a different JavaScript attribute name. -This is mostly useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords). +This is useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords). For example: @@ -30,4 +30,13 @@ var action = { -It may also be used when declaring external [polymorphic variants](/docs/manual/latest/polymorphic-variant). See the `@string` and `@int` decorators for more details. +### References + +* [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) describes aliasing polymorphic variants using the `@as` decorator. +* [Fixed Arguments](/docs/manual/latest/bind-to-js-function#fixed-arguments) describes passing predetermined argument values to JavaScript functions using the `@as` decorator. + +### Related + +* `@int` +* `@string` +* `@variadic` From 037a8a1ac0b3cfb537c53fda61fe8555243153b8 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 13:58:34 +1100 Subject: [PATCH 41/61] Tweak as decorator --- misc_docs/syntax/decorator_as.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index b888b00c9..31b873ee5 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -32,8 +32,8 @@ var action = { ### References -* [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) describes aliasing polymorphic variants using the `@as` decorator. -* [Fixed Arguments](/docs/manual/latest/bind-to-js-function#fixed-arguments) describes passing predetermined argument values to JavaScript functions using the `@as` decorator. +* [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) +* [Fixed Arguments](/docs/manual/latest/bind-to-js-function#fixed-arguments) ### Related From bf26f7ec270c871c1aba28293b5fbf87e14b09d9 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 14:30:45 +1100 Subject: [PATCH 42/61] Simplify the deriving decorator --- misc_docs/syntax/decorator_deriving.mdx | 192 +++--------------------- 1 file changed, 21 insertions(+), 171 deletions(-) diff --git a/misc_docs/syntax/decorator_deriving.mdx b/misc_docs/syntax/decorator_deriving.mdx index d32a60315..97dd92ce1 100644 --- a/misc_docs/syntax/decorator_deriving.mdx +++ b/misc_docs/syntax/decorator_deriving.mdx @@ -1,202 +1,52 @@ --- id: "deriving-decorator" -keywords: ["deriving", "decorator", "record", "variant"] +keywords: ["deriving", "decorator", "record"] name: "@deriving" summary: "This is the `@deriving` decorator." category: "decorators" --- -The `@deriving(accessors)` decorator can be used to either: +When the `@deriving` decorator is applied to a **record** type, +it expands the type into a factory function plus a set of +getter/setter functions for it's fields. -* Generate getter functions for a decorated **record** type, or -* Generate creator functions for constructors of a **variant** type. +> Note that this is an outdated decorator and you may no longer need to use it. +> See [Convert Record Type to Abstract Record](/docs/manual/latest/generate-converters-accessors#convert-record-type-to-abstract-record) for more details. -The `@deriving(abstract)` decorator creates: - -* An abstract type representing the "abstract record". -* A creator function for the new abstract type, where labeled arguments represent the attributes of the record. -* A set of setter / getter functions for each record attribute - -Note that when using the `@deriving(abstract)` decorator, the original record type will be removed. -You'll need to use the newly created functions to create / get / set values of this type. - -Example of **record** accessors: +### Example ```res -@deriving(accessors) +@deriving(abstract) type person = { name: string, age: int, + job: string, } -// This generates functions with signatures: -// let name: (person) => string; -// let age: (person) => int; - -let toString = (person): string => { - name(person) ++ " " ++ Belt.Int.toString(age(person)) -} - -let misha = { - name: "Misha", - age: 20, -} +let joe = person(~name="Joe", ~age=20, ~job="teacher") -let result = toString(misha) +let joeName = nameGet(joe) +let joeAge = ageGet(joe) +let joeJob = jobGet(joe) ``` ```js -function name(param) { - return param.name; -} - -function age(param) { - return param.age; -} - -function toString(person) { - return person.name + " " + String(person.age); -} - -var misha = { - name: "Misha", +var joe = { + name: "Joe", age: 20, + job: "teacher" }; -var result = toString(misha); +var joeName = joe.name; +var joeAge = joe.age; +var joeJob = joe.job; ``` -Example of **variant** accessors: - - - -```res -@deriving(accessors) -type action = - | SetName(string) - | SetAge(int) - | ClearAll - -// This generates functions with signatures: -// let setName: (string) => action; -// let age: (person) => int; - -let dispatch = action => { - switch action { - | SetName(name) => Js.log2("SetName", name) - | SetAge(age) => Js.log2("SetAge", age) - | ClearAll => Js.log("ClearAll") - } -} - -dispatch(setName("Hello")) -dispatch(setAge(123)) -dispatch(clearAll) -``` - -```js -function setName(param_0) { - return { - TAG: /* SetName */ 0, - _0: param_0, - } -} - -function setAge(param_0) { - return { - TAG: /* SetAge */ 1, - _0: param_0, - } -} - -function dispatch(action) { - if (typeof action === "number") { - console.log("ClearAll") - return - } - if (action.TAG === /* SetName */ 0) { - console.log("SetName", action._0) - return - } - console.log("SetAge", action._0) -} +### References -dispatch({ - TAG: /* SetName */ 0, - _0: "Hello", -}) - -dispatch({ - TAG: /* SetAge */ 1, - _0: 123, -}) - -dispatch(/* ClearAll */ 0) - -var clearAll = /* ClearAll */ 0 -``` - - - -Example of **abstract record** type: - - - -```res -@deriving(abstract) -type person = { - name: string, - mutable age: int, // Use the mutable keyword for generating setters -} - -// Generates the following: -// -// An abstract type, replacing the original type: -// -// type person -// -// A type constructor: -// -// let person: (~name: string, ~age: int) => person -// -// Getters: -// -// let nameGet: (person) => string; -// let ageGet: (person) => int -// -// Setters (only mutable attributes) -// -// let ageSet: (person, int) => unit - -let friend = person(~name="Misha", ~age=20) - -Js.log(friend->nameGet) // => "Misha" - -// Increase age by 1 via mutation -friend->ageSet(friend->ageGet + 1) - -Js.log(friend->ageGet) // => 21 - -// This will NOT be possible (original type has been removed) -// let misha = {name: "Misha", age: 20} - -``` - -```js -var friend = { - name: "Misha", - age: 20 -}; - -console.log(friend.name); - -friend.age = friend.age + 1 | 0; - -console.log(friend.age); -``` +* [Convert Record Type to Abstract Record](/docs/manual/latest/generate-converters-accessors#convert-record-type-to-abstract-record) - \ No newline at end of file From b5ece0962ebb5f3cdf917845270ffef39c50b50a Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 14:31:45 +1100 Subject: [PATCH 43/61] Tweak as decorator formatting --- misc_docs/syntax/decorator_as.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index 31b873ee5..644be25ea 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -10,7 +10,7 @@ The `@as` decorator is commonly used on record types to alias record field names This is useful to map to JavaScript attribute names that cannot be expressed in ReScript (such as keywords). -For example: +### Example From 8de8283916007b0c55a2898049a1b266c7b8317c Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:25:55 +1100 Subject: [PATCH 44/61] Update get and set decorators --- misc_docs/syntax/decorator_get.mdx | 8 ++++- misc_docs/syntax/decorator_get_index.mdx | 44 ++++++----------------- misc_docs/syntax/decorator_set.mdx | 8 +++++ misc_docs/syntax/decorator_set_index.mdx | 45 +++++++----------------- 4 files changed, 38 insertions(+), 67 deletions(-) diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx index 26e204017..c5a572fe6 100644 --- a/misc_docs/syntax/decorator_get.mdx +++ b/misc_docs/syntax/decorator_get.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@get` decorator is used to bind to a property of an object. -For example: +### Example @@ -35,3 +35,9 @@ var top = div.scrollTop ### References - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) + +### Related + +- `@set` +- `@get_index` +- `@set_index` diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index ef48a6545..205b4be03 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -6,40 +6,10 @@ summary: "This is the `@get_index` decorator." category: "decorators" --- -The `@get_index` decorator is used to access a dynamic property or index. +The `@get_index` decorator is used to access a dynamic property on an object, +or an index of an array. -For example with an Array: - - - -```res -type t - -@new external create: int => t = "Array" -@set_index external set: (t, int, string) => unit = "" -@get_index external get: (t, int) => string = "" - -let a = create(3) -a->set(0, "zero") -a->set(1, "one") -a->set(2, "two") - -let value = a->get(1) -``` - -```js -var a = new Array(3); - -a[0] = "zero"; -a[1] = "one"; -a[2] = "two"; - -var value = a[1]; -``` - - - -And an example with an object: +### Example @@ -69,5 +39,13 @@ var value = o["y"]; ``` + ### References + - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) + +### Related + +- `@get` +- `@set` +- `@set_index` diff --git a/misc_docs/syntax/decorator_set.mdx b/misc_docs/syntax/decorator_set.mdx index 430608437..062aac0ed 100644 --- a/misc_docs/syntax/decorator_set.mdx +++ b/misc_docs/syntax/decorator_set.mdx @@ -33,4 +33,12 @@ div.scrollTop = 100 +### References +- [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) + +### Related + +- `@get` +- `@set_index` +- `@get_index` diff --git a/misc_docs/syntax/decorator_set_index.mdx b/misc_docs/syntax/decorator_set_index.mdx index c79e71dd2..3c1ca386b 100644 --- a/misc_docs/syntax/decorator_set_index.mdx +++ b/misc_docs/syntax/decorator_set_index.mdx @@ -6,40 +6,10 @@ summary: "This is the `@set_index` decorator." category: "decorators" --- -The `@set_index` decorator is used to set a dynamic property or index. +The `@set_index` decorator is used to set a dynamic property on an object, +or an index of an array. -For example with an Array: - - - -```res -type t - -@new external create: int => t = "Array" -@set_index external set: (t, int, string) => unit = "" -@get_index external get: (t, int) => string = "" - -let a = create(3) -a->set(0, "zero") -a->set(1, "one") -a->set(2, "two") - -let value = a->get(1) -``` - -```js -var a = new Array(3); - -a[0] = "zero"; -a[1] = "one"; -a[2] = "two"; - -var value = a[1]; -``` - - - -And an example with an object: +### Example @@ -70,3 +40,12 @@ var value = o["y"]; +### References + +- [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) + +### Related + +- `@get` +- `@set` +- `@get_index` From 3a2f7f48468343633c045aa7a43840b418141c31 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:30:31 +1100 Subject: [PATCH 45/61] Update inline decorator --- misc_docs/syntax/decorator_inline.mdx | 66 ++------------------------- 1 file changed, 4 insertions(+), 62 deletions(-) diff --git a/misc_docs/syntax/decorator_inline.mdx b/misc_docs/syntax/decorator_inline.mdx index 105231d49..4bdab6c34 100644 --- a/misc_docs/syntax/decorator_inline.mdx +++ b/misc_docs/syntax/decorator_inline.mdx @@ -6,40 +6,10 @@ summary: "This is the `@inline` decorator." category: "decorators" --- -The `@inline` decorator tells the compiler to copy (i.e. inline) its value in every place the binding is being used. This is especially useful for cases where string constants can't be used as variables, but need to be present as constant values. +The `@inline` decorator tells the compiler to inline its value +in every place the binding is being used, rather than use a variable. -For example, consider the following code *without* the `@inline` decorator. - - - -```res -module Colors = { - let green = "green" - let red = "red" -} - -let allowedColors = [Colors.green, Colors.red] -``` - -```js -var green = "green"; -var red = "red"; - -var Colors = { - green: green, - red: red -}; - -var allowedColors = [ - green, - red -]; -``` - - - - -And compare *with* the `@inline` decorator. +### Example @@ -64,34 +34,6 @@ var allowedColors = [ -A more advanced, but common use-case is to inline the `NODE_ENV` strings: - - - -```res -module NodeEnv = { - @val @scope("process.env") external env: string = "NODE_ENV" - - @inline - let development = "development" - - @inline - let production = "production" -} - -if NodeEnv.env === NodeEnv.development { - Js.log("development") -} -``` - -```js -if (process.env.NODE_ENV === "development") { - console.log("development"); -} -``` - - - ### References -- [Attribute (Decorator)](https://rescript-lang.org/docs/manual/latest/attribute) +- [Inlining Constants](/docs/manual/latest/inlining-constants) From 06845753f7bb14f9b4e35c4de8d6caf4b09f2f17 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:32:59 +1100 Subject: [PATCH 46/61] Update int decorator --- misc_docs/syntax/decorator_int.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx index cc677a054..ec8cf84c3 100644 --- a/misc_docs/syntax/decorator_int.mdx +++ b/misc_docs/syntax/decorator_int.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@int` decorator can be used with [polymorphic variants](/docs/manual/latest/polymorphic-variant) and the `@as` decorator on *externals* to modify the compiled JavaScript to use integers for the values instead of strings. -For example: +### Example @@ -27,3 +27,5 @@ setStatus(2); ``` + + From 98b316d93c8465eb1d90fe4da9e6a58577d96582 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:36:38 +1100 Subject: [PATCH 47/61] Simplify meth decorator --- misc_docs/syntax/decorator_meth.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/misc_docs/syntax/decorator_meth.mdx b/misc_docs/syntax/decorator_meth.mdx index 4dadaa42c..2a054e1d0 100644 --- a/misc_docs/syntax/decorator_meth.mdx +++ b/misc_docs/syntax/decorator_meth.mdx @@ -6,9 +6,12 @@ summary: "This is the `@meth` decorator." category: "decorators" --- -The `@meth` decorator is used to call a function on a JavaScript object, and avoid issues with currying. +The `@meth` decorator is used to call a function on a JavaScript object, +and avoid issues with currying. -For example, consider the following JavaScript code: +### Example + +Suppose we have the following JavaScript: ```js function say (a, b) { @@ -20,7 +23,7 @@ var john = { }; ``` -The shape of the john object could be typed and accessed as follows: +We can model and bind to this object as follows. @@ -38,8 +41,5 @@ john.say("hey", "jude"); -Note that we are using the object property notation to access the method. - -If you omit the `@meth` decorator in the function signature, the type checker will error, because it is ensured by the compiler to enforce only fully applied functions in JavaScript objects. From e248f6dacf498d0ff0a554ac145b77157edbb2db Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:38:00 +1100 Subject: [PATCH 48/61] Update module decorator --- misc_docs/syntax/decorator_module.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_module.mdx b/misc_docs/syntax/decorator_module.mdx index d3fe1277b..70bcf7cf0 100644 --- a/misc_docs/syntax/decorator_module.mdx +++ b/misc_docs/syntax/decorator_module.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@module` decorator is used to bind to a JavaScript module. -For example: +### Example @@ -27,4 +27,6 @@ var root = Path.dirname("/User/github"); -See the [Import from JavaScript](/docs/manual/latest/import-from-export-to-js#import-from-javascript) section for full details, including other variations of how this decorator may be used. +### References + +* [Import from JavaScript](/docs/manual/latest/import-from-export-to-js#import-from-javascript) From f634206be9b3ece8d86cc63811e1ed03131fa66c Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:40:08 +1100 Subject: [PATCH 49/61] Simplify new decorator --- misc_docs/syntax/decorator_new.mdx | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/misc_docs/syntax/decorator_new.mdx b/misc_docs/syntax/decorator_new.mdx index a93a3b192..6b57d5d5d 100644 --- a/misc_docs/syntax/decorator_new.mdx +++ b/misc_docs/syntax/decorator_new.mdx @@ -6,7 +6,10 @@ summary: "This is the `@new` decorator." category: "decorators" --- -The `@new` decorator is used whenever you need to bind to a JavaScript class constructor that requires the `new` keword for instantiation. +The `@new` decorator is used whenever you need to bind to a JavaScript +class constructor that requires the `new` keword for instantiation. + +### Example @@ -24,21 +27,6 @@ var now = new Date(); -When the object is not available on the global scope, combine it with `@module`: - - - -```res -type t - -@module @new external book: unit => t = "Book" +### References -let myBook = book() -``` - -```js -var Book = require("Book"); -var myBook = new Book(); -``` - - +* [Bind to a JS Object That's a Class](/docs/manual/latest/bind-to-js-object#bind-to-a-js-object-thats-a-class) \ No newline at end of file From 8d58c6c1fd17399ab31a9dd95bb303be19297f69 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:42:59 +1100 Subject: [PATCH 50/61] Simplify return decorator --- misc_docs/syntax/decorator_return.mdx | 58 +++++---------------------- 1 file changed, 9 insertions(+), 49 deletions(-) diff --git a/misc_docs/syntax/decorator_return.mdx b/misc_docs/syntax/decorator_return.mdx index ea9b77c48..3f9337dca 100644 --- a/misc_docs/syntax/decorator_return.mdx +++ b/misc_docs/syntax/decorator_return.mdx @@ -8,52 +8,8 @@ category: "decorators" The `@return` decorator is used to control how `null` and `undefined` values are converted to `option` types in ReScript. -Consider the following code *without* the `@return` decorator: - - - -```res -type element -type dom - -@send -external getElementById: (dom, string) => option = "getElementById" - -let test = dom => { - let elem = dom->getElementById("haha") - switch elem { - | None => "None: Only when value is undefined" - | Some(_) => "Some: When value is not undefined or is null" - } -} -``` - -```js -function test(dom) { - var elem = dom.getElementById("haha"); - if (elem !== undefined) { - return "Some: When value is not undefined or is null"; - } else { - return "None: Only when value is undefined"; - } -} -``` - - - -Here, `Some` can include `null` values. - -The `@return` decorator can specify how `null` and `undefined` are handled. - -There are four versions of the decorator: - -1. `@return(nullable)` converts `null` and `undefined` to `None`. -2. `@return(null_to_opt)` converts `null` to `None`. -3. `@return(undefined_to_opt)` converts `undefined` to `None`. -4. `@return(identity)` has the same behaviour as omitting the decorator. It is rarely used, but introduced here for debugging purposes. - -Example with `@return(nullable)`: +### Example @@ -67,8 +23,8 @@ external getElementById: (dom, string) => option = "getElementById" let test = dom => { let elem = dom->getElementById("haha") switch elem { - | None => "None: When value is undefined or null" - | Some(_) => "Some: When value is not undefined and not null" + | None => 1 + | Some(_) => 2 } } ``` @@ -77,11 +33,15 @@ let test = dom => { function test(dom) { var elem = dom.getElementById("haha"); if (elem == null) { - return "None: When value is undefined or null"; + return 1; } else { - return "Some: When value is not undefined and not null"; + return 2; } } ``` + +### References + +* [Function Nullable Return Value Wrapping](/docs/manual/latest/bind-to-js-function#function-nullable-return-value-wrapping) \ No newline at end of file From c764884167c6a337e9f04883e691769ddfd3826b Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:49:49 +1100 Subject: [PATCH 51/61] Update scope decorator --- misc_docs/syntax/decorator_scope.mdx | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/misc_docs/syntax/decorator_scope.mdx b/misc_docs/syntax/decorator_scope.mdx index d354886a6..4a9f8af76 100644 --- a/misc_docs/syntax/decorator_scope.mdx +++ b/misc_docs/syntax/decorator_scope.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@scope` decorator is used with other decorators such as `@val` and `@module` to declare a parent scope for the binding. -For example: +### Example @@ -16,25 +16,15 @@ For example: @scope("Math") @val external floor: float => int = "floor" -@scope(("location", "origin")) @val -external originLength: string = "length" - -@module("MyModule") @scope("CONSTANTS") -external initialDays: int = "initialDays" - -Js.log(floor(3.4)) -Js.log(originLength) -Js.log(initialDays) +let result = floor(3.4) ``` ```js -var MyModule = require("MyModule") - -console.log(Math.floor(3.4)) -console.log(location.origin.length) -console.log(MyModule.CONSTANTS.initialDays) +var result = Math.floor(3.4); ``` -Note that the order of the decorators doesn't matter. \ No newline at end of file +### References + +* [Global Modules](/docs/manual/latest/bind-to-global-js-values#global-modules) \ No newline at end of file From 0be53130939f0ed4ff7e58e579c36011cc303601 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:55:11 +1100 Subject: [PATCH 52/61] Update send decorator --- misc_docs/syntax/decorator_send.mdx | 27 +++++++++------------------ 1 file changed, 9 insertions(+), 18 deletions(-) diff --git a/misc_docs/syntax/decorator_send.mdx b/misc_docs/syntax/decorator_send.mdx index 961f65362..bae452ce5 100644 --- a/misc_docs/syntax/decorator_send.mdx +++ b/misc_docs/syntax/decorator_send.mdx @@ -6,35 +6,26 @@ summary: "This is the `@send` decorator." category: "decorators" --- -The `@send` decorator is used to call a function on an object. +The `@send` decorator is used to bind to a method on an object. -For example: +### Example ```res -type element +type document +@bs.send external getElementById: (document, string) => Dom.element = "getElementById" +@bs.val external doc: document = "document" -@scope("document") @val -external createElement: string => element = "createElement" - -@send -external appendChild: (element, element) => element = "appendChild" - -let div = createElement("div") -let button = createElement("button") - -let _ = appendChild(div, button) +let el = getElementById(doc, "myId") ``` ```js -var div = document.createElement("div"); - -var button = document.createElement("button"); - -div.appendChild(button); +var el = document.getElementById("myId"); ``` +### References +* [Bind to JS Function](/docs/manual/latest/bind-to-js-function) \ No newline at end of file From 7598d8640ecb90599aa376d9f878602bec9eac04 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 15:58:26 +1100 Subject: [PATCH 53/61] Update string and int decorators --- misc_docs/syntax/decorator_int.mdx | 4 ++++ misc_docs/syntax/decorator_string.mdx | 6 +++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx index ec8cf84c3..07031a067 100644 --- a/misc_docs/syntax/decorator_int.mdx +++ b/misc_docs/syntax/decorator_int.mdx @@ -28,4 +28,8 @@ setStatus(2); +### References + +* [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) + diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx index 6594b98c5..1522e66ea 100644 --- a/misc_docs/syntax/decorator_string.mdx +++ b/misc_docs/syntax/decorator_string.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@string` decorator can be used with [polymorphic variants](/docs/manual/latest/polymorphic-variant) and the `@as` decorator on *externals* to modify the string values used for the variants in the compiled JavaScript. -For example: +### Example @@ -27,3 +27,7 @@ setStatus("NOT_STARTED"); ``` + +### References + +* [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) \ No newline at end of file From 3a779bfabb24fed35f953cd2d1bfb4ca0248bdac Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:00:13 +1100 Subject: [PATCH 54/61] Update unboxed --- misc_docs/syntax/decorator_unboxed.mdx | 35 +++++--------------------- 1 file changed, 6 insertions(+), 29 deletions(-) diff --git a/misc_docs/syntax/decorator_unboxed.mdx b/misc_docs/syntax/decorator_unboxed.mdx index 5efe495e0..4eb9c7c89 100644 --- a/misc_docs/syntax/decorator_unboxed.mdx +++ b/misc_docs/syntax/decorator_unboxed.mdx @@ -6,35 +6,10 @@ summary: "This is the `@unboxed` decorator." category: "decorators" --- -The `@unboxed` decorator provides a way to unwrap **variant** constructors that have a *single* argument, or **record** objects that have a *single* field. +The `@unboxed` decorator provides a way to unwrap **variant** constructors +that have a *single* argument, or **record** objects that have a *single* field. -For example, consider the following code: - - - -```res -type name = Name(string) -let studentName = Name("Joe") - -type greeting = {message: string} -let hi = {message: "hello!"} -``` - -```js -var studentName = /* Name */{ - _0: "Joe" -}; - -var hi = { - message: "hello!" -}; -``` - - - -When compiled to JavaScript, these values are represented as objects. - -If we now add the `@unboxed` decorator, the object wrappers are removed from the JavaScript output: +### Example @@ -55,4 +30,6 @@ var hi = "hello!"; -See the [Unboxed](/docs/manual/latest/unboxed) section for more details. +### References + +* [Unboxed](/docs/manual/latest/unboxed) \ No newline at end of file From 43e81dc117ceada31a02aa9dd2214a17a7118147 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:05:17 +1100 Subject: [PATCH 55/61] Update unwrap decorator --- misc_docs/syntax/decorator_unwrap.mdx | 33 ++++++++------------------- 1 file changed, 10 insertions(+), 23 deletions(-) diff --git a/misc_docs/syntax/decorator_unwrap.mdx b/misc_docs/syntax/decorator_unwrap.mdx index a488daadf..1b65d7737 100644 --- a/misc_docs/syntax/decorator_unwrap.mdx +++ b/misc_docs/syntax/decorator_unwrap.mdx @@ -6,24 +6,10 @@ summary: "This is the `@unwrap` decorator." category: "decorators" --- -The `@unwrap` decorator may be used when binding to external functions that accept multiple types for an argument. +The `@unwrap` decorator may be used when binding to external functions +that accept multiple types for an argument. -Consider the following JavaScript function: - -```js -function padLeft(padding, str) { - if (typeof padding === "number") { - return " ".repeat(padding) + str; - } - if (typeof padding === "string") { - return padding + str; - } - throw new Error("Expected padding to be number or string"); -} -``` -Note how `padding` can be either a number or a string. - -Here is how you'd bind to this function: +### Example @@ -33,16 +19,17 @@ Here is how you'd bind to this function: string ) => string = "padLeft"; -let _ = padLeft(#Int(7), "eleven"); -let _ = padLeft(#Str("7"), "eleven"); +let result1 = padLeft(#Int(7), "eleven"); +let result2 = padLeft(#Str("7"), "eleven"); ``` ```js -padLeft(7, "eleven"); - -padLeft("7", "eleven"); +var result1 = padLeft(7, "eleven"); +var result2 = padLeft("7", "eleven"); ``` -Review the JavaScript output and note how `@unwrap` simply unwraps the polymorphic variant constructor. +### References + +* [Modeling Polymorphic Function](/docs/manual/latest/bind-to-js-function#modeling-polymorphic-function) \ No newline at end of file From 1d029535d27bc3d068235653b934babd8f6266cf Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:08:42 +1100 Subject: [PATCH 56/61] Update val decorator --- misc_docs/syntax/decorator_val.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/misc_docs/syntax/decorator_val.mdx b/misc_docs/syntax/decorator_val.mdx index fa13595a5..71c9babbd 100644 --- a/misc_docs/syntax/decorator_val.mdx +++ b/misc_docs/syntax/decorator_val.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@val` decorator allows you to bind to JavaScript values that are on the global scope. -For example: +### Example @@ -29,5 +29,6 @@ var timeoutID = setTimeout(function (param) { -To access global values on another global object, such as `Date.now` or `location.origin.length` see the `@scope` decorator. +### References +* [Bind to Global JS Values](/docs/manual/latest/bind-to-global-js-values) From 9be40cfd4d053de592c8336a72bed6afa10ff33e Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:11:44 +1100 Subject: [PATCH 57/61] Update variadic decorator --- misc_docs/syntax/decorator_variadic.mdx | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/misc_docs/syntax/decorator_variadic.mdx b/misc_docs/syntax/decorator_variadic.mdx index 4e9dcc1ae..78bc14c2d 100644 --- a/misc_docs/syntax/decorator_variadic.mdx +++ b/misc_docs/syntax/decorator_variadic.mdx @@ -8,7 +8,7 @@ category: "decorators" The `@variadic` decorator is used to model JavaScript functions that take a variable number of arguments, where all arguments are of the same type. -For example: +### Example @@ -25,21 +25,6 @@ var result = Math.max(5, -2, 6, 1); -If your function has mandatory arguments, you can use the `@as` decorator to add them: +### References - - -```res -@val @variadic -external warn: (@as(404) _, @as("NOT_FOUND") _, array) => unit = "log" - -warn([]) -warn(["this", "page", "is", "not", "found"]) -``` - -```js -log(404, "NOT_FOUND"); -log(404, "NOT_FOUND", "this", "page", "is", "not", "found"); -``` - - +* [Variadic Function Arguments](/docs/manual/latest/bind-to-js-function#variadic-function-arguments) \ No newline at end of file From 5141b495ed11382c58cb19a0d18fbb0314ff48dc Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:24:39 +1100 Subject: [PATCH 58/61] Clean up, standardise, simplify --- misc_docs/syntax/decorator_as.mdx | 8 +------ misc_docs/syntax/decorator_deriving.mdx | 2 +- misc_docs/syntax/decorator_get.mdx | 24 ++++++--------------- misc_docs/syntax/decorator_get_index.mdx | 8 +------ misc_docs/syntax/decorator_inline.mdx | 2 +- misc_docs/syntax/decorator_int.mdx | 2 +- misc_docs/syntax/decorator_meth.mdx | 2 +- misc_docs/syntax/decorator_module.mdx | 2 +- misc_docs/syntax/decorator_new.mdx | 2 +- misc_docs/syntax/decorator_return.mdx | 3 +-- misc_docs/syntax/decorator_scope.mdx | 2 +- misc_docs/syntax/decorator_send.mdx | 2 +- misc_docs/syntax/decorator_set.mdx | 27 ++++++------------------ misc_docs/syntax/decorator_set_index.mdx | 8 +------ misc_docs/syntax/decorator_string.mdx | 2 +- misc_docs/syntax/decorator_unwrap.mdx | 2 +- 16 files changed, 27 insertions(+), 71 deletions(-) diff --git a/misc_docs/syntax/decorator_as.mdx b/misc_docs/syntax/decorator_as.mdx index 644be25ea..85eb5cd29 100644 --- a/misc_docs/syntax/decorator_as.mdx +++ b/misc_docs/syntax/decorator_as.mdx @@ -1,6 +1,6 @@ --- id: "as-decorator" -keywords: ["as", "decorator", "record", "field", "alias", "object"] +keywords: ["as", "decorator"] name: "@as" summary: "This is the `@as` decorator." category: "decorators" @@ -34,9 +34,3 @@ var action = { * [Constrain Arguments Better](/docs/manual/latest/bind-to-js-function#constrain-arguments-better) * [Fixed Arguments](/docs/manual/latest/bind-to-js-function#fixed-arguments) - -### Related - -* `@int` -* `@string` -* `@variadic` diff --git a/misc_docs/syntax/decorator_deriving.mdx b/misc_docs/syntax/decorator_deriving.mdx index 97dd92ce1..ef2a0954f 100644 --- a/misc_docs/syntax/decorator_deriving.mdx +++ b/misc_docs/syntax/decorator_deriving.mdx @@ -1,6 +1,6 @@ --- id: "deriving-decorator" -keywords: ["deriving", "decorator", "record"] +keywords: ["deriving", "decorator"] name: "@deriving" summary: "This is the `@deriving` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_get.mdx b/misc_docs/syntax/decorator_get.mdx index c5a572fe6..c3d69e230 100644 --- a/misc_docs/syntax/decorator_get.mdx +++ b/misc_docs/syntax/decorator_get.mdx @@ -1,6 +1,6 @@ --- id: "get-decorator" -keywords: ["get", "decorator", "property", "object", "bind"] +keywords: ["get", "decorator"] name: "@get" summary: "This is the `@get` decorator." category: "decorators" @@ -13,21 +13,15 @@ The `@get` decorator is used to bind to a property of an object. ```res -type element +type window +@bs.val external window: window = "window" +@bs.get external getName: window => string = "name" -@scope("document") @val -external createElement: string => element = "createElement" - -@get -external getScrollTop: element => unit = "scrollTop" - -let div = createElement("div") -let top = getScrollTop(div) +let name = getName(window) ``` ```js -var div = document.createElement("div") -var top = div.scrollTop +var name = window.name; ``` @@ -35,9 +29,3 @@ var top = div.scrollTop ### References - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) - -### Related - -- `@set` -- `@get_index` -- `@set_index` diff --git a/misc_docs/syntax/decorator_get_index.mdx b/misc_docs/syntax/decorator_get_index.mdx index 205b4be03..8eec67fed 100644 --- a/misc_docs/syntax/decorator_get_index.mdx +++ b/misc_docs/syntax/decorator_get_index.mdx @@ -1,6 +1,6 @@ --- id: "get-index-decorator" -keywords: ["get", "decorator", "array", "object", "index"] +keywords: ["get", "index", "decorator"] name: "@get_index" summary: "This is the `@get_index` decorator." category: "decorators" @@ -43,9 +43,3 @@ var value = o["y"]; ### References - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) - -### Related - -- `@get` -- `@set` -- `@set_index` diff --git a/misc_docs/syntax/decorator_inline.mdx b/misc_docs/syntax/decorator_inline.mdx index 4bdab6c34..5f630ae19 100644 --- a/misc_docs/syntax/decorator_inline.mdx +++ b/misc_docs/syntax/decorator_inline.mdx @@ -1,6 +1,6 @@ --- id: "inline-decorator" -keywords: ["inline", "decorator", "constant"] +keywords: ["inline", "decorator"] name: "@inline" summary: "This is the `@inline` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_int.mdx b/misc_docs/syntax/decorator_int.mdx index 07031a067..8cbd6d4ac 100644 --- a/misc_docs/syntax/decorator_int.mdx +++ b/misc_docs/syntax/decorator_int.mdx @@ -1,6 +1,6 @@ --- id: "int-decorator" -keywords: ["int", "decorator", "polymorphic", "variant", "as", "external"] +keywords: ["int", "decorator"] name: "@int" summary: "This is the `@int` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_meth.mdx b/misc_docs/syntax/decorator_meth.mdx index 2a054e1d0..306182d4e 100644 --- a/misc_docs/syntax/decorator_meth.mdx +++ b/misc_docs/syntax/decorator_meth.mdx @@ -1,6 +1,6 @@ --- id: "meth-decorator" -keywords: ["meth", "decorator", "object", "function"] +keywords: ["meth", "decorator"] name: "@meth" summary: "This is the `@meth` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_module.mdx b/misc_docs/syntax/decorator_module.mdx index 70bcf7cf0..5847a500a 100644 --- a/misc_docs/syntax/decorator_module.mdx +++ b/misc_docs/syntax/decorator_module.mdx @@ -1,6 +1,6 @@ --- id: "module-decorator" -keywords: ["module", "decorator", "import", "require", "bind"] +keywords: ["module", "decorator"] name: "@module" summary: "This is the `@module` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_new.mdx b/misc_docs/syntax/decorator_new.mdx index 6b57d5d5d..056a16fcd 100644 --- a/misc_docs/syntax/decorator_new.mdx +++ b/misc_docs/syntax/decorator_new.mdx @@ -1,6 +1,6 @@ --- id: "new-decorator" -keywords: ["new", "decorator", "object"] +keywords: ["new", "decorator"] name: "@new" summary: "This is the `@new` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_return.mdx b/misc_docs/syntax/decorator_return.mdx index 3f9337dca..3c5da1e31 100644 --- a/misc_docs/syntax/decorator_return.mdx +++ b/misc_docs/syntax/decorator_return.mdx @@ -1,6 +1,6 @@ --- id: "return-decorator" -keywords: ["return", "decorator", "null", "undefined"] +keywords: ["return", "decorator"] name: "@return" summary: "This is the `@return` decorator." category: "decorators" @@ -8,7 +8,6 @@ category: "decorators" The `@return` decorator is used to control how `null` and `undefined` values are converted to `option` types in ReScript. - ### Example diff --git a/misc_docs/syntax/decorator_scope.mdx b/misc_docs/syntax/decorator_scope.mdx index 4a9f8af76..548bd8cee 100644 --- a/misc_docs/syntax/decorator_scope.mdx +++ b/misc_docs/syntax/decorator_scope.mdx @@ -1,6 +1,6 @@ --- id: "scope-decorator" -keywords: ["scope", "decorator", "bind", "global"] +keywords: ["scope", "decorator"] name: "@scope" summary: "This is the `@scope` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_send.mdx b/misc_docs/syntax/decorator_send.mdx index bae452ce5..74ac8b1b3 100644 --- a/misc_docs/syntax/decorator_send.mdx +++ b/misc_docs/syntax/decorator_send.mdx @@ -1,6 +1,6 @@ --- id: "send-decorator" -keywords: ["send", "decorator", "object"] +keywords: ["send", "decorator"] name: "@send" summary: "This is the `@send` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_set.mdx b/misc_docs/syntax/decorator_set.mdx index 062aac0ed..ce2ff896b 100644 --- a/misc_docs/syntax/decorator_set.mdx +++ b/misc_docs/syntax/decorator_set.mdx @@ -1,6 +1,6 @@ --- id: "set-decorator" -keywords: ["set", "property", "object", "bind"] +keywords: ["set", "decorator"] name: "@set" summary: "This is the `@set` decorator." category: "decorators" @@ -8,27 +8,20 @@ category: "decorators" The `@set` decorator is used to set a property of an object. -For example: +### Example ```res -type element +type window +@bs.val external window: window = "window" +@bs.set external setName: (window, string) => unit = "name" -@scope("document") @val -external createElement: string => element = "createElement" - -@set -external setScrollTop: (element, int) => unit = "scrollTop" - -let div = createElement("div") -setScrollTop(div, 100) +setName(window, "MyWindow") ``` ```js -var div = document.createElement("div") - -div.scrollTop = 100 +window.name = "MyWindow"; ``` @@ -36,9 +29,3 @@ div.scrollTop = 100 ### References - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) - -### Related - -- `@get` -- `@set_index` -- `@get_index` diff --git a/misc_docs/syntax/decorator_set_index.mdx b/misc_docs/syntax/decorator_set_index.mdx index 3c1ca386b..47d27991a 100644 --- a/misc_docs/syntax/decorator_set_index.mdx +++ b/misc_docs/syntax/decorator_set_index.mdx @@ -1,6 +1,6 @@ --- id: "set-index-decorator" -keywords: ["set", "decorator", "array", "object", "index"] +keywords: ["set", "index", decorator"] name: "@set_index" summary: "This is the `@set_index` decorator." category: "decorators" @@ -43,9 +43,3 @@ var value = o["y"]; ### References - [Bind using Special `@bs` Getters & Setters](/docs/manual/latest/bind-to-js-object#bind-using-special-bs-getters--setters) - -### Related - -- `@get` -- `@set` -- `@get_index` diff --git a/misc_docs/syntax/decorator_string.mdx b/misc_docs/syntax/decorator_string.mdx index 1522e66ea..4b24e7b76 100644 --- a/misc_docs/syntax/decorator_string.mdx +++ b/misc_docs/syntax/decorator_string.mdx @@ -1,6 +1,6 @@ --- id: "string-decorator" -keywords: ["string", "decorator", "polymorphic", "variant", "as", "external"] +keywords: ["string", "decorator"] name: "@string" summary: "This is the `@string` decorator." category: "decorators" diff --git a/misc_docs/syntax/decorator_unwrap.mdx b/misc_docs/syntax/decorator_unwrap.mdx index 1b65d7737..89337556f 100644 --- a/misc_docs/syntax/decorator_unwrap.mdx +++ b/misc_docs/syntax/decorator_unwrap.mdx @@ -1,6 +1,6 @@ --- id: "unwrap-decorator" -keywords: ["unwrap", "decorator", "external"] +keywords: ["unwrap", "decorator"] name: "@unwrap" summary: "This is the `@unwrap` decorator." category: "decorators" From f0bc37560aa78fe75925fdf3cef020a2f314d41a Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:25:04 +1100 Subject: [PATCH 59/61] Update val decorator --- misc_docs/syntax/decorator_val.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_val.mdx b/misc_docs/syntax/decorator_val.mdx index 71c9babbd..396621b71 100644 --- a/misc_docs/syntax/decorator_val.mdx +++ b/misc_docs/syntax/decorator_val.mdx @@ -1,6 +1,6 @@ --- id: "val-decorator" -keywords: ["val", "decorator", "bind", "global"] +keywords: ["val", "decorator"] name: "@val" summary: "This is the `@val` decorator." category: "decorators" From 97ddb3a0fa1d4623dc965e9257915662989eacfe Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 16:53:36 +1100 Subject: [PATCH 60/61] Add obj decorator --- misc_docs/syntax/decorator_obj.mdx | 35 ++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 misc_docs/syntax/decorator_obj.mdx diff --git a/misc_docs/syntax/decorator_obj.mdx b/misc_docs/syntax/decorator_obj.mdx new file mode 100644 index 000000000..ae6e14d39 --- /dev/null +++ b/misc_docs/syntax/decorator_obj.mdx @@ -0,0 +1,35 @@ +--- +id: "obj-decorator" +keywords: ["obj", "decorator"] +name: "@obj" +summary: "This is the `@obj` decorator." +category: "decorators" +--- + +The `@obj` decorator is used to create functions that return JavaScript objects +with properties that match the function's parameter labels. + +### Example + + + +```res +@bs.obj +external action: (~name: string, unit) => _ = "" + +let helloAction = action(~name="Hello") +``` + +```js +function helloAction(param) { + return { + name: "Hello", + } +} +``` + + + +### References + +* [Convert External into JS Object Creation Function](/docs/manual/latest/generate-converters-accessors#convert-external-into-js-object-creation-function) \ No newline at end of file From f8b7a7820c2e1bd414769da84c594f63fce46489 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Sat, 9 Jan 2021 17:03:21 +1100 Subject: [PATCH 61/61] Fix deriving typo --- misc_docs/syntax/decorator_deriving.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/decorator_deriving.mdx b/misc_docs/syntax/decorator_deriving.mdx index ef2a0954f..a686a3e86 100644 --- a/misc_docs/syntax/decorator_deriving.mdx +++ b/misc_docs/syntax/decorator_deriving.mdx @@ -8,7 +8,7 @@ category: "decorators" When the `@deriving` decorator is applied to a **record** type, it expands the type into a factory function plus a set of -getter/setter functions for it's fields. +getter/setter functions for its fields. > Note that this is an outdated decorator and you may no longer need to use it. > See [Convert Record Type to Abstract Record](/docs/manual/latest/generate-converters-accessors#convert-record-type-to-abstract-record) for more details.