1 | # shell-quote
|
2 |
|
3 | Parse and quote shell commands.
|
4 |
|
5 | [![build status](https://secure.travis-ci.org/substack/node-shell-quote.png)](http://travis-ci.org/substack/node-shell-quote)
|
6 |
|
7 | [![browser support](https://ci.testling.com/substack/node-shell-quote.png)](https://ci.testling.com/substack/node-shell-quote)
|
8 |
|
9 | # example
|
10 |
|
11 | ## quote
|
12 |
|
13 | ``` js
|
14 | var quote = require('shell-quote').quote;
|
15 | var s = quote([ 'a', 'b c d', '$f', '"g"' ]);
|
16 | console.log(s);
|
17 | ```
|
18 |
|
19 | output
|
20 |
|
21 | ```
|
22 | a 'b c d' \$f '"g"'
|
23 | ```
|
24 |
|
25 | ## parse
|
26 |
|
27 | ``` js
|
28 | var parse = require('shell-quote').parse;
|
29 | var xs = parse('a "b c" \\$def \'it\\\'s great\'');
|
30 | console.dir(xs);
|
31 | ```
|
32 |
|
33 | output
|
34 |
|
35 | ```
|
36 | [ 'a', 'b c', '\\$def', 'it\'s great' ]
|
37 | ```
|
38 |
|
39 | ## parse with an environment variable
|
40 |
|
41 | ``` js
|
42 | var parse = require('shell-quote').parse;
|
43 | var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' });
|
44 | console.dir(xs);
|
45 | ```
|
46 |
|
47 | output
|
48 |
|
49 | ```
|
50 | [ 'beep', '--boop=/home/robot' ]
|
51 | ```
|
52 |
|
53 | ## parse with custom escape charcter
|
54 |
|
55 | ``` js
|
56 | var parse = require('shell-quote').parse;
|
57 | var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' }, { escape: '^' });
|
58 | console.dir(xs);
|
59 | ```
|
60 |
|
61 | output
|
62 |
|
63 | ```
|
64 | [ 'beep', '--boop=/home/robot' ]
|
65 | ```
|
66 |
|
67 | ## parsing shell operators
|
68 |
|
69 | ``` js
|
70 | var parse = require('shell-quote').parse;
|
71 | var xs = parse('beep || boop > /byte');
|
72 | console.dir(xs);
|
73 | ```
|
74 |
|
75 | output:
|
76 |
|
77 | ```
|
78 | [ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
|
79 | ```
|
80 |
|
81 | ## parsing shell comment
|
82 |
|
83 | ``` js
|
84 | var parse = require('shell-quote').parse;
|
85 | var xs = parse('beep > boop # > kaboom');
|
86 | console.dir(xs);
|
87 | ```
|
88 |
|
89 | output:
|
90 |
|
91 | ```
|
92 | [ 'beep', { op: '>' }, 'boop', { comment: '> kaboom' } ]
|
93 | ```
|
94 |
|
95 | # methods
|
96 |
|
97 | ``` js
|
98 | var quote = require('shell-quote').quote;
|
99 | var parse = require('shell-quote').parse;
|
100 | ```
|
101 |
|
102 | ## quote(args)
|
103 |
|
104 | Return a quoted string for the array `args` suitable for using in shell
|
105 | commands.
|
106 |
|
107 | ## parse(cmd, env={})
|
108 |
|
109 | Return an array of arguments from the quoted string `cmd`.
|
110 |
|
111 | Interpolate embedded bash-style `$VARNAME` and `${VARNAME}` variables with
|
112 | the `env` object which like bash will replace undefined variables with `""`.
|
113 |
|
114 | `env` is usually an object but it can also be a function to perform lookups.
|
115 | When `env(key)` returns a string, its result will be output just like `env[key]`
|
116 | would. When `env(key)` returns an object, it will be inserted into the result
|
117 | array like the operator objects.
|
118 |
|
119 | When a bash operator is encountered, the element in the array with be an object
|
120 | with an `"op"` key set to the operator string. For example:
|
121 |
|
122 | ```
|
123 | 'beep || boop > /byte'
|
124 | ```
|
125 |
|
126 | parses as:
|
127 |
|
128 | ```
|
129 | [ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
|
130 | ```
|
131 |
|
132 | # install
|
133 |
|
134 | With [npm](http://npmjs.org) do:
|
135 |
|
136 | ```
|
137 | npm install shell-quote
|
138 | ```
|
139 |
|
140 | # license
|
141 |
|
142 | MIT
|