0
# Output Formatting
1

2
Flexible output formatting system supporting multiple formats for different integration needs including programmatic consumption, reporting, and human-readable display.
3

4
## Capabilities
5

6
### Tree Format
7

8
Converts license data to hierarchical tree-formatted string for human-readable console output.
9

10
```javascript { .api }
11
/**
12
 * Convert license data to tree-formatted string
13
 * @param data - License data from init() callback
14
 * @returns Tree-formatted string representation
15
 */
16
function asTree(data: LicenseData): string;
17
```
18

19
**Usage Example:**
20

21
```javascript
22
const checker = require("license-checker");
23

24
checker.init({ start: process.cwd() }, function(err, packages) {
25
  const treeOutput = checker.asTree(packages);
26
  console.log(treeOutput);
27
});
28
```
29

30
**Example Output:**
31
```
32
├─ chalk@2.4.2
33
│  ├─ licenses: MIT
34
│  ├─ repository: https://github.com/chalk/chalk
35
│  └─ publisher: Sindre Sorhus
36
├─ debug@3.2.7
37
│  ├─ licenses: MIT  
38
│  ├─ repository: https://github.com/visionmedia/debug
39
│  └─ publisher: TJ Holowaychuk
40
└─ nopt@4.0.3
41
   ├─ licenses: ISC
42
   ├─ repository: https://github.com/npm/nopt
43
   └─ publisher: Isaac Z. Schlueter
44
```
45

46
### Console Print
47

48
Directly prints license data in tree format to console.
49

50
```javascript { .api }
51
/**
52
 * Print license data in tree format to console
53
 * @param data - License data from init() callback
54
 */
55
function print(data: LicenseData): void;
56
```
57

58
**Usage Example:**
59

60
```javascript
61
checker.init({ start: process.cwd() }, function(err, packages) {
62
  checker.print(packages); // Outputs directly to console
63
});
64
```
65

66
### Summary Format
67

68
Generates a summary showing license usage statistics with counts.
69

70
```javascript { .api }
71
/**
72
 * Convert license data to summary format showing license counts
73
 * @param data - License data from init() callback
74
 * @returns Summary string with license usage statistics
75
 */
76
function asSummary(data: LicenseData): string;
77
```
78

79
**Usage Example:**
80

81
```javascript
82
checker.init({ start: process.cwd() }, function(err, packages) {
83
  const summary = checker.asSummary(packages);
84
  console.log(summary);
85
});
86
```
87

88
**Example Output:**
89
```
90
├─ MIT: 45
91
├─ ISC: 12
92
├─ Apache-2.0: 8
93
├─ BSD-3-Clause: 5
94
├─ BSD-2-Clause: 3
95
└─ GPL-3.0: 1
96
```
97

98
### CSV Format
99

100
Exports license data as comma-separated values for spreadsheet import and data analysis.
101

102
```javascript { .api }
103
/**
104
 * Convert license data to CSV format
105
 * @param data - License data from init() callback
106
 * @param customFormat - Optional custom field specification
107
 * @param csvComponentPrefix - Optional prefix for component column
108
 * @returns CSV-formatted string
109
 */
110
function asCSV(data: LicenseData, customFormat?: CustomFormat, csvComponentPrefix?: string): string;
111

112
interface CustomFormat {
113
  [fieldName: string]: string | boolean;
114
}
115
```
116

117
**Usage Examples:**
118

119
```javascript
120
// Basic CSV output
121
const csvOutput = checker.asCSV(packages);
122
console.log(csvOutput);
123

124
// CSV with custom format
125
const customCsv = checker.asCSV(packages, {
126
  "name": "",
127
  "version": "", 
128
  "licenses": "",
129
  "repository": "",
130
  "publisher": ""
131
});
132

133
// CSV with component prefix
134
const prefixedCsv = checker.asCSV(packages, customFormat, "my-app");
135
```
136

137
**Example Output (basic):**
138
```csv
139
"module name","license","repository"
140
"chalk@2.4.2","MIT","https://github.com/chalk/chalk"
141
"debug@3.2.7","MIT","https://github.com/visionmedia/debug"
142
"nopt@4.0.3","ISC","https://github.com/npm/nopt"
143
```
144

145
**Example Output (with custom format):**
146
```csv
147
"module name","name","version","licenses","repository","publisher"
148
"chalk@2.4.2","chalk","2.4.2","MIT","https://github.com/chalk/chalk","Sindre Sorhus"
149
"debug@3.2.7","debug","3.2.7","MIT","https://github.com/visionmedia/debug","TJ Holowaychuk"
150
```
151

152
**Example Output (with component prefix):**
153
```csv
154
"component","module name","license","repository"
155
"my-app","chalk@2.4.2","MIT","https://github.com/chalk/chalk"
156
"my-app","debug@3.2.7","MIT","https://github.com/visionmedia/debug"
157
```
158

159
### Markdown Format
160

161
Converts license data to markdown format for documentation and reports.
162

163
```javascript { .api }
164
/**
165
 * Convert license data to markdown format
166
 * @param data - License data from init() callback  
167
 * @param customFormat - Optional custom field specification
168
 * @returns Markdown-formatted string
169
 */
170
function asMarkDown(data: LicenseData, customFormat?: CustomFormat): string;
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
// Basic markdown output
177
const mdOutput = checker.asMarkDown(packages);
178
console.log(mdOutput);
179

180
// Markdown with custom format
181
const customMd = checker.asMarkDown(packages, {
182
  "licenses": "",
183
  "publisher": "",
184
  "description": ""
185
});
186
```
187

188
**Example Output (basic):**
189
```markdown
190
[chalk@2.4.2](https://github.com/chalk/chalk) - MIT
191
[debug@3.2.7](https://github.com/visionmedia/debug) - MIT  
192
[nopt@4.0.3](https://github.com/npm/nopt) - ISC
193
```
194

195
**Example Output (with custom format):**
196
```markdown
197
 - **[chalk@2.4.2](https://github.com/chalk/chalk)**
198
    - licenses: MIT
199
    - publisher: Sindre Sorhus
200
    - description: Terminal string styling done right
201
 - **[debug@3.2.7](https://github.com/visionmedia/debug)**
202
    - licenses: MIT
203
    - publisher: TJ Holowaychuk
204
    - description: small debugging utility
205
```
206

207
### Custom Format Specification
208

209
The `customFormat` parameter allows controlling which fields are included in CSV and Markdown output:
210

211
```javascript { .api }
212
interface CustomFormat {
213
  [fieldName: string]: string | boolean;
214
}
215
```
216

217
**Field Options:**
218
- **String values**: Use as default if field missing from package data
219
- **Boolean `false`**: Exclude field from output entirely
220
- **Empty string `""`**: Include field if present in package, empty if missing
221
- **Custom default**: Use custom value if field missing
222

223
**Available Fields:**
224
- `name` - Package name
225
- `version` - Package version
226
- `licenses` - License identifier(s)
227
- `repository` - Repository URL
228
- `publisher` - Author/publisher name
229
- `email` - Author email
230
- `url` - Author/package URL
231
- `path` - Package filesystem path
232
- `licenseFile` - License file path
233
- `licenseText` - Full license text content
234
- `copyright` - Copyright information
235
- `description` - Package description
236
- `homepage` - Package homepage URL
237
- `keywords` - Package keywords array
238
- Any other field from package.json
239

240
**Custom Format Example:**
241

242
```javascript
243
const customFormat = {
244
  "name": "",                    // Include package name
245
  "version": "",                 // Include version
246
  "licenses": "",               // Include licenses
247
  "repository": "",             // Include repository
248
  "description": "No description", // Default value if missing
249
  "licenseText": false,         // Exclude license text
250
  "private": false,             // Exclude private flag
251
  "customField": "N/A"          // Custom default for missing field
252
};
253

254
checker.init({
255
  start: process.cwd(),
256
  customFormat: customFormat
257
}, function(err, packages) {
258
  const csv = checker.asCSV(packages, customFormat);
259
  const md = checker.asMarkDown(packages, customFormat);
260
});
261
```
262

263
### CLI Integration
264

265
All formatting functions integrate with the CLI tool through command-line flags:
266

267
```bash
268
# Tree format (default)
269
license-checker
270

271
# JSON format  
272
license-checker --json
273

274
# CSV format
275
license-checker --csv
276

277
# Markdown format
278
license-checker --markdown
279

280
# Summary format
281
license-checker --summary
282

283
# Custom format from file
284
license-checker --customPath ./custom-format.json
285

286
# Output to file
287
license-checker --json --out licenses.json
288
license-checker --csv --out licenses.csv
289
```
290

291
The CLI automatically applies appropriate formatting based on flags and handles file output, colored terminal display, and format-specific options like CSV component prefixes.