Frames | No Frames |
1: /* 2: * Copyright 2003-2005 The Apache Software Foundation 3: * Copyright 2005 Stephen McConnell 4: * 5: * Licensed under the Apache License, Version 2.0 (the "License"); 6: * you may not use this file except in compliance with the License. 7: * You may obtain a copy of the License at 8: * 9: * http://www.apache.org/licenses/LICENSE-2.0 10: * 11: * Unless required by applicable law or agreed to in writing, software 12: * distributed under the License is distributed on an "AS IS" BASIS, 13: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14: * See the License for the specific language governing permissions and 15: * limitations under the License. 16: */ 17: package net.dpml.cli; 18: 19: import java.util.Comparator; 20: import java.util.List; 21: import java.util.ListIterator; 22: import java.util.Set; 23: 24: /** 25: * The super type of all options representing a particular element of the 26: * command line interface. 27: * 28: * @author <a href="@PUBLISHER-URL@">@PUBLISHER-NAME@</a> 29: * @version @PROJECT-VERSION@ 30: */ 31: public interface Option 32: { 33: /** 34: * Processes String arguments into a CommandLine. 35: * 36: * The iterator will initially point at the first argument to be processed 37: * and at the end of the method should point to the first argument not 38: * processed. This method MUST process at least one argument from the 39: * ListIterator. 40: * 41: * @param commandLine the CommandLine object to store results in 42: * @param args the arguments to process 43: * @throws OptionException if any problems occur 44: */ 45: void process( 46: final WriteableCommandLine commandLine, 47: final ListIterator args ) 48: throws OptionException; 49: 50: /** 51: * Adds defaults to a CommandLine. 52: * 53: * Any defaults for this option are applied as well as the defaults for 54: * any contained options 55: * 56: * @param commandLine the CommandLine object to store defaults in 57: */ 58: void defaults( WriteableCommandLine commandLine ); 59: 60: /** 61: * Indicates whether this Option will be able to process the particular 62: * argument. 63: * 64: * @param commandLine the CommandLine object to store defaults in 65: * @param argument the argument to be tested 66: * @return true if the argument can be processed by this Option 67: */ 68: boolean canProcess( WriteableCommandLine commandLine, String argument ); 69: 70: /** 71: * Indicates whether this Option will be able to process the particular 72: * argument. The ListIterator must be restored to the initial state before 73: * returning the boolean. 74: * 75: * @see #canProcess(WriteableCommandLine,String) 76: * @param commandLine the CommandLine object to store defaults in 77: * @param arguments the ListIterator over String arguments 78: * @return true if the argument can be processed by this Option 79: */ 80: boolean canProcess( WriteableCommandLine commandLine, final ListIterator arguments ); 81: 82: /** 83: * Identifies the argument prefixes that should trigger this option. This 84: * is used to decide which of many Options should be tried when processing 85: * a given argument string. 86: * 87: * The returned Set must not be null. 88: * 89: * @return The set of triggers for this Option 90: */ 91: Set getTriggers(); 92: 93: /** 94: * Identifies the argument prefixes that should be considered options. This 95: * is used to identify whether a given string looks like an option or an 96: * argument value. Typically an option would return the set [--,-] while 97: * switches might offer [-,+]. 98: * 99: * The returned Set must not be null. 100: * 101: * @return The set of prefixes for this Option 102: */ 103: Set getPrefixes(); 104: 105: /** 106: * Checks that the supplied CommandLine is valid with respect to this 107: * option. 108: * 109: * @param commandLine the CommandLine to check. 110: * @throws OptionException if the CommandLine is not valid. 111: */ 112: void validate( WriteableCommandLine commandLine ) throws OptionException; 113: 114: /** 115: * Builds up a list of HelpLineImpl instances to be presented by HelpFormatter. 116: * 117: * @see HelpLine 118: * @see net.dpml.cli.util.HelpFormatter 119: * @param depth the initial indent depth 120: * @param helpSettings the HelpSettings that should be applied 121: * @param comp a comparator used to sort options when applicable. 122: * @return a List of HelpLineImpl objects 123: */ 124: List helpLines( int depth, Set helpSettings, Comparator comp ); 125: 126: /** 127: * Appends usage information to the specified StringBuffer 128: * 129: * @param buffer the buffer to append to 130: * @param helpSettings a set of display settings @see DisplaySetting 131: * @param comp a comparator used to sort the Options 132: */ 133: void appendUsage( StringBuffer buffer, Set helpSettings, Comparator comp ); 134: 135: /** 136: * The preferred name of an option is used for generating help and usage 137: * information. 138: * 139: * @return The preferred name of the option 140: */ 141: String getPreferredName(); 142: 143: /** 144: * Returns a description of the option. This string is used to build help 145: * messages as in the HelpFormatter. 146: * 147: * @see net.dpml.cli.util.HelpFormatter 148: * @return a description of the option. 149: */ 150: String getDescription(); 151: 152: /** 153: * Returns the id of the option. This can be used in a loop and switch 154: * construct: 155: * 156: * <code> 157: * for(Option o : cmd.getOptions()){ 158: * switch(o.getId()){ 159: * case POTENTIAL_OPTION: 160: * ... 161: * } 162: * } 163: * </code> 164: * 165: * The returned value is not guarenteed to be unique. 166: * 167: * @return the id of the option. 168: */ 169: int getId(); 170: 171: /** 172: * Recursively searches for an option with the supplied trigger. 173: * 174: * @param trigger the trigger to search for. 175: * @return the matching option or null. 176: */ 177: Option findOption( String trigger ); 178: 179: /** 180: * Indicates whether this option is required to be present. 181: * @return true if the CommandLine will be invalid without this Option 182: */ 183: boolean isRequired(); 184: }