joptsimple.BuiltinHelpFormatter Maven / Gradle / Ivy
/*
The MIT License
Copyright (c) 2004-2015 Paul R. Holser, Jr.
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
package joptsimple;
import java.util.*;
import joptsimple.internal.Messages;
import joptsimple.internal.Rows;
import joptsimple.internal.Strings;
import static joptsimple.ParserRules.*;
import static joptsimple.internal.Classes.*;
import static joptsimple.internal.Strings.*;
/**
* A help formatter that allows configuration of overall row width and column separator width.
*
* The formatter produces output in two sections: one for the options, and one for non-option arguments.
*
* The options section has two columns: the left column for the options, and the right column for their
* descriptions. The formatter will allow as much space as possible for the descriptions, by minimizing the option
* column's width, no greater than slightly less than half the overall desired width.
*
* The non-option arguments section is one column, occupying as much width as it can.
*
* Subclasses are free to override bits of this implementation as they see fit. Inspect the code
* carefully to understand the flow of control that this implementation guarantees.
*
* @author Paul Holser
*/
public class BuiltinHelpFormatter implements HelpFormatter {
private final Rows nonOptionRows;
private final Rows optionRows;
/**
* Makes a formatter with a pre-configured overall row width and column separator width.
*/
BuiltinHelpFormatter() {
this( 80, 2 );
}
/**
* Makes a formatter with a given overall row width and column separator width.
*
* @param desiredOverallWidth how many characters wide to make the overall help display
* @param desiredColumnSeparatorWidth how many characters wide to make the separation between option column and
* description column
*/
public BuiltinHelpFormatter( int desiredOverallWidth, int desiredColumnSeparatorWidth ) {
nonOptionRows = new Rows( desiredOverallWidth * 2, 0 );
optionRows = new Rows( desiredOverallWidth, desiredColumnSeparatorWidth );
}
/**
* {@inheritDoc}
*
* This implementation:
*
* - Sorts the given descriptors by their first elements of {@link OptionDescriptor#options()}
* - Passes the resulting sorted set to {@link #addRows(java.util.Collection)}
* - Returns the result of {@link #formattedHelpOutput()}
*
*/
public String format( Map options ) {
optionRows.reset();
nonOptionRows.reset();
Comparator comparator =
new Comparator() {
public int compare( OptionDescriptor first, OptionDescriptor second ) {
return first.options().iterator().next().compareTo( second.options().iterator().next() );
}
};
Set sorted = new TreeSet<>( comparator );
sorted.addAll( options.values() );
addRows( sorted );
return formattedHelpOutput();
}
/**
* Adds a row of option help output in the left column, with empty space in the right column.
*
* @param single text to put in the left column
*/
protected void addOptionRow( String single ) {
addOptionRow( single, "" );
}
/**
* Adds a row of option help output in the left and right columns.
*
* @param left text to put in the left column
* @param right text to put in the right column
*/
protected void addOptionRow( String left, String right ) {
optionRows.add( left, right );
}
/**
* Adds a single row of non-option argument help.
*
* @param single single row of non-option argument help text
*/
protected void addNonOptionRow( String single ) {
nonOptionRows.add( single, "" );
}
/**
* Resizes the columns of all the rows to be no wider than the widest element in that column.
*/
protected void fitRowsToWidth() {
nonOptionRows.fitToWidth();
optionRows.fitToWidth();
}
/**
* Produces non-option argument help.
*
* @return non-option argument help
*/
protected String nonOptionOutput() {
return nonOptionRows.render();
}
/**
* Produces help for options and their descriptions.
*
* @return option help
*/
protected String optionOutput() {
return optionRows.render();
}
/**
* Produces help output for an entire set of options and non-option arguments.
*
* This implementation concatenates:
*
* - the result of {@link #nonOptionOutput()}
* - if there is non-option output, a line separator
* - the result of {@link #optionOutput()}
*
*
* @return help output for entire set of options and non-option arguments
*/
protected String formattedHelpOutput() {
StringBuilder formatted = new StringBuilder();
String nonOptionDisplay = nonOptionOutput();
if ( !Strings.isNullOrEmpty( nonOptionDisplay ) )
formatted.append( nonOptionDisplay ).append( LINE_SEPARATOR );
formatted.append( optionOutput() );
return formatted.toString();
}
/**
* Adds rows of help output for the given options.
*
* This implementation:
*
* - Calls {@link #addNonOptionsDescription(java.util.Collection)} with the options as the argument
* - If there are no options, calls {@link #addOptionRow(String)} with an argument that indicates
* that no options are specified.
* - Otherwise, calls {@link #addHeaders(java.util.Collection)} with the options as the argument,
* followed by {@link #addOptions(java.util.Collection)} with the options as the argument.
* - Calls {@link #fitRowsToWidth()}.
*
*
* @param options descriptors for the configured options of a parser
*/
protected void addRows( Collection options ) {
addNonOptionsDescription( options );
if ( options.isEmpty() )
addOptionRow( message( "no.options.specified" ) );
else {
addHeaders( options );
addOptions( options );
}
fitRowsToWidth();
}
/**
* Adds non-option arguments descriptions to the help output.
*
* This implementation:
*
* - {@linkplain #findAndRemoveNonOptionsSpec(java.util.Collection) Finds and removes the non-option
* arguments descriptor}
* - {@linkplain #shouldShowNonOptionArgumentDisplay(OptionDescriptor) Decides whether there is
* anything to show for non-option arguments}
* - If there is, {@linkplain #addNonOptionRow(String) adds a header row} and
* {@linkplain #addNonOptionRow(String) adds a}
* {@linkplain #createNonOptionArgumentsDisplay(OptionDescriptor) non-option arguments description}
*
*
* @param options descriptors for the configured options of a parser
*/
protected void addNonOptionsDescription( Collection options ) {
OptionDescriptor nonOptions = findAndRemoveNonOptionsSpec( options );
if ( shouldShowNonOptionArgumentDisplay( nonOptions ) ) {
addNonOptionRow( message( "non.option.arguments.header" ) );
addNonOptionRow( createNonOptionArgumentsDisplay( nonOptions ) );
}
}
/**
* Decides whether or not to show a non-option arguments help.
*
* This implementation responds with {@code true} if the non-option descriptor has a non-{@code null},
* non-empty value for any of {@link OptionDescriptor#description()},
* {@link OptionDescriptor#argumentTypeIndicator()}, or {@link OptionDescriptor#argumentDescription()}.
*
* @param nonOptionDescriptor non-option argument descriptor
* @return {@code true} if non-options argument help should be shown
*/
protected boolean shouldShowNonOptionArgumentDisplay( OptionDescriptor nonOptionDescriptor ) {
return !Strings.isNullOrEmpty( nonOptionDescriptor.description() )
|| !Strings.isNullOrEmpty( nonOptionDescriptor.argumentTypeIndicator() )
|| !Strings.isNullOrEmpty( nonOptionDescriptor.argumentDescription() );
}
/**
* Creates a non-options argument help string.
*
* This implementation creates an empty string buffer and calls
* {@link #maybeAppendOptionInfo(StringBuilder, OptionDescriptor)}
* and {@link #maybeAppendNonOptionsDescription(StringBuilder, OptionDescriptor)}, passing them the
* buffer and the non-option arguments descriptor.
*
* @param nonOptionDescriptor non-option argument descriptor
* @return help string for non-options
*/
protected String createNonOptionArgumentsDisplay( OptionDescriptor nonOptionDescriptor ) {
StringBuilder buffer = new StringBuilder();
maybeAppendOptionInfo( buffer, nonOptionDescriptor );
maybeAppendNonOptionsDescription( buffer, nonOptionDescriptor );
return buffer.toString();
}
/**
* Appends help for the given non-option arguments descriptor to the given buffer.
*
* This implementation appends {@code " -- "} if the buffer has text in it and the non-option arguments
* descriptor has a {@link OptionDescriptor#description()}; followed by the
* {@link OptionDescriptor#description()}.
*
* @param buffer string buffer
* @param nonOptions non-option arguments descriptor
*/
protected void maybeAppendNonOptionsDescription( StringBuilder buffer, OptionDescriptor nonOptions ) {
buffer.append( buffer.length() > 0 && !Strings.isNullOrEmpty( nonOptions.description() ) ? " -- " : "" )
.append( nonOptions.description() );
}
/**
* Finds the non-option arguments descriptor in the given collection, removes it, and returns it.
*
* @param options descriptors for the configured options of a parser
* @return the non-option arguments descriptor
*/
protected OptionDescriptor findAndRemoveNonOptionsSpec( Collection options ) {
for ( Iterator it = options.iterator(); it.hasNext(); ) {
OptionDescriptor next = it.next();
if ( next.representsNonOptions() ) {
it.remove();
return next;
}
}
throw new AssertionError( "no non-options argument spec" );
}
/**
* Adds help row headers for option help columns.
*
* This implementation uses the headers {@code "Option"} and {@code "Description"}. If the options contain
* a "required" option, the {@code "Option"} header looks like {@code "Option (* = required)}. Both headers
* are "underlined" using {@code "-"}.
*
* @param options descriptors for the configured options of a parser
*/
protected void addHeaders( Collection options ) {
if ( hasRequiredOption( options ) ) {
addOptionRow( message( "option.header.with.required.indicator" ), message( "description.header" ) );
addOptionRow( message( "option.divider.with.required.indicator" ), message( "description.divider" ) );
} else {
addOptionRow( message( "option.header" ), message( "description.header" ) );
addOptionRow( message( "option.divider" ), message( "description.divider" ) );
}
}
/**
* Tells whether the given option descriptors contain a "required" option.
*
* @param options descriptors for the configured options of a parser
* @return {@code true} if at least one of the options is "required"
*/
protected final boolean hasRequiredOption( Collection options ) {
for ( OptionDescriptor each : options ) {
if ( each.isRequired() )
return true;
}
return false;
}
/**
* Adds help rows for the given options.
*
* This implementation loops over the given options, and for each, calls {@link #addOptionRow(String, String)}
* using the results of {@link #createOptionDisplay(OptionDescriptor)} and
* {@link #createDescriptionDisplay(OptionDescriptor)}, respectively, as arguments.
*
* @param options descriptors for the configured options of a parser
*/
protected void addOptions( Collection options ) {
for ( OptionDescriptor each : options ) {
if ( !each.representsNonOptions() )
addOptionRow( createOptionDisplay( each ), createDescriptionDisplay( each ) );
}
}
/**
* Creates a string for how the given option descriptor is to be represented in help.
*
* This implementation gives a string consisting of the concatenation of:
*
* - {@code "* "} for "required" options, otherwise {@code ""}
* - For each of the {@link OptionDescriptor#options()} of the descriptor, separated by {@code ", "}:
*
* - {@link #optionLeader(String)} of the option
* - the option
*
*
* - the result of {@link #maybeAppendOptionInfo(StringBuilder, OptionDescriptor)}
*
*
* @param descriptor a descriptor for a configured option of a parser
* @return help string
*/
protected String createOptionDisplay( OptionDescriptor descriptor ) {
StringBuilder buffer = new StringBuilder( descriptor.isRequired() ? "* " : "" );
for ( Iterator i = descriptor.options().iterator(); i.hasNext(); ) {
String option = i.next();
buffer.append( optionLeader( option ) );
buffer.append( option );
if ( i.hasNext() )
buffer.append( ", " );
}
maybeAppendOptionInfo( buffer, descriptor );
return buffer.toString();
}
/**
* Gives a string that represents the given option's "option leader" in help.
*
* This implementation answers with {@code "--"} for options of length greater than one; otherwise answers
* with {@code "-"}.
*
* @param option a string option
* @return an "option leader" string
*/
protected String optionLeader( String option ) {
return option.length() > 1 ? DOUBLE_HYPHEN : HYPHEN;
}
/**
* Appends additional info about the given option to the given buffer.
*
* This implementation:
*
* - calls {@link #extractTypeIndicator(OptionDescriptor)} for the descriptor
* - calls {@link joptsimple.OptionDescriptor#argumentDescription()} for the descriptor
* - if either of the above is present, calls
* {@link #appendOptionHelp(StringBuilder, String, String, boolean)}
*
*
* @param buffer string buffer
* @param descriptor a descriptor for a configured option of a parser
*/
protected void maybeAppendOptionInfo( StringBuilder buffer, OptionDescriptor descriptor ) {
String indicator = extractTypeIndicator( descriptor );
String description = descriptor.argumentDescription();
if ( indicator != null || !isNullOrEmpty( description ) )
appendOptionHelp( buffer, indicator, description, descriptor.requiresArgument() );
}
/**
* Gives an indicator of the type of arguments of the option described by the given descriptor,
* for use in help.
*
* This implementation asks for the {@link OptionDescriptor#argumentTypeIndicator()} of the given
* descriptor, and if it is present and not {@code "java.lang.String"}, parses it as a fully qualified
* class name and returns the base name of that class; otherwise returns {@code null}.
*
* @param descriptor a descriptor for a configured option of a parser
* @return type indicator text
*/
protected String extractTypeIndicator( OptionDescriptor descriptor ) {
String indicator = descriptor.argumentTypeIndicator();
if ( !isNullOrEmpty( indicator ) && !String.class.getName().equals( indicator ) )
return shortNameOf( indicator );
return null;
}
/**
* Appends info about an option's argument to the given buffer.
*
* This implementation calls {@link #appendTypeIndicator(StringBuilder, String, String, char, char)} with
* the surrounding characters {@code '<'} and {@code '>'} for options with {@code required} arguments, and
* with the surrounding characters {@code '['} and {@code ']'} for options with optional arguments.
*
* @param buffer string buffer
* @param typeIndicator type indicator
* @param description type description
* @param required indicator of "required"-ness of the argument of the option
*/
protected void appendOptionHelp( StringBuilder buffer, String typeIndicator, String description,
boolean required ) {
if ( required )
appendTypeIndicator( buffer, typeIndicator, description, '<', '>' );
else
appendTypeIndicator( buffer, typeIndicator, description, '[', ']' );
}
/**
* Appends a type indicator for an option's argument to the given buffer.
*
* This implementation appends, in order:
*
* - {@code ' '}
* - {@code start}
* - the type indicator, if not {@code null}
* - if the description is present, then {@code ": "} plus the description if the type indicator is
* present; otherwise the description only
* - {@code end}
*
*
* @param buffer string buffer
* @param typeIndicator type indicator
* @param description type description
* @param start starting character
* @param end ending character
*/
protected void appendTypeIndicator( StringBuilder buffer, String typeIndicator, String description,
char start, char end ) {
buffer.append( ' ' ).append( start );
if ( typeIndicator != null )
buffer.append( typeIndicator );
if ( !Strings.isNullOrEmpty( description ) ) {
if ( typeIndicator != null )
buffer.append( ": " );
buffer.append( description );
}
buffer.append( end );
}
/**
* Gives a string representing a description of the option with the given descriptor.
*
* This implementation:
*
* - Asks for the descriptor's {@link OptionDescriptor#defaultValues()}
* - If they're not present, answers the descriptor's {@link OptionDescriptor#description()}.
* - If they are present, concatenates and returns:
*
* - the descriptor's {@link OptionDescriptor#description()}
* - {@code ' '}
* - {@code "default: "} plus the result of {@link #createDefaultValuesDisplay(java.util.List)},
* surrounded by parentheses
*
*
*
*
* @param descriptor a descriptor for a configured option of a parser
* @return display text for the option's description
*/
protected String createDescriptionDisplay( OptionDescriptor descriptor ) {
List defaultValues = descriptor.defaultValues();
if ( defaultValues.isEmpty() )
return descriptor.description();
String defaultValuesDisplay = createDefaultValuesDisplay( defaultValues );
return ( descriptor.description()
+ ' '
+ surround( message( "default.value.header" ) + ' ' + defaultValuesDisplay, '(', ')' )
).trim();
}
/**
* Gives a display string for the default values of an option's argument.
*
* This implementation gives the {@link Object#toString()} of the first value if there is only one value,
* otherwise gives the {@link Object#toString()} of the whole list.
*
* @param defaultValues some default values for a given option's argument
* @return a display string for those default values
*/
protected String createDefaultValuesDisplay( List defaultValues ) {
return defaultValues.size() == 1 ? defaultValues.get( 0 ).toString() : defaultValues.toString();
}
/**
* Looks up and gives a resource bundle message.
*
* This implementation looks in the bundle {@code "joptsimple.HelpFormatterMessages"} in the default
* locale, using a key that is the concatenation of this class's fully qualified name, {@code '.'},
* and the given key suffix, formats the corresponding value using the given arguments, and returns
* the result.
*
* @param keySuffix suffix to use when looking up the bundle message
* @param args arguments to fill in the message template with
* @return a formatted localized message
*/
protected String message( String keySuffix, Object... args ) {
return Messages.message(
Locale.getDefault(),
"joptsimple.HelpFormatterMessages",
BuiltinHelpFormatter.class,
keySuffix,
args );
}
}