document tagged templates from rescript-lang/rescript#6250

Author: tsnobip

misc_docs/syntax/decorator_taggedTemplate.mdx

@@ -0,0 +1,35 @@
+---
+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
+type res 
+@module("bun") @taggedTemplate 
+external sh: (array<string>, array<string>) => promise<res> = "$"
+
+let filename = "index.res"
+let res = await sh`ls ${filename}`
+```
+
+```js 
+import * as $$Bun from "bun";
+var filename = "index.res"
+var res = await $$Bun.$`ls ${filename}` 
+```
+
+</CodeTab>
+
+### References
+
+* [Tagged template functions](/docs/manual/latest/bind-to-js-function#tagged_template-functions)

pages/docs/manual/latest/bind-to-js-function.mdx

@@ -421,3 +421,34 @@ 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.
+All you need to do is defining a binding to a function that has 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
+type res 
+@module("bun") @taggedTemplate 
+external sh: (array<string>, array<string>) => promise<res> = "$"
+
+let filename = "index.res"
+let res = await sh`ls ${filename}`
+```
+
+```js 
+import * as $$Bun from "bun";
+var filename = "index.res"
+var res = 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.

pages/docs/manual/latest/interop-cheatsheet.mdx

@@ -38,6 +38,7 @@ This is a glossary with examples. All the features are described by later pages.
 - [`@uncurry`](bind-to-js-function#extra-solution)
 - [`@unwrap`](bind-to-js-function#trick-2-polymorphic-variant--bsunwrap)
 - [`@val`](bind-to-global-js-values#global-modules)
+- [`@taggedTemplate`](bind-to-js-function#tagged_template-functions)
 
 - [`@deprecated`](attribute#usage)
 - [`genType`](https://github.com/reason-association/genType)
@@ -193,6 +194,27 @@ external join: array<string> => string = "join"
 
 </CodeTab>
 
+### Tagged template functions
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+type res 
+@module("bun") @taggedTemplate 
+external sh: (array<string>, array<string>) => promise<res> = "$"
+
+let filename = "index.res"
+let res = await sh`ls ${filename}`
+```
+
+```js 
+import * as $$Bun from "bun";
+var filename = "index.res"
+var res = await $$Bun.$`ls ${filename}` 
+```
+
+</CodeTab>
+
 ### Polymorphic Function
 
 <CodeTab labels={["ReScript", "JS Output"]}>

pages/docs/manual/latest/overview.mdx

@@ -34,12 +34,13 @@ canonical: "/docs/manual/latest/overview"
 
 ### String & Character
 
-| JavaScript                | ReScript              |
-| --------------------------| --------------------- |
-| `"Hello world!"`          | Same                  |
-| `'Hello world!'`          | Strings must use `"`  |
-| `"hello " + "world"`      | `"hello " ++ "world"` |
-| `` `hello ${message}` ``  | Same                  |
+| JavaScript                    | ReScript              |
+| ----------------------------- | --------------------- |
+| `"Hello world!"`              | Same                  |
+| `'Hello world!'`              | Strings must use `"`  |
+| `"hello " + "world"`          | `"hello " ++ "world"` |
+| `` `hello ${message}` ``      | Same                  |
+| `` sql`select ${fnName};` ``  | Same                  |
 
 ### Boolean