/** Similar to {@link #usage(PrintStream, Help.Ansi)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}. * @since 3.2 */ public String getUsageMessage(Help.Ansi ansi) { return usage(new StringBuilder(), getHelpFactory().create(getCommandSpec(), Help.defaultColorScheme(ansi))).toString(); } /** Similar to {@link #usage(PrintStream, Help.ColorScheme)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}.
/** Registers the specified subcommand with this Help. * @param commandName the name of the subcommand to display in the usage message * @param command the {@code CommandSpec} or {@code @Command} annotated object to get more information from * @return this Help instance (for method chaining) * @deprecated */ @Deprecated public Help addSubcommand(String commandName, Object command) { commands.put(commandName, getHelpFactory().create(CommandSpec.forAnnotatedObject(command, commandSpec.commandLine().factory), defaultColorScheme(Ansi.AUTO))); return this; }
/** Similar to {@link #usage(PrintStream)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}. * @since 3.2 */ public String getUsageMessage() { return usage(new StringBuilder(), getHelpFactory().create(getCommandSpec(), Help.defaultColorScheme(Help.Ansi.AUTO))).toString(); } /** Similar to {@link #usage(PrintStream, Help.Ansi)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}.
/** Similar to {@link #usage(PrintStream, Help.Ansi)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}. * @since 3.2 */ public String getUsageMessage(Help.Ansi ansi) { return usage(new StringBuilder(), getHelpFactory().create(getCommandSpec(), Help.defaultColorScheme(ansi))).toString(); } /** Similar to {@link #usage(PrintStream, Help.ColorScheme)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}.
/** Registers the specified subcommand with this Help. * @param commandName the name of the subcommand to display in the usage message * @param command the {@code CommandSpec} or {@code @Command} annotated object to get more information from * @return this Help instance (for method chaining) * @deprecated */ @Deprecated public Help addSubcommand(String commandName, Object command) { commands.put(commandName, getHelpFactory().create(CommandSpec.forAnnotatedObject(command, commandSpec.commandLine().factory), defaultColorScheme(Ansi.AUTO))); return this; }
/** Constructs a new {@code Help} instance with a default color scheme, initialized from annotatations * on the specified class and superclasses. * @param command the annotated object to create usage help for * @param ansi whether to emit ANSI escape codes or not */ public Help(Object command, Ansi ansi) { this(command, defaultColorScheme(ansi)); } /** Constructs a new {@code Help} instance with the specified color scheme, initialized from annotatations
/** Similar to {@link #usage(PrintStream)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}. * @since 3.2 */ public String getUsageMessage() { return usage(new StringBuilder(), getHelpFactory().create(getCommandSpec(), Help.defaultColorScheme(Help.Ansi.AUTO))).toString(); } /** Similar to {@link #usage(PrintStream, Help.Ansi)}, but returns the usage help message as a String instead of printing it to the {@code PrintStream}.
new Column(39, 2, WRAP)); TwoOptionsPerRowLayout layout = new TwoOptionsPerRowLayout( Help.defaultColorScheme(ansi), textTable, Help.createMinimalOptionRenderer(),
textTable.indentWrappedLines = 0; Layout layout = new Layout( Help.defaultColorScheme(ansi), textTable, Help.createMinimalOptionRenderer(),
/** * Helper method that may be useful when processing the list of {@code CommandLine} objects that result from successfully * {@linkplain #parse(String...) parsing} command line arguments. This method prints out * {@linkplain #usage(PrintStream, Help.Ansi) usage help} if {@linkplain #isUsageHelpRequested() requested} * or {@linkplain #printVersionHelp(PrintStream, Help.Ansi) version help} if {@linkplain #isVersionHelpRequested() requested} * and returns {@code true}. If the command is a {@link Command#helpCommand()} and {@code runnable} or {@code callable}, * that command is executed and this method returns {@code true}. * Otherwise, if none of the specified {@code CommandLine} objects have help requested, * this method returns {@code false}.<p> * Note that this method <em>only</em> looks at the {@link Option#usageHelp() usageHelp} and * {@link Option#versionHelp() versionHelp} attributes. The {@link Option#help() help} attribute is ignored. * </p><p><b>Implementation note:</b></p><p> * When an error occurs while processing the help request, it is recommended custom Help commands throw a * {@link ParameterException} with a reference to the parent command. This will print the error message and the * usage for the parent command, and will use the exit code of the exception handler if one was set. * </p> * @param parsedCommands the list of {@code CommandLine} objects to check if help was requested * @param out the {@code PrintStream} to print help to if requested * @param err the error string to print diagnostic messages to, in addition to the output from the exception handler * @param ansi for printing help messages using ANSI styles and colors * @return {@code true} if help was printed, {@code false} otherwise * @see IHelpCommandInitializable * @since 3.0 */ public static boolean printHelpIfRequested(List<CommandLine> parsedCommands, PrintStream out, PrintStream err, Help.Ansi ansi) { return printHelpIfRequested(parsedCommands, out, err, Help.defaultColorScheme(ansi)); } /**
@Test public void testMinimalOptionRenderer_rendersFirstDeclaredOptionNameAndDescription() { class Example { @Option(names = {"---long", "-L"}, description = "long description") String longField; @Option(names = {"-b", "-a", "--alpha"}, description = "other") String otherField; } Help.IOptionRenderer renderer = Help.createMinimalOptionRenderer(); Help help = new Help(new Example(), Help.Ansi.ON); Help.IParamLabelRenderer parameterRenderer = help.createDefaultParamLabelRenderer(); OptionSpec option = help.options().get(0); Text[][] row1 = renderer.render(option, parameterRenderer, Help.defaultColorScheme( help.ansi())); assertEquals(1, row1.length); //assertArrayEquals(new String[]{"---long=<longField>", "long description"}, row1[0]); assertArrayEquals(new Text[]{ help.ansi().new Text(format("%s---long%s=%s<longField>%s", "@|fg(yellow) ", "|@", "@|italic ", "|@")), help.ansi().new Text("long description")}, row1[0]); OptionSpec option2 = help.options().get(1); Text[][] row2 = renderer.render(option2, parameterRenderer, Help.defaultColorScheme( help.ansi())); assertEquals(1, row2.length); //assertArrayEquals(new String[]{"-b=<otherField>", "other"}, row2[0]); assertArrayEquals(new Text[]{ help.ansi().new Text(format("%s-b%s=%s<otherField>%s", "@|fg(yellow) ", "|@", "@|italic ", "|@")), help.ansi().new Text("other")}, row2[0]); }
@Test public void testDefaultLayout_addsEachRowToTable() { final Text[][] values = { textArray(Help.Ansi.OFF, "a", "b", "c", "d"), textArray(Help.Ansi.OFF, "1", "2", "3", "4") }; final int[] count = {0}; TextTable tt = TextTable.forDefaultColumns(Help.Ansi.OFF, UsageMessageSpec.DEFAULT_USAGE_WIDTH); tt = new TextTable(Help.Ansi.OFF, tt.columns()) { @Override public void addRowValues(Text[] columnValues) { assertArrayEquals(values[count[0]], columnValues); count[0]++; } }; Help.Layout layout = new Help.Layout(Help.defaultColorScheme(Help.Ansi.OFF), tt); layout.layout(null, values); assertEquals(2, count[0]); }
public static String usageString(CommandLine commandLine, Ansi ansi) { ByteArrayOutputStream baos = new ByteArrayOutputStream(); commandLine.usage(new PrintStream(baos, true), ansi); String result = baos.toString(); assertEquals(result, commandLine.getUsageMessage(ansi)); if (ansi == Ansi.AUTO) { baos.reset(); commandLine.usage(new PrintStream(baos, true)); assertEquals(result, baos.toString()); assertEquals(result, commandLine.getUsageMessage()); } else if (ansi == Ansi.ON) { baos.reset(); commandLine.usage(new PrintStream(baos, true), Help.defaultColorScheme(Ansi.ON)); assertEquals(result, baos.toString()); assertEquals(result, commandLine.getUsageMessage(Help.defaultColorScheme(Ansi.ON))); } return result; }
@Test public void testCommandAliasAnnotationUsageHelp() { CommandLine commandLine = new CommandLine(new TopLevelCommand()); ByteArrayOutputStream baos = new ByteArrayOutputStream(); commandLine.usage(new PrintStream(baos), CommandLine.Help.defaultColorScheme(Help.Ansi.ON).commands(Help.Ansi.Style.underline)); // add underline String expected = Help.Ansi.ON.new Text(String.format("" + "Usage: @|bold,underline top|@ [COMMAND]%n" + "top level command%n" + "Commands:%n" + " @|bold,underline sub|@, @|bold,underline s|@, @|bold,underline sb|@ I'm subcommand No. 1!%n" + " @|bold,underline sub2|@, @|bold,underline s2|@, @|bold,underline sb2|@ I'm subcommand 2 but pretty good still%n")).toString(); assertEquals(expected, baos.toString()); }
/** Similar to {@link #usage(PrintStream, Help.Ansi)} but with the specified {@code PrintWriter} instead of a {@code PrintStream}. * @since 3.0 */ public void usage(PrintWriter writer, Help.Ansi ansi) { usage(writer, Help.defaultColorScheme(ansi)); }
@Test public void testTextDefaultColorScheme() { Ansi ansi = Ansi.ON; CommandLine.Help.ColorScheme scheme = CommandLine.Help.defaultColorScheme(ansi); assertEquals(scheme.ansi().new Text("@|yellow -p|@"), scheme.optionText("-p")); assertEquals(scheme.ansi().new Text("@|bold command|@"), scheme.commandText("command")); assertEquals(scheme.ansi().new Text("@|yellow FILE|@"), scheme.parameterText("FILE")); assertEquals(scheme.ansi().new Text("@|italic NUMBER|@"), scheme.optionParamText("NUMBER")); }
@Test public void testCommandAliasAnnotationSubcommandUsageHelp() { CommandLine commandLine = new CommandLine(new TopLevelCommand()); ByteArrayOutputStream baos = new ByteArrayOutputStream(); commandLine.getSubcommands().get("sub").usage(new PrintStream(baos), CommandLine.Help.defaultColorScheme(Help.Ansi.ON).commands(Help.Ansi.Style.underline)); // add underline String expected = Help.Ansi.ON.new Text(String.format("" + "Usage: @|bold,underline top sub|@ [COMMAND]%n" + "I'm subcommand No. 1!%n" + "Commands:%n" + " @|bold,underline subsub|@, @|bold,underline ss|@, @|bold,underline sbsb|@ I'm like a 3rd rate command but great bang for your buck%n")).toString(); assertEquals(expected, baos.toString()); } }
/** * Delegates to {@link #usage(PrintStream, Help.ColorScheme)} with the {@linkplain Help#defaultColorScheme(CommandLine.Help.Ansi) default color scheme}. * @param out the printStream to print to * @param ansi whether the usage message should include ANSI escape codes or not * @see #usage(PrintStream, Help.ColorScheme) */ public void usage(PrintStream out, Help.Ansi ansi) { usage(out, Help.defaultColorScheme(ansi)); } /** Similar to {@link #usage(PrintStream, Help.Ansi)} but with the specified {@code PrintWriter} instead of a {@code PrintStream}.
/** Constructs a new {@code Help} instance with a default color scheme, initialized from annotatations * on the specified class and superclasses. * @param command the annotated object to create usage help for * @param ansi whether to emit ANSI escape codes or not */ public Help(Object command, Ansi ansi) { this(command, defaultColorScheme(ansi)); } /** Constructs a new {@code Help} instance with the specified color scheme, initialized from annotatations
@Test(expected = InitializationException.class) public void testUsageObjectPrintstreamColorschemeRequiresAnnotatedCommand() { class App { } CommandLine.usage(new App(), System.out, Help.defaultColorScheme(Help.Ansi.OFF)); }