1 /*

     2  * Copyright (c) 2009, 2015, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /*

    27  * This file is available under and governed by the GNU General Public

    28  * License version 2 only, as published by the Free Software Foundation.

    29  * However, the following notice accompanied the original version of this

    30  * file:

    31  *

    32  * The MIT License

    33  *

    34  * Copyright (c) 2004-2014 Paul R. Holser, Jr.

    35  *

    36  * Permission is hereby granted, free of charge, to any person obtaining

    37  * a copy of this software and associated documentation files (the

    38  * "Software"), to deal in the Software without restriction, including

    39  * without limitation the rights to use, copy, modify, merge, publish,

    40  * distribute, sublicense, and/or sell copies of the Software, and to

    41  * permit persons to whom the Software is furnished to do so, subject to

    42  * the following conditions:

    43  *

    44  * The above copyright notice and this permission notice shall be

    45  * included in all copies or substantial portions of the Software.

    46  *

    47  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

    48  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

    49  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

    50  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE

    51  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

    52  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

    53  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    54  */

    55 

    56 package jdk.internal.joptsimple;

    57 

    58 import java.util.Collection;

    59 import java.util.Comparator;

    60 import java.util.Iterator;

    61 import java.util.List;

    62 import java.util.Map;

    63 import java.util.Set;

    64 import java.util.TreeSet;

    65 

    66 import jdk.internal.joptsimple.internal.Rows;

    67 import jdk.internal.joptsimple.internal.Strings;

    68 

    69 import static jdk.internal.joptsimple.ParserRules.*;

    70 import static jdk.internal.joptsimple.internal.Classes.*;

    71 import static jdk.internal.joptsimple.internal.Strings.*;

    72 

    73 /**

    74  * <p>A help formatter that allows configuration of overall row width and column separator width.</p>

    75  *

    76  * <p>The formatter produces a two-column output. The left column is for the options, and the right column for their

    77  * descriptions. The formatter will allow as much space as possible for the descriptions, by minimizing the option

    78  * column's width, no greater than slightly less than half the overall desired width.</p>

    79  *

    80  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>

    81  */

    82 public class BuiltinHelpFormatter implements HelpFormatter {

    83     private final Rows nonOptionRows;

    84     private final Rows optionRows;

    85 

    86     /**

    87      * Makes a formatter with a pre-configured overall row width and column separator width.

    88      */

    89     BuiltinHelpFormatter() {

    90         this( 80, 2 );

    91     }

    92 

    93     /**

    94      * Makes a formatter with a given overall row width and column separator width.

    95      *

    96      * @param desiredOverallWidth how many characters wide to make the overall help display

    97      * @param desiredColumnSeparatorWidth how many characters wide to make the separation between option column and

    98      * description column

    99      */

   100     public BuiltinHelpFormatter( int desiredOverallWidth, int desiredColumnSeparatorWidth ) {

   101         nonOptionRows = new Rows( desiredOverallWidth * 2, 0 );

   102         optionRows = new Rows( desiredOverallWidth, desiredColumnSeparatorWidth );

   103     }

   104 

   105     public String format( Map<String, ? extends OptionDescriptor> options ) {

   106         Comparator<OptionDescriptor> comparator =

   107             new Comparator<OptionDescriptor>() {

   108                 public int compare( OptionDescriptor first, OptionDescriptor second ) {

   109                     return first.options().iterator().next().compareTo( second.options().iterator().next() );

   110                 }

   111             };

   112 

   113         Set<OptionDescriptor> sorted = new TreeSet<OptionDescriptor>( comparator );

   114         sorted.addAll( options.values() );

   115 

   116         addRows( sorted );

   117 

   118         return formattedHelpOutput();

   119     }

   120 

   121     private String formattedHelpOutput() {

   122         StringBuilder formatted = new StringBuilder();

   123         String nonOptionDisplay = nonOptionRows.render();

   124         if ( !Strings.isNullOrEmpty( nonOptionDisplay ) )

   125             formatted.append( nonOptionDisplay ).append( LINE_SEPARATOR );

   126         formatted.append( optionRows.render() );

   127 

   128         return formatted.toString();

   129     }

   130 

   131     private void addRows( Collection<? extends OptionDescriptor> options ) {

   132         addNonOptionsDescription( options );

   133 

   134         if ( options.isEmpty() )

   135             optionRows.add( "No options specified", "" );

   136         else {

   137             addHeaders( options );

   138             addOptions( options );

   139         }

   140 

   141         fitRowsToWidth();

   142     }

   143 

   144     private void addNonOptionsDescription( Collection<? extends OptionDescriptor> options ) {

   145         OptionDescriptor nonOptions = findAndRemoveNonOptionsSpec( options );

   146         if ( shouldShowNonOptionArgumentDisplay( nonOptions ) ) {

   147             nonOptionRows.add( "Non-option arguments:", "" );

   148             nonOptionRows.add(createNonOptionArgumentsDisplay(nonOptions), "");

   149         }

   150     }

   151 

   152     private boolean shouldShowNonOptionArgumentDisplay( OptionDescriptor nonOptions ) {

   153         return !Strings.isNullOrEmpty( nonOptions.description() )

   154             || !Strings.isNullOrEmpty( nonOptions.argumentTypeIndicator() )

   155             || !Strings.isNullOrEmpty( nonOptions.argumentDescription() );

   156     }

   157 

   158     private String createNonOptionArgumentsDisplay(OptionDescriptor nonOptions) {

   159         StringBuilder buffer = new StringBuilder();

   160         maybeAppendOptionInfo( buffer, nonOptions );

   161         maybeAppendNonOptionsDescription( buffer, nonOptions );

   162 

   163         return buffer.toString();

   164     }

   165 

   166     private void maybeAppendNonOptionsDescription( StringBuilder buffer, OptionDescriptor nonOptions ) {

   167         buffer.append( buffer.length() > 0 && !Strings.isNullOrEmpty( nonOptions.description() ) ? " -- " : "" )

   168             .append( nonOptions.description() );

   169     }

   170 

   171     private OptionDescriptor findAndRemoveNonOptionsSpec( Collection<? extends OptionDescriptor> options ) {

   172         for ( Iterator<? extends OptionDescriptor> it = options.iterator(); it.hasNext(); ) {

   173             OptionDescriptor next = it.next();

   174             if ( next.representsNonOptions() ) {

   175                 it.remove();

   176                 return next;

   177             }

   178         }

   179 

   180         throw new AssertionError( "no non-options argument spec" );

   181     }

   182 

   183     private void addHeaders( Collection<? extends OptionDescriptor> options ) {

   184         if ( hasRequiredOption( options ) ) {

   185             optionRows.add("Option (* = required)", "Description");

   186             optionRows.add("---------------------", "-----------");

   187         } else {

   188             optionRows.add("Option", "Description");

   189             optionRows.add("------", "-----------");

   190         }

   191     }

   192 

   193     private boolean hasRequiredOption( Collection<? extends OptionDescriptor> options ) {

   194         for ( OptionDescriptor each : options ) {

   195             if ( each.isRequired() )

   196                 return true;

   197         }

   198 

   199         return false;

   200     }

   201 

   202     private void addOptions( Collection<? extends OptionDescriptor> options ) {

   203         for ( OptionDescriptor each : options ) {

   204             if ( !each.representsNonOptions() )

   205                 optionRows.add( createOptionDisplay( each ), createDescriptionDisplay( each ) );

   206         }

   207     }

   208 

   209     private String createOptionDisplay( OptionDescriptor descriptor ) {

   210         StringBuilder buffer = new StringBuilder( descriptor.isRequired() ? "* " : "" );

   211 

   212         for ( Iterator<String> i = descriptor.options().iterator(); i.hasNext(); ) {

   213             String option = i.next();

   214             buffer.append( option.length() > 1 ? DOUBLE_HYPHEN : HYPHEN );

   215             buffer.append( option );

   216 

   217             if ( i.hasNext() )

   218                 buffer.append( ", " );

   219         }

   220 

   221         maybeAppendOptionInfo( buffer, descriptor );

   222 

   223         return buffer.toString();

   224     }

   225 

   226     private void maybeAppendOptionInfo( StringBuilder buffer, OptionDescriptor descriptor ) {

   227         String indicator = extractTypeIndicator( descriptor );

   228         String description = descriptor.argumentDescription();

   229         if ( indicator != null || !isNullOrEmpty( description ) )

   230             appendOptionHelp( buffer, indicator, description, descriptor.requiresArgument() );

   231     }

   232 

   233     private String extractTypeIndicator( OptionDescriptor descriptor ) {

   234         String indicator = descriptor.argumentTypeIndicator();

   235 

   236         if ( !isNullOrEmpty( indicator ) && !String.class.getName().equals( indicator ) )

   237             return shortNameOf( indicator );

   238 

   239         return null;

   240     }

   241 

   242     private void appendOptionHelp( StringBuilder buffer, String typeIndicator, String description, boolean required ) {

   243         if ( required )

   244             appendTypeIndicator( buffer, typeIndicator, description, '<', '>' );

   245         else

   246             appendTypeIndicator( buffer, typeIndicator, description, '[', ']' );

   247     }

   248 

   249     private void appendTypeIndicator( StringBuilder buffer, String typeIndicator, String description,

   250                                       char start, char end ) {

   251         buffer.append( ' ' ).append( start );

   252         if ( typeIndicator != null )

   253             buffer.append( typeIndicator );

   254 

   255         if ( !Strings.isNullOrEmpty( description ) ) {

   256             if ( typeIndicator != null )

   257                 buffer.append( ": " );

   258 

   259             buffer.append( description );

   260         }

   261 

   262         buffer.append( end );

   263     }

   264 

   265     private String createDescriptionDisplay( OptionDescriptor descriptor ) {

   266         List<?> defaultValues = descriptor.defaultValues();

   267         if ( defaultValues.isEmpty() )

   268             return descriptor.description();

   269 

   270         String defaultValuesDisplay = createDefaultValuesDisplay( defaultValues );

   271         return ( descriptor.description() + ' ' + surround( "default: " + defaultValuesDisplay, '(', ')' ) ).trim();

   272     }

   273 

   274     private String createDefaultValuesDisplay( List<?> defaultValues ) {

   275         return defaultValues.size() == 1 ? defaultValues.get( 0 ).toString() : defaultValues.toString();

   276     }

   277 

   278     private void fitRowsToWidth() {

   279         nonOptionRows.fitToWidth();

   280         optionRows.fitToWidth();

   281     }

   282 }