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.

node.inspect( 'tmp/some-dir'[, options] )

Sometimes it's useful, for debugging purposes, to dump part of your build to disk in order to inspect it. This method will continuously write the contents of node to 'tmp-some-dir' whenever they change, as long as Gobble is running. It returns this, so it doesn't affect the build in any way - it's just a convenient way to see what's going on.

If you pass { clean: true } as the second argument, the target folder will be emptied, otherwise existing files will be left alone.

Built-in transforms

There are a handful of built-in transforms:

node.include( patterns )

Filters out any files that don't 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.