base-generators
Advanced tools
Adds project-generator support to your
baseapplication.
You might also be interested in base-task.
(TOC generated by verb using markdown-toc)
Install with npm:
$ npm i 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:
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/');
Register configfile with the given name and options.
Params
name {String}configfile {String}options {Object}returns {object}Register generator name with the given fn.
Params
name {String}fn {Function}: Generator function or instancereturns {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
});
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
});
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
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');
Search for globally installed generator name. If found, then generator
is registered and returned, otherwise undefined is returned.
Params
name {String}returns {Object|undefined}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}fn {Function}: Optionally supply a rename function.returns {Object|undefined}: Returns the generator instance if found, or undefined.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');
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']);
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;
});
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;
});
Create a generator alias from the given name.
Params
name {String}options {Object}returns {String}: Returns the alias.Create a generator's full name from the given alias.
Params
alias {String}options {Object}returns {String}: Returns the full name.Getter/setter for defining the configname name to use for lookups.
By default configname is set to generator.js.
Getter/setter for defining the configfile name to use for lookups.
By default configfile is set to generator.js.
Getter/setter for defining the configpath name to use for lookups.
By default configpath is set to generator.js.
Getter/setter for defining the modulename name to use for lookups.
By default modulename is set to generate.
Getter/setter for the base (or shared) instance of generate.
When a generator is registered, the current instance (this) is
passed as the "parent" instance to the generator. The base getter
ensures that the base instance is always the firstGen instance_.
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}Generate readme and API documentation with verb:
$ npm i -d && npm run docs
Or, if verb is installed globally:
$ verb
Install dev dependencies:
$ npm i -d && npm test
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Jon Schlinkert
Copyright © 2016 Jon Schlinkert Released under the MIT license.
This file was generated by verb, v0.9.0, on February 12, 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.