Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smikhalevski/argcat
🙀 The simplest CLI arguments parser.
https://github.com/smikhalevski/argcat
argument-parser cli
Last synced: 4 days ago
JSON representation
🙀 The simplest CLI arguments parser.
- Host: GitHub
- URL: https://github.com/smikhalevski/argcat
- Owner: smikhalevski
- License: mit
- Created: 2022-12-06T18:38:13.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-10-24T19:43:09.000Z (about 1 year ago)
- Last Synced: 2024-11-01T13:38:57.345Z (13 days ago)
- Topics: argument-parser, cli
- Language: TypeScript
- Homepage:
- Size: 955 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
The simplest CLI arguments parser.
```sh
npm install --save-prod argcat
```
# Usage
```ts
import { parseArgs } from 'argcat';
const options = parseArgs(process.argv.slice(2));
```
Arguments prefixed with a `'--'` are treated as options:
```ts
parseArgs(['--foo']);
// ⮕ { foo: [] }
```
Options can have values:
```ts
parseArgs(['--foo', 'bar']);
// ⮕ { foo: ['bar'] }
parseArgs(['--foo', '--qux', 'bar']);
// ⮕ { foo: [], qux: ['bar'] }
```
If an option is repeated multiple times then all values are captured in an array:
```ts
parseArgs(['--foo', 'bar', '--foo', 'qux']);
// ⮕ { foo: ['bar', 'qux'] }
```
Arguments that aren't prefixed with minus chars are stored under `''` key:
```ts
parseArgs(['foo', 'bar']);
// ⮕ { '': ['foo', 'bar'] }
```
There's a special option `'--'`, after which all arguments are stored under `'--'` key:
```ts
parseArgs(['--', '--foo', 'bar']);
// ⮕ { '--': ['--foo', 'bar'] }
```
Mark an option as a flag to prevent value capturing:
```ts
parseArgs(['--foo', 'bar']);
// ⮕ { foo: ['bar'] }
parseArgs(['--foo', 'bar'], { flags: ['foo'] });
// ⮕ { foo: true, '': ['bar'] }
```
Flag options have `true` value instead of an array.
# Shorthands
By default, shorthand options are ignored:
```ts
parseArgs(['-x']);
// ⮕ {}
```
To preserve shorthands, use `keepShorthands` option:
```ts
parseArgs(['-x'], { keepShorthands: true });
// ⮕ { x: [] }
```
Multiple shorthands can be combined:
```ts
parseArgs(['-abc'], { keepShorthands: true });
// ⮕ { a: [], b: [], c: [] }
```
Use `shorthand` mapping to expand shorthands:
```ts
parseArgs(['-x'], { shorthands: { x: 'foo' } });
// ⮕ { foo: [] }
```
Shorthand options can have values:
```ts
parseArgs(['-x', 'bar'], { keepShorthands: true });
// ⮕ { x: ['bar'] }
parseArgs(['-abc', 'bar'], { keepShorthands: true });
// ⮕ { a: [], b: [], c: ['bar'] }
```
# Commands
argcat doesn't have a special treatment for commands syntax, but it can be easily emulated:
```ts
const argv = ['push', '--tags'];
const result = parseArgs(argv, { flags: ['tags'] });
// ⮕ { '': ['push'], tags: true }
```
The first element of `''` is a command:
```ts
const command = result[''].shift();
if (command === 'push') {
// Push it to the limit
}
```
Note that this approach allows user to specify options before the command:
```ts
const result = parseArgs(['--tags', 'push'], { flags: ['tags'] });
// ⮕ { '': ['push'], tags: true }
```
# Type coercion
Combine argcat with [Doubter](https://github.com/smikhalevski/doubter#readme) to validate parsed arguments and to coerce
their types.
```ts
import { parseArgs } from 'argcat';
import * as d from 'doubter';
// 1️⃣ Define the shape of a CLI options object
const optionsShape = d
.object({
age: d.number()
})
.strip();
const options = optionsShape.parse(
// 2️⃣ Convert process.argv.slice(2) to options
parseArgs(['--age', '42']),
// 3️⃣ Enable type coercion
{ coerce: true }
);
// ⮕ { age: 42 }
```
Cat by Laura Graves