Awesome
base-generators
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
.register
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 nameoptions
{Object|Function|String}: or generatorgenerator
{Object|Function|String}: Generator function, instance or filepath.returns
{Object}: Returns the generator 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.
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.
.setGenerator
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 nameoptions
{Object|Function|String}: or generatorgenerator
{Object|Function|String}: Generator function, instance or filepath.returns
{Object}: Returns the generator instance.
.getGenerator
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.
.findGenerator
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 onoptions.toAlias
returns
{Object|undefined}: Returns the generator instance if found, or undefined.
.getSubGenerator
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 getoptions
{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 foroptions
{Object}fn
{Function}: Lookup function that must return an array of names.returns
{Object}
.extendWith
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.
.toAlias
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
- 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.
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.