Skip to content

Plugin that adds project-generator support to your `base` application.

License

Notifications You must be signed in to change notification settings

base/base-generators

Repository files navigation

base-generators NPM version NPM downloads Linux Build Status

Adds project-generator support to your base application.

You might also be interested in base-task.

Table of Contents

(TOC generated by verb using markdown-toc)

Install

Install with npm:

$ npm install --save base-generators

HEADS UP!

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

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

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

Alias to .setGenerator.

Example

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

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.

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.

Example

app.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
});

Params

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

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

Example

app.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
});

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.

Get generator name from app.generators, same as [findGenerator], but also invokes the returned generator with the current instance. Dot-notation may be used for getting sub-generators.

Example

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

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

Params

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

Find generator name, by first searching the cache, then searching the cache of the base generator. Use this to get a generator without invoking it.

Example

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

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

Params

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

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

Example

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.

Example

console.log(app.hasGenerator('foo'));

Params

  • name {String}
  • val {Object|Function}
  • returns {Boolean}

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}

Extend the generator instance with settings and features of another generator.

Example

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

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

Params

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

Create a generator alias from the given name. By default the alias is the string after the last dash. Or the whole string if no dash exists.

Example

var camelcase = require('camel-case');
var alias = app.toAlias('foo-bar-baz');
//=> 'baz'

// custom `toAlias` function
app.option('toAlias', function(name) {
  return camelcase(name);
});
var alias = app.toAlias('foo-bar-baz');
//=> 'fooBarBaz'

Params

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

About

Related projects

Contributing

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

Contributors

Commits Contributor
227 jonschlinkert
6 doowb

Building docs

(This document was generated by verb-generate-readme (a verb generator), please don't edit the readme directly. Any changes to the readme must be made in .verb.md.)

To generate the readme and API documentation with verb:

$ npm install -g verb verb-generate-readme && verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

License

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


This file was generated by verb-generate-readme, v0.2.0, on November 22, 2016.

About

Plugin that adds project-generator support to your `base` application.

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

  •  
  •  

Packages

No packages published