feature: support using unified as a template tag.

unifiedjs · Nov 4, 2018 · 0bfa080 · 0bfa080
1 parent e0705f4
commit 0bfa080
Show file tree

Hide file tree

Showing 4 changed files with 234 additions and 0 deletions.
diff --git a/index.js b/index.js
@@ -66,6 +66,8 @@ function unified() {
   processor.runSync = runSync
   processor.process = process
   processor.processSync = processSync
+  processor.templateTag = templateTag
+  processor.templateTagSync = templateTagSync
 
   // Expose.
   return processor
@@ -397,6 +399,16 @@ function unified() {
       bail(err)
     }
   }
+
+  // fold template expression into a string that can be passed to `process`
+  function templateTag() {
+    return process(String.raw.apply(null, arguments))
+  }
+
+  // fold template expression into a string that can be passed to `processSync`
+  function templateTagSync() {
+    return processSync(String.raw.apply(null, arguments))
+  }
 }
 
 // Check if `func` is a constructor.

diff --git a/readme.md b/readme.md
@@ -693,6 +693,105 @@ Yields:
 </html>
 ```
 
+### `processor.templateTag(strings[, ...keys])`
+
+Process the given template string as configured on the processor. The process invokes `process` internally.
+
+###### Parameters
+
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates>
+
+###### Returns
+
+[`Promise`][promise].  Rejected with an error or resolved with the resulting file.
+
+###### Example
+
+The below example shows how the `process` function can be used to process a
+[file][] whether plugins are asynchronous or not with a callback.
+
+```js
+var unified = require('unified')
+var parse = require('remark-parse')
+var stringify = require('remark-stringify')
+var github = require('remark-github')
+var report = require('vfile-reporter')
+
+var md = unified()
+  .use(parse)
+  .use(github)
+  .use(stringify)
+  .templateTag
+
+md`@mention`
+  .then(function(file) {
+    console.error(file)
+    console.log(String(file))
+  })
+  .catch(function (err) {
+    console.error(report(err))
+  })
+```
+
+Yields:
+
+```markdown
+no issues found
+[**@mention**](https://github.com/blog/821)
+```
+
+
+### `processor.templateTagSync(strings[, ...keys])`
+
+Process the given template string as configured on the processor. The process invokes `processSync` internally.
+
+###### Parameters
+
+<https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates>
+
+###### Returns
+
+[`VFile`][file] — Virtual file with modified [`contents`][vfile-contents].
+
+###### Example
+
+The below example shows how the `templateTagSync` function can be used to process a
+[file][] if all plugins are known to be synchronous.
+
+```js
+var unified = require('unified')
+var markdown = require('remark-parse')
+var remark2rehype = require('remark-rehype')
+var doc = require('rehype-document')
+var format = require('rehype-format')
+var html = require('rehype-stringify')
+
+var html = unified()
+  .use(markdown)
+  .use(remark2rehype)
+  .use(doc)
+  .use(format)
+  .use(html)
+  .templateTagSync
+
+console.log(html`# Hello world!`.toString())
+```
+
+Yields:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+  </head>
+  <body>
+    <h1>Hello world!</h1>
+  </body>
+</html>
+```
+
 ### `processor.data(key[, value])`
 
 Get or set information in an in-memory key-value store accessible to all phases

diff --git a/test/index.js b/test/index.js
@@ -10,6 +10,7 @@ require('./parse')
 require('./run')
 require('./stringify')
 require('./process')
+require('./template-tag')
 
 var asyncfunctions = false
 

diff --git a/test/template-tag.js b/test/template-tag.js
@@ -0,0 +1,122 @@
+'use strict'
+
+var test = require('tape')
+var simple = require('./util/simple')
+var noop = require('./util/noop')
+var unified = require('..')
+
+test('templateTag`string`', function(t) {
+  var n = {type: 'bravo'}
+
+  t.plan(7)
+
+  var tag = unified()
+    .use(function() {
+      this.Parser = Parser
+      Parser.prototype.parse = parse
+
+      function Parser(doc, file) {
+        t.equal(typeof doc, 'string', 'should pass `doc` to `Parser`')
+        t.equal(file.toString(), 'alpha', 'should pass file to `Parser`')
+      }
+
+      function parse() {
+        return n
+      }
+    })
+    .use(function() {
+      return transformer
+      function transformer(tree, file) {
+        t.equal(tree, n, 'should pass `tree` to transformers')
+        t.equal(file.toString(), 'alpha', 'should pass file to transformers')
+      }
+    })
+    .use(function() {
+      this.Compiler = Compiler
+      Compiler.prototype.compile = compile
+
+      function Compiler(tree, file) {
+        t.equal(tree, n, 'should pass `tree` to `Compiler`')
+        t.equal(file.toString(), 'alpha', 'should pass file to `Compiler`')
+      }
+
+      function compile() {
+        return 'charlie'
+      }
+    }).templateTag
+
+  tag`alpha`.then(
+    function(file) {
+      t.equal(file.toString(), 'charlie', 'should resolve the file')
+    },
+    function() {
+      t.fail('should resolve, not reject, the file')
+    }
+  )
+})
+
+test('templateTagSync`string`', function(t) {
+  t.plan(4)
+
+  t.throws(
+    function() {
+      return unified().templateTagSync``
+    },
+    /Cannot `processSync` without `Parser`/,
+    'should throw without `Parser`'
+  )
+
+  t.throws(
+    function() {
+      var p = unified()
+      p.Parser = noop.Parser
+      return p.templateTagSync``
+    },
+    /Cannot `processSync` without `Compiler`/,
+    'should throw without `Compiler`'
+  )
+
+  t.throws(
+    function() {
+      var tag = unified()
+        .use(parse)
+        .use(plugin)
+        .use(compile).templateTagSync
+
+      function parse() {
+        this.Parser = simple.Parser
+      }
+      function compile() {
+        this.Compiler = noop.Compiler
+      }
+      function plugin() {
+        return transformer
+      }
+      function transformer() {
+        return new Error('bravo')
+      }
+
+      return tag`delta`
+    },
+    /Error: bravo/,
+    'should throw error from `templateTagSync`'
+  )
+
+  t.equal(
+    unified()
+      .use(function() {
+        this.Parser = simple.Parser
+      })
+      .use(function() {
+        return transformer
+        function transformer(node) {
+          node.value = 'alpha'
+        }
+      })
+      .use(function() {
+        this.Compiler = simple.Compiler
+      }).templateTagSync`delta`.toString(),
+    'alpha',
+    'should pass the result file'
+  )
+})