Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 178 lines (122 sloc) 6.49 kb
46bd905 @polotek README
polotek authored
1 `procstreams` is a little experiment with shell scripting in node.
2
a9f30e1 @polotek update readme
polotek authored
3 This is a rough first attempt. Right now all it does is make it easier
4 to create child processes and compose them together in a similar way to
5 unix command line scripting.
46bd905 @polotek README
polotek authored
6
7 var $p = require('procstreams');
8 $p('cat lines.txt').pipe('wc -l')
a9f30e1 @polotek update readme
polotek authored
9 .data(function(stdout, stderr) {
10 console.log(stdout); // prints number of lines in the file lines.txt
11 });
46bd905 @polotek README
polotek authored
12
13 $p('mkdir foo')
14 .and('cp file.txt foo/')
15 .and('rm file.txt')
a9f30e1 @polotek update readme
polotek authored
16 .on('exit', function() {
17 console.log('done');
18 });
46bd905 @polotek README
polotek authored
19
2dc9468 @polotek more readme updates. license
polotek authored
20 ## procstream function
46bd905 @polotek README
polotek authored
21
a9f30e1 @polotek update readme
polotek authored
22 The procstream function is the main entry point which creates a child
23 process that's pipeable and composable. It takes arguments in several
2dc9468 @polotek more readme updates. license
polotek authored
24 formats. It returns a `ProcStream` object that represents the child process.
46bd905 @polotek README
polotek authored
25
2dc9468 @polotek more readme updates. license
polotek authored
26 procstream(cmd, argsArray, options, callback)
46bd905 @polotek README
polotek authored
27
28 `cmd` can be the name of the command, or an array of strings with cmd and args
29 or a string of cmd + args.
30
31 `args` (optional) can be a string of args or an array of arg strings
32
33 `options` (optional) options object
34
35 `callback` (optional) callback to be called on the "exit" event from the proc.
36 It receives the same arguments as the child process exit callback
37
38 ### options
39
89134c9 @polotek minor readme updates
polotek authored
40 The options object supports all of the options from [`child_process.spawn`](http://nodejs.org/docs/v0.6.5/api/child_processes.html#child_process.spawn) plus
2dc9468 @polotek more readme updates. license
polotek authored
41 a few additions specific to procstreams:
46bd905 @polotek README
polotek authored
42
43 `out` - Boolean that determines if the proc output is directed to the main
44 process output
45
a9f30e1 @polotek update readme
polotek authored
46 By default when a procstream is created, the stdout and stderr of the
47 child process is directed to the stdout and stderr of the calling
48 process. This isn't always what you want. Pass `false` here to disable.
46bd905 @polotek README
polotek authored
49
50 `stderr` - Stream. The stderr of the proc will be directed to this stream if
51 provided
52
a9f30e1 @polotek update readme
polotek authored
53
2dc9468 @polotek more readme updates. license
polotek authored
54 ## ProcStream
55
56 The ProcStream object represents the child process that is being
57 executed. It is an `EventEmitter` and it also has various methods for
58 chaining procstreams together.
59
60
46bd905 @polotek README
polotek authored
61 ### procstream methods
62
63 Each procstream has a set of methods that aid composition. Each of these
a9f30e1 @polotek update readme
polotek authored
64 methods takes as input a procstream or a set of arguments like the
65 procstream function. Each method returns the input procstream so it can
66 be chained.
46bd905 @polotek README
polotek authored
67
a9f30e1 @polotek update readme
polotek authored
68 **proc1.pipe(proc2)**
46bd905 @polotek README
polotek authored
69
c79ae3a @substack updated docs with streaming map pipe example
authored
70 Similar to node's `Stream.pipe`, this is modeled after unix command
a9f30e1 @polotek update readme
polotek authored
71 piping. The stdout of in_proc is directed to the stdin of out_proc.
c79ae3a @substack updated docs with streaming map pipe example
authored
72 Stderr of `proc1` is directed to stderr of `proc2`. This method chains by
73 returning `proc2`.
74
75 `proc2` can also be a node `Stream` object and can be interleaved with piping to
76 commands:
77
78 var $p = require('procstreams');
79
80 $p('cat tests/fixtures/10lines.txt')
81 .pipe('grep even')
82 .pipe('wc -l')
83 .pipe(process.stdout)
84
85 If your `Stream` object has a `write()` function and emits `'data'` events then
86 you can interleave shell commands with streaming map functions:
87
88 var $p = require('../')
89 var Stream = require('stream').Stream
90
91 var grepEven = new Stream
92 grepEven.writable = true
93 grepEven.readable = true
94
95 var data = ''
96 grepEven.write = function (buf) { data += buf }
97 grepEven.end = function () {
98 this.emit('data', data
99 .split('\n')
100 .map(function (line) { return line + '\n' })
101 .filter(function (line) { return line.match(/even/) })
102 .join('')
103 )
104 this.emit('end')
105 }
106
107 $p('cat ../tests/fixtures/10lines.txt')
108 .pipe(grepEven)
109 .pipe('wc -l')
110 .pipe(process.stdout)
46bd905 @polotek README
polotek authored
111
112 **proc1.then(proc2)**
113
a9f30e1 @polotek update readme
polotek authored
114 Like 2 commands run in succession (separated by ';'), the proc1 is run
2dc9468 @polotek more readme updates. license
polotek authored
115 to completion; then proc 2 is run. This method chains by
116 returning proc2.
46bd905 @polotek README
polotek authored
117
118 **proc1.and(proc2)**
119
a9f30e1 @polotek update readme
polotek authored
120 Like the `&&` operator, the proc1 is run to completion; if it exits with
121 a 0 error code, proc2 is run. If the error code is non-zero, proc2 is
2dc9468 @polotek more readme updates. license
polotek authored
122 not run. This method chains by returning proc2.
46bd905 @polotek README
polotek authored
123
124 **proc1.or(proc2)**
125
a9f30e1 @polotek update readme
polotek authored
126 Like the `||` operator, the proc1 is run to completion; if it exits with
127 a non-zero error code, proc2 is run. If the error code is zero, proc2 is
2dc9468 @polotek more readme updates. license
polotek authored
128 not run. This method chains by returning proc2.
46bd905 @polotek README
polotek authored
129
a9f30e1 @polotek update readme
polotek authored
130 **proc.data(fn)**
46bd905 @polotek README
polotek authored
131
a9f30e1 @polotek update readme
polotek authored
132 $('cat some-large-file.txt')
133 .data(function(stdout, stderr) {
134 // process the full output of the proc
135 })
136
137 This function will cause the output of the proc to be collected and
138 passed to this callback on exit. The callback receives the stdout and
2dc9468 @polotek more readme updates. license
polotek authored
139 stderr of the proc. This method chains by
140 returning the same proc.
a9f30e1 @polotek update readme
polotek authored
141
142 **proc.out()**
143
144 Direct the stdout and stderr of the proc to the calling process. This is
2dc9468 @polotek more readme updates. license
polotek authored
145 useful if you pass `out: false` as an option but want to pipe out later. This method chains by
146 returning the same proc.
a9f30e1 @polotek update readme
polotek authored
147
148
4e62868 @polotek minor readme edits
polotek authored
149 ## Why?
46bd905 @polotek README
polotek authored
150
a9f30e1 @polotek update readme
polotek authored
151 Shell scripting languages are extremely powerful, but they're also
152 annoyingly esoteric. They're difficult to read because of the terse and
153 obscure syntax. And for most web programmers they only come up often
154 enough to be frustrating. Many people now use general purpose languages
155 like python and ruby because they're more familiar and easily installed
156 in most environments.
46bd905 @polotek README
polotek authored
157
a9f30e1 @polotek update readme
polotek authored
158 But currently node isn't very good for this type of scripting. So
159 procstreams is my attempt to add some nice abstractions to the node api
160 that enable easier scripting in javascript.
46bd905 @polotek README
polotek authored
161
162
4e62868 @polotek minor readme edits
polotek authored
163 ## TODO
46bd905 @polotek README
polotek authored
164
165 * Add options for converting the format of proc output, e.g. numbers, json, etc.
166 * Add better ways to take action at various events in the proc chain execution
2dc9468 @polotek more readme updates. license
polotek authored
167
168
169 ## The MIT License
170
171 Copyright (c)
172
173 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
174
175 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
176
177 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.