Package Exports

base-generators

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (base-generators) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

base-generators

Adds project-generator support to your base application.

You might also be interested in base-task.

Install

Install with npm:

$ npm i 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:

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

.resolve

Attempts to find a generator with the given name and options.

Params

name {String}: Can be a module name or filepath to a module that is locally or globally installed.
options {Object}
returns {Object}: Returns the filepath to the generator, if found.

Example

// resolve by generator "alias"
app.resolve('foo');

// resolve by generator name
app.resolve('generate-foo');

// resolve by filepath
app.resolve('./a/b/c/');

Params

name {String}
configfile {String}
options {Object}
returns {object}

.register

Params

name {String}
fn {Function}: Generator function or instance
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

Register generator name with the given fn, or get generator name if only one argument is passed. This method calls the .getGenerator method but goes one step further: if name is not already registered, it will try to resolve and register the generator before returning it (or undefined if unsuccessful).

Params

name {String}
fn {Function|Object}: Generator function or instance. When fn is defined, this method is just a proxy for the .register method.
returns {Object}: Returns the generator instance or undefined if not resolved.

Example

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

.hasGenerator

Return true if the given name exists on the generators object. Dot-notation may be used to check for sub-generators.

Params

name {String}
returns {Boolean}: Returns true if the generator exists.

Example

base.register('foo', function(app) {
  app.register('bar', function() {});
});

base.hasGenerator('foo');
//=> true
base.hasGenerator('bar');
//=> false
base.hasGenerator('foo.bar');
//=> true

.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, and last searching for a globally installed generator.

Params

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

.globalGenerator

Search for globally installed generator name. If found, then generator is registered and returned, otherwise undefined is returned.

Params

name {String}
returns {Object|undefined}

.invoke

Invoke the given generator in the context of (this) the current instance.

Params

app {String|Object}: Generator name or instance.
returns {Object}: Returns the instance for chaining.

Example

base.invoke('foo');

.extendWith

Alias for .invoke, Extend the current generator instance with the settings of other generators.

Params

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

Example

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

.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.

.fullname

Create a generator's full name from the given alias.

Params

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

Example

app.register('foo', function(app, base) {
  // "app" is a private instance created for "foo"
  // "base" is a shared instance, also accessible using `app.base`
});

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

Params

name {String}

bach: Compose your async functions with elegance | homepage
base: base is the foundation for creating modular, unit testable and highly pluggable node.js applications, starting… more | 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-methods to allow plugins to be called any time after init. | homepage
base-task: base plugin that provides a very thin wrapper around https://github.com/doowb/composer for adding task methods to… more | homepage
composer: API-first task runner with three methods: task, run and watch. | homepage
gulp: The streaming build system | homepage

Generate docs

Generate readme and API documentation with verb:

$ npm i -d && npm run docs

Or, if verb is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

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

Author

Jon Schlinkert

License

This file was generated by verb, v0.9.0, on February 17, 2016.

JSPM

base-generators

Package Exports

Readme

base-generators

TOC

Install

Usage

Examples

Tasks

Generators

Sub-generators

In the wild

API

.resolve

.register

.generator

.hasGenerator

.getGenerator

.findGenerator

.globalGenerator

.invoke

.extendWith

.generate

.generateEach

.alias

.fullname

.configname

.configfile

.configpath

.modulename

.base

Generate docs

Running tests

Contributing

Author

License

base-generators

Package Exports

Readme

base-generators

TOC

Install

Usage

Examples

Tasks

Generators

Sub-generators

In the wild

API

Related projects

Generate docs

Running tests

Contributing

Author

License