.verb.md

HEADS UP!

The .generateEach method has been deprecated. Use .generate instead.

Usage

var generators = require('{%= name %}');
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

The following applications use this library:

• [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

{%= apidocs("index.js") %} {%= apidocs("lib/*.js") %}