Add support for syntax tree input to remark(1)

This update removes the previously supported `-a, --ast` flag, and
renames it to `--tree-out`.  In addition, `--tree-in` is now supported
to depict that the read input is an already parsed syntax tree in JSON.
And, this commit introduces a new `-t, --tree` flag which turns both
`--tree-in` and `--tree-out` on, thus specifying a tree input and a
tree output.

Closes GH-126.
Closes GH-156.

Reviewed-By: Eugene Sharygin <eush77@gmail.com>

Author: wooorm

doc/remark.1.md

@@ -132,13 +132,30 @@ $ remark --no-rc readme.md -oqw
 The watch is stopped when `SIGINT` is received (usually done by pressing
 `CTRL-C`).
 
-### `-a`, `--ast`
+### `-t`, `--tree`
 
 ```sh
-remark readme.md --ast
+remark --tree < input.json > output.json
 ```
 
-Instead of outputting document the internally used AST is exposed.
+Read input as a syntax tree instead of markdown and write output as a
+syntax tree instead of markdown.
+
+### `--tree-in`
+
+```sh
+remark --tree-in < input.json > output.md
+```
+
+Read input as a syntax tree instead of markdown.
+
+### `--tree-out`
+
+```sh
+remark --tree-out < input.md > output.json
+```
+
+Write output as a syntax tree instead of markdown.
 
 ### `-q`, `--quiet`
 

lib/cli/cli.js

@@ -238,11 +238,13 @@ var program = new Command(pack.name)
     .option('-u, --use <plugins>', 'use transform plugin(s)', plugins, {})
     .option('-e, --ext <extensions>', 'specify extensions', extensions, [])
     .option('-w, --watch', 'watch for changes and reprocess', false)
-    .option('-a, --ast', 'output AST information', false)
     .option('-q, --quiet', 'output only warnings and errors', false)
     .option('-S, --silent', 'output only errors', false)
     .option('-f, --frail', 'exit with 1 on warnings', false)
+    .option('-t, --tree', 'input and output syntax tree', false)
     .option('--file-path <path>', 'specify file path to process as', false)
+    .option('--tree-out', 'output syntax tree', false)
+    .option('--tree-in', 'input syntax tree', false)
     .option('--no-stdout', 'disable writing to stdout', true)
     .option('--no-color', 'disable color in output', false)
     .option('--no-rc', 'disable configuration from .remarkrc', false)
@@ -290,7 +292,9 @@ function CLI(argv) {
         self.plugins = program.use;
         self.color = program.color;
         self.out = program.stdout;
-        self.ast = program.ast;
+        self.treeIn = program.treeIn || program.tree;
+        self.treeOut = program.treeOut || program.tree;
+        self.tree = program.tree || (self.treeIn && self.treeOut);
         self.detectRC = program.rc;
         self.detectIgnore = program.ignore;
         self.quiet = program.quiet;
@@ -308,7 +312,9 @@ function CLI(argv) {
         self.plugins = config.plugins;
         self.color = config.color;
         self.out = config.stdout;
-        self.ast = config.ast;
+        self.treeIn = config.treeIn || config.tree;
+        self.treeOut = config.treeOut || config.tree;
+        self.tree = config.tree || (config.treeIn && config.treeOut);
         self.detectRC = config.detectRC;
         self.detectIgnore = config.detectIgnore;
         self.quiet = config.quiet;

lib/cli/file-pipeline/parse.js

@@ -40,6 +40,20 @@ function parse(context) {
         return;
     }
 
+    if (context.fileSet.cli.treeIn) {
+        debug('Not parsing already parsed document');
+
+        try {
+            file.namespace('mdast').tree = JSON.parse(file.toString());
+        } catch (err) {
+            file.fail(err);
+        }
+
+        file.contents = '';
+
+        return;
+    }
+
     debug('Parsing document');
 
     context.processor.parse(file, context.settings);

lib/cli/file-pipeline/stringify.js

@@ -39,14 +39,14 @@ function stringify(context) {
     var file = context.file;
     var value;
 
-    if (!context.processor || context.ast) {
+    if (!context.processor) {
         debug('Not compiling failed document');
         return;
     }
 
     debug('Compiling document');
 
-    if (cli.ast) {
+    if (cli.treeOut) {
         file.move({
             'extension': 'json'
         });

man/remark.1

@@ -125,15 +125,33 @@ When watching files which would normally regenerate, this behaviour is ignored u
 .RE
 .P
 The watch is stopped when \fBSIGINT\fR is received (usually done by pressing \fBCTRL-C\fR).
-.SS "\fB-a\fR, \fB--ast\fR"
+.SS "\fB-t\fR, \fB--tree\fR"
 .P
 .RS 2
 .nf
-remark readme.md --ast
+remark --tree < input.json > output.json
 .fi
 .RE
 .P
-Instead of outputting document the internally used AST is exposed.
+Read input as a syntax tree instead of markdown and write output as a syntax tree instead of markdown.
+.SS "\fB--tree-in\fR"
+.P
+.RS 2
+.nf
+remark --tree-in < input.json > output.md
+.fi
+.RE
+.P
+Read input as a syntax tree instead of markdown.
+.SS "\fB--tree-out\fR"
+.P
+.RS 2
+.nf
+remark --tree-out < input.md > output.json
+.fi
+.RE
+.P
+Write output as a syntax tree instead of markdown.
 .SS "\fB-q\fR, \fB--quiet\fR"
 .P
 .RS 2

readme.md

@@ -189,11 +189,13 @@ Options:
   -u, --use <plugins>       use transform plugin(s)
   -e, --ext <extensions>    specify extensions
   -w, --watch               watch for changes and reprocess
-  -a, --ast                 output AST information
   -q, --quiet               output only warnings and errors
   -S, --silent              output only errors
   -f, --frail               exit with 1 on warnings
+  -t, --tree                input and output syntax tree
   --file-path <path>        specify file path to process as
+  --tree-out                output syntax tree
+  --tree-in                 input syntax tree
   --no-stdout               disable writing to stdout
   --no-color                disable color in output
   --no-rc                   disable configuration from .remarkrc

test/cli.sh

@@ -104,15 +104,11 @@ it "Should ignore herestring when with files (for now)"
     assert $? 0
 
 #
-# `--ast`.
+# `--tree-out`.
 #
 
-it "Should accept \`--ast\`"
-    $COMMAND --ast $markdown > /dev/null 2>&1
-    assert $? 0
-
-it "Should accept \`-a\`"
-    $COMMAND -a $markdown > /dev/null 2>&1
+it "Should accept \`--tree-out\`"
+    $COMMAND --tree-out $markdown > /dev/null 2>&1
     assert $? 0
 
 #