API reference

node = gobble( 'foo' )

Returns a node object representing the contents of the 'foo' directory.

node = gobble([ node1, node2[, ...nodeN] ])

Returns the result of merging the input nodes. Later files overwrite earlier ones.

node2 = node1.transform( transformer, options )

Returns a tree that is the result of applying transformer to node1. See Writing plugins for more information.

node2 = node1.transformIf( condition, transformer, options )

If condition is met, is the equivalent of node.transform(), otherwise returns node1. Useful for only enabling certain transformations (e.g. minifying) in production.

node2 = node1.observe( observer, options )

Similar to .transform(), except that the observer function receives only an inputdir, not an outputdir, and should not affect the build itself. Useful for linting, running tests and so on.

node2 = node1.observeIf( condition, observer, options );

As per .transformIf(), allows you to run an observer only if condition is met, otherwise it will be skipped.

Built-in transforms

There are a handful of built-in transforms:

node.include( patterns )

Filters the input node to only include files that match patterns. patterns can be a minimatch string, or an array of them.

node.exclude( patterns )

Opposite of node.include(patterns).

node.grab( subdirectory )

Grab all the files in the specified subdirectory. For example, if src/assets were a directory with an images subdirectory, you could do this:

assets = gobble( 'src/assets' );
images = assets.grab( 'images' );

images would now contain the contents of src/assets/images.

node.moveTo( subfolder )

The opposite of node.grab():

pub = gobble([ images, fonts, otherStuff ]).moveTo( 'public' );

Serving and building programmatically

Most of the time you'll want to use gobble-cli to serve or build your projects. Occasionally, however, you might need to do so from within node.js.

task = node.serve( options )

The task object is an EventEmitter, which emits info, warning and error events. It has three additional methods:

• task.pause() stops serving the node
• task.resume(node) starts serving a new node
• task.close() shuts everything down

(The pause() and resume() methods are used by gobble-cli to restart builds when the gobblefile changes.)

The options object is not required. It can have the following properties:

• port - defaults to 4567
• gobbledir - where to write temporary files. Defaults to process.env.GOBBLE_TMP_DIR or .gobble.

task = node.build( options )

The task object is an EventEmitter, just like node.serve() except that it will emit a complete event. It has two additional methods:

• task.then(callback) - the callback is called once the build is complete
• task.catch(errback) - the errback is called if something goes wrong

In other words, it's a Promise as well as an EventEmitter.

This time, options must be included:

• dest - required. Where to write the files to
• gobbledir - optional. As above
• force - optional, defaults to false. Whether to empty dest before proceeding. If force is false, and dest exists and is non-empty, the build will abort.