001/* 002 Licensed to the Apache Software Foundation (ASF) under one or more 003 contributor license agreements. See the NOTICE file distributed with 004 this work for additional information regarding copyright ownership. 005 The ASF licenses this file to You under the Apache License, Version 2.0 006 (the "License"); you may not use this file except in compliance with 007 the License. You may obtain a copy of the License at 008 009 http://www.apache.org/licenses/LICENSE-2.0 010 011 Unless required by applicable law or agreed to in writing, software 012 distributed under the License is distributed on an "AS IS" BASIS, 013 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 See the License for the specific language governing permissions and 015 limitations under the License. 016 */ 017 018package org.apache.commons.cli; 019 020import java.util.ArrayList; 021import java.util.Arrays; 022import java.util.Enumeration; 023import java.util.List; 024import java.util.ListIterator; 025import java.util.Properties; 026 027/** 028 * {@code Parser} creates {@link CommandLine}s. 029 * 030 * @deprecated since 1.3, the two-pass parsing with the flatten method is not enough flexible to handle complex cases 031 */ 032@Deprecated 033public abstract class Parser implements CommandLineParser { 034 /** CommandLine instance */ 035 protected CommandLine cmd; 036 037 /** Current Options */ 038 private Options options; 039 040 /** List of required options strings */ 041 private List requiredOptions; 042 043 /** 044 * Throws a {@link MissingOptionException} if all of the required options are not present. 045 * 046 * @throws MissingOptionException if any of the required Options are not present. 047 */ 048 protected void checkRequiredOptions() throws MissingOptionException { 049 // if there are required options that have not been processed 050 if (!getRequiredOptions().isEmpty()) { 051 throw new MissingOptionException(getRequiredOptions()); 052 } 053 } 054 055 /** 056 * Subclasses must implement this method to reduce the {@code arguments} that have been passed to the parse method. 057 * 058 * @param opts The Options to parse the arguments by. 059 * @param arguments The arguments that have to be flattened. 060 * @param stopAtNonOption specifies whether to stop flattening when a non option has been encountered 061 * @return a String array of the flattened arguments 062 * @throws ParseException if there are any problems encountered while parsing the command line tokens. 063 */ 064 protected abstract String[] flatten(Options opts, String[] arguments, boolean stopAtNonOption) throws ParseException; 065 066 /** 067 * Gets the options. 068 * 069 * @return the options. 070 */ 071 protected Options getOptions() { 072 return options; 073 } 074 075 /** 076 * Gets the required options. 077 * 078 * @return the required options. 079 */ 080 protected List getRequiredOptions() { 081 return requiredOptions; 082 } 083 084 /** 085 * Parses the specified {@code arguments} based on the specified {@link Options}. 086 * 087 * @param options the {@code Options} 088 * @param arguments the {@code arguments} 089 * @return the {@code CommandLine} 090 * @throws ParseException if there are any problems encountered while parsing the command line tokens. 091 */ 092 @Override 093 public CommandLine parse(final Options options, final String[] arguments) throws ParseException { 094 return parse(options, arguments, null, false); 095 } 096 097 /** 098 * Parses the specified {@code arguments} based on the specified {@link Options}. 099 * 100 * @param options the {@code Options} 101 * @param arguments the {@code arguments} 102 * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments 103 * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a 104 * ParseException. 105 * @return the {@code CommandLine} 106 * @throws ParseException if an error occurs when parsing the arguments. 107 */ 108 @Override 109 public CommandLine parse(final Options options, final String[] arguments, final boolean stopAtNonOption) throws ParseException { 110 return parse(options, arguments, null, stopAtNonOption); 111 } 112 113 /** 114 * Parse the arguments according to the specified options and properties. 115 * 116 * @param options the specified Options 117 * @param arguments the command line arguments 118 * @param properties command line option name-value pairs 119 * @return the list of atomic option and value tokens 120 * @throws ParseException if there are any problems encountered while parsing the command line tokens. 121 * @since 1.1 122 */ 123 public CommandLine parse(final Options options, final String[] arguments, final Properties properties) throws ParseException { 124 return parse(options, arguments, properties, false); 125 } 126 127 /** 128 * Parse the arguments according to the specified options and properties. 129 * 130 * @param options the specified Options 131 * @param arguments the command line arguments 132 * @param properties command line option name-value pairs 133 * @param stopAtNonOption if {@code true} an unrecognized argument stops the parsing and the remaining arguments 134 * are added to the {@link CommandLine}s args list. If {@code false} an unrecognized argument triggers a 135 * ParseException. 136 * @return the list of atomic option and value tokens 137 * @throws ParseException if there are any problems encountered while parsing the command line tokens. 138 * @since 1.1 139 */ 140 public CommandLine parse(final Options options, final String[] arguments, final Properties properties, final boolean stopAtNonOption) 141 throws ParseException { 142 // clear out the data in options in case it's been used before (CLI-71) 143 for (final Option opt : options.helpOptions()) { 144 opt.clearValues(); 145 } 146 // clear the data from the groups 147 for (final OptionGroup group : options.getOptionGroups()) { 148 group.setSelected(null); 149 } 150 // initialize members 151 setOptions(options); 152 cmd = CommandLine.builder().build(); 153 boolean eatTheRest = false; 154 final List<String> tokenList = Arrays.asList(flatten(getOptions(), arguments == null ? new String[0] : arguments, stopAtNonOption)); 155 final ListIterator<String> iterator = tokenList.listIterator(); 156 // process each flattened token 157 while (iterator.hasNext()) { 158 final String token = iterator.next(); 159 // the value is the double-dash 160 if ("--".equals(token)) { 161 eatTheRest = true; 162 } 163 // the value is a single dash 164 else if ("-".equals(token)) { 165 if (stopAtNonOption) { 166 eatTheRest = true; 167 } else { 168 cmd.addArg(token); 169 } 170 } 171 // the value is an option 172 else if (token.startsWith("-")) { 173 if (stopAtNonOption && !getOptions().hasOption(token)) { 174 eatTheRest = true; 175 cmd.addArg(token); 176 } else { 177 processOption(token, iterator); 178 } 179 } 180 // the value is an argument 181 else { 182 cmd.addArg(token); 183 if (stopAtNonOption) { 184 eatTheRest = true; 185 } 186 } 187 // eat the remaining tokens 188 if (eatTheRest) { 189 while (iterator.hasNext()) { 190 final String str = iterator.next(); 191 // ensure only one double-dash is added 192 if (!"--".equals(str)) { 193 cmd.addArg(str); 194 } 195 } 196 } 197 } 198 processProperties(properties); 199 checkRequiredOptions(); 200 return cmd; 201 } 202 203 /** 204 * Process the argument values for the specified Option {@code opt} using the values retrieved from the specified 205 * iterator {@code iter}. 206 * 207 * @param opt The current Option 208 * @param iter The iterator over the flattened command line Options. 209 * @throws ParseException if an argument value is required and it is has not been found. 210 */ 211 public void processArgs(final Option opt, final ListIterator<String> iter) throws ParseException { 212 // loop until an option is found 213 while (iter.hasNext()) { 214 final String str = iter.next(); 215 // found an Option, not an argument 216 if (getOptions().hasOption(str) && str.startsWith("-")) { 217 iter.previous(); 218 break; 219 } 220 // found a value 221 try { 222 opt.processValue(Util.stripLeadingAndTrailingQuotes(str)); 223 } catch (final RuntimeException exp) { 224 iter.previous(); 225 break; 226 } 227 } 228 if (opt.getValues() == null && !opt.hasOptionalArg()) { 229 throw new MissingArgumentException(opt); 230 } 231 } 232 233 /** 234 * Process the Option specified by {@code arg} using the values retrieved from the specified iterator 235 * {@code iter}. 236 * 237 * @param arg The String value representing an Option 238 * @param iter The iterator over the flattened command line arguments. 239 * @throws ParseException if {@code arg} does not represent an Option 240 */ 241 protected void processOption(final String arg, final ListIterator<String> iter) throws ParseException { 242 final boolean hasOption = getOptions().hasOption(arg); 243 // if there is no option throw an UnrecognizedOptionException 244 if (!hasOption) { 245 throw new UnrecognizedOptionException("Unrecognized option: " + arg, arg); 246 } 247 // get the option represented by arg 248 final Option opt = (Option) getOptions().getOption(arg).clone(); 249 // update the required options and groups 250 updateRequiredOptions(opt); 251 // if the option takes an argument value 252 if (opt.hasArg()) { 253 processArgs(opt, iter); 254 } 255 // set the option on the command line 256 cmd.addOption(opt); 257 } 258 259 /** 260 * Sets the values of Options using the values in {@code properties}. 261 * 262 * @param properties The value properties to be processed. 263 * @throws ParseException if there are any problems encountered while processing the properties. 264 */ 265 protected void processProperties(final Properties properties) throws ParseException { 266 if (properties == null) { 267 return; 268 } 269 for (final Enumeration<?> e = properties.propertyNames(); e.hasMoreElements();) { 270 final String option = e.nextElement().toString(); 271 final Option opt = options.getOption(option); 272 if (opt == null) { 273 throw new UnrecognizedOptionException("Default option wasn't defined", option); 274 } 275 // if the option is part of a group, check if another option of the group has been selected 276 final OptionGroup group = options.getOptionGroup(opt); 277 final boolean selected = group != null && group.getSelected() != null; 278 if (!cmd.hasOption(option) && !selected) { 279 // get the value from the properties instance 280 final String value = properties.getProperty(option); 281 if (opt.hasArg()) { 282 if (opt.getValues() == null || opt.getValues().length == 0) { 283 try { 284 opt.processValue(value); 285 } catch (final RuntimeException exp) { // NOPMD 286 // if we cannot add the value don't worry about it 287 } 288 } 289 } else if (!("yes".equalsIgnoreCase(value) || "true".equalsIgnoreCase(value) || "1".equalsIgnoreCase(value))) { 290 // if the value is not yes, true or 1 then don't add the 291 // option to the CommandLine 292 continue; 293 } 294 cmd.addOption(opt); 295 updateRequiredOptions(opt); 296 } 297 } 298 } 299 300 /** 301 * Sets the options. 302 * 303 * @param options the options. 304 */ 305 protected void setOptions(final Options options) { 306 this.options = options; 307 this.requiredOptions = new ArrayList<>(options.getRequiredOptions()); 308 } 309 310 /** 311 * Removes the option or its group from the list of expected elements. 312 * 313 * @param opt 314 */ 315 private void updateRequiredOptions(final Option opt) throws ParseException { 316 // if the option is a required option remove the option from 317 // the requiredOptions list 318 if (opt.isRequired()) { 319 getRequiredOptions().remove(opt.getKey()); 320 } 321 // if the option is in an OptionGroup make that option the selected 322 // option of the group 323 if (getOptions().getOptionGroup(opt) != null) { 324 final OptionGroup group = getOptions().getOptionGroup(opt); 325 if (group.isRequired()) { 326 getRequiredOptions().remove(group); 327 } 328 group.setSelected(opt); 329 } 330 } 331 332}