From d55ae0fe8028f51e9661bdc28dad28cdc994c686 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 11:05:28 +1000 Subject: [PATCH 01/11] Add Syntax Lookup Extension Points --- misc_docs/syntax/extension_debugger.mdx | 32 ++++++++++++++ .../syntax/extension_embed_raw_expression.mdx | 34 +++++++++++++++ .../syntax/extension_embed_raw_top_level.mdx | 43 +++++++++++++++++++ misc_docs/syntax/extension_identity.mdx | 31 +++++++++++++ .../syntax/extension_regular_expression.mdx | 29 +++++++++++++ src/SyntaxLookup.mjs | 17 +++++--- src/SyntaxLookup.res | 5 ++- 7 files changed, 184 insertions(+), 7 deletions(-) create mode 100644 misc_docs/syntax/extension_debugger.mdx create mode 100644 misc_docs/syntax/extension_embed_raw_expression.mdx create mode 100644 misc_docs/syntax/extension_embed_raw_top_level.mdx create mode 100644 misc_docs/syntax/extension_identity.mdx create mode 100644 misc_docs/syntax/extension_regular_expression.mdx diff --git a/misc_docs/syntax/extension_debugger.mdx b/misc_docs/syntax/extension_debugger.mdx new file mode 100644 index 000000000..ca745a8e4 --- /dev/null +++ b/misc_docs/syntax/extension_debugger.mdx @@ -0,0 +1,32 @@ +--- +id: "debugger" +keywords: ["javascript", "embed", "raw", "debugger"] +name: "%debugger" +summary: "This is the `debugger` extension point." +category: "extensionpoints" +--- + +`%debugger` is used to insert a JavaScript `debugger` statement. + + + +```res +let f = (x, y) => { + %debugger + x + y +} +``` + +```js +function f(x, y) { + debugger; + return (x + y) | 0; +} +``` + + + +### References + +* [Embed Raw JavaScript: Debugger](/docs/manual/latest/embed-raw-javascript#debugger) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) diff --git a/misc_docs/syntax/extension_embed_raw_expression.mdx b/misc_docs/syntax/extension_embed_raw_expression.mdx new file mode 100644 index 000000000..9039610dc --- /dev/null +++ b/misc_docs/syntax/extension_embed_raw_expression.mdx @@ -0,0 +1,34 @@ +--- +id: "embed-raw-expression" +keywords: ["javascript", "embed", "raw", "expression"] +name: "%raw" +summary: "This is the `embed JavaScript expression` extension point." +category: "extensionpoints" +--- + +`%raw` is used to embed JavaScript expressions. + + + +```res +let canUseCanvas: unit => bool = %raw(` + function canUseCanvas() { + return !!document.createElement('canvas').getContext; + } +`) +``` + +```js +var canUseCanvas = function canUseCanvas() { + return !!document.createElement("canvas").getContext; +}; +``` + + + +See `%%raw` for embedding top level blocks of JavaScript code rather than expressions. + +### References + +* [Embed Raw JavaScript](/docs/manual/latest/embed-raw-javascript) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) diff --git a/misc_docs/syntax/extension_embed_raw_top_level.mdx b/misc_docs/syntax/extension_embed_raw_top_level.mdx new file mode 100644 index 000000000..79a89cc81 --- /dev/null +++ b/misc_docs/syntax/extension_embed_raw_top_level.mdx @@ -0,0 +1,43 @@ +--- +id: "embed-raw-top-level" +keywords: ["javascript", "embed", "raw"] +name: "%%raw" +summary: "This is the `embed top level JavaScript` extension point." +category: "extensionpoints" +--- + +`%%raw` is used to embed top level JavaScript code. + + + +```res +%%raw(` + const message = "hello"; + + function greet(m) { + console.log(m) + } + + greet(message) +`) +``` + +```js +const message = "hello"; + +function greet(m) { + console.log(m); +} + +greet(message); +``` + + + +See `%raw` for embedding JavaScript expressions rather than top level blocks of code. + +### References + +* [Embed Raw JavaScript](/docs/manual/latest/embed-raw-javascript) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) +* [Converting from JS](/docs/manual/latest/converting-from-js) diff --git a/misc_docs/syntax/extension_identity.mdx b/misc_docs/syntax/extension_identity.mdx new file mode 100644 index 000000000..263efdcce --- /dev/null +++ b/misc_docs/syntax/extension_identity.mdx @@ -0,0 +1,31 @@ +--- +id: "identity" +keywords: ["identity", "external", "type", "convert"] +name: "%identity" +summary: "This is the `identity` extension point." +category: "extensionpoints" +--- + +`%identity` is used with `external` to convert a value from one type to another type. + + + +```res +external convertToFloat: int => float = "%identity" +let age = 10 +let gpa = 2.1 +. convertToFloat(age) +``` + +```js +var gpa = 2.1 + 10; +var age = 10; +``` + + + +### References + +* [Type Escape Hatch](/docs/manual/latest/type#type-escape-hatch) +* [Dangerous Type Cast](/docs/manual/latest/interop-cheatsheet#dangerous-type-cast) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) + diff --git a/misc_docs/syntax/extension_regular_expression.mdx b/misc_docs/syntax/extension_regular_expression.mdx new file mode 100644 index 000000000..10c620864 --- /dev/null +++ b/misc_docs/syntax/extension_regular_expression.mdx @@ -0,0 +1,29 @@ +--- +id: "regular-expression" +keywords: ["regular", "expression", "re"] +name: "%re" +summary: "This is the `regular expression` extension point." +category: "extensionpoints" +--- + +`%re` is used to insert JavaScript regular expressions. + + + +```res +let regex = %re("/^hello/") +let result = regex->Js.Re.test_("hello world") +``` + +```js +var regex = /^hello/; +var result = regex.test("hello world"); +``` + + + +### References + +* [Regular Expressions](/docs/manual/latest/primitive-types#regular-expression) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) +* [Js.Re API](/docs/manual/latest/api/js/re) diff --git a/src/SyntaxLookup.mjs b/src/SyntaxLookup.mjs index c098d7610..27c211ebf 100644 --- a/src/SyntaxLookup.mjs +++ b/src/SyntaxLookup.mjs @@ -30,9 +30,11 @@ function toString(t) { return "Operators"; case /* LanguageConstructs */2 : return "Language Constructs"; - case /* SpecialValues */3 : + case /* ExtensionPoints */3 : + return "Extension Points"; + case /* SpecialValues */4 : return "Special Values"; - case /* Other */4 : + case /* Other */5 : return "Other"; } @@ -42,14 +44,16 @@ function fromString(s) { switch (s) { case "decorators" : return /* Decorators */0; + case "extensionpoints" : + return /* ExtensionPoints */3; case "languageconstructs" : return /* LanguageConstructs */2; case "operators" : return /* Operators */1; case "specialvalues" : - return /* SpecialValues */3; + return /* SpecialValues */4; default: - return /* Other */4; + return /* Other */5; } } @@ -244,8 +248,9 @@ function SyntaxLookup(Props) { /* Decorators */0, /* Operators */1, /* LanguageConstructs */2, - /* SpecialValues */3, - /* Other */4 + /* ExtensionPoints */3, + /* SpecialValues */4, + /* Other */5 ], (function (cat) { return [ toString(cat), diff --git a/src/SyntaxLookup.res b/src/SyntaxLookup.res index f04f44d93..27f77c7ee 100644 --- a/src/SyntaxLookup.res +++ b/src/SyntaxLookup.res @@ -31,12 +31,13 @@ let requireSyntaxFile: string => MdxComp.t = %raw(` `) module Category = { - type t = Decorators | Operators | LanguageConstructs | SpecialValues | Other + type t = Decorators | Operators | LanguageConstructs | ExtensionPoints | SpecialValues | Other let toString = t => switch t { | Decorators => "Decorators" | Operators => "Operators" + | ExtensionPoints => "Extension Points" | LanguageConstructs => "Language Constructs" | SpecialValues => "Special Values" | Other => "Other" @@ -48,6 +49,7 @@ module Category = { | "specialvalues" => SpecialValues | "operators" => Operators | "languageconstructs" => LanguageConstructs + | "extensionpoints" => ExtensionPoints | _ => Other } } @@ -241,6 +243,7 @@ let make = () => { Decorators, Operators, LanguageConstructs, + ExtensionPoints, SpecialValues, Other, ]->Belt.Array.map(cat => { From 61b52a42db581a9ffd29557649a2a8d6121d76b8 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 11:33:33 +1000 Subject: [PATCH 02/11] Add Syntax Lookup Private Let Binding --- misc_docs/syntax/extension_private_let.mdx | 43 ++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 misc_docs/syntax/extension_private_let.mdx diff --git a/misc_docs/syntax/extension_private_let.mdx b/misc_docs/syntax/extension_private_let.mdx new file mode 100644 index 000000000..540b9d214 --- /dev/null +++ b/misc_docs/syntax/extension_private_let.mdx @@ -0,0 +1,43 @@ +--- +id: "private-let" +keywords: ["private", "let"] +name: "%%private" +summary: "This is the `private let binding` extension point." +category: "extensionpoints" +--- + +`%%private` is used to make let bindings private. + + + +```res +module Calc = { + %%private(let mult = (x, y) => x * y) + + let double = x => mult(x, 2) + let triple = x => mult(x, 3) +} +``` + +```js +function $$double(x) { + return x << 1; +} + +function triple(x) { + return Math.imul(x, 3); +} + +var Calc = { + $$double: $$double, + triple: triple, +}; +``` + + + +### References + +* [Private Let Bindings](/docs/manual/latest/let-binding#private-let-bindings) +* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point) + From 8e23def08f0ca4afdfc1b679194f2404fbc59474 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:25:15 +1000 Subject: [PATCH 03/11] Rename Syntax Lookup Raw JS --- ...mbed_raw_expression.mdx => extension_raw_expression.mdx} | 6 +++--- ..._embed_raw_top_level.mdx => extension_raw_top_level.mdx} | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) rename misc_docs/syntax/{extension_embed_raw_expression.mdx => extension_raw_expression.mdx} (81%) rename misc_docs/syntax/{extension_embed_raw_top_level.mdx => extension_raw_top_level.mdx} (83%) diff --git a/misc_docs/syntax/extension_embed_raw_expression.mdx b/misc_docs/syntax/extension_raw_expression.mdx similarity index 81% rename from misc_docs/syntax/extension_embed_raw_expression.mdx rename to misc_docs/syntax/extension_raw_expression.mdx index 9039610dc..c8d31cb37 100644 --- a/misc_docs/syntax/extension_embed_raw_expression.mdx +++ b/misc_docs/syntax/extension_raw_expression.mdx @@ -1,8 +1,8 @@ --- -id: "embed-raw-expression" -keywords: ["javascript", "embed", "raw", "expression"] +id: "raw-expression" +keywords: ["javascript", "raw", "expression"] name: "%raw" -summary: "This is the `embed JavaScript expression` extension point." +summary: "This is the `JavaScript expression` extension point." category: "extensionpoints" --- diff --git a/misc_docs/syntax/extension_embed_raw_top_level.mdx b/misc_docs/syntax/extension_raw_top_level.mdx similarity index 83% rename from misc_docs/syntax/extension_embed_raw_top_level.mdx rename to misc_docs/syntax/extension_raw_top_level.mdx index 79a89cc81..f692e4050 100644 --- a/misc_docs/syntax/extension_embed_raw_top_level.mdx +++ b/misc_docs/syntax/extension_raw_top_level.mdx @@ -1,8 +1,8 @@ --- -id: "embed-raw-top-level" -keywords: ["javascript", "embed", "raw"] +id: "raw-top-level" +keywords: ["javascript", "raw"] name: "%%raw" -summary: "This is the `embed top level JavaScript` extension point." +summary: "This is the `top level JavaScript` extension point." category: "extensionpoints" --- From 56118f8f8ce91069297131a4c7b6072d83974a39 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:43:48 +1000 Subject: [PATCH 04/11] Add top level raw import example --- misc_docs/syntax/extension_raw_top_level.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/misc_docs/syntax/extension_raw_top_level.mdx b/misc_docs/syntax/extension_raw_top_level.mdx index f692e4050..38f975477 100644 --- a/misc_docs/syntax/extension_raw_top_level.mdx +++ b/misc_docs/syntax/extension_raw_top_level.mdx @@ -34,6 +34,20 @@ greet(message); +It's also very useful to do imports with side-effects like this: + + + +```res +%%raw(`import "main.css"`) +``` + +```js +import "main.css"; +``` + + + See `%raw` for embedding JavaScript expressions rather than top level blocks of code. ### References From f367fa339f76ff93f27c0f6fbbb8936ed838aa1f Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:45:17 +1000 Subject: [PATCH 05/11] Update misc_docs/syntax/extension_identity.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_identity.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_identity.mdx b/misc_docs/syntax/extension_identity.mdx index 263efdcce..635990ef0 100644 --- a/misc_docs/syntax/extension_identity.mdx +++ b/misc_docs/syntax/extension_identity.mdx @@ -6,7 +6,7 @@ summary: "This is the `identity` extension point." category: "extensionpoints" --- -`%identity` is used with `external` to convert a value from one type to another type. +`%identity` is used with `external` to do an **unsafe conversion** of a value from one type to another type. From 2ac8a133a03f731d80d16538e57a6a21d751b034 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:47:06 +1000 Subject: [PATCH 06/11] Update misc_docs/syntax/extension_regular_expression.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_regular_expression.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_regular_expression.mdx b/misc_docs/syntax/extension_regular_expression.mdx index 10c620864..eed9f0c77 100644 --- a/misc_docs/syntax/extension_regular_expression.mdx +++ b/misc_docs/syntax/extension_regular_expression.mdx @@ -6,7 +6,7 @@ summary: "This is the `regular expression` extension point." category: "extensionpoints" --- -`%re` is used to insert JavaScript regular expressions. +`%re` is used to create JavaScript regular expressions. From 1eedc0bb15fca1fc24fb47f0f87bb77f88cb0f52 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:56:35 +1000 Subject: [PATCH 07/11] Update misc_docs/syntax/extension_raw_top_level.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_raw_top_level.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_raw_top_level.mdx b/misc_docs/syntax/extension_raw_top_level.mdx index 38f975477..036cc786c 100644 --- a/misc_docs/syntax/extension_raw_top_level.mdx +++ b/misc_docs/syntax/extension_raw_top_level.mdx @@ -2,7 +2,7 @@ id: "raw-top-level" keywords: ["javascript", "raw"] name: "%%raw" -summary: "This is the `top level JavaScript` extension point." +summary: "This is the `raw top level expression` extension point." category: "extensionpoints" --- From 8af00e2d21a71eeb18e15d407adcc17bf67b48bb Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:56:44 +1000 Subject: [PATCH 08/11] Update misc_docs/syntax/extension_raw_top_level.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_raw_top_level.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_raw_top_level.mdx b/misc_docs/syntax/extension_raw_top_level.mdx index 036cc786c..c957707dc 100644 --- a/misc_docs/syntax/extension_raw_top_level.mdx +++ b/misc_docs/syntax/extension_raw_top_level.mdx @@ -1,5 +1,5 @@ --- -id: "raw-top-level" +id: "raw-top-level-expression" keywords: ["javascript", "raw"] name: "%%raw" summary: "This is the `raw top level expression` extension point." From cd0318e212b5e779cbb9b02e9e1d8f532656e7a6 Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:57:00 +1000 Subject: [PATCH 09/11] Update misc_docs/syntax/extension_raw_expression.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_raw_expression.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_raw_expression.mdx b/misc_docs/syntax/extension_raw_expression.mdx index c8d31cb37..c405c32ce 100644 --- a/misc_docs/syntax/extension_raw_expression.mdx +++ b/misc_docs/syntax/extension_raw_expression.mdx @@ -6,7 +6,7 @@ summary: "This is the `JavaScript expression` extension point." category: "extensionpoints" --- -`%raw` is used to embed JavaScript expressions. +`%raw` is used to embed "raw JavaScript expressions". From 16eed95f6645fc2d1df36ee57de66a5a8fb7c5cf Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 17:57:10 +1000 Subject: [PATCH 10/11] Update misc_docs/syntax/extension_raw_expression.mdx Co-authored-by: Patrick Ecker --- misc_docs/syntax/extension_raw_expression.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/misc_docs/syntax/extension_raw_expression.mdx b/misc_docs/syntax/extension_raw_expression.mdx index c405c32ce..dd263b8c8 100644 --- a/misc_docs/syntax/extension_raw_expression.mdx +++ b/misc_docs/syntax/extension_raw_expression.mdx @@ -2,7 +2,7 @@ id: "raw-expression" keywords: ["javascript", "raw", "expression"] name: "%raw" -summary: "This is the `JavaScript expression` extension point." +summary: "This is the `raw expression` extension point." category: "extensionpoints" --- From f2ca3207d2ff3c04b2d7c3c7cdfd2ae9c9d158dd Mon Sep 17 00:00:00 2001 From: Kevan Stannard Date: Thu, 9 Sep 2021 18:08:32 +1000 Subject: [PATCH 11/11] Rename raw top level expression file --- ...n_raw_top_level.mdx => extension_raw_top_level_expression.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename misc_docs/syntax/{extension_raw_top_level.mdx => extension_raw_top_level_expression.mdx} (100%) diff --git a/misc_docs/syntax/extension_raw_top_level.mdx b/misc_docs/syntax/extension_raw_top_level_expression.mdx similarity index 100% rename from misc_docs/syntax/extension_raw_top_level.mdx rename to misc_docs/syntax/extension_raw_top_level_expression.mdx