Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 233 lines (185 sloc) 7.95 kB
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
1 # Shell: applications with pluggable middleware
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
2
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
3 Shell brings a Connect inspired API, Express inspired routing, and other
4 similar functionality to console based applications.
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
5
e86f814 @wdavidw Add main functionnalities in readme
authored
6 * Run both in shell mode and command mode
7 * First class citizen for console application (arrows, ctrl-a, ctrl-u,...)
8 * User friendly with history, help messages and many other plugings
9 * Foundation to structure and build complex based applications
10 * Command matching, parameters and advanced functionnalities found in Express routing
11 * Flexible architecture based on middlewares for plugin creation and routing enhancement
12 * Familiar API for those of us using Connect or Express
13 * Predifined commands with plugins for Redis, HTTP servers, Cloud9, CoffeeScript, ...
14
f31f02a @wdavidw Add change and license file
authored
15 ## Installation
16
17 Shell is open source and licensed under the new BSD license.
18
19 ```bash
20 npm install shell
21 ```
22
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
23 ## Example: a simple Redis client
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
24
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
25 ```javascript
1b24eda @ubun2 Correct formatting.
ubun2 authored
26 var shell = require('shell');
27 // Initialization
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
28 var app = new shell( { chdir: __dirname } )
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
29 // Middleware registration
1b24eda @ubun2 Correct formatting.
ubun2 authored
30 app.configure(function() {
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
31 app.use(function(req, res, next){
32 app.client = require('redis').createClient()
33 next()
34 });
1b24eda @ubun2 Correct formatting.
ubun2 authored
35 app.use(shell.history({
36 shell: app
37 }));
38 app.use(shell.completer({
39 shell: app
40 }));
41 app.use(shell.redis({
42 config: 'redis.conf',
43 pidfile: 'redis.pid'
44 }));
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
45 app.use(shell.router({
46 shell: app
47 }));
1b24eda @ubun2 Correct formatting.
ubun2 authored
48 app.use(shell.help({
49 shell: app,
50 introduction: true
51 }));
52 });
53 // Command registration
54 app.cmd('redis keys :pattern', 'Find keys', function(req, res, next){
55 app.client.keys(req.params.pattern, function(err, keys){
56 if(err){ return res.styles.red(err.message), next(); }
57 res.cyan(keys.join('\n')||'no keys');
58 res.prompt();
569168a @wdavidw Emit command events
authored
59 });
1b24eda @ubun2 Correct formatting.
ubun2 authored
60 });
61 // Event notification
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
62 app.on('quit', function(){
63 app.client.quit();
1b24eda @ubun2 Correct formatting.
ubun2 authored
64 });
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
65 ```
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
66
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
67 ## Creating and Configuring a Shell
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
68
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
69 ```javascript
481c1aa @wdavidw Fix read me example
authored
70 var app = shell();
1b24eda @ubun2 Correct formatting.
ubun2 authored
71 app.configure(function() {
72 app.use(shell.history({shell: app}));
73 app.use(shell.completer({shell: app}));
74 app.use(shell.help({shell: app, introduction: true}));
75 });
76 app.configure('prod', function() {
77 app.set('title', 'Production Mode');
78 });
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
79 ```
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
80
6425b74 @wdavidw Change workspace discovery starting point to the root script; Introdu…
authored
81 ## Shell settings
3bf667c @wdavidw Rename options to settings; Add set function
authored
82
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
83 The constructor `shell` takes an optional object. Options are:
c333996 @wdavidw Readme with sample, creation, history and completer documentations
authored
84
6425b74 @wdavidw Change workspace discovery starting point to the root script; Introdu…
authored
85 - `chdir` , Changes the current working directory of the process, a string of the directory, boolean true will default to the `workspace` (in which case `workspace` must be provided or discoverable)
86 - `prompt` , Character for command prompt, Defaults to ">>"
87 - `stdin` , Source to read from
88 - `stdout` , Destination to write to
89 - `env` , Running environment, Defaults to the `env` setting (or `NODE_ENV` if defined, eg: `production`, `develepment`).
90 - `isShell` , Detect whether the command is runned inside a shell are as a single command.
91 - `noPrompt` , Do not prompt the user for a command, usefull to plug your own starting mechanisme (eg: starting with a question).
92 - `workspace` , Project root directory or null if none was found. The discovery strategy start from the current working directory and traverse each parent dir looking for a `node_module` directory or a `package.json` file.
3bf667c @wdavidw Rename options to settings; Add set function
authored
93
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
94 Shell settings may be set by calling `app.set('key', value)`. They can be retrieved by calling the same function without a second argument.
3bf667c @wdavidw Rename options to settings; Add set function
authored
95
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
96 ```javascript
1b24eda @ubun2 Correct formatting.
ubun2 authored
97 var app = new shell({
98 chdir: true
99 });
100 app.set('env', 'prod');
101 app.configure('prod', function() {
102 console.log(app.set('env'));
103 });
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
104 ```
37976bd @wdavidw Add 'project_dir' property
authored
105
6425b74 @wdavidw Change workspace discovery starting point to the root script; Introdu…
authored
106 As with Express, `app.configure` allows the customization of plugins for all or specific environments, while `app.use` registers plugins.
107
108 If `app.configure` is called without specifying the environment as the first argument, the provided callback is always called. Otherwise, the environment must match the `env` setting or the global variable `NODE_ENV`.
37976bd @wdavidw Add 'project_dir' property
authored
109
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
110 ## Middlewares and plugins
111
112 Shell is build on a middleware architecute. When a command is issued, multiple callbacks are executed sequentially until one decide to stop the process (calling `res.prompt()` or `shell.quit`. Those callbacks are called middlewares. A callback recieve 3 arguments: a `request` object, a `response` object and the next callback. Traditionnaly, `request` deals with `stdin` while `response` deals with `stdout`.
113
114 A plugin is simply a function which configure and return a middleware. Same plugin also enrich the Shell application with new routes and functions.
115
569168a @wdavidw Emit command events
authored
116 ## Shell events
117
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
118 The following events may be emitted:
569168a @wdavidw Emit command events
authored
119
452c1a8 @wdavidw Test router; Test error; Emit error event
authored
120 - `"command"` , listen to all executed commands, provide the command name as first argument.
121 - `#{command}` , listen to a particular event.
122 - `"quit"` , called when the application is about to quit.
123 - `"error"` , called on error providing the error object as the first callback argument.
124 - `"exit"` , called when the process exit.
569168a @wdavidw Emit command events
authored
125
63995ee @wdavidw Process are now daemon by default, change detached property to attach
authored
126 ## Request parameter
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
127
128 The request object contains the following properties:
129
130 - `shell` , (required) A reference to your shell application.
131 - `command` , Command entered by the user
132 - `params` , Parameters object extracted from the command, defined by the `shell.router` middleware
133 - `qestion` , Ask questions with optionally suggested and default answers
268a5d4 @wdavidw Remove `Shell.confirm`, now only in req; New `styles.unstyle` function
authored
134 - `confirm` , Ask a question expecting a boolean answer
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
135
63995ee @wdavidw Process are now daemon by default, change detached property to attach
authored
136 ## Response parameter
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
137
138 The response object inherits from styles containing methods for printing, coloring and bolding:
139
140 Colors:
141
142 - `black`
143 - `white`
144 - `yellow`
145 - `blue`
146 - `cyan`
147 - `green`
148 - `magenta`
149 - `red`
150 - `bgcolor`
151 - `color`
152 - `nocolor`
153
154 Style:
155
156 - `regular`
157 - `weight`
158 - `bold`
159
160 Display:
161
63995ee @wdavidw Process are now daemon by default, change detached property to attach
authored
162
163 - `prompt` , Exits the current command and return user to the prompt.
164 - `ln` , Print a new line
165 - `print` , Print a text
166 - `println` , Print a text followed by a new line
167 - `reset` , Stop any formating like color or bold
168 - `pad` , Print a text with a fixed padding
169 - `raw` , Return a text
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
170
452c1a8 @wdavidw Test router; Test error; Emit error event
authored
171 ## Router plugin
e789dea @wdavidw Add response object to middlewares; Add prompt message option
authored
172
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
173 The functionality provided by the 'routes' module is very similar to that of
174 express. Options passed during creation are:
264465f @wdavidw Rehabilitate params in router; Add sensitive option; Improve readme
authored
175
a8353f5 @wdavidw Simplify history and change configuration attributes
authored
176 - `shell` , (required) A reference to your shell application.
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
177 - `sensitive` , (optional) Defaults to `false`, set to `true` if the match should be case sensitive.
264465f @wdavidw Rehabilitate params in router; Add sensitive option; Improve readme
authored
178
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
179 New routes are defined with the `cmd` method. A route is made of pattern against which the user command is matched, an optional description and one or more route specific middlewares to handle the command. The pattern is either a string or a regular expression. Middlewares receive three parameters: a request object, a response object, and a function. Command parameters are substituted and made available in the `params` object of the request parameter.
264465f @wdavidw Rehabilitate params in router; Add sensitive option; Improve readme
authored
180
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
181 Parameters can have restrictions in parenthesis immediately following the
182 keyword, as in express: `:id([0-9]+)`. See the `list` route in the example:
183
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
184 ```javascript
1b24eda @ubun2 Correct formatting.
ubun2 authored
185 var app = new shell();
186 app.configure(function(){
187 app.use(shell.router({
188 shell: app
189 }));
190 });
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
191
1b24eda @ubun2 Correct formatting.
ubun2 authored
192 // Route middleware
193 var auth = function(req, res, next){
194 if(req.params.uid == process.getuid()){
195 next()
196 }else{
197 throw new Error('Not me');
198 }
199 }
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
200
1b24eda @ubun2 Correct formatting.
ubun2 authored
201 // Global parameter substitution
202 app.param('uid', function(req, res, next){
203 exec('whoami', function(err, stdout, sdterr){
204 req.params.username = stdout;
205 next();
206 });
207 });
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
208
1b24eda @ubun2 Correct formatting.
ubun2 authored
209 // Simple command
210 app.cmd('help', function(req, res){
211 res.cyan('Run this command `./ami user ' + process.getuid() + '`');
212 res.prompt()
213 });
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
214
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
215 // Command with parameter
1b24eda @ubun2 Correct formatting.
ubun2 authored
216 app.cmd('user :uid', auth, function(req, res){
217 res.cyan('Yes, you are ' + req.params.username);
218 });
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
219
9b37c93 @wdavidw Remove question from shell, only in request; Simplify, fix and test q…
authored
220 // Command with contrained parameter
221 app.cmd('user :id([0-9]+)', function(req, res) {
222 res.cyan('User id is ' + req.params.id);
b11c4c0 @rf Fixing typos and adding `format` specifiers
rf authored
223 res.prompt();
224 });
41aa0a8 Added syntax highlighting for code blocks. Several fixes to English …
Tony authored
225 ```
e789dea @wdavidw Add response object to middlewares; Add prompt message option
authored
226
e090a66 @wdavidw Add Russ and Tony as contributors
authored
227 Contributors
228 ------------
229
230 * David Worms : <https://github.com/wdavidw>
231 * Tony: <https://github.com/Zearin>
232 * Russ Frank : <https://github.com/russfrank>
Something went wrong with that request. Please try again.