Capitano allows you to craft powerful command line applications, your way.
capitano = require('capitano')
capitano.command
signature: 'utils print <title> [words...]'
options: [
signature: 'date'
boolean: true
alias: [ 'd' ]
]
action: (params, options) ->
log = ''
if options.date
log += "#{new Date()} "
log += "#{params.title}: #{params.words}"
console.log(log)
capitano.run(process.argv)
$ myCoolApp utils print Error Something very bad happened
Error: Something very bad happened
$ myCoolApp utils print Error Something very bad happened -d
Thu Dec 18 2014 14:49:27 GMT-0400 (BOT) Error: Something very bad happened
Install capitano by running:
$ npm install --save capitano
Register a command. Capitano understands the following options, but you can pass custom options to do nifty things (see the examples section):
The command signature. If it's *, it will match anything that is not matched by other commands.
Function to call when the signature is matched. This function gets passed a parameter and an options object.
Array of objects describing the options specific to this command. See the options section for more information.
Register a global option, which will be accessible from every command (and from outside too!) so be careful about naming collisions!
It accepts an object containing the following options:
The option signature excluding any parameter (foo instead of foo <bar>).
Whether the option is boolean (doesn't accepts any parameters). It defaults to false. If parameter is defined, then boolean should be false.
The name of the parameter, excluding required/optional tags (bar instead of <bar>). Notice that if you set boolean: true, then you have to omit this option.
Define an alias, or a set of alias for an option. Aliases can contain single letter abbreviations (f, l) or full option names (baz, foo).
Run and execute the application given a set of arguments (usually process.argv):
capitano.run(process.argv)
Note: capitano.run is a shorcut function for capitano.execute(capitano.parse(argv)). You will usually use this function, however you can use parse() and execute() in particular situations when you need to differenciate between parsing and executing the commands.
Parse, but not execute the command line arguments (usually process.argv).
It returns a cli object containing three fields:
A string representing the issued command, omitting any option.
An object containing the raw representation of the given options.
An object containing the matches and parsed global options.
It accepts a cli object (returned by capitano.parse()) and
executes the corresponding command, with it's corresponding options.
An object containing the current registered commands an options. As with Capitano you're expected to implement every command (including help, etc) this object comes handy to accomplish a wide range of tasks.
It includes the following fields:
An array containing every registered command so far (with capitano.command())
See the Command class for more information.
An array containing every registered global option so far (with capitano.globalOption()).
See the Option class for more information.
A self explanatory function that returns a command that matches a specific signature.
Get command that matches a signature, without taking parameters into account.
This means that a command app create <id> will be matched by a signature app create.
An object containing some settings used by Capitano.
It includes the following fields:
signatures.wildcard (string) The wildcard symbol. Defaults to *.actions.commandNotFound(signature) The function called when a command was not found. By default, it prints a boring Command not found: <signature> and exits with an error code 1.actions.onError(Error) The function called when there is an error. By default, it prints the error message and exits with an error code 1.Pro tip: If you want to modify these settings, do it as early as possible (before registering any commands/global options) as some settings are used when performing the mentioned tasks.
The Capitano Command class contains the following public fields:
See the Signature class.
An array of Option classes.
A predicate method that returns true if a command represents a wildcard.
The Capitano Signature class contains the following public fields:
A predicate method that returns true if the signature has at least one parameter.
A predicate method that returns true if the signature has at least one variadic parameter.
A predicate method that returns true if the signature represents a wildcard.
The Capitano Option class contains the following public fields:
See Signature class.
A string or array of string alias.
Whether the option is boolean or not.
An option parameter (optional).
Capitano is very flexible, allowing you to implement all sort of crazy stuff. Here I present some common patterns that I've been doing on Capitano. If you have an interesting idea that you think it's worth to share, please submit a PR!
Notice this is a very rudimentary help page and lacks features such as printing global options, command specific options, handling correct aligment, etc, but you can at least get an idea on how to implement this for yourself.
capitano = require('capitano')
capitano.command
signature: 'version'
description: 'output version information'
action: ...
capitano.command
signature: 'help'
description: 'output general help page'
action: ->
console.log("Usage: #{myAppName} [COMMANDS] [OPTIONS]")
console.log('\nCommands:\n')
for command in capitano.state.commands
continue if command.isWildcard()
console.log("\t#{command.signature}\t\t\t"#{command.description})
capitano.run(process.argv)
$ app help
Usage: MyCoolApp [COMMANDS] [OPTIONS]
Commands:
version output version information
help output general help page
capitano = require('capitano')
capitano.command
signature: 'version'
description: 'output version information'
help: '''
Software versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software. Within a given version number category (major, minor), these numbers are generally assigned in increasing order and correspond to new developments in the software. At a fine-grained level, revision control is often used for keeping track of incrementally different versions of electronic information, whether or not this information is computer software.
'''
action: ...
capitano.command
signature: 'help [command...]'
description: 'output general help page'
action: (params) ->
return outputGeneralHelp() if not params?
command = capitano.state.getMatchCommand(params.command)
if not command? or command.isWildcard()
return capitano.defaults.actions.commandNotFound(params.command)
console.log(command.help)
capitano.run(process.argv)
$ app help version
Software versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software. Within a given version number category (major, minor), these numbers are generally assigned in increasing order and correspond to new developments in the software. At a fine-grained level, revision control is often used for keeping track of incrementally different versions of electronic information, whether or not this information is computer software.
Run the test suite by doing:
$ gulp test
Before submitting a PR, please make sure that you include tests, and that coffeelint runs without any warning:
$ gulp lint
If you're having any problem, please raise an issue on GitHub.
The project is licensed under the MIT license.
1.0.4
FAQs
Powerful, non opitionated command line parser for serious applications
The npm package capitano receives a total of 2,762 weekly downloads. As such, capitano popularity was classified as popular.
We found that capitano demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.