Launch your command line tool with ease.
See this blog post, or read on.
Say you're writing a CLI tool. Let's call it hacker. You want to configure it using a Hackerfile
. This is node, so you install hacker
locally for each project you use it in. But, in order to get the hacker
command in your PATH, you also install it globally.
Now, when you run the hacker
command, you want it to use the Hackerfile
in your current directory, and the local installation of hacker
next to it. It'd be nice if it traversed up your folders until it found a Hackerfile
βfor those times when you're not in the root directory of your project. Heck, you might even want to launch it from a folder outside of your project by manually specifying a working directory. Liftoff manages this for you.
So, everything is working great. Now you can find your local hacker
and Hackerfile
with ease. Unfortunately, it turns out you've authored your Hackerfile
in coffee-script, or some other JS variant. In order to support that, you have to load the compiler for it, and then register the extension for it with node. Good news, Liftoff can do that too.
Create an instance of Liftoff to invoke your application.
An example utilizing all options:
var Hacker = new Liftoff({
name: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile',
addExtensions: ['.anything'],
processTitle: 'hacker',
cwdFlag: 'cwd',
configPathFlag: 'hackerfile',
preloadFlag: 'require',
completionFlag: 'completion',
completions: function (type) {
console.log('Completions not implemented.');
}
});
Sugar for setting processTitle
, moduleName
, configName
& configPathFlag
automatically.
Type: String
Default: null
These are equivalent:
new Liftoff({
processTitle: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile',
configPathFlag: 'hackerfile'
});
new Liftoff({name:'hacker'});
Sets which module your application expects to find locally when being run.
Type: String
Default: null
Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.
Type: String
Default: null
Explicitly add custom extensions to include when searching for a configuration file. Node supports .js
, .json
& .node
natively, so there is no need to add these.
An example usage would be setting this to ['rc']
. With a configName of .myapp
, Liftoff would then look for .myapp{rc,.js,.json,.node}
Type: Array
Default: []
Sets what the process title will be.
Type: String
Default: null
Sets what flag to use for altering the current working directory. For example, myapp --cwd ../
would invoke your application as though you'd called it from the parent of your current directory.
Type: String
Default: cwd
Sets what flag to use for defining the path to your configfile. For example, myapp --myappfile /var/www/project/Myappfile.js
would explicitly specify the location of your config file. Note: Liftoff will assume the current working directory is the directory containing the config file unless an alternate location is specified using cwdFlag
.
Type: String
Default: same as configName
These are functionally indentical:
myapp --myappfile /var/www/project/Myappfile.js
myapp --cwd /var/www/project
These will run myapp from a shared directory as though it were located in another project:
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project1
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project2
Sets what flag to use for pre-loading modules. For example, myapp --require coffee-script
would require a local version of coffee-script (if available) before attempting to find your configuration file. If your required module registers a new
require.extension, it will be included as an option when looking for a file matching configName
.
Type: String
Default: "require"
A method to handle bash/zsh/whatever completions.
Type: Function
Default: null
Emitted when a module is pre-loaded.
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('require', function (name, module) {
console.log('Requiring external module: '+name+'...');
// automatically register coffee-script extensions
if (name === 'coffee-script') {
module.register();
}
});
Emitted when a requested module cannot be preloaded.
var Hacker = new Liftoff({name:'hacker'});
Hacker.on('requireFail', function (name, err) {
console.log('Unable to load:', name, err);
});
A function to start your application. When invoked, this
will be your instance of Liftoff. The env
param will contain the following keys:
argv
: cli arguments, as parsed by minimist, or as passed in manually.cwd
: the current working directorypreload
: an array of modules that liftoff tried to pre-loadvalidExtensions
: an array of supported extensions for your config fileconfigNameRegex
: the regular expression used to find your config fileconfigPath
: the full path to your configuration file (if found)configBase
: the base directory of your configuration file (if found)modulePath
: the full path to the local module your project relies on (if found)modulePackage
: the contents of the local module's package.json (if found)
Manually specify command line arguments. Useful for invoking the CLI programmatically.
Type: Object
Default: null
Check out the hacker project to see a working example of this tool.
To try the example, do the following:
- Install the sample project
hacker
withnpm install -g hacker
. - Make a
Hackerfile.js
with some arbitrary javascript it. - Install hacker next to it with
npm install hacker
. - Run
hacker
while in the same parent folder.
For extra credit, try writing your Hackerfile
in coffeescript. Then, run hacker --require coffee-script
. Make sure you install coffee-script locally, though.