base-generators
Advanced tools
Adds project-generator support to your base application.
You might also be interested in base-task.
Install with npm:
$ npm install base-generators --save
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();
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 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;
});
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 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!');
});
Checked off as they're added:
Alias to .setGenerator.
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.Example
base.register('foo', function(app, base) {
// "app" is a private instance created for the generator
// "base" is a shared 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.
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
});
Store a generator by file path or instance with the given name and options.
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.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
});
Get generator name from app.generators and invoke it with the current instance. 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');
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.
Params
name {String}options {Function}: Optionally supply a rename function on options.toAliasreturns {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');
Get sub-generator name, optionally using dot-notation for nested generators.
Params
name {String}: The property-path of the generator to getoptions {Object}Example
app.getSubGenerator('foo.bar.baz');
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 foroptions {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.
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']);
app.extendWith(require('generate-defaults'));
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;
});
Run generators, calling .config.process first if it exists.
Params
name {String|Array}: generator to runtasks {Array|String}: tasks to runapp {Object}: Application instancegenerator {Object}: generator instanceCreate 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.
Params
name {String}options {Object}returns {String}: Returns the alias.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'
Get the generator alias created by calling the app.toAlias function.
returns {String}: Returns the value from generator.env.aliasExample
console.log(generator.alias);
Get the name that was used to originally registered the generator.
returns {String}: Returns the value from generator.env.nameExample
var app = new Base();
var foo = app.register('foo', function() {});
console.log(foo.name);
//=> 'foo'
var bar = foo.register('bar', function() {});
console.log(bar.name);
//=> 'bar'
var baz = bar.register('baz', function() {});
console.log(baz.name);
//=> 'baz'
Get a generator's namespace, which created from the generator's parent namespace plus the generator's alias.
returns {String}: Returns the value from generator.env.namespaceExample
var foo = app.register('foo', function() {});
console.log(foo.namespace);
//=> 'foo'
var bar = foo.register('bar', function() {});
console.log(bar.namespace);
//=> 'foo.bar'
var baz = bar.register('baz', function() {});
console.log(baz.namespace);
//=> 'foo.bar.baz'
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.Example
generator.invoke();
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}Example
var isMatch = generator.isMatch('foo/bar.js');
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;
});
Run generators, calling .config.process first if it exists.
Params
name {String|Array}: generator to runtasks {Array|String}: tasks to runapp {Object}: Application instancegenerator {Object}: generator instanceReturn true if task name exists on app.tasks.
Params
name {String}: Task name to checkExample
app.task('foo', function() {});
console.log(app.hasTask('foo'));
//=> true
You might also be interested in these projects:
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Generate readme and API documentation with verb:
$ npm install verb && npm run docs
Or, if verb is installed globally:
$ verb
Install dev dependencies:
$ npm install -d && npm test
Jon Schlinkert
Copyright © 2016, Jon Schlinkert. Released under the MIT license.
This file was generated by verb, v0.9.0, on May 14, 2016.
FAQs
Adds project-generator support to your `base` application.
The npm package base-generators receives a total of 18,740 weekly downloads. As such, base-generators popularity was classified as popular.
We found that base-generators demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
FSF files an amicus brief against Neo4j, defending the AGPL and warning against adding restrictive terms that undermine free software rights.
Research
Security News
Malicious PyPI package ‘set-utils’ steals Ethereum private keys by exfiltrating them through blockchain transactions via the Polygon RPC.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.