@GeoffreyBooth and@lydell I've made the changes to output interpolated strings as template literals.

Am looking for some input, as I'm lacking nodes.coffee knowledge. Specifically, StringWithInterpolations now extends Base, not Parens. Extending Parens is unnecessary, as we don't need to bracket template literals (they have clear backtick begin and end markers).

Am looking for guidance on which StringWithInterpolations fields to overload from Base. I copied Parens, which overloadedchildren,unwrap andisComplex. I am unclear on whether we need to overloadchildren orisComplex. The tests pass if I remove these fields.

Relevant lines are below.

Thoughts?

exports.StringWithInterpolations = class StringWithInterpolations extends Base  constructor: (@body) ->  #TODO: Is this needed / correct?  children: ['body']  #NOTE: unwrap returns this to stop ancestor nodes reaching in to grab @body, and using  #      @body.compileNode. StringWithInterpolations.compileNode is _the_ custom logic to  #      output interpolated strings as code.  unwrap: -> this  #TODO: Is this needed / correct?  isComplex : -> @body.isComplex()

@lydell and@jashkenas I’ve been wondering about the purpose ofchildren,unwrap,isComplex,isStatement,jumps,makeReturn and so on since I started working in the CoffeeScript codebase. Perhaps it’s time for a new wiki page explaining hownodes.coffee works? Or more detailed comments?

Explaining how that stuff works would be awesome. I struggle with it every time I touch nodes.coffee.

I think this is roughly what some of them do:

• children tells which properties to recurse into when tree walking.
• Ifnode.isComplex() is false, it is safe to usenode more than once. Otherwise you need to store the value ofnode in a variable and output that variable several times instead. Kind of like this:5 is not complex.returnFive() is complex.
• I guessmakeReturn has to do with implicit returns.
• Not sure whatjumps does.
• RegardingisStatement, I guess it has to do with "everything is an expression". A few things can't be expressions, though, such asbreak. I think there are some error messages that come from nodes.coffee due statements ending up in expression position.

All of the above might be used for more things as well, but that's just what I (think I) remember from the top of my head.

Thanks@lydell. Okay@greghuc, I think you got everything right. I updated your comments to use Markdown, since those comments become the annotated source, and I removed theTODOs per@lydell’s notes. I think this is probably good to go.@lydell, did you have any other notes?

I think this is roughly what some of them do:

children tells which properties to recurse into when tree walking.

The children listis the structure of the AST. Theparent pointer, and the pointer to thechildren are how you can traverse the tree.

If node.isComplex() is false, it is safe to use node more than once. Otherwise you need to store the value of node in a variable and output that variable several times instead. Kind of like this: 5 is not complex. returnFive() is complex.

Exactly. It's all about "do we need to cache this expression?"

I guess makeReturn has to do with implicit returns.

makeReturn is what we use to force an arbitrary node into the returned value from a function. Helpful for implicit returns — when any valid coffeescript statement or expression could need to be returned ... something that doesn't happen in JS. Most of these are simple. If/elses and for-loops are not.

Not sure what jumps does.

Jumps tells you if an expression, or an internal part of an expression has a flow control construct (likebreak, orcontinue, orreturn, orthrow) that jumps out of the normal flow of control and can't be used as a value. This is important because things like this make no sense — we have to disallow them:

value=if condition100elsereturn5

Regarding isStatement, I guess it has to do with "everything is an expression". A few things can't be expressions, though, such as break. I think there are some error messages that come from nodes.coffee due statements ending up in expression position.

Exactly. Things thatisStatement returnstrue for are things that can't be used as expressions.

If anyone wants to put any of the above into docs or further comments, feel free.

@lydell and@jashkenas I merged your comments intohttps://github.com/jashkenas/coffeescript/wiki/%5BHowTo%5D-How-parsing-works