Add parser support for block params

[mmun]

Adds basic support for block params on blocks:

{{#block ... as |foo|}}...{{/block}}
{{^block ... as |foo|}}...{{/block}}
{{#block ... as |foo bar|}}...{{/block}}
{{^block ... as |foo bar|}}...{{/block}}

The block params are stored as an array of strings on the program node.

For example {{#block ... as |foo bar|}}...{{/block}} generates a program node with a blockParams property set to [ 'foo', 'bar' ].

[kpdecker]

So a block can only have 1 parameter declaration? What does |foo bar| mean?

[mmun]

foo and bar are names for the first two yielded values.

For example,

{{#each items as |item index|}}
  {{index}}: {{item.name}}
{{/each}}

is intended to be read like

items.forEach(function(item, index) {
  buffer.push(index + ": " + item.name);
});

In order to actually supply values for the block params, you must invoke the template with an arguments option (this isn't implemented yet as it's not a parser concern). For example, a possible implementation of the each helper in HTMLBars might look something like

function eachHelper(params, options) {
  var items = params[0];
  var fragment = document.createDocumentFragment();

  for (var i = 0; i < items.length; i++) {
    var result = options.fn(this, {
      arguments: [ items[i], i, items ]
    });

    fragment.appendChild(result);
  }

  return fragment;
}

[mmun]

If you're going to cut Handlebars 3.0 in the near future we should reconsider the syntax and allow for something more breaking so that the pipes are not required.

[kpdecker]

I chatted about this a little bit with @wycats a few weeks ago but I don't think I got quite the right idea for what the goal was.

So the desire here is to implement an arbitrary set of named values that the helper can populate per whatever it's needs are? These can then be injected into the child programs by the compiler in a manner that is more optimized than overriding context values and more explicit than the @index values, etc?

Regarding the breaking comment, what are the other syntaxes that you would want to consider that would be breaking otherwise?

[mmun]

That's correct. I will re-emphasize a minor point: naming the block params is a responsibility of the program (although they do appear syntactically in the block's opening mustache). The helper just provides the ordered set of values.

The alternate syntax we considered was {{#block ... as foo}} for a single yielded value and {{#block ... as (foo bar baz)}} for multiple yielded values. The parens are not subexpressions, they are just visual separators because we felt that too many consecutive ID tokens might be hard for humans to visually parse :P. This would essentially require as to be a keyword. I am open to alternatives.

[mmun]

This feature massively collides with @data so I didn't bother taking a stab at the compiler until you shared your thoughts.

One benefit of this feature is that you won't need to use @../index to climb contexts. In fact you could rewrite the default helpers not to use @data at all. Stuff like @first and @last may be better suited as subexpressions, e.g. (eq index 0).

[kpdecker]

as is a keyword in this implementation as well. Regardless, I like the explicitness of || There's already some confusion around subexpressions and I don't think that overriding that syntax further is the best idea.

For singular parameters, perhaps not requiring || is ok but it doesn't seem like it provides a huge win, at the potential expense or parser ambiguity/complexity.

[mmun]

In the current implementation you can use as anywhere you could before because the OPEN_BLOCK_PARAMS token is as\s+| and | is not a valid start for an ID. In the alternate syntax this is no longer true. That's all I meant by "keyword".

But I guess it's moot if you prefer the pipe syntax :)

[kpdecker]

Ah true. Generally fine with this. I think that only thing that gives me pause right now is it's not immediately clear how this might be implemented at the other levels of the language.

Any thoughts on how those binding would be propagated within the compiler?

[mmun]

It seems like the existing data already does the job of holding the environment. Basically

{{#each people as |person|}}
  {{greeting}} {{person.name}}
{{/each}}

should treat {{person.name}} like how {{@person.name}} is treated now. The template compiler should also read the block arguments (maybe there's a less confusing name for this) and inject them into data. This should happen in the preamble of the child template.

Concretely, the precompiled spec would only require adding a bit of preamble to any child templates with block params. Here's is the template above's precompiled spec, and a diff of the small changes I made:

https://gist.github.com/mmun/1d893edd87a7476eee89/revisions

[kpdecker]

Close enough for me to use as a basis. I don't think it's a good idea to modify the data object in the template if we are already passing an args object, but those sorts of details can be ironed out in the implementation of that.

[kpdecker]

Released in 3.0.0