0
# Core Parsing
1
2
The main parsing function that converts command-line arguments into structured JavaScript objects. This is the primary interface for yargs-parser.
3
4
## Import
5
6
```typescript
7
import parser from "yargs-parser";
8
```
9
10
## API
11
12
```typescript { .api }
13
function parser(args: ArgsInput, opts?: Partial<Options>): Arguments;
14
15
type ArgsInput = string | any[];
16
17
interface Arguments {
18
/** Non-option arguments */
19
_: (string | number)[];
20
/** Arguments after the end-of-options flag `--` */
21
'--'?: (string | number)[];
22
/** All remaining options */
23
[argName: string]: any;
24
}
25
```
26
27
## Basic Usage
28
29
### Parse Array of Arguments
30
31
```typescript
32
import parser from "yargs-parser";
33
34
// Parse process arguments
35
const argv = parser(process.argv.slice(2));
36
37
// Parse custom array
38
const result = parser(['--foo', 'bar', '--number', '42', 'positional']);
39
console.log(result);
40
// Output: { _: ['positional'], foo: 'bar', number: 42 }
41
```
42
43
### Parse String Arguments
44
45
```typescript
46
// Parse argument string
47
const result = parser("--foo=99 --bar hello -x 33");
48
console.log(result);
49
// Output: { _: [], foo: 99, bar: 'hello', x: 33 }
50
51
// Parse complex string with positional args
52
const complex = parser("command --verbose --file input.txt output.txt");
53
console.log(complex);
54
// Output: { _: ['command', 'output.txt'], verbose: true, file: 'input.txt' }
55
```
56
57
## Option Processing
58
59
### Boolean Options
60
61
```typescript
62
// Short and long boolean flags
63
const booleans = parser(['-v', '--debug', '--no-color']);
64
console.log(booleans);
65
// Output: { _: [], v: true, debug: true, color: false }
66
```
67
68
### String and Number Options
69
70
```typescript
71
// Automatic type inference
72
const mixed = parser(['--name', 'Alice', '--port', '3000', '--ratio', '0.75']);
73
console.log(mixed);
74
// Output: { _: [], name: 'Alice', port: 3000, ratio: 0.75 }
75
```
76
77
### Array Options
78
79
```typescript
80
// Multiple values create arrays
81
const arrays = parser(['--file', 'a.txt', '--file', 'b.txt', '--tag', 'dev', '--tag', 'test']);
82
console.log(arrays);
83
// Output: { _: [], file: ['a.txt', 'b.txt'], tag: ['dev', 'test'] }
84
```
85
86
### Short Option Groups
87
88
```typescript
89
// Combined short options
90
const grouped = parser(['-abc', 'value']);
91
console.log(grouped);
92
// Output: { _: [], a: true, b: true, c: 'value' }
93
```
94
95
### Camel Case Expansion
96
97
```typescript
98
// Hyphenated options become camelCase
99
const camelCase = parser(['--foo-bar', 'value', '--multi-word-option']);
100
console.log(camelCase);
101
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value', 'multi-word-option': true, multiWordOption: true }
102
```
103
104
### Dot Notation
105
106
```typescript
107
// Nested object creation
108
const nested = parser(['--db.host', 'localhost', '--db.port', '5432', '--server.name', 'api']);
109
console.log(nested);
110
// Output: { _: [], db: { host: 'localhost', port: 5432 }, server: { name: 'api' } }
111
```
112
113
### End-of-Options Handling
114
115
```typescript
116
// Arguments after -- are treated as positional
117
const endOfOptions = parser(['--verbose', '--', '--not-an-option', 'file.txt']);
118
console.log(endOfOptions);
119
// Output: { _: [], verbose: true, '--': ['--not-an-option', 'file.txt'] }
120
```
121
122
## Advanced Usage
123
124
### Type Coercion with Options
125
126
```typescript
127
// Explicit type specification
128
const typed = parser(['--count', '5', '--name', 'test', '--debug'], {
129
number: ['count'],
130
string: ['name'],
131
boolean: ['debug']
132
});
133
console.log(typed);
134
// Output: { _: [], count: 5, name: 'test', debug: true }
135
```
136
137
### Aliases
138
139
```typescript
140
// Define option aliases
141
const withAliases = parser(['-n', 'Alice', '-v'], {
142
alias: {
143
name: ['n'],
144
verbose: ['v']
145
}
146
});
147
console.log(withAliases);
148
// Output: { _: [], n: 'Alice', name: 'Alice', v: true, verbose: true }
149
```
150
151
### Default Values
152
153
```typescript
154
// Provide default values
155
const withDefaults = parser(['--name', 'Bob'], {
156
default: {
157
port: 3000,
158
debug: false,
159
name: 'Anonymous'
160
}
161
});
162
console.log(withDefaults);
163
// Output: { _: [], name: 'Bob', port: 3000, debug: false }
164
```
165
166
## Error Handling
167
168
The main parser function does not throw errors for invalid input but may return unexpected results. For error handling, use the `detailed` parsing mode.
169
170
```typescript
171
// Basic parsing continues with invalid input
172
const result = parser(['--invalid-number', 'not-a-number']);
173
console.log(result);
174
// Output: { _: [], 'invalid-number': 'not-a-number' }
175
```