base-generators

Adds project-generator support to your base application.

You might also be interested in base-task.

TOC

• Install
• Usage
• Examples
  • Tasks
  • Generators
  • Sub-generators
• In the wild
• API
• Related projects
• Contributing
• Building docs
• Running tests
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install base-generators --save

Usage

var generators = require('base-generators');
var Base = require('base');

// register the plugin before instantiating, to make 
// sure the plugin is called on all Generator instances 
Base.use(generators());
var base = new Base();

Examples

All examples assume the following code is defined:

var Base = require('base');
var generators = require('base-generators');

Base.use(generators());
var base = new Base();

Tasks

Tasks are exactly the same as gulp tasks, and are powered by bach and composer.

Register a task:

base.task('default', function(cb) {
  // do stuff
  cb();
});

Run a task:

base.build('default', function(err) {
  if (err) throw err;
});

Generators

I heard you liked tasks, so I put some tasks in your tasks.

What's a generator?

Generators are functions that are registered by name, and are used to encapsulate and organize code, tasks, other generators, or sub-generators, in a sharable, publishable and easily re-usable way.

In case it helps, here are some live examples.

Register a generator:

base.register('foo', function(app, base) {
  // `app` is the generator's "private" instance
  // `base` is a "shared" instance, accessible by all generators
});

Get a generator:

var foo = base.generator('foo');

Register tasks in a generator:

base.register('foo', function(app, base) {
  app.task('default', function() {});
  app.task('one', function() {});
  app.task('two', function() {});
});

Run a generator's tasks:

The .generate method simply calls the .build method on a specific generator.

To run a generator's tasks, pass the generator name as the first argument, and optionally define one or more tasks as the second argument. (If no tasks are defined, the default task is run.)

// run the "default" task on generator "foo"
base.generate('foo', function(err) {
  if (err) throw err;
  console.log('done!');
});

// or specify tasks
base.generate('foo', ['default'], function() {});
base.generate('foo', ['one', 'two'], function() {});

Alternatively, you can call .build on the generator directly:

// run the "default" task on generator "foo"
base.generator('foo')
  .build('default', function(err) {
    if (err) throw err;
  });

Sub-generators

Sub-generators are just generators that are registered on (or invoked within) another generator instance.

Register sub-generators:

Register generators one, two, and three on generator foo:

base.register('foo', function(app, base) {
  app.register('one', function() {});
  app.register('two', function() {});
  app.register('three', function() {});
});

Get a sub-generator:

Use dot-notation to get a sub-generator:

var one = base.generator('foo.one');

Sub-generators may be nested to any level. In reality, you probably won't write code like the following example, but this only illustrates the point that generators are extremely composable, and can be built on top of or with other generators.

base.register('a', function(a, base) {
  // do stuff
  a.register('b', function(b) {
    // do stuff
    b.register('c', function(c) {
      // do stuff
      c.register('d', function(d) {
        // do stuff
        d.register('e', function(e) {
          // arbitrary task
          e.task('default', function(cb) {
            console.log('e > default!');
            cb();
          });
        });
      });
    });
  });
});

base.getGenerator('a.b.c.d.e')
  .build(function(err) {
    if (err) throw err;
    // 'e > default!'
  });

Register tasks on sub-generators:

base.register('foo', function(app, base) {
  app.register('one', function(one) {
    one.task('default', function() {});
    one.task('a', function() {});
    one.task('b', function() {});
    one.task('c', function() {});
  });

  app.register('two', function(two) {
    two.task('default', function() {});
  });

  app.register('three', function(three) {
    three.task('default', function() {});
  });
});

Run a sub-generator's tasks

// run the `default` task from sub-generator `foo.one`
base.generate('foo.one', function(err) {
  if (err) throw err;
  console.log('done!');
});

Run multiple tasks on a sub-generator:

// run tasks `a`, `b` and `c` on sub-generator `foo.one`
base.generate('foo.one', ['a', 'b', 'c'], function(err) {
  if (err) throw err;
  console.log('done!');
});

In the wild

Checked off as they're added:

• generate: adds a CLI, template rendering, fs methods and generator convenience-methods to base-generators
• assemble: site generation
• verb: documentation generation
• update: renames generators to "updaters", which are used to keep your project up-to-date

API

.register

Alias to .setGenerator.

Params

• name {String}: The generator's name
• options {Object|Function|String}: or generator
• generator {Object|Function|String}: Generator function, instance or filepath.
• returns {Object}: Returns the generator instance.

Example

base.register('foo', function(app, base) {
  // "app" is a private instance created for the generator
  // "base" is a shared instance
});

.generator

Get and invoke generator name, or register generator name with the given val and options, then invoke and return the generator instance. This method differs from .register, which lazily invokes generator functions when .generate is called.

Params

• name {String}
• fn {Function|Object}: Generator function, instance or filepath.
• returns {Object}: Returns the generator instance or undefined if not resolved.

Example

base.generator('foo', function(app, base, env, options) {
  // "app" - private instance created for generator "foo"
  // "base" - instance shared by all generators
  // "env" - environment object for the generator
  // "options" - options passed to the generator
});

.setGenerator

Store a generator by file path or instance with the given name and options.

Params

• name {String}: The generator's name
• options {Object|Function|String}: or generator
• generator {Object|Function|String}: Generator function, instance or filepath.
• returns {Object}: Returns the generator instance.

Example

base.setGenerator('foo', function(app, base) {
  // "app" - private instance created for generator "foo"
  // "base" - instance shared by all generators
  // "env" - environment object for the generator
  // "options" - options passed to the generator
});

.getGenerator

Get generator name from app.generators. Dot-notation may be used to get a sub-generator.

Params

• name {String}: Generator name.
• returns {Object|undefined}: Returns the generator instance or undefined.

Example

var foo = app.getGenerator('foo');

// get a sub-generator
var baz = app.getGenerator('foo.bar.baz');

.findGenerator

Find generator name, by first searching the cache, then searching the cache of the base generator.

Params

• name {String}
• options {Function}: Optionally supply a rename function on options.toAlias
• returns {Object|undefined}: Returns the generator instance if found, or undefined.

Example

// search by "alias"
var foo = app.findGenerator('foo');

// search by "full name"
var foo = app.findGenerator('generate-foo');

.getSubGenerator

Get sub-generator name, using dot-notation for nested generators.

app.getSubGenerator('foo.bar.baz')'
```'

**Params**

* `name` **{String}**: The property-path of the generator to get    
* `options` **{Object}**    

Iterate over `app.generators` and call `generator.isMatch(name)`
on `name` until a match is found.

**Params**

* `name` **{String}**    
* `returns` **{Object|undefined}**: Returns a generator object if a match is found.  

For example, if the lookup `name` is `foo`, the function might
return `["generator-foo", "foo"]`, to ensure that the lookup happens
in that order.

**Params**

* `name` **{String}**: Generator name to search for    
* `options` **{Object}**    
* `fn` **{Function}**: Lookup function that must return an array of names.    
* `returns` **{Object}**  

### [.extendWith](index.js#L371)
Extend the generator instance with settings and features of another generator.

**Params**

* `app` **{String|Object}**    
* `returns` **{Object}**: Returns the instance for chaining.  

**Example**

```js
var foo = base.generator('foo');
base.extendWith(foo);
// or
base.extendWith('foo');
// or
base.extendWith(['foo', 'bar', 'baz']);

app.extendWith(require('generate-defaults'));

.generate

Run a generator and tasks, calling the given callback function upon completion.

Params

• name {String}
• tasks {String|Array}
• cb {Function}: Callback function that exposes err as the only parameter.

Events

• emits: generate with the generator name and the array of tasks that are queued to run.

Example

// run tasks `bar` and `baz` on generator `foo`
base.generate('foo', ['bar', 'baz'], function(err) {
  if (err) throw err;
});

// or use shorthand
base.generate('foo:bar,baz', function(err) {
  if (err) throw err;
});

// run the `default` task on generator `foo`
base.generate('foo', function(err) {
  if (err) throw err;
});

// run the `default` task on the `default` generator, if defined
base.generate(function(err) {
  if (err) throw err;
});

.generateEach

Iterate over an array of generators and tasks, calling generate on each.

Params

• tasks {String|Array}: Array of generators and tasks to run.
• cb {Function}: Callback function that exposes err as the only parameter.

Example

// run tasks `a` and `b` on generator `foo`,
// and tasks `c` and `d` on generator `bar`
base.generateEach(['foo:a,b', 'bar:c,d'], function(err) {
  if (err) throw err;
});

.alias

Create a generator alias from the given name.

Params

• name {String}
• options {Object}
• returns {String}: Returns the alias.

Get the generator alias

• returns {String}: Returns the value from generator.env.alias

Get the generator name

• returns {String}: Returns the value from generator.env.name

Get the generator namespace

• returns {String}: Returns the value from generator.env.namespace

Invoke generator.fn with the given options and optional context.

Params

• options {Object}
• context {Object}
• returns {Object}: Returns the context object or generator instance, modified by invoking fn.

Returns true if str matches one of the following properties on generator.env

• key: the original name used to register the generator
• name: the name of the generator. this can be different than key if the generator was registered using a filepath.
• path: the file path of the generator.

Params

• str {String}
• returns {Boolean}

Return true if the given name exists on the app.tasks object.

Params

• name {String}

Related projects

You might also be interested in these projects:

• bach: Compose your async functions with elegance | homepage
• base-fs: base-methods plugin that adds vinyl-fs methods to your 'base' application for working with the file… more | homepage
• base-pipeline: base-methods plugin that adds pipeline and plugin methods for dynamically composing streaming plugin pipelines. | homepage
• base-plugins: Upgrade's plugin support in base applications to allow plugins to be called any time after… more | homepage
• base-task: base plugin that provides a very thin wrapper around https://github.com/doowb/composer for adding task methods to… more | homepage
• base: base is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… more | homepage
• composer: API-first task runner with three methods: task, run and watch. | homepage
• gulp: The streaming build system | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

Generate readme and API documentation with verb:

$ npm install verb && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

This file was generated by verb, v0.9.0, on April 20, 2016.