0
# Argument Parsing
1

2
Core command-line argument parsing functionality with comprehensive type validation and shorthand support. The main interface for processing command-line options.
3

4
## Capabilities
5

6
### Main Parsing Function
7

8
Parses command-line arguments with type validation and shorthand expansion.
9

10
```javascript { .api }
11
/**
12
 * Parse command line arguments with type validation and shorthand expansion
13
 * @param types - Object defining expected types for each option
14
 * @param shorthands - Object mapping shorthand names to full option arrays
15
 * @param args - Arguments to parse (defaults to process.argv)
16
 * @param slice - Where to start parsing (defaults to 2)
17
 * @returns Parsed options object with argv metadata
18
 */
19
function nopt(
20
  types?: object,
21
  shorthands?: object,
22
  args?: string[],
23
  slice?: number
24
): ParsedOptions;
25

26
interface ParsedOptions {
27
  [key: string]: any;
28
  argv: {
29
    remain: string[];    // Arguments after option parsing
30
    cooked: string[];    // Arguments after shorthand expansion  
31
    original: string[];  // Original arguments before processing
32
  };
33
}
34
```
35

36
**Usage Examples:**
37

38
```javascript
39
const nopt = require("nopt");
40
const path = require("path");
41

42
// Define types and shorthands
43
const knownOpts = {
44
  "verbose": Boolean,
45
  "output": path,
46
  "count": Number,
47
  "files": [String, Array]  // Can be string or array of strings
48
};
49

50
const shortHands = {
51
  "v": ["--verbose"],
52
  "o": ["--output"],
53
  "c": ["--count"]
54
};
55

56
// Parse arguments
57
const parsed = nopt(knownOpts, shortHands, process.argv, 2);
58
console.log(parsed);
59

60
// Example with custom arguments
61
const customArgs = ["--verbose", "-o", "/tmp/output", "--count=5", "file1.txt"];
62
const result = nopt(knownOpts, shortHands, customArgs, 0);
63
// Result: { verbose: true, output: "/tmp/output", count: 5, argv: {...} }
64
```
65

66
### Advanced Parsing Features
67

68
**Shorthand Combinations:**
69
```javascript
70
// Single character shorthands can be combined: -abc = -a -b -c
71
const shortHands = {
72
  "a": ["--alpha"],
73
  "b": ["--beta"], 
74
  "c": ["--charlie"]
75
};
76

77
// Command: -abc
78
// Expands to: --alpha --beta --charlie
79
```
80

81
**Negation Patterns:**
82
```javascript
83
// --no-verbose sets verbose to false
84
const parsed = nopt({ verbose: Boolean }, {}, ["--no-verbose"]);
85
// Result: { verbose: false, argv: {...} }
86
```
87

88
**Array Options:**
89
```javascript
90
const types = { files: [String, Array] };
91

92
// Multiple values: --files file1.txt --files file2.txt
93
// Result: { files: ["file1.txt", "file2.txt"] }
94

95
// Single value: --files single.txt  
96
// Result: { files: "single.txt" }
97
```
98

99
### Error Handling
100

101
Configure custom handlers for different parsing scenarios:
102

103
```javascript
104
const nopt = require("nopt");
105

106
// Set global handlers
107
nopt.invalidHandler = function(key, value, type, data) {
108
  console.error(`Invalid value '${value}' for option '${key}' (expected ${type})`);
109
};
110

111
nopt.unknownHandler = function(key) {
112
  console.error(`Unknown option: ${key}`);
113
};
114

115
nopt.abbrevHandler = function(short, long) {
116
  console.log(`Expanded '${short}' to '${long}'`);
117
};
118

119
// Parse with handlers active
120
const result = nopt(types, shorthands, args);
121
```
122

123
## Types
124

125
```javascript { .api }
126
// Main parsing result interface
127
interface ParsedOptions {
128
  [key: string]: any;
129
  argv: ArgumentMetadata;
130
}
131

132
interface ArgumentMetadata {
133
  remain: string[];    // Non-option arguments remaining after parsing
134
  cooked: string[];    // All arguments after shorthand expansion
135
  original: string[];  // Original arguments before any processing
136
  toString(): string;  // JSON representation of original arguments
137
}
138

139
// Error handler function signatures
140
type InvalidHandler = (key: string, value: any, type: any, data: object) => void;
141
type UnknownHandler = (key: string, nextValue?: string) => void;
142
type AbbrevHandler = (short: string, long: string) => void;
143
```