1 | # shell-quote <sup>[![Version Badge][npm-version-svg]][package-url]</sup>
|
2 |
|
3 | [![github actions][actions-image]][actions-url]
|
4 | [![coverage][codecov-image]][codecov-url]
|
5 | [![License][license-image]][license-url]
|
6 | [![Downloads][downloads-image]][downloads-url]
|
7 |
|
8 | [![npm badge][npm-badge-png]][package-url]
|
9 |
|
10 | Parse and quote shell commands.
|
11 |
|
12 | # example
|
13 |
|
14 | ## quote
|
15 |
|
16 | ``` js
|
17 | var quote = require('shell-quote').quote;
|
18 | var s = quote([ 'a', 'b c d', '$f', '"g"' ]);
|
19 | console.log(s);
|
20 | ```
|
21 |
|
22 | output
|
23 |
|
24 | ```
|
25 | a 'b c d' \$f '"g"'
|
26 | ```
|
27 |
|
28 | ## parse
|
29 |
|
30 | ``` js
|
31 | var parse = require('shell-quote').parse;
|
32 | var xs = parse('a "b c" \\$def \'it\\\'s great\'');
|
33 | console.dir(xs);
|
34 | ```
|
35 |
|
36 | output
|
37 |
|
38 | ```
|
39 | [ 'a', 'b c', '\\$def', 'it\'s great' ]
|
40 | ```
|
41 |
|
42 | ## parse with an environment variable
|
43 |
|
44 | ``` js
|
45 | var parse = require('shell-quote').parse;
|
46 | var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' });
|
47 | console.dir(xs);
|
48 | ```
|
49 |
|
50 | output
|
51 |
|
52 | ```
|
53 | [ 'beep', '--boop=/home/robot' ]
|
54 | ```
|
55 |
|
56 | ## parse with custom escape character
|
57 |
|
58 | ``` js
|
59 | var parse = require('shell-quote').parse;
|
60 | var xs = parse('beep --boop="$PWD"', { PWD: '/home/robot' }, { escape: '^' });
|
61 | console.dir(xs);
|
62 | ```
|
63 |
|
64 | output
|
65 |
|
66 | ```
|
67 | [ 'beep', '--boop=/home/robot' ]
|
68 | ```
|
69 |
|
70 | ## parsing shell operators
|
71 |
|
72 | ``` js
|
73 | var parse = require('shell-quote').parse;
|
74 | var xs = parse('beep || boop > /byte');
|
75 | console.dir(xs);
|
76 | ```
|
77 |
|
78 | output:
|
79 |
|
80 | ```
|
81 | [ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
|
82 | ```
|
83 |
|
84 | ## parsing shell comment
|
85 |
|
86 | ``` js
|
87 | var parse = require('shell-quote').parse;
|
88 | var xs = parse('beep > boop # > kaboom');
|
89 | console.dir(xs);
|
90 | ```
|
91 |
|
92 | output:
|
93 |
|
94 | ```
|
95 | [ 'beep', { op: '>' }, 'boop', { comment: '> kaboom' } ]
|
96 | ```
|
97 |
|
98 | # methods
|
99 |
|
100 | ``` js
|
101 | var quote = require('shell-quote').quote;
|
102 | var parse = require('shell-quote').parse;
|
103 | ```
|
104 |
|
105 | ## quote(args)
|
106 |
|
107 | Return a quoted string for the array `args` suitable for using in shell
|
108 | commands.
|
109 |
|
110 | ## parse(cmd, env={})
|
111 |
|
112 | Return an array of arguments from the quoted string `cmd`.
|
113 |
|
114 | Interpolate embedded bash-style `$VARNAME` and `${VARNAME}` variables with
|
115 | the `env` object which like bash will replace undefined variables with `""`.
|
116 |
|
117 | `env` is usually an object but it can also be a function to perform lookups.
|
118 | When `env(key)` returns a string, its result will be output just like `env[key]`
|
119 | would. When `env(key)` returns an object, it will be inserted into the result
|
120 | array like the operator objects.
|
121 |
|
122 | When a bash operator is encountered, the element in the array with be an object
|
123 | with an `"op"` key set to the operator string. For example:
|
124 |
|
125 | ```
|
126 | 'beep || boop > /byte'
|
127 | ```
|
128 |
|
129 | parses as:
|
130 |
|
131 | ```
|
132 | [ 'beep', { op: '||' }, 'boop', { op: '>' }, '/byte' ]
|
133 | ```
|
134 |
|
135 | # install
|
136 |
|
137 | With [npm](http://npmjs.org) do:
|
138 |
|
139 | ```
|
140 | npm install shell-quote
|
141 | ```
|
142 |
|
143 | # license
|
144 |
|
145 | MIT
|
146 |
|
147 | [package-url]: https://npmjs.org/package/shell-quote
|
148 | [npm-version-svg]: https://versionbadg.es/ljharb/shell-quote.svg
|
149 | [deps-svg]: https://david-dm.org/ljharb/shell-quote.svg
|
150 | [deps-url]: https://david-dm.org/ljharb/shell-quote
|
151 | [dev-deps-svg]: https://david-dm.org/ljharb/shell-quote/dev-status.svg
|
152 | [dev-deps-url]: https://david-dm.org/ljharb/shell-quote#info=devDependencies
|
153 | [npm-badge-png]: https://nodei.co/npm/shell-quote.png?downloads=true&stars=true
|
154 | [license-image]: https://img.shields.io/npm/l/shell-quote.svg
|
155 | [license-url]: LICENSE
|
156 | [downloads-image]: https://img.shields.io/npm/dm/shell-quote.svg
|
157 | [downloads-url]: https://npm-stat.com/charts.html?package=shell-quote
|
158 | [codecov-image]: https://codecov.io/gh/ljharb/shell-quote/branch/main/graphs/badge.svg
|
159 | [codecov-url]: https://app.codecov.io/gh/ljharb/shell-quote/
|
160 | [actions-image]: https://img.shields.io/endpoint?url=https://github-actions-badge-u3jn4tfpocch.runkit.sh/ljharb/shell-quote
|
161 | [actions-url]: https://github.com/ljharb/shell-quote/actions
|