<commit_before># base-compose [![NPM version](https://img.shields.io/npm/v/base-compose.svg)](https://www.npmjs.com/package/base-compose) [![Build Status](https://img.shields.io/travis/node-base/base-compose.svg)](https://travis-ci.org/node-base/base-compose)

> Compose elements from multiple applications into one.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm i base-compose --save
```

## Usage

This plugin requires an "app" using the [base-generators](https://github.com/jonschlinkert/base-generators) to be able to lookup generators to compose.
Some of the [composition handler](#composition-handler-api) methods require an "app" that is inherited from
[templates](https://github.com/jonschlinkert/templates) or use specific plugins. The methods and plugins are specified in the [api](#api) section.

```js
var compose = require('base-compose');
app.use(compose());
```

## API

### [.compose](index.js#L39)

Setup a composition by passing in an array of generators to compose elements. If a generator cannot be found, an error will be thrown.

**Params**

* `generators` **{Array}**: Array of generators to be composed.
* `returns` **{Object}**: Instance of [CompositionHandler](#composition-handler-api)

**Example**

```js
var composition = app.compose(['a', 'b', 'c']);

// most of the time, use chaining
app.compose(['a', 'b', 'c'])
  .data()
  .options()
  .views();
```

### Composition Handler API

### [.data](lib/composition-handler.js#L40)

Merge the `cache.data` object from each generator onto the `app.cache.data` object. This method requires the `.data()` method from [templates](https://github.com/jonschlinkert/templates).

**Params**

* `key` **{String}**: Optionally pass a key to merge from the `data` object.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
a.data({foo: 'a'});
b.data({foo: 'b'});
c.data({foo: 'c'});

app.compose(['a', 'b', 'c'])
  .data();

console.log(app.cache.data);
//=> {foo: 'c'}
```

### [.engines](lib/composition-handler.js#L69)

Merge the engines from each generator into the `app` engines. This method requires the `.engine()` methods from [templates](https://github.com/jonschlinkert/templates).

* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .engines();
```

### [.helpers](lib/composition-handler.js#L93)

Merge the helpers from each generator into the `app` helpers. This method requires the `.helper` method from [templates](https://github.com/jonschlinkert/templates).

* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .helpers();
```

### [.options](lib/composition-handler.js#L124)

Merge the options from each generator into the `app` options. This method requires using the [base-option](https://github.com/node-base/base-option) plugin.

**Params**

* `key` **{String}**: Optionally pass a key to merge from the `options` object.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
a.option({foo: 'a'});
b.option({foo: 'b'});
c.option({foo: 'c'});

app.compose(['a', 'b', 'c'])
  .options();

console.log(app.options);
//=> {foo: 'c'}
```

### [.tasks](lib/composition-handler.js#L153)

Copy the specified tasks from each generator into the `app` tasks. Task dependencies will also be copied. This method requires using the [base-task](https://github.com/node-base/base-task) plugin.

+ `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .tasks(['foo', 'bar', 'default']);
```

### [.views](lib/composition-handler.js#L178)

Copy the view collections and loaded views from each generator to the `app`. This method requires using an "app" inherited from [templates](https://github.com/jonschlinkert/templates).

* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .views();
```

### [.iterator](lib/composition-handler.js#L245)

Iterates over the specified generators and only calls `fn` on existing generators. Function passed into the iterator will be invoked with the current generator being iterated over (`gen`) and the app passed into the original function. No binding is done within the iterator so the function passed in can be safely bound.

**Params**

* `generators` **{Array}**: Optional array of generator names to be looked up and iterated over.
* `fn` **{Function}**: Function invoked with generator currently being iterated over and the app.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .iterator(function(gen, app) {
    // do work
    app.data(gen.cache.data);
  });

// optionally, a different array of generator names may be passed as the first argument.
app.compose(['a', 'b', 'c'])
  .iterator(['d', 'e', 'f'], function(gen, app) {
    // do work
  });
```

## Related projects
<commit_msg>generating readme documentation with verb<commit_after># base-compose [![NPM version](https://img.shields.io/npm/v/base-compose.svg)](https://www.npmjs.com/package/base-compose) [![Build Status](https://img.shields.io/travis/node-base/base-compose.svg)](https://travis-ci.org/node-base/base-compose)

> Compose elements from multiple applications into one.

## Install

Install with [npm](https://www.npmjs.com/):

```sh
$ npm i base-compose --save
```

## Usage

This plugin requires an "app" using the [base-generators](https://github.com/jonschlinkert/base-generators) to be able to lookup generators to compose.
Some of the [composition handler](#composition-handler-api) methods require an "app" that is inherited from
[templates](https://github.com/jonschlinkert/templates) or use specific plugins. The methods and plugins are specified in the [api](#api) section.

```js
var compose = require('base-compose');
app.use(compose());
```

## API

### [.compose](index.js#L39)

Setup a composition by passing in an array of generators to compose elements. If a generator cannot be found, an error will be thrown.

**Params**

* `generators` **{Array}**: Array of generators to be composed.
* `returns` **{Object}**: Instance of [CompositionHandler](#composition-handler-api)

**Example**

```js
var composition = app.compose(['a', 'b', 'c']);

// most of the time, use chaining
app.compose(['a', 'b', 'c'])
  .data()
  .options()
  .views();
```

### Composition Handler API

### [.data](lib/composition-handler.js#L40)

Merge the `cache.data` object from each generator onto the `app.cache.data` object. This method requires the `.data()` method from [templates](https://github.com/jonschlinkert/templates).

**Params**

* `key` **{String}**: Optionally pass a key to merge from the `data` object.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
a.data({foo: 'a'});
b.data({foo: 'b'});
c.data({foo: 'c'});

app.compose(['a', 'b', 'c'])
  .data();

console.log(app.cache.data);
//=> {foo: 'c'}
```

### [.engines](lib/composition-handler.js#L69)

Merge the engines from each generator into the `app` engines. This method requires the `.engine()` methods from [templates](https://github.com/jonschlinkert/templates).

* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .engines();
```

### [.helpers](lib/composition-handler.js#L93)

Merge the helpers from each generator into the `app` helpers. This method requires the `.helper` method from [templates](https://github.com/jonschlinkert/templates).

* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .helpers();
```

### [.options](lib/composition-handler.js#L124)

Merge the options from each generator into the `app` options. This method requires using the [base-option](https://github.com/node-base/base-option) plugin.

**Params**

* `key` **{String}**: Optionally pass a key to merge from the `options` object.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
a.option({foo: 'a'});
b.option({foo: 'b'});
c.option({foo: 'c'});

app.compose(['a', 'b', 'c'])
  .options();

console.log(app.options);
//=> {foo: 'c'}
```

### [.tasks](lib/composition-handler.js#L153)

Copy the specified tasks from each generator into the `app` tasks. Task dependencies will also be copied. This method requires using the [base-task](https://github.com/node-base/base-task) plugin.

+ `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .tasks(['foo', 'bar', 'default']);
```

### [.views](lib/composition-handler.js#L180)

Copy the view collections and loaded views from each generator to the `app`. This method requires using an "app" inherited from [templates](https://github.com/jonschlinkert/templates).

**Params**

* `names` **{Array}**: Optionally pass an array of collection names that will be copied. When names are not sepcified, all collections are copied.
* `filter` **{Function}**: Optionally pass a filter function that will receive the `key, view, collection` for each view being copied. Returning `false` will not copy the view.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .views();
```

### [.iterator](lib/composition-handler.js#L247)

Iterates over the specified generators and only calls `fn` on existing generators. Function passed into the iterator will be invoked with the current generator being iterated over (`gen`) and the app passed into the original function. No binding is done within the iterator so the function passed in can be safely bound.

**Params**

* `generators` **{Array}**: Optional array of generator names to be looked up and iterated over.
* `fn` **{Function}**: Function invoked with generator currently being iterated over and the app.
* `returns` **{Object}**: Returns `this` for chaining

**Example**

```js
app.compose(['a', 'b', 'c'])
  .iterator(function(gen, app) {
    // do work
    app.data(gen.cache.data);
  });

// optionally, a different array of generator names may be passed as the first argument.
app.compose(['a', 'b', 'c'])
  .iterator(['d', 'e', 'f'], function(gen, app) {
    // do work
  });
```

## Related projects

{'fraction_non_alphanumeric': 0.1858986896147076, 'fraction_numerical': 0.003911597887737141, 'mean_word_length': 4.774703557312253, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 26, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6553595', 'n_tokens_mistral': 3374, 'n_tokens_neox': 3243, 'n_words': 1053}