# argv-split

> Split argv(argument vector) and handle special cases, such as quoted values.

Latest version **3.2.1** (published 2024-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install argv-split
pnpm add argv-split
yarn add argv-split
bun add argv-split
```

## Health

**Score 25/100 (F)** — status: maintenance-mode.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.1 |
| Published | 2024-11-19 |
| First published | 2014-08-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 0 |
| Unpacked size | 9.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 10 |
| Author | Kael |
| Maintainers | kael |
| Keywords | argv, argument-vector, split, quote, quoted-value, balance |

## Links

- npm: https://www.npmjs.com/package/argv-split
- Repository: https://github.com/kaelzhang/node-argv-split
- Homepage: https://github.com/kaelzhang/node-argv-split#readme
- Issues: https://github.com/kaelzhang/node-argv-split/issues
- npm.io page: https://npm.io/package/argv-split

## Recent versions

- 3.2.1 (latest) — 2024-11-19
- 3.2.0 — 2024-11-19
- 3.1.0 — 2024-11-19
- 3.0.0 — 2024-11-19
- 2.0.1 — 2017-03-25
- 2.0.0 — 2017-03-25
- 1.0.1 — 2016-04-16
- 1.0.0 — 2015-11-21
- 0.1.1 — 2014-08-13
- 0.1.0 — 2014-08-13

## README

[![Build Status](https://github.com/kaelzhang/node-argv-split/actions/workflows/nodejs.yml/badge.svg)](https://github.com/kaelzhang/node-argv-split/actions/workflows/nodejs.yml)

# argv-split

Split argv(argument vector) and handle special cases, such as quoted or escaped values.

## Why?

```js
const split = require('split')

const mkdir = 'mkdir "foo bar"'
mkdir.split(' ')    // ['mkdir', '"foo', 'bar"']  -> Oops!
split(mkdir)        // ['mkdir', 'foo bar']       -> Oh yeah!

const mkdir2 = 'mkdir foo\\ bar'.split(' ')
mkdir2.split(' ')   // ['mkdir', 'foo\\', 'bar']  -> Oops!
split(mkdir2)       // ['mkdir', 'foo bar']       -> Oh yeah!
```

## `argv-split` handles all special cases with complete unit tests.

```sh
# shell command:        javascript array:
foo a\ b                # ['foo', 'a b']
foo \'                  # ['foo', '\\\'']
foo \"                  # ['foo', '\\"']
foo "a b"               # ['foo', 'a b']
foo "a\ b"              # ['foo', 'a\\ b']
foo '\'                 # ['foo', '\\']
foo --abc="a b"         # ['foo', '--abc=a b']
foo --abc=a\ b          # ['foo', '--abc=a b']

# argv-split also handles line feeds
foo \
    --abc=a\ b          # ['foo', '--abc=a b']

# etc
```

```js
split('foo \\\n    --abc=a\\ b')    // ['foo', '--abc=a b']
```

## Error Codes

### `UNMATCHED_SINGLE`

If a command missed the closing single quote, the error will throw:

Shell command:

```sh
foo --abc 'abc
```

```js
try {
  split('foo --abc \'abc')
} catch (e) {
  console.log(e.code)   // 'UNMATCHED_SINGLE'
}
```

### `UNMATCHED_DOUBLE`

If a command missed the closing double quote, the error will throw:

```sh
foo --abc "abc
```

### `ESCAPED_EOF`

If a command unexpectedly ends with a `\`, the error will throw:

```sh
foo --abc a\# if there is nothing after \, the error will throw
foo --abc a\ # if there is a whitespace after, then -> ['foo', '--abc', 'a ']
```

### `NON_STRING`

If the argument passed to `split` is not a string, the error will throw

```js
split(undefined)
```

## Install

```sh
$ npm i argv-split
```

# Methods

## split(string) -> Array<string>

Splits a string, and balance quoted parts. The usage is quite simple, see examples above.

Returns `Array<string>`


## split.join(args, options?) -> string

Join the given array of argument vectors into a valid argument string

New in `3.1.0`

- **args** `Array<string>` arguments to be joined
- **options?** `Object=`
  - **quote** `string="` should we use single quote or double quote when a certain argument needs to be quoted. Defaults to `"`

```js
'command ' + join(['foo "bar', "'baz"])

// command "foo \"bar" "'baz"
```

### Handle Line Feeds

There is a special value of `split.LF` which could help us to create valid commands with line feeds:

```js
'kubectl' + join(['apply', '--prune', '-f', 'manifest.yaml', split.LF, '-l', 'app=nginx'])

// kubectl apply --prune -f manifest.yaml \
// -l app=nginx
```

## License

MIT

---
_Source: https://npm.io/package/argv-split · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._