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] )

This feature is temporarily absent as of 0.6.3... returning shortly!

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 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.