@typedef {String} can.stache.key key
@parent can.stache.types


@description A named reference to a value in the [can.view.Scope scope] or 
[can.view.Options helper scope] in a template.

@option {String}

A key specifies a value in the [can.view.Scope scope] or 
[can.view.Options options] of a template being rendered. The
key is used to look up a value in the scope.

What the key looks like changes the behavior of how a value is looked up in 
the scope. Keys can look like:

 - `{{name}}` - Single property name.
 - `{{name.first}}` - Multiple property names.
 - `{{foo\\.bar}}` - Single property name that includes a dot character.
 - `{{./name}}` - Single property in the current context.
 - `{{../name}}` - Single property in the parent context.
 - `{{.}}` or `{{this}}` - The current context.
 - `{{../.}}` - The parent context.
 - `{{@key}}` - Pass the value at key, even if it's a function or a compute.
 - `{{~key}}` - Pass a compute as the key's value instead of the value.
 - `{{*variable}}` - Reference a value in template scope.
 - `{{%key}}` - A special value that is added to scope. Examples:
    - `{{%index}}` - The index of a value in an array or [can.List].
    - `{{%key}}` - The property name of a value within an object or [can.Map].
    - `{{%element}}` - The element an event was dispatched on.
    - `{{%event}}` - The event object.
    - `{{%viewModel}}` - The viewModel of the current element.

@body

## Use

A key references a value within the [can.view.Scope scope] of a 
template being rendered. In the following example, the 
key is `name`:

    <h1>{{name}}</h1>
    
If this template is rendered with:

    {
      name: "Austin"
    }

The template writes out:

    <h1>Austin</h1>

A scope is a collection of multiple contexts. By default, a 
key walks up the scope to each context until it finds a value. For example,
a template like:

    {{first}} {{last}}
      {{#children}}
        {{first}} {{last}}
      {{/children}}

Rendered with:

    {
      first: "Barry", last: "Meyer",
      children: [
        {first: "Kim", last: "Sully"},
        {first: "Justin"},
      ]
    }

Writes out:

    Barry Meyer
        Kim Sully
        Justin Meyer

When `last` is looked up on the `{first: "Justin"}` object and not found,
it will then try to read the parent context's `last` property.  This is
why "Justin Meyer" is written out.

Keys have different operators that control the values that are 
looked up or the value that is returned:

- __value lookup__ `EXPRESSION.key`
- __current context__ `./key`
- __parent context__ `../key`
- __context__ `.` or `this`
- __special__ `%special`
- __template variable__ `*key`
- __at__ `@key`
- __compute__ `~key`



## Default key return values by expression and data types

Keys can have slightly different default behavior depending if they are used in:

 - [helper arguments](can.stache.expressions.html#section_Helperexpression) like: `{{helper some.key}}`
 
when compared to the other places they are used:

 - [lookup expressions](can.stache.expressions.html#section_KeyLookupexpressions) like: `{{some.key}}`
 - [call-expression arguments](can.stache.expressions.html#section_Callexpression) like: `{{helper(some.key)}}`
 - [can.view.bindings.can-EVENT event bindings] like: `($click)="method(some.key)"`
 - [can.view.bindings data bindings] like: `{some-attr}="some.key"`

Furthermore keys return different values depending on the data type.

In general:

 - Functions are called to get their return value. (Use the AT operator `@` to prevent this).
 - Keys in helper expression arguments that find observable data return 
   a [can.compute] that represents the value. 
 - Keys in other expressions return the value.
 - If no observable data is found, the key's value is returned in all expressions.

The following illustrates what `some.key` would return given
different data structures as a helper expression and in all other expressions.

```
// A non-observable JS object:
{some: {key: "value"}};
   // Helper -> "value"
   // Other  -> "value"

// A non-observable JS object w/ a function at the end
{some: {key: function(){ return "value"; }}}
   // Helper -> "value"
   // Other  -> "value"

// A non-observable JS object with intermeidate functions:
{some: function(){ return {key: "value"}}}
   // Helper -> "value"
   // Other  -> "value"

// A observable can.Map
{some: new can.Map({key: "value"})}
   // Helper -> can.compute("value")
   // Other  -> "value"

// A method on an observable can.Map that reads observables
var Some = can.Map.extend({key: function(){ return this.attr("value")}})
{some: new Some({value: "value"})}
   // Helper -> can.compute("value")
   // Other  -> "value"
```

## context operators `./`, `../`, `.` and `this`

Sometimes, especially with recursive templates, you want to control which
context is used to lookup.  Adding `./` before the key name will 
only look up in the current context.

The following template:

    {{first}} {{last}}
      {{#children}}
        {{first}} {{./last}}
      {{/children}}

Rendered with:

    {
      first: "Barry", last: "Meyer",
      children: [
        {first: "Kim", last: "Sully"},
        {first: "Justin"},
      ]
    }

Writes out:

    Barry Meyer
        Kim Sully
        Justin 

Notice that `{{./last}}` returns nothing because there's no `last` property
in the `{first: "Justin"}` object.


Adding `../` before a key will lookup the key starting in the parent 
context.  By changing the previous template to:

    {{first}} {{last}}
      {{#children}}
        {{first}} {{../last}}
      {{/children}}

It will write out:

    Barry Meyer
        Kim Meyer
        Justin Meyer

You can use `.././last` to lookup `last` _only_ in the parent context.


To write out the current context, write `{{.}}` or `{{this}}`. For example,
a template like:

    {{#each names}}{{.}} {{/each}}

With data like:

    {names: ["Jan","Mark","Andrew"]}

Will write out:

    Jan Mark Andrew 

## at operator `@`

The AT operator indicates to return whatever value is at a key, regardless
if it's a function or a compute.

The following illustrates what `some@key` would return given
different data structures:


```
// A non-observable JS object:
{some: {key: "value"}} 
   //-> "value"

// A non-observable JS object w/ a function at the end
{some: {key: function(){ return "value"; }}}
   //-> function(){ return "value"; }

// A non-observable JS object with intermeidate functions:
{some: function(){ return {key: "value"}}}
   //-> "value"

// A observable can.Map
{some: new can.Map({key: "value"})}
   //-> "value"

// A method on an observable can.Map that reads observables
var Some = can.Map.extend({key: function(){ return this.attr("value")}})
{some: new Some({value: "value"})}
   //-> function(){ return this.attr("value")}
```

Where `some@key` returns a function, that function is "bound" via `.bind(context)`
to the parent object.  This means that calling the function will
have `this` set to what is expected.

If the AT operator is used at the start of a key like:

```
{{method(@key)}}
```

This will return whatever is at the `key` property on the first context in the scope
to have a non-undefined `key` value.

The AT operator can be used multiple times within a value lookup expression like:

```
{{method(models@Todo@findAll)}}
```


## compute operator `~`

The compute operator can be used in non helper expressions to pass
a compute instead of a value if an observable is found.  This
makes non-helper expression arguments behave similar to helper 
expression arguments.

The following illustrates what `~some.key` would return given
different data structures:

```
// A non-observable JS object:
{some: {key: "value"}} 
   //-> "value"

// A non-observable JS object w/ a function at the end
{some: {key: function(){ return "value"; }}}
   //-> "value"

// A non-observable JS object with intermeidate functions:
{some: function(){ return {key: "value"}}}
   //-> "value"

// A observable can.Map
{some: new can.Map({key: "value"})}
   //-> can.compute("value")

// A method on an observable can.Map that reads observables
var Some = can.Map.extend({key: function(){ return this.attr("value")}})
{some: new Some({value: "value"})}
   //-> can.compute(function(){ return this.attr("value")})
```

Notice that `~` should only be used once in a value lookup expression.

## template variable operator `*`

Every template contains a context which is able to store values
local to the template. Keys with `*` reference variables in that context.

Template variables are often used to pass data between 
components. `<component-a>` exports its `propA` value to the
template variable `*variable`.  This is, in turn, used to update
the value of `propB` in `<component-b>`.

```
<component-a {^prop-a}="*variable"/>
<component-b {prop-b}="*variable"/>
```

Template variables are global to the template. Similar to JavaScript `var` 
variables, template variables do not have block leve scope.  The following
does not work:

```
{{#each something}}
	<component-a {^prop-a}="*variable"/>
	<component-b {prop-b}="*variable"/>
{{/each}}
```

To work around this, an `localContext` helper could be created as follows:

```
can.stache.regsiterHelper("localContext", function(options){
  return options.fn(new can.Map());
});
```

And used like:

```
{{#each something}}
	{{#localContext}}
	  <component-a {^prop-a}="./variable"/>
	  <component-b {prop-b}="./variable"/>
	{{/localContext}}
{{/each}}
```

## special operator `%`

[can.view.bindings.can-EVENT Event bindings] and some helpers like [can.stache.helpers.each]
provide special values that start with `%` to prevent potential collisions with
other values.  

### %index and %key

When looping over an array or [can.List], you an use `%index` to write out
the index of each property:

    {{#each task}}
      <li>{{%index}} {{name}}</li>
    {{/each}}
    
Indexes start at 0.  If you want to start at 1, you can create a helper like:

    can.stache.registerHelper('%indexNum', function(options){
      return options.scope.attr("%index")+1;
    })

And use it like:

    {{#each task}}
      <li>{{%indexNum}} {{name}}</li>
    {{/each}}

### %element

In an event binding, `%element` references the DOM element the event happened on:

```
<input ($click)="doSomething(%element.value)"/>
```

### %event

In an event binding, `%event` references the dispatched event object:

```
<input ($click)="doSomething(%event)/>"
```

### %viewModel

In an event binding, `%viewModel` references the view model of the current element:

```
<my-component (closed)="doSomething(%viewModel)"/>
```