main

node-main

At the most basic level, node-main provides an easy way to specify an entry point for a script that is ran on the command line. It allows us to call a block of code only when the script is executed from the command line. If the script is require'd into another node module, it will not execute the main block.

node-main also supports automatic usage generation, and a whole plethora of tools that serve as shortcuts while writing command line scripts.

// Code out here will always run, as it is outside the main block
console.log('Hello');

require('main')(module)
.usage('./someScript [flags] <firstName> <lastName> <filePath>',
'',
'This simple script will write your first and last name',
'to a file. The middle initial is optional as a flag.')
.flags({
    middleInitial: {
        alias: 'm', default: '', describe: 'Middle Initial'
    }
})
.run(function($) {
    // code in this block only runs when called directly from the CLI
    $.assert.argsLen(2);
    var fullName = $(0) + $('middleInitial') + $(1);
    var filePath = $(2);
    $.writeSync(filePath, fullName).cout('done!');
});

Of course, this is only the tip of what's available. Visit the example directories and the documentation for more information

Installation

npm install --save main

Don't forget the --save flag. It will preserve the version you are using as node-main is still going through many changes.

Usage

For more advanced usage information that covers everything, please visit the full documentation (WIP).

The Basics

You're going to need to require the main module in your script. This is the minumum boilerplate to use node-main:

require('main')(module).run(function() {
    // code here will be executed when ran from the CLI
});

If you would like to set up usage information and flags, simply add those two before calling run like so:

require('main')(module)
.usage(
    './someScript [options] <arg1> <arg2>',
    '',
    'We can expand this usage information to multiple',
    'lines if we want to go into detail of how a ',
    'script is to be used.')
.flags({
    flagOne: { alias: 'o' },
    flagTwo: { boolean: true },
    flagThree: { demand: true, description: 'third flag' }
})
.run(function(scriptTools) { // SCRIPT TOOLS
    // code here will be executed when ran from the CLI
});

The flags use node-optimist - so options that are valid there, will be valid in node-main (such as demand, boolean, alias, etc.).

Also note that I have included a scriptTools variable inside of the run function. This allows us to access the tools that help in writing CLI scripts. For the remainder of The Basics, I'll refer to the scriptTools variable as "$"

// the "scriptTools" can be named anything, even $
require('main')(module).run(function($) { /* ... */ });

Script Tools

Script tools provide shortcuts for repetitive things that come up frequently when writing CLI scripts.

Visit the full documentation (WIP) for an exhaustive list of the tools available for use. Visit the example directory to see some in use.

argument/flag fetching

If you wanted to fetch the value for flag 'foo' and get the first positional argument:

$('foo'); // value of the flag foo
$(0); // the first positional argument

And array of received arguments can be accessed with $.args and an object containing all the flag values can be accessed with $.flags.

printing to the console

$.cout('hello world'); //same as console.log

Others include $.cerr (console.error), $.out (process.stdout.write), $.err (process.stderr.write).

files

There are synchronous and asynchronous versions of all file operations. The sync ones are chainable and can be used in the following fashion:

var file = '/tmp/README.md';
$.cout(
    $.writeSync(file, '# Hello World')
    .appendSync(file, 'foo bar')
    .readSync(file)
);

The async versions use a promise based implementation. The above can be re-written using asynchronously using promises as such:

var file = '/tmp/README.md';
$.write(file, '# Hello World').then(function() {
    return $.append(file, 'foo bar');
}).then(function() {
    return $.read(file);
}).then($.cout);

A non-exhaustive list of some other file functions (all have async counterparts)

$.walkSync
$.existsSync
$.mkdirSync
$.touchSync
$.rmSync

There is also a $.mktemp function to generate a random file name in the operating systems temporary directory. It doesn't create the file - that's up to you.

async helpers

There are async helpers such as $.chain, $.sequence, and many more to help streamline further, but these are well above the basics. Using $.chain, the async file example above can be reduced to:

$.chain(
    [ $.write, file, '# Hello World' ],
    [ $.append, file, 'foo bar' ],
    [ $.read, file ],
    [ $.cout ]
);

that's all for now

That should be enough to get you started.

Contributing

Feel free to add in new features as long as they are accompanied with test cases. Running npm test should get you started.