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