0
# Console Interface
1

2
Plop's console interface provides user interaction functions for displaying help, selecting generators, initializing plopfiles, and showing visual feedback during operations.
3

4
## Capabilities
5

6
### Generator Selection
7

8
Interactive generator selection when multiple generators are available.
9

10
```javascript { .api }
11
/**
12
 * Display generator selection list to user
13
 * @param plopList - Array of available generators with name and description
14
 * @param message - Optional custom selection message
15
 * @returns Promise resolving to selected generator name
16
 */
17
async function chooseOptionFromList(plopList, message);
18
```
19

20
**Generator List Format:**
21

22
```javascript { .api }
23
interface GeneratorInfo {
24
  name: string;           // Generator name
25
  description?: string;   // Optional description
26
}
27
```
28

29
**Usage Examples:**
30

31
```javascript
32
import { chooseOptionFromList } from "plop/src/console-out.js";
33

34
const generators = [
35
  { name: "component", description: "React component generator" },
36
  { name: "page", description: "Next.js page generator" }
37
];
38

39
const selectedGenerator = await chooseOptionFromList(
40
  generators,
41
  "Please choose a generator:"
42
);
43
```
44

45
### Help System
46

47
Display comprehensive help information for users.
48

49
```javascript { .api }
50
/**
51
 * Display help screen with usage information and available options
52
 */
53
function displayHelpScreen();
54
```
55

56
The help screen includes:
57
- Usage examples for different command patterns
58
- Complete list of CLI options and flags
59
- Examples of bypass argument usage
60
- Advanced options for power users
61

62
### Generator Help
63

64
Show specific help for individual generators.
65

66
```javascript { .api }
67
/**
68
 * Display help message for a specific generator showing available prompts
69
 * @param generator - Generator object with prompts configuration
70
 */
71
function getHelpMessage(generator);
72
```
73

74
**Generator Format:**
75

76
```javascript { .api }
77
interface Generator {
78
  prompts: Prompt[];      // Array of inquirer prompts
79
  name: string;           // Generator name
80
  description?: string;   // Generator description
81
}
82

83
interface Prompt {
84
  name: string;           // Prompt name for CLI arguments
85
  message: string;        // Prompt message text
86
  help?: string;          // Optional help text
87
  type: string;           // Inquirer prompt type
88
}
89
```
90

91
### Plopfile Initialization
92

93
Create initial plopfile configurations for new projects.
94

95
```javascript { .api }
96
/**
97
 * Create initial plopfile.js or plopfile.ts in current directory
98
 * @param force - Overwrite existing plopfile if present (default: false)
99
 * @param useTypescript - Generate TypeScript plopfile (default: false)
100
 * @throws Error if plopfile exists and force is false
101
 */
102
function createInitPlopfile(force, useTypescript);
103
```
104

105
**Generated JavaScript Plopfile:**
106

107
```javascript
108
export default function (plop) {
109
  plop.setGenerator('basics', {
110
    description: 'this is a skeleton plopfile',
111
    prompts: [],
112
    actions: []
113
  });
114
}
115
```
116

117
**Generated TypeScript Plopfile:**
118

119
```typescript
120
import type { NodePlopAPI } from 'plop'
121

122
export default async function (plop: NodePlopAPI) {
123

124
}
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
import { createInitPlopfile } from "plop/src/console-out.js";
131

132
// Create basic JavaScript plopfile
133
createInitPlopfile(false, false);
134

135
// Create TypeScript plopfile, overwriting existing
136
createInitPlopfile(true, true);
137
```
138

139
### Action Type Display
140

141
Visual mapping of action types to console symbols for better user experience.
142

143
```javascript { .api }
144
/**
145
 * Map action type names to display symbols or full names
146
 * @param name - Action type name (add, modify, append, etc.)
147
 * @param noMap - Show full type name instead of symbol
148
 * @returns Formatted display string for action type
149
 */
150
function typeMap(name, noMap);
151
```
152

153
**Type Display Mapping:**
154

155
```javascript { .api }
156
interface TypeDisplayMapping {
157
  function: string;    // "->" (yellow)
158
  add: string;         // "++" (green)
159
  addMany: string;     // "+!" (green)
160
  modify: string;      // "+-" (green/red)
161
  append: string;      // "_+" (green)
162
  skip: string;        // "--" (green)
163
}
164
```
165

166
**Usage Examples:**
167

168
```javascript
169
import { typeMap } from "plop/src/console-out.js";
170

171
console.log(typeMap("add", false));     // "++ " (with green color)
172
console.log(typeMap("add", true));      // "add" (dimmed)
173
console.log(typeMap("modify", false));  // "+-" (green/red)
174
```
175

176
## Input Processing
177

178
### Bypass Data Processing
179

180
Process and validate bypass arguments for generators.
181

182
```javascript { .api }
183
/**
184
 * Combine different types of bypass data for generator prompts
185
 * @param generator - Generator object with prompts configuration
186
 * @param bypassArr - Array of positional bypass arguments
187
 * @param plopArgV - Named arguments from CLI (--name=value format)
188
 * @returns Array of processed bypass values
189
 */
190
function combineBypassData(generator, bypassArr, plopArgV);
191
```
192

193
**Processing Rules:**
194

195
- Validates named arguments against prompt names
196
- Merges positional and named bypass arguments
197
- Converts undefined values to "_" placeholders
198
- Throws errors for invalid arguments or too many values
199

200
**Usage Examples:**
201

202
```javascript
203
import { combineBypassData } from "plop/src/bypass.js";
204

205
const generator = {
206
  name: "component",
207
  prompts: [
208
    { name: "name", type: "input" },
209
    { name: "type", type: "list" }
210
  ]
211
};
212

213
// Positional arguments
214
const bypass1 = combineBypassData(generator, ["MyComponent", "react"], {});
215
// Result: ["MyComponent", "react"]
216

217
// Named arguments
218
const bypass2 = combineBypassData(generator, [], { name: "MyComponent", type: "react" });
219
// Result: ["MyComponent", "react"]
220

221
// Mixed arguments
222
const bypass3 = combineBypassData(generator, ["MyComponent"], { type: "react" });
223
// Result: ["MyComponent", "react"]
224
```
225

226
## Console Styling
227

228
Plop uses chalk for colored console output:
229

230
- **Green**: Successful operations, added files
231
- **Red**: Errors, failed operations
232
- **Yellow**: Warnings, function indicators
233
- **Blue**: Information messages, plop branding
234
- **Gray/Dim**: Secondary information, help text
235

236
## Error Messages
237

238
Standard error message formats:
239

240
```javascript { .api }
241
const ERROR_FORMATS = {
242
  noPlopfile: "[PLOP] No plopfile found",
243
  noGenerators: "[PLOP] No generator found in plopfile",
244
  generatorNotFound: '[PLOP] Could not find a generator for "{name}"',
245
  tooManyArgs: '[PLOP] Too many bypass arguments passed for "{generator}"',
246
  invalidArg: '[PLOP] "{arg}" is an invalid argument for "{generator}"',
247
  readError: "[PLOP] Something went wrong with reading your plop file",
248
  initExists: '"{filename}" already exists at this location.'
249
};
250
```