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
020/**
021 * A class that implements the <code>CommandLineParser</code> interface
022 * can parse a String array according to the {@link Options} specified
023 * and return a {@link CommandLine}.
024 */
025public interface CommandLineParser
026{
027    /**
028     * Parse the arguments according to the specified options.
029     *
030     * @param options the specified Options
031     * @param arguments the command line arguments
032     * @return the list of atomic option and value tokens
033     *
034     * @throws ParseException if there are any problems encountered
035     * while parsing the command line tokens.
036     */
037    CommandLine parse(Options options, String[] arguments) throws ParseException;
038
039    /**
040     * Parse the arguments according to the specified options and
041     * properties.
042     *
043     * @param options the specified Options
044     * @param arguments the command line arguments
045     * @param properties command line option name-value pairs
046     * @return the list of atomic option and value tokens
047     *
048     * @throws ParseException if there are any problems encountered
049     * while parsing the command line tokens.
050     */
051    /* To maintain binary compatibility, this is commented out.
052       It is still in the abstract Parser class, so most users will
053       still reap the benefit.
054    CommandLine parse(Options options, String[] arguments, Properties properties)
055               throws ParseException;
056     */
057
058    /**
059     * Parse the arguments according to the specified options.
060     *
061     * @param options the specified Options
062     * @param arguments the command line arguments
063     * @param stopAtNonOption if <code>true</code> an unrecognized argument stops
064     *     the parsing and the remaining arguments are added to the 
065     *     {@link CommandLine}s args list. If <code>false</code> an unrecognized
066     *     argument triggers a ParseException.
067     *
068     * @return the list of atomic option and value tokens
069     * @throws ParseException if there are any problems encountered
070     * while parsing the command line tokens.
071     */
072    CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException;
073
074    /**
075     * Parse the arguments according to the specified options and
076     * properties.
077     *
078     * @param options the specified Options
079     * @param arguments the command line arguments
080     * @param properties command line option name-value pairs
081     * @param stopAtNonOption if <code>true</code> an unrecognized argument stops
082     *     the parsing and the remaining arguments are added to the 
083     *     {@link CommandLine}s args list. If <code>false</code> an unrecognized
084     *     argument triggers a ParseException.
085     *
086     * @return the list of atomic option and value tokens
087     * @throws ParseException if there are any problems encountered
088     * while parsing the command line tokens.
089     */
090    /* To maintain binary compatibility, this is commented out.
091       It is still in the abstract Parser class, so most users will
092       still reap the benefit.
093    CommandLine parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption)
094            throws ParseException;
095     */
096}