Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.cli; import java.util.ArrayList; import java.util.Arrays; import java.util.Enumeration; import java.util.Iterator; import java.util.List; import java.util.ListIterator; import java.util.Properties; /** * <code>Parser</code> creates {@link CommandLine}s. * * @author John Keyes (john at integralsource.com) * @version $Revision: 680644 $, $Date: 2008-07-29 01:13:48 -0700 (Tue, 29 Jul 2008) $ */ public abstract class Parser implements CommandLineParser { /** commandline instance */ protected CommandLine cmd; /** current Options */ private Options options; /** list of required options strings */ private List requiredOptions; protected void setOptions(final Options options) { this.options = options; this.requiredOptions = new ArrayList(options.getRequiredOptions()); } protected Options getOptions() { return options; } protected List getRequiredOptions() { return requiredOptions; } /** * Subclasses must implement this method to reduce * the <code>arguments</code> that have been passed to the parse method. * * @param opts The Options to parse the arguments by. * @param arguments The arguments that have to be flattened. * @param stopAtNonOption specifies whether to stop * flattening when a non option has been encountered * @return a String array of the flattened arguments */ protected abstract String[] flatten(Options opts, String[] arguments, boolean stopAtNonOption); /** * Parses the specified <code>arguments</code> based * on the specifed {@link Options}. * * @param options the <code>Options</code> * @param arguments the <code>arguments</code> * @return the <code>CommandLine</code> * @throws ParseException if an error occurs when parsing the * arguments. */ public CommandLine parse(Options options, String[] arguments) throws ParseException { return parse(options, arguments, null, false); } /** * Parse the arguments according to the specified options and properties. * * @param options the specified Options * @param arguments the command line arguments * @param properties command line option name-value pairs * @return the list of atomic option and value tokens * @throws ParseException if there are any problems encountered * while parsing the command line tokens. * * @since 1.1 */ public CommandLine parse(Options options, String[] arguments, Properties properties) throws ParseException { return parse(options, arguments, properties, false); } /** * Parses the specified <code>arguments</code> * based on the specifed {@link Options}. * * @param options the <code>Options</code> * @param arguments the <code>arguments</code> * @param stopAtNonOption specifies whether to stop interpreting the * arguments when a non option has been encountered * and to add them to the CommandLines args list. * @return the <code>CommandLine</code> * @throws ParseException if an error occurs when parsing the arguments. */ public CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException { return parse(options, arguments, null, stopAtNonOption); } /** * Parse the arguments according to the specified options and * properties. * * @param options the specified Options * @param arguments the command line arguments * @param properties command line option name-value pairs * @param stopAtNonOption stop parsing the arguments when the first * non option is encountered. * * @return the list of atomic option and value tokens * * @throws ParseException if there are any problems encountered * while parsing the command line tokens. * * @since 1.1 */ public CommandLine parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption) throws ParseException { // clear out the data in options in case it's been used before (CLI-71) for (Iterator it = options.helpOptions().iterator(); it.hasNext();) { Option opt = (Option) it.next(); opt.clearValues(); } // initialise members setOptions(options); cmd = new CommandLine(); boolean eatTheRest = false; if (arguments == null) { arguments = new String[0]; } List tokenList = Arrays.asList(flatten(getOptions(), arguments, stopAtNonOption)); ListIterator iterator = tokenList.listIterator(); // process each flattened token while (iterator.hasNext()) { String t = (String) iterator.next(); // the value is the double-dash if ("--".equals(t)) { eatTheRest = true; } // the value is a single dash else if ("-".equals(t)) { if (stopAtNonOption) { eatTheRest = true; } else { cmd.addArg(t); } } // the value is an option else if (t.startsWith("-")) { if (stopAtNonOption && !getOptions().hasOption(t)) { eatTheRest = true; cmd.addArg(t); } else { processOption(t, iterator); } } // the value is an argument else { cmd.addArg(t); if (stopAtNonOption) { eatTheRest = true; } } // eat the remaining tokens if (eatTheRest) { while (iterator.hasNext()) { String str = (String) iterator.next(); // ensure only one double-dash is added if (!"--".equals(str)) { cmd.addArg(str); } } } } processProperties(properties); checkRequiredOptions(); return cmd; } /** * Sets the values of Options using the values in <code>properties</code>. * * @param properties The value properties to be processed. */ protected void processProperties(Properties properties) { if (properties == null) { return; } for (Enumeration e = properties.propertyNames(); e.hasMoreElements();) { String option = e.nextElement().toString(); if (!cmd.hasOption(option)) { Option opt = getOptions().getOption(option); // get the value from the properties instance String value = properties.getProperty(option); if (opt.hasArg()) { if (opt.getValues() == null || opt.getValues().length == 0) { try { opt.addValueForProcessing(value); } catch (RuntimeException exp) { // if we cannot add the value don't worry about it } } } else if (!("yes".equalsIgnoreCase(value) || "true".equalsIgnoreCase(value) || "1".equalsIgnoreCase(value))) { // if the value is not yes, true or 1 then don't add the // option to the CommandLine break; } cmd.addOption(opt); } } } /** * Throws a {@link MissingOptionException} if all of the required options * are not present. * * @throws MissingOptionException if any of the required Options * are not present. */ protected void checkRequiredOptions() throws MissingOptionException { // if there are required options that have not been processsed if (!getRequiredOptions().isEmpty()) { throw new MissingOptionException(getRequiredOptions()); } } /** * <p>Process the argument values for the specified Option * <code>opt</code> using the values retrieved from the * specified iterator <code>iter</code>. * * @param opt The current Option * @param iter The iterator over the flattened command line * Options. * * @throws ParseException if an argument value is required * and it is has not been found. */ public void processArgs(Option opt, ListIterator iter) throws ParseException { // loop until an option is found while (iter.hasNext()) { String str = (String) iter.next(); // found an Option, not an argument if (getOptions().hasOption(str) && str.startsWith("-")) { iter.previous(); break; } // found a value try { opt.addValueForProcessing(Util.stripLeadingAndTrailingQuotes(str)); } catch (RuntimeException exp) { iter.previous(); break; } } if (opt.getValues() == null && !opt.hasOptionalArg()) { throw new MissingArgumentException(opt); } } /** * Process the Option specified by <code>arg</code> using the values * retrieved from the specfied iterator <code>iter</code>. * * @param arg The String value representing an Option * @param iter The iterator over the flattened command line arguments. * * @throws ParseException if <code>arg</code> does not represent an Option */ protected void processOption(String arg, ListIterator iter) throws ParseException { boolean hasOption = getOptions().hasOption(arg); // if there is no option throw an UnrecognisedOptionException if (!hasOption) { throw new UnrecognizedOptionException("Unrecognized option: " + arg, arg); } // get the option represented by arg Option opt = (Option) getOptions().getOption(arg).clone(); // if the option is a required option remove the option from // the requiredOptions list if (opt.isRequired()) { getRequiredOptions().remove(opt.getKey()); } // if the option is in an OptionGroup make that option the selected // option of the group if (getOptions().getOptionGroup(opt) != null) { OptionGroup group = getOptions().getOptionGroup(opt); if (group.isRequired()) { getRequiredOptions().remove(group); } group.setSelected(opt); } // if the option takes an argument value if (opt.hasArg()) { processArgs(opt, iter); } // set the option on the command line cmd.addOption(opt); } }