isotoma/yay — Issue #4: YEP1: Reusable chunks
Author: Jc2k
Created: 2011-11-15 21:00:49+00:00
State: open

## Abstract

This YEP proposes to provide reusable blocks of config that can be inserted with different parameters.

## Problem

When using Yay in Yaybu we often repeat the same things over and over again. While you can work around this to some extend using hooks like this:

```yaml
things: []

resources.append:
.foreach thing in things:
Execute:
name: do-stuff-to-${thing}

things.append:
- workaround
```

But you sacrifice control over when execution occurs. This can lead to 'cannot forward declare' errors.

## Proposed Solution

You define a reusable chunk with the ```.define```

```yaml
.define Virtualenv:
- Directory:
name: ${directory}
owner: ${owner}
mode: 0755

- Execute:
name: virtualenv-${directory}
command: virtualenv --no-site-packages ${directory}
user: ${owner}
creates: ${directory}/bin/pip

- Execute:
name: pip-${directory}
command: ${directory}/bin/pip install -r requirements.txt
user: ${owner}
cwd: ${checkout}
```

You can call it with the ```@``` decorator:

```
.foreach ev in envs:
- Checkout:
name: /var/loca/checkouts/zap

- @Virtualenv:
directory: /var/local/envs/zap
hoo: ha
```

```
.define Virtualenv:
File:
name: /var/local/sites/${name}

# Here, the Virtualenv definition is captured from the foreach
resources.append:
.foreach name in the_big_book_of_names: ${@Virtualenv}

# Here it name is not from the foreach, the value that is passed in explicitly is used.
resources.append:
.foreach name in the big_book_of_names:
- @Virtualenv:
name: this has priority

# Your chunks can yield mappings, sequences or literals
.define LoveYou: Hi ${name}, you are amazing.

markov.append:
.foreach name in the big_book_of_names: ${@LoveYou}

markov.append:
.foreach name in the_big_book_of_names:
@LoveYou:
name: Mr Eeejit
```

## Scope

This changes the behaviour of mapping keys and adds additional behaviours to ```${}``` expressions.

## Risks

Any string starting ```@``` will become a reserved word.

## Transition

This introduces new language features - it shouldn't change any existing language behaviour, but might affect any configs that use "@" in their keys.