AST flag/API option; generic AST output for all nodes (#5044)

* Add `nodes` option to Node API, that returns POJO representation of AST; starting point for toPlainObject method on node classes to return the serializable plain JavaScript object representation of each node

* Make --nodes also return JSON (pretty-printed, though not colorized)

* Alphabetize CLI flags

* Use new `ast` flag to request AST, restoring prior `nodes` flag; rename toPlainObject to toJSON

Author: GeoffreyBooth

lib/coffeescript/coffeescript.js

@@ -94,7 +94,13 @@ exports.compile = compile = withPrettyErrors (code, options = {}) ->
         options.bare = yes
         break
 
-  fragments = parser.parse(tokens).compileToFragments options
+  nodes = parser.parse tokens
+  # If all that was requested was a POJO representation of the nodes, e.g.
+  # the abstract syntax tree (AST), we can stop now and just return that.
+  if options.ast
+    return nodes.toJSON()
+
+  fragments = nodes.compileToFragments options
 
   currentLine = 0
   currentLine += 1 if options.header

lib/coffeescript/command.js

@@ -32,12 +32,14 @@ BANNER = '''
 
 # The list of all the valid option flags that `coffee` knows how to handle.
 SWITCHES = [
+  [      '--ast',               'generate an abstract syntax tree of nodes']
   ['-b', '--bare',              'compile without a top-level function wrapper']
   ['-c', '--compile',           'compile to JavaScript and save as .js files']
   ['-e', '--eval',              'pass a string from the command line as input']
   ['-h', '--help',              'display this help message']
   ['-i', '--interactive',       'run an interactive CoffeeScript REPL']
   ['-j', '--join [FILE]',       'concatenate the source CoffeeScript before compiling']
+  ['-l', '--literate',          'treat stdio as literate style coffeescript']
   ['-m', '--map',               'generate source map and save as .js.map files']
   ['-M', '--inline-map',        'generate source map and include it directly in output']
   ['-n', '--nodes',             'print out the parse tree that the parser produces']
@@ -47,7 +49,6 @@ SWITCHES = [
   ['-p', '--print',             'print out the compiled JavaScript']
   ['-r', '--require [MODULE*]', 'require the given module before eval or REPL']
   ['-s', '--stdio',             'listen for and compile scripts over stdio']
-  ['-l', '--literate',          'treat stdio as literate style coffeescript']
   ['-t', '--transpile',         'pipe generated JavaScript through Babel']
   [      '--tokens',            'print out the tokens that the lexer/rewriter produce']
   ['-v', '--version',           'display the version number']
@@ -207,6 +208,9 @@ compileScript = (file, input, base = null) ->
       printTokens CoffeeScript.tokens task.input, task.options
     else if opts.nodes
       printLine CoffeeScript.nodes(task.input, task.options).toString().trim()
+    else if opts.ast
+      compiled = CoffeeScript.compile task.input, task.options
+      printLine JSON.stringify(compiled, null, 2)
     else if opts.run
       CoffeeScript.register()
       CoffeeScript.eval opts.prelude, task.options if opts.prelude
@@ -499,6 +503,7 @@ compileOptions = (filename, base) ->
     transpile: opts.transpile
     sourceMap: opts.map
     inlineMap: opts['inline-map']
+    ast: opts.ast
 
   if filename
     if base

lib/coffeescript/nodes.js

@@ -257,14 +257,53 @@ exports.Base = class Base
   lastNode: (list) ->
     if list.length is 0 then null else list[list.length - 1]
 
-  # `toString` representation of the node, for inspecting the parse tree.
+  # Debugging representation of the node, for inspecting the parse tree.
   # This is what `coffee --nodes` prints out.
   toString: (idt = '', name = @constructor.name) ->
     tree = '\n' + idt + name
     tree += '?' if @soak
     @eachChild (node) -> tree += node.toString idt + TAB
     tree
 
+  # Plain JavaScript object representation of the node, that can be serialized
+  # as JSON. This is used for generating an abstract syntax tree (AST).
+  # This is what the `ast` option in the Node API returns.
+  toJSON: ->
+    # We try to follow the [Babel AST spec](https://github.com/babel/babel/blob/master/packages/babylon/ast/spec.md)
+    # as closely as possible, for improved interoperability with other tools.
+    obj =
+      type: @constructor.name
+      # Convert `locationData` to Babel’s style.
+      loc:
+        start:
+          line: @locationData.first_line
+          column: @locationData.first_column
+        end:
+          line: @locationData.last_line
+          column: @locationData.last_column
+
+    # Add serializable properties to the output. Properties that aren’t
+    # automatically serializable (because they’re already a primitive type)
+    # should be handled on a case-by-case basis in child node classes’ own
+    # `toJSON` methods.
+    for property, value of this
+      continue if property in ['locationData', 'children']
+      continue if value is undefined # Don’t skip `null` or `false` values.
+      if typeof value is 'boolean' or typeof value is 'number' or typeof value is 'string'
+        obj[property] = value
+
+    # Work our way down the tree. This is like `eachChild`, except that we
+    # preserve the child node name, and arrays.
+    for attr in @children when @[attr]
+      if Array.isArray(@[attr])
+        obj[attr] = []
+        for child in flatten [@[attr]]
+          obj[attr].push child.unwrap().toJSON()
+      else
+        obj[attr] = @[attr].unwrap().toJSON()
+
+    obj
+
   # Passes each child to a function, breaking when the function returns `false`.
   eachChild: (func) ->
     return this unless @children

src/coffeescript.coffee

@@ -119,12 +119,14 @@ Usage: coffee [options] path/to/script.coffee [args]
 
 If called without options, `coffee` will run your script.
 
+      --ast          generate an abstract syntax tree of nodes
   -b, --bare         compile without a top-level function wrapper
   -c, --compile      compile to JavaScript and save as .js files
   -e, --eval         pass a string from the command line as input
   -h, --help         display this help message
   -i, --interactive  run an interactive CoffeeScript REPL
   -j, --join         concatenate the source CoffeeScript before compiling
+  -l, --literate     treat stdio as literate style coffeescript
   -m, --map          generate source map and save as .js.map files
   -M, --inline-map   generate source map and include it directly in output
   -n, --nodes        print out the parse tree that the parser produces
@@ -134,7 +136,6 @@ If called without options, `coffee` will run your script.
   -p, --print        print out the compiled JavaScript
   -r, --require      require the given module before eval or REPL
   -s, --stdio        listen for and compile scripts over stdio
-  -l, --literate     treat stdio as literate style coffeescript
   -t, --transpile    pipe generated JavaScript through Babel
       --tokens       print out the tokens that the lexer/rewriter produce
   -v, --version      display the version number