0
# Help System
1

2
Comprehensive help generation system with ANSI styling, customizable sections, and usage message formatting. Supports both automatic help generation and custom help rendering with extensive customization options.
3

4
## Capabilities
5

6
### Help Class
7

8
Core help generation functionality with support for ANSI styling and custom formatting.
9

10
```java { .api }
11
public static class Help {
12
    /**
13
     * Creates a Help instance for the specified command
14
     * @param commandSpec the command specification
15
     */
16
    public Help(CommandSpec commandSpec);
17
    
18
    /**
19
     * Creates a Help instance with custom color scheme
20
     * @param commandSpec the command specification
21
     * @param colorScheme the color scheme for styling
22
     */
23
    public Help(CommandSpec commandSpec, ColorScheme colorScheme);
24
    
25
    /**
26
     * Gets the full synopsis including all options and parameters
27
     */
28
    public String fullSynopsis();
29
    
30
    /**
31
     * Gets a detailed synopsis with custom formatting
32
     * @param synopsisHeadingLength length of synopsis heading
33
     * @param optionSort comparator for sorting options
34
     * @param clusterOptions whether to cluster boolean options
35
     */
36
    public String detailedSynopsis(int synopsisHeadingLength, Comparator<OptionSpec> optionSort, boolean clusterOptions);
37
    
38
    /**
39
     * Gets the complete usage help message
40
     */
41
    public String toString();
42
    
43
    /**
44
     * Gets formatted option list
45
     */
46
    public String optionList();
47
    
48
    /**
49
     * Gets formatted parameter list
50
     */
51
    public String parameterList();
52
    
53
    /**
54
     * Gets formatted command list for subcommands
55
     */
56
    public String commandList();
57
}
58
```
59

60
**Usage Examples:**
61

62
```java
63
@Command(name = "myapp", description = "Example application")
64
class MyApp {
65
    @Option(names = {"-v", "--verbose"}) boolean verbose;
66
    @Parameters(description = "Input files") List<String> files;
67
}
68

69
CommandLine cmd = new CommandLine(new MyApp());
70
Help help = cmd.getHelp();
71

72
// Generate full help text
73
System.out.println(help.toString());
74

75
// Generate just the synopsis
76
System.out.println("Usage: " + help.fullSynopsis());
77

78
// Generate option list only
79
System.out.println("Options:");
80
System.out.println(help.optionList());
81
```
82

83
### Help Section Customization
84

85
Customizable help sections with predefined section keys and custom renderers.
86

87
```java { .api }
88
/**
89
 * Standard help section keys in display order
90
 */
91
public static final String SECTION_KEY_HEADER_HEADING = "headerHeading";
92
public static final String SECTION_KEY_HEADER = "header";
93
public static final String SECTION_KEY_SYNOPSIS_HEADING = "synopsisHeading";
94
public static final String SECTION_KEY_SYNOPSIS = "synopsis";
95
public static final String SECTION_KEY_DESCRIPTION_HEADING = "descriptionHeading";
96
public static final String SECTION_KEY_DESCRIPTION = "description";
97
public static final String SECTION_KEY_PARAMETER_LIST_HEADING = "parameterListHeading";
98
public static final String SECTION_KEY_PARAMETER_LIST = "parameterList";
99
public static final String SECTION_KEY_OPTION_LIST_HEADING = "optionListHeading";
100
public static final String SECTION_KEY_OPTION_LIST = "optionList";
101
public static final String SECTION_KEY_COMMAND_LIST_HEADING = "commandListHeading";
102
public static final String SECTION_KEY_COMMAND_LIST = "commandList";
103
public static final String SECTION_KEY_EXIT_CODE_LIST_HEADING = "exitCodeListHeading";
104
public static final String SECTION_KEY_EXIT_CODE_LIST = "exitCodeList";
105
public static final String SECTION_KEY_FOOTER_HEADING = "footerHeading";
106
public static final String SECTION_KEY_FOOTER = "footer";
107

108
/**
109
 * Interface for rendering help sections
110
 */
111
public interface IHelpSectionRenderer {
112
    String render(Help help);
113
}
114

115
/**
116
 * Factory for creating Help instances
117
 */
118
public interface IHelpFactory {
119
    Help create(CommandSpec commandSpec, ColorScheme colorScheme);
120
}
121
```
122

123
**Usage Example:**
124

125
```java
126
CommandLine cmd = new CommandLine(new MyApp());
127

128
// Customize help section order
129
List<String> sections = Arrays.asList(
130
    Help.SECTION_KEY_HEADER_HEADING,
131
    Help.SECTION_KEY_HEADER,
132
    Help.SECTION_KEY_SYNOPSIS_HEADING,
133
    Help.SECTION_KEY_SYNOPSIS,
134
    Help.SECTION_KEY_DESCRIPTION_HEADING,
135
    Help.SECTION_KEY_DESCRIPTION,
136
    Help.SECTION_KEY_OPTION_LIST_HEADING,
137
    Help.SECTION_KEY_OPTION_LIST,
138
    Help.SECTION_KEY_FOOTER_HEADING,
139
    Help.SECTION_KEY_FOOTER
140
);
141
cmd.setHelpSectionKeys(sections);
142

143
// Custom section renderer
144
Map<String, IHelpSectionRenderer> sectionMap = cmd.getHelpSectionMap();
145
sectionMap.put(Help.SECTION_KEY_HEADER, help -> 
146
    "@|bold,underline Custom Application Header|@%n");
147
cmd.setHelpSectionMap(sectionMap);
148
```
149

150
### ANSI Color Support
151

152
ANSI color and styling support for enhanced help message formatting.
153

154
```java { .api }
155
public enum Ansi {
156
    AUTO, ON, OFF;
157
    
158
    /**
159
     * Enables or disables ANSI colors globally
160
     */
161
    public static void setEnabled(boolean enabled);
162
    
163
    /**
164
     * Checks if ANSI colors are enabled
165
     */
166
    public static boolean isEnabled();
167
}
168

169
/**
170
 * Color scheme for styling help messages
171
 */
172
public static class ColorScheme {
173
    /**
174
     * Creates a default color scheme
175
     */
176
    public ColorScheme();
177
    
178
    /**
179
     * Creates a color scheme with ANSI preference
180
     */
181
    public ColorScheme(Ansi ansi);
182
    
183
    /**
184
     * Applies color markup to text
185
     */
186
    public Text apply(String plainText, String markup);
187
}
188
```
189

190
**Usage Examples:**
191

192
```java
193
// Enable ANSI colors
194
Help.Ansi.setEnabled(true);
195

196
// Create help with color scheme
197
CommandLine cmd = new CommandLine(new MyApp());
198
Help.ColorScheme colorScheme = new Help.ColorScheme(Help.Ansi.ON);
199
cmd.setColorScheme(colorScheme);
200

201
// Print colored help
202
cmd.usage(System.out);
203

204
// Manual color application
205
@Command(name = "app", 
206
         header = "@|bold,underline My Application|@",
207
         description = "@|yellow This is a colored description.|@")
208
class ColoredApp { }
209
```
210

211
### Built-in Help Command
212

213
Pre-built help command for subcommand hierarchies.
214

215
```java { .api }
216
public static final class HelpCommand implements IHelpCommandInitializable, IHelpCommandInitializable2, Runnable, Callable<Integer> {
217
    /**
218
     * Default constructor for built-in help command
219
     */
220
    public HelpCommand();
221
    
222
    /**
223
     * Initializes the help command with parent command context
224
     */
225
    public void init(CommandLine helpCommandLine, Help.Ansi ansi, PrintStream out, PrintStream err);
226
    
227
    /**
228
     * Executes the help command
229
     */
230
    public void run();
231
    
232
    /**
233
     * Executes the help command and returns exit code
234
     */
235
    public Integer call();
236
}
237
```
238

239
**Usage Example:**
240

241
```java
242
@Command(name = "myapp", 
243
         subcommands = {HelpCommand.class, SubCommand1.class, SubCommand2.class})
244
class MyApp {
245
    // Main command implementation
246
}
247

248
// Usage: myapp help [COMMAND]
249
// Shows help for main command or specific subcommand
250
```
251

252
### Help Message Formatting
253

254
Control over help message formatting and layout options.
255

256
```java { .api }
257
/**
258
 * Sets whether line breaks are adjusted for wide CJK characters
259
 */
260
public CommandLine setAdjustLineBreaksForWideCJKCharacters(boolean adjustForWideChars);
261
public boolean isAdjustLineBreaksForWideCJKCharacters();
262

263
/**
264
 * Sets interpolation of variables in help text
265
 */
266
public CommandLine setInterpolateVariables(boolean interpolate);
267
public boolean isInterpolateVariables();
268
```
269

270
**Usage Example:**
271

272
```java
273
@Command(name = "app",
274
         description = "Application version ${COMMAND-VERSION}",
275
         footer = "For more information, visit ${COMMAND-NAME}.example.com")
276
class InterpolatedApp { }
277

278
CommandLine cmd = new CommandLine(new InterpolatedApp());
279
cmd.setInterpolateVariables(true); // Enable variable interpolation
280

281
// Variables like ${COMMAND-NAME}, ${COMMAND-VERSION} will be replaced
282
cmd.usage(System.out);
283
```
284

285
### Static Help Utilities
286

287
Static methods for quick help generation without creating CommandLine instances.
288

289
```java { .api }
290
/**
291
 * Prints usage help to specified output stream
292
 */
293
public static void usage(Object command, PrintStream out);
294
public static void usage(Object command, PrintStream out, Help.Ansi ansi);
295
public static void usage(Object command, PrintStream out, Help.ColorScheme colorScheme);
296

297
/**
298
 * Handles help requests from parse results
299
 */
300
public static boolean printHelpIfRequested(ParseResult parseResult);
301

302
/**
303
 * Executes help request and returns appropriate exit code
304
 */
305
public static Integer executeHelpRequest(ParseResult parseResult);
306
```
307

308
**Usage Examples:**
309

310
```java
311
// Quick help printing
312
CommandLine.usage(new MyApp(), System.out);
313

314
// With ANSI colors
315
CommandLine.usage(new MyApp(), System.out, Help.Ansi.ON);
316

317
// Handle help in parse loop
318
ParseResult parseResult = cmd.parseArgs(args);
319
if (CommandLine.printHelpIfRequested(parseResult)) {
320
    return; // Help was printed, exit early
321
}
322

323
// Execute help with proper exit code
324
Integer exitCode = CommandLine.executeHelpRequest(parseResult);
325
if (exitCode != null) {
326
    System.exit(exitCode);
327
}
328
```
329

330
## Supporting Types
331

332
```java { .api }
333
/**
334
 * Represents styled text with ANSI markup
335
 */
336
public static class Text {
337
    public Text(String plainText);
338
    public String toString();
339
    public int length();
340
}
341

342
/**
343
 * Interface for initializing help commands
344
 */
345
public interface IHelpCommandInitializable {
346
    void init(CommandLine helpCommandLine, Help.Ansi ansi, PrintStream out, PrintStream err);
347
}
348

349
/**
350
 * Extended interface for help command initialization
351
 */
352
public interface IHelpCommandInitializable2 extends IHelpCommandInitializable {
353
    void init(CommandLine helpCommandLine, Help.Ansi ansi, PrintStream out, PrintStream err);
354
}
355
```