Syntax Lookup: Extension Points (#444)

* Add Syntax Lookup Extension Points

* Add Syntax Lookup Private Let Binding

* Rename Syntax Lookup Raw JS

* Add top level raw import example

* Update misc_docs/syntax/extension_identity.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Update misc_docs/syntax/extension_regular_expression.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Update misc_docs/syntax/extension_raw_top_level.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Update misc_docs/syntax/extension_raw_top_level.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Update misc_docs/syntax/extension_raw_expression.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Update misc_docs/syntax/extension_raw_expression.mdx

Co-authored-by: Patrick Ecker <[email protected]>

* Rename raw top level expression file

Co-authored-by: Patrick Ecker <[email protected]>

Author: kevanstannard

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.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let f = (x, y) => {
+  %debugger
+  x + y
+}
+```
+
+```js
+function f(x, y) {
+  debugger;
+  return (x + y) | 0;
+}
+```
+
+</CodeTab>
+
+### References
+
+* [Embed Raw JavaScript: Debugger](/docs/manual/latest/embed-raw-javascript#debugger)
+* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point)

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 do an **unsafe conversion** of a value from one type to another type.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+external convertToFloat: int => float = "%identity"
+let age = 10
+let gpa = 2.1 +. convertToFloat(age)
+```
+
+```js
+var gpa = 2.1 + 10;
+var age = 10;
+```
+
+</CodeTab>
+
+### 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)
+

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.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```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,
+};
+```
+
+</CodeTab>
+
+### References
+
+* [Private Let Bindings](/docs/manual/latest/let-binding#private-let-bindings)
+* [Extension Point Attributes](/docs/manual/latest/attribute#extension-point)
+

misc_docs/syntax/extension_raw_expression.mdx

@@ -0,0 +1,34 @@
+---
+id: "raw-expression"
+keywords: ["javascript", "raw", "expression"]
+name: "%raw"
+summary: "This is the `raw expression` extension point."
+category: "extensionpoints"
+---
+
+`%raw` is used to embed "raw JavaScript expressions".
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let canUseCanvas: unit => bool = %raw(`
+  function canUseCanvas() {
+    return !!document.createElement('canvas').getContext;
+  }
+`)
+```
+
+```js
+var canUseCanvas = function canUseCanvas() {
+  return !!document.createElement("canvas").getContext;
+};
+```
+
+</CodeTab>
+
+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)

misc_docs/syntax/extension_raw_top_level_expression.mdx

@@ -0,0 +1,57 @@
+---
+id: "raw-top-level-expression"
+keywords: ["javascript", "raw"]
+name: "%%raw"
+summary: "This is the `raw top level expression` extension point."
+category: "extensionpoints"
+---
+
+`%%raw` is used to embed top level JavaScript code.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```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);
+```
+
+</CodeTab>
+
+It's also very useful to do imports with side-effects like this:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+%%raw(`import "main.css"`)
+```
+
+```js
+import "main.css";
+```
+
+</CodeTab>
+
+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)

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 create JavaScript regular expressions.
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+let regex = %re("/^hello/")
+let result = regex->Js.Re.test_("hello world")
+```
+
+```js
+var regex = /^hello/;
+var result = regex.test("hello world");
+```
+
+</CodeTab>
+
+### 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)

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),

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 => {