From 9272668e00fc9bb85d2bf8337f1f2b05206506df Mon Sep 17 00:00:00 2001 From: Branden Visser Date: Sun, 20 Apr 2014 11:41:58 -0400 Subject: [PATCH] Added whoami example --- README.md | 111 +++++++++++++++++++++++------- commands/help.js | 3 +- examples/whoami/commands/greet.js | 13 ++++ examples/whoami/commands/iam.js | 26 +++++++ examples/whoami/run.js | 26 +++++++ 5 files changed, 152 insertions(+), 27 deletions(-) create mode 100644 examples/whoami/commands/greet.js create mode 100644 examples/whoami/commands/iam.js create mode 100644 examples/whoami/run.js diff --git a/README.md b/README.md index d2ad3f0..43b8cd1 100644 --- a/README.md +++ b/README.md @@ -9,54 +9,113 @@ for your CLI utility. Currently: -* Multi-line command support -* Customizable PS1 / PS2 prompts -* Mutable environment for stateful shell sessions -* Help / command list index +* Multi-line commands +* Custom PS1 and PS2 prompts +* API and Model for creating and loading your own commands +* Environment support for stateful CLI sessions -Future: +Planned: -* Automated auto-complete functionality +* Using "Up" arrow key to load previous commands +* Using "Tab" auto-complete based on loaded ## Examples -Create an interactive shell with just a `help` and `quit` command: +### Whoami + +See `examples/whoami` for this tutorial. + +**Sample Setup:** -**Code:** ```javascript var Corporal = require('corporal'); -new Corporal().start(); +var corporal = new Corporal({ + + // Commands will be loaded from JS files in the "commands" directory. Each command + // exports an object that contains data and functions for describing and invoking + // the command + 'commands': __dirname + '/commands' + + // Define an initial environment + // * The arbitrary "me" environment variable defines who the "current user" is + // * The ps1 variable pulls the current value of the "me" variable to put in the PS1 prompt + // * The the "colors" module is used to provide "bold" styling on the PS1 + // * The ps2 variable is used as the prompt prefix in multi-line commands. "> " is also + // the default value + 'env': { + 'me': 'unknown' + 'ps1' '%(me)s$ '.bold, + 'ps2': '> ' + } +}); + +// Start the interactive prompt +corporal.start(); ``` -**Session:** -``` -> help -List of available commands: +**Sample Command:** -help: Show a dialog of all available commands. -quit: Quit the interactive shell. +`commands/iam.js` command is used to set in the environment the current user. The name of the JS file will indicate what the name of the command should be: -> blah -Invalid command: blah +```javascript +var optimist = require('optimist'); -List of available commands: +module.exports = { + + // Required: Defines a description for the command that can be seen in command listings + // and help dialogs + 'description': 'Tell the session who you are.', + + // Optional: Additional text to show how the command can be used. Can be multi-line, etc... + 'help': 'Usage: iam ', -help: Show a dialog of all available commands. -quit: Quit the interactive shell. + // The function that actually invokes the command. Optimist is being used here to parse + // the array arguments that were provided to your command, however you can use whatever + // utility you want + 'invoke': function(session, args, callback) { -> help help + // Parse the arguments using optimist + var argv = optimist.parse(args); -Show a dialog of all available commands. + // Update the environment to indicate who the specified user now is + session.env('me', argv._[0] || 'unknown'); -Usage: help [] + // The callback always needs to be invoked to finish the command + return callback(); + } +}; +``` + +**Sample Usage:** + +``` +~/Source/node-corporal$ node examples/whoami/run.js +unknown$ help +List of available commands: + +help : Show a dialog of all available commands. +quit : Quit the interactive shell. +greet: Give a greeting to the current user. +iam : Tell the session who you are. -> help quit +unknown$ greet +Hello, unknown +unknown$ iam branden +branden$ greet +Hello, branden +branden$ iam \ +> \ +> steve +steve$ help iam -Quit the interactive shell. +Tell the session who you are. -> quit +Usage: iam + +steve$ quit ``` + ## License Copyright (c) 2014 Branden Visser diff --git a/commands/help.js b/commands/help.js index a54b9be..7e9e749 100644 --- a/commands/help.js +++ b/commands/help.js @@ -15,7 +15,8 @@ module.exports = { console.log(''); if (_.isString(command.help)) { - process.stdout.write(command.help); + console.log(command.help); + console.log(''); } } else { console.log('No command found with name: "%s"', commandName); diff --git a/examples/whoami/commands/greet.js b/examples/whoami/commands/greet.js new file mode 100644 index 0000000..35e3c0e --- /dev/null +++ b/examples/whoami/commands/greet.js @@ -0,0 +1,13 @@ +module.exports = { + + // Required: Defines a description for the command that can be seen in command listings + // and help dialogs + 'description': 'Give a greeting to the current user.', + + // The function that actually invokes the command. Simply pull the current state of the + // "me" environment variable and print it to the console. + 'invoke': function(session, args, callback) { + console.log('Hello, ' + session.env('me').bold); + return callback(); + } +}; diff --git a/examples/whoami/commands/iam.js b/examples/whoami/commands/iam.js new file mode 100644 index 0000000..1e6dfc8 --- /dev/null +++ b/examples/whoami/commands/iam.js @@ -0,0 +1,26 @@ +var optimist = require('optimist'); + +module.exports = { + + // Required: Defines a description for the command that can be seen in command listings + // and help dialogs + 'description': 'Tell the session who you are.', + + // Optional: Additional text to show how the command can be used. Can be multi-line, etc... + 'help': 'Usage: iam ', + + // The function that actually invokes the command. Optimist is being used here to parse + // the array arguments that were provided to your command, however you can use whatever + // utility you want + 'invoke': function(session, args, callback) { + + // Parse the arguments using optimist + var argv = optimist.parse(args); + + // Update the environment to indicate who the specified user now is + session.env('me', argv._[0] || 'unknown'); + + // The callback always needs to be invoked to finish the command + return callback(); + } +}; diff --git a/examples/whoami/run.js b/examples/whoami/run.js new file mode 100644 index 0000000..36b7d5b --- /dev/null +++ b/examples/whoami/run.js @@ -0,0 +1,26 @@ +var colors = require('colors'); +var path = require('path'); + +var Corporal = require('../../index'); +var corporal = new Corporal({ + + // Commands will be loaded from JS files in the "commands" directory. Each command + // exports an object that contains data and functions for describing and invoking + // the command + 'commands': path.join(__dirname, 'commands'), + + // Define an initial environment: + // * The arbitrary "me" environment variable defines who the "current user" is + // * The ps1 variable pulls the current value of the "me" variable to put in the PS1 prompt + // * The the "colors" module is used to provide "bold" styling on the PS1 + // * The ps2 variable is used as the prompt prefix in multi-line commands. "> " is also + // the default value + 'env': { + 'me': 'unknown', + 'ps1': '%(me)s$ '.bold, + 'ps2': '> ' + } +}); + +// Start the interactive prompt +corporal.start();