tabalot

Tab complete all the things

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
tabalot
2610.8.08 years ago9 years agoMinified + gzip package size for tabalot in KB

Readme

tabalot
Tab complete all the things!
npm install tabalot
tabalot is a node module that lets you build command line apps with rich built in tab completion support

Getting started

Lets make a sample app and link it with npm. Write the example below to a file called app.js
#!/usr/bin/env node
var tab = require('tabalot');

tab('hello')
	(function() {
		console.log('world');
	})

tab.parse();

You need to add a package.json file as well. The one below will make app.js executable as tabtest
{
	"name": "tabtest",
	"bin": {
		"tabtest": "./app.js" // we need a bin name
	}
}

To try the app locally just use npm to link it
npm link # will add the app to your path
And install the tab completion
tabtest completion --save # installs the completion to your bash_completion.d folder
If you use zsh you can install it with
tabtest completion > ~./zshrc
The app is now installed and ready to be tab completed. Open a shell and try the following
tabtest <tab>
tabtest hello <enter>
world
It is as simple as that.

Completing arguments

To complete arguments we just need to pass them to tabalot
tab('hello')
	('--world', '-w', ['world', 'welt', 'verden'])
	('--debug')
	(function(opts) {
		console.log(opts);
	})

In the above program we just added a boolean argument --debug and a --world argument that should complete to one of the 3 values.
Try running
tabtest <tab>
tabtest hello --<tab><tab>       # prints --world --debug
tabtest hello --world <tab><tab> # prints world verden welt
tabtest hello --world v<tab>
tabtest hello --world verden <enter>
The above program will output
{
	world: 'verden',
	debug: false
}

Positional arguments

If you want to complete a positional (or nameless) argument simply omit the name and it will be added as an argument to call function
tab('hello')
	(['world', 'verden', 'welt'])
	(function(world, opts) {
		console.log(world)
	})

Try running
tabtest <tab>
tabtest hello <tab><tab> # prints world verden welt
tabtest hello v<tab>
tabtest hello verden <enter>
The above program will output
verden

Dynamic completion

Instead of passing the static values ['world', 'welt', 'verden'] we can pass an async function to the completer as well
tab('hello')
	('--world', '-w', function(callback) {
		callback(null, ['world', 'welt' 'verden']);
	})
	(function(opts) {
		console.log(opts);
	})

Catch-all route

If you omit the command name from tab that route will be called and tab completed if no one else matches
tab()
	('--world', '-w', ['world', 'welt'])
	(function() {
		console.log('I was called by doing tabtest --world world');
	})

Completion helpers

Tabalot ships with support for a couple of typical completions. Use these by passing @name as the completer.
tab('hello')
	('--file', '@file') // completes a file or directory
	('--dir', '@dir')   // completes a directory
	('--host', '@host') // completes a hostname (by looking at known_hosts)
License
MIT