Merge pull request #803 from tsnobip/tagged_templates

Document tagged templates

Author: fhammerschmidt

compilers/package-lock.json

@@ -6,9 +6,11 @@
   "license": "MIT",
   "dependencies": {
     "@rescript/core": "^0.6.0",
+    "@rescript/react": "^0.12.0",
     "rescript-1000": "npm:rescript@10.0.0",
     "rescript-1010": "npm:rescript@10.1.0",
     "rescript-1100": "npm:rescript@11.0.0",
+    "rescript-1110": "npm:rescript@11.1.0-rc.1",
     "rescript-820": "npm:bs-platform@8.2.0",
     "rescript-902": "npm:bs-platform@9.0.2",
     "rescript-912": "npm:rescript@9.1.2"

compilers/package.json

@@ -1,11 +1,13 @@
 {
   "name": "dummy",
+  "jsx": { "version": 4 },
   "sources": {
     "dir": "dummy",
     "subdirs": true
   },
   "bs-dependencies": [
-    "@rescript/core"
+    "@rescript/core",
+    "@rescript/react"
   ],
   "bsc-flags": [
     "-open RescriptCore"

compilers/rescript.json

@@ -28,6 +28,7 @@
     "lazy-values",
     "promise",
     "async-await",
+    "tagged-templates",
     "module",
     "import-export",
     "attribute",

data/sidebar_manual_latest.json

@@ -0,0 +1,36 @@
+---
+id: "taggedTemplate-decorator"
+keywords: ["taggedTemplate", "tagged", "template", "decorator"]
+name: "@taggedTemplate"
+summary: "This is the `@taggedTemplate` decorator."
+category: "decorators"
+---
+**Since 11.1**
+
+The `@taggedTemplate` decorator is used to bind to JavaScript tag functions.
+
+### Example
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+// see https://bun.sh/docs/runtime/shell
+type result = {exitCode: int}
+@module("bun") @taggedTemplate
+external sh: (array<string>, array<string>) => promise<result> = "$"
+
+let filename = "index.res"
+let result = await sh`ls ${filename}`
+```
+
+```js 
+import * as $$Bun from "bun";
+var filename = "index.res";
+var result = await $$Bun.$`ls ${filename}`;
+```
+
+</CodeTab>
+
+### References
+
+* [Tagged template functions](/docs/manual/latest/bind-to-js-function#tagged_template-functions)

misc_docs/syntax/decorator_taggedTemplate.mdx

@@ -26,7 +26,8 @@
     "gentype": "^3.44.0",
     "glob": "^7.1.4",
     "gray-matter": "^4.0.3",
-    "highlight.js": "^10.5.0",
+    "highlight.js": "^11.9.0",
+    "highlightjs-rescript": "^0.1.2",
     "lz-string": "^1.4.4",
     "next": "^13.1.1",
     "next-mdx-remote": "^4.4.1",
@@ -42,8 +43,8 @@
     "remark-parse": "^10.0.2",
     "remark-slug": "^5.1.2",
     "remark-stringify": "^7.0.3",
-    "rescript": "^11.0.0",
     "request": "^2.88.0",
+    "rescript": "^11.0.0",
     "stringify-object": "^3.3.0",
     "unified": "^8.4.0"
   },

package-lock.json

@@ -421,3 +421,39 @@ Currently 4 directives are supported: `null_to_opt`, `undefined_to_opt`, `nullab
 <!-- When the return type is unit: the compiler will append its return value with an OCaml unit literal to make sure it does return unit. Its main purpose is to make the user consume FFI in idiomatic OCaml code, the cost is very very small and the compiler will do smart optimizations to remove it when the returned value is not used (mostly likely). -->
 
 `identity` will make sure that compiler will do nothing about the returned value. It is rarely used, but introduced here for debugging purpose.
+
+## Tagged template functions
+
+**Since 11.1**
+
+**Experimental** You can easily bind to [JS tagged template functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
+Tag functions in JS expect as input an array of strings and variadic parameters for the arguments of the interpolation.
+To bind to those functions in ReScript, the binding signature must have two arrays as arguments,
+the first one being an array of strings and the second can be an array of anything.
+You add the `@taggedTemplate` annotation and you're good to go!
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+// see https://bun.sh/docs/runtime/shell
+type result = {exitCode: int}
+@module("bun") @taggedTemplate
+external sh: (array<string>, array<string>) => promise<result> = "$"
+
+let filename = "index.res"
+let result = await sh`ls ${filename}`
+```
+
+```js 
+import * as $$Bun from "bun";
+var filename = "index.res";
+var result = await $$Bun.$`ls ${filename}`;
+```
+
+</CodeTab>
+
+Notice that it gets compiled to tagged template literals in JS, which allows
+to use JS tools that only work on the literals and not by calling directly the tag function.
+
+There are plenty of useful JS tools you can bind to, like [`gql`](https://github.com/apollographql/graphql-tag),
+[`sql`](https://github.com/porsager/postgres), [`css`](https://github.com/mayank99/ecsstatic) and a lot others!