Gear Reference

Gear.js - Build System for Node.js and the Browser

Gear.js provides the workflow and a set of basic Queue tasks.

Queue initialization

new gear.Queue() // Start with an empty list of Blobs ... // Chain some task declarations .run(); // Starts the execution of the tasks

The Queue is generally created with the optional gear-lib registry of tasks. However this page only shows the tasks available in the most basic Queue.

Optionally, the Queue can be created with a custom logger : see log() and inspect(). A custom logger is an object with a log method.

new gear.Queue({ logger: { log: function(object) { // do something }}) // chain tasks

Core tasks

.append(string)

Appends a new blob string at the end of the list.
Alias of the load() method.

.concat([options])

Concatenates the whole list of blobs into a single new Blob.
options is an optional object with the following property :
callback
Function to execute on each blob in the list. Return a string which replaces the blob.

.get(index)

Keeps only the blob at the given index in the list. The other blobs are discarded.

.inspect()

Displays the complete list of blobs, with their properties and content, to the console, or to the custom queue logger.

.log(string)

Displays a message to the console, or to the custom queue logger.

.load(string)

Alias of the append() method.

.prepend(string)

Prepends a new blob string at the beginning of the list.

.read(name)
.read(<array of names>)

Reads one or more files and appends their content to the blob list.
name is the file path, relative to the Gearfile.
A new blob is created for each file, with its name property set to the file name.

Optionally, each file can be given as an object with the following properties :
name
name or relative path
encoding
'utf8' (default), 'ascii', or 'base64'
sync
boolean

.readBefore(name)
.readBefore(<array of names>)

Same as read() but the file blobs are added at the beginning of the blob list.

.replace(options)

Executes a search-and-replace on each blob in the list.
options is an object or an array of objects with the following properties :
regex
The string or RegExp object to search.
flags
If regex is a string, any combination of the strings 'g', 'i', 'm', 'y' (see the RegExp documentation on MDN). The default value is 'mg'.
replace
The replacement string, or a callback function to be invoked to create the replacement string (see the String.replace() documentation on MDN).

If options is an array of such objects, each replacement is executed on each blob. This allows multiple search-and-replace operations in a single statement.

.run([callback])

Not a task, but an essential part of the process, since it launches the execution of the task queue. Each task is executed after the previous one is finished. If a callback function is given, it is invoked after the task queue is complete, with the following arguments :
err
The error object or null if everything was OK.
res
The final array of Blobs.

.stamp(options)

Adds a prefix or a suffix to each blob. This task does not create or remove any blob, it just modifies the existing ones.
options is an object with the following properties :
prefix
(optional) The string to be prepended to each Blob.
postfix
(optional) The string to be appended to each Blob.

.tasks(workflow)

Executes a complex workflow. Determines the best order for running the subtasks, based on their requirements. Each subtask can optionally depend on other subtasks being completed first, and each subtask is run as soon as its requirements are satisfied.
See async.auto .

Each property key of the workflow object is the name of a subtask. The corresponding property value is an object with the following properties :
requires
(optional) The requirement for this subtask to begin. Can be either the name of a single subtask, or an array of subtask names.
task
The Queue task to execute. For simple tasks like concat(), the name is sufficient. If the task has parameters, this is an array with the task name and parameters.
new gear.Queue() .read('foo.js') .log('Parallel Tasks') .tasks({ read: {task: ['read', ['foo.js', 'bar.js', 'baz.js']]}, combine: {requires: 'read', task: 'concat'}, print: {requires: 'combine', task: 'inspect'}, // Runs when read and combine complete parallel: {task: ['log', "Hello Gear.js world!"]} // Run parallel to read }) .run();

.test(options)

Applies a callback to each Blob, and abort the Queue if the callback returns a non-null value.
Note, that since this task applies the callback to each blob item in parallel, there is no guarantee that the callbacks will complete in order (see async.each).
options is an object with the following property :
callback
A function to be invoked with each blob. If the return value is not null, the Queue stops and the error object reflects this value.

.write(name)
.write(<array of names>)

Writes blobs to disk.
name is the file path, relative to the Gearfile. Each blob is written in a separate file.

Optionally, each file can be given as an object with the following properties :
name
name or relative path
encoding
'utf8' (default), 'ascii', or 'base64'
new gear.Queue() .read(['foo.js', {name: 'bar.js'}, 'baz.js']) .write(['newfoo.js', 'newbar.js']) // Not writing 'baz.js' .run();