0
# Detailed Parsing
1

2
Advanced parsing mode that returns comprehensive information including error details, alias mappings, and parsing metadata. This mode is primarily used by the yargs framework itself but can be useful for debugging and advanced use cases.
3

4
## Import
5

6
```typescript
7
import parser from "yargs-parser";
8
```
9

10
## API
11

12
```typescript { .api }
13
function parser.detailed(args: ArgsInput, opts?: Partial<Options>): DetailedArguments;
14

15
interface DetailedArguments {
16
  /** An object representing the parsed value of `args` */
17
  argv: Arguments;
18
  /** Populated with an error object if an exception occurred during parsing */
19
  error: Error | null;
20
  /** The inferred list of aliases built by combining lists in opts.alias */
21
  aliases: Dictionary<string[]>;
22
  /** Any new aliases added via camel-case expansion */
23
  newAliases: Dictionary<boolean>;
24
  /** Any new argument created by opts.default, no aliases included */
25
  defaulted: Dictionary<boolean>;
26
  /** The configuration loaded from the yargs stanza in package.json */
27
  configuration: Configuration;
28
}
29

30
interface Arguments {
31
  /** Non-option arguments */
32
  _: (string | number)[];
33
  /** Arguments after the end-of-options flag `--` */
34
  '--'?: (string | number)[];
35
  /** All remaining options */
36
  [argName: string]: any;
37
}
38

39
interface Dictionary<T = any> {
40
  [key: string]: T;
41
}
42
```
43

44
## Basic Usage
45

46
```typescript
47
import parser from "yargs-parser";
48

49
const result = parser.detailed(['--foo', 'bar', '--verbose', '-n', 'test'], {
50
  alias: { name: ['n'] },
51
  boolean: ['verbose'],
52
  default: { port: 3000 }
53
});
54

55
console.log(result);
56
```
57

58
Output:
59
```javascript
60
{
61
  argv: { _: [], foo: 'bar', verbose: true, n: 'test', name: 'test', port: 3000 },
62
  error: null,
63
  aliases: { name: ['n'] },
64
  newAliases: {},
65
  defaulted: { port: true },
66
  configuration: { /* full configuration object */ }
67
}
68
```
69

70
## Error Handling
71

72
The detailed parser captures parsing errors in the `error` property:
73

74
```typescript
75
const result = parser.detailed(['--config', 'invalid-file.json'], {
76
  config: ['config']
77
});
78

79
if (result.error) {
80
  console.error('Parsing error:', result.error.message);
81
} else {
82
  console.log('Parsed successfully:', result.argv);
83
}
84
```
85

86
## Alias Information
87

88
### Configured Aliases
89

90
The `aliases` property contains all explicitly configured aliases:
91

92
```typescript
93
const result = parser.detailed(['-v', '--name', 'Alice'], {
94
  alias: {
95
    verbose: ['v'],
96
    name: ['n', 'user']
97
  }
98
});
99

100
console.log(result.aliases);
101
// Output: { verbose: ['v'], name: ['n', 'user'] }
102
```
103

104
### New Aliases from Camel-Case Expansion
105

106
The `newAliases` property tracks aliases created through camel-case expansion:
107

108
```typescript
109
const result = parser.detailed(['--foo-bar', 'value']);
110

111
console.log(result.newAliases);
112
// Output: { fooBar: true }
113
console.log(result.argv);
114
// Output: { _: [], 'foo-bar': 'value', fooBar: 'value' }
115
```
116

117
## Default Value Tracking
118

119
The `defaulted` property identifies which arguments received default values:
120

121
```typescript
122
const result = parser.detailed(['--name', 'Alice'], {
123
  default: {
124
    port: 3000,
125
    debug: false,
126
    name: 'Anonymous'
127
  }
128
});
129

130
console.log(result.defaulted);
131
// Output: { port: true, debug: true }
132
// Note: 'name' is not in defaulted because it was explicitly provided
133
```
134

135
## Configuration Information
136

137
The `configuration` property contains the complete configuration object used for parsing:
138

139
```typescript
140
const result = parser.detailed(['--foo'], {
141
  configuration: {
142
    'camel-case-expansion': false,
143
    'dot-notation': true
144
  }
145
});
146

147
console.log(result.configuration);
148
// Output: Complete configuration with custom and default values
149
```
150

151
## Debugging Usage
152

153
Detailed parsing is particularly useful for debugging argument parsing issues:
154

155
```typescript
156
function debugParser(args: string[], options?: any) {
157
  const result = parser.detailed(args, options);
158
  
159
  console.log('Parsed arguments:', result.argv);
160
  console.log('Configured aliases:', result.aliases);
161
  console.log('Auto-generated aliases:', result.newAliases);
162
  console.log('Defaulted values:', result.defaulted);
163
  
164
  if (result.error) {
165
    console.error('Parsing error:', result.error);
166
  }
167
  
168
  return result.argv;
169
}
170

171
debugParser(['--foo-bar', 'value', '--debug'], {
172
  alias: { debug: ['d'] },
173
  default: { port: 8080 }
174
});
175
```
176

177
## Comparison with Basic Parsing
178

179
```typescript
180
// Basic parsing - returns only the parsed arguments
181
const basic = parser(['--foo', 'bar']);
182
console.log(basic);
183
// Output: { _: [], foo: 'bar' }
184

185
// Detailed parsing - returns comprehensive information
186
const detailed = parser.detailed(['--foo', 'bar']);
187
console.log(detailed.argv);  // Same as basic result
188
console.log(detailed.error); // null
189
console.log(detailed.aliases); // {}
190
console.log(detailed.newAliases); // {}
191
console.log(detailed.defaulted); // {}
192
```
193

194
## Advanced Use Cases
195

196
### Custom Configuration Validation
197

198
```typescript
199
function validateConfig(args: string[], expectedConfig: Partial<Configuration>) {
200
  const result = parser.detailed(args, { configuration: expectedConfig });
201
  
202
  // Verify configuration was applied correctly
203
  for (const [key, value] of Object.entries(expectedConfig)) {
204
    if (result.configuration[key] !== value) {
205
      console.warn(`Configuration mismatch for ${key}: expected ${value}, got ${result.configuration[key]}`);
206
    }
207
  }
208
  
209
  return result;
210
}
211
```
212

213
### Alias Analysis
214

215
```typescript
216
function analyzeAliases(args: string[], options: any) {
217
  const result = parser.detailed(args, options);
218
  
219
  console.log('Explicit aliases used:');
220
  Object.entries(result.aliases).forEach(([key, aliases]) => {
221
    console.log(`  ${key}: ${aliases.join(', ')}`);
222
  });
223
  
224
  console.log('Auto-generated aliases:');
225
  Object.keys(result.newAliases).forEach(alias => {
226
    console.log(`  ${alias} (from camel-case expansion)`);
227
  });
228
  
229
  return result.argv;
230
}
231
```