View Javadoc
1   /**
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  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  
18  package org.apache.commons.cli;
19  
20  /**
21   * A class that implements the <code>CommandLineParser</code> interface
22   * can parse a String array according to the {@link Options} specified
23   * and return a {@link CommandLine}.
24   */
25  public interface CommandLineParser
26  {
27      /**
28       * Parse the arguments according to the specified options.
29       *
30       * @param options the specified Options
31       * @param arguments the command line arguments
32       * @return the list of atomic option and value tokens
33       *
34       * @throws ParseException if there are any problems encountered
35       * while parsing the command line tokens.
36       */
37      CommandLine parse(Options options, String[] arguments) throws ParseException;
38  
39      /**
40       * Parse the arguments according to the specified options and
41       * properties.
42       *
43       * @param options the specified Options
44       * @param arguments the command line arguments
45       * @param properties command line option name-value pairs
46       * @return the list of atomic option and value tokens
47       *
48       * @throws ParseException if there are any problems encountered
49       * while parsing the command line tokens.
50       */
51      /* To maintain binary compatibility, this is commented out.
52         It is still in the abstract Parser class, so most users will
53         still reap the benefit.
54      CommandLine parse(Options options, String[] arguments, Properties properties)
55                 throws ParseException;
56       */
57  
58      /**
59       * Parse the arguments according to the specified options.
60       *
61       * @param options the specified Options
62       * @param arguments the command line arguments
63       * @param stopAtNonOption if <code>true</code> an unrecognized argument stops
64       *     the parsing and the remaining arguments are added to the 
65       *     {@link CommandLine}s args list. If <code>false</code> an unrecognized
66       *     argument triggers a ParseException.
67       *
68       * @return the list of atomic option and value tokens
69       * @throws ParseException if there are any problems encountered
70       * while parsing the command line tokens.
71       */
72      CommandLine parse(Options options, String[] arguments, boolean stopAtNonOption) throws ParseException;
73  
74      /**
75       * Parse the arguments according to the specified options and
76       * properties.
77       *
78       * @param options the specified Options
79       * @param arguments the command line arguments
80       * @param properties command line option name-value pairs
81       * @param stopAtNonOption if <code>true</code> an unrecognized argument stops
82       *     the parsing and the remaining arguments are added to the 
83       *     {@link CommandLine}s args list. If <code>false</code> an unrecognized
84       *     argument triggers a ParseException.
85       *
86       * @return the list of atomic option and value tokens
87       * @throws ParseException if there are any problems encountered
88       * while parsing the command line tokens.
89       */
90      /* To maintain binary compatibility, this is commented out.
91         It is still in the abstract Parser class, so most users will
92         still reap the benefit.
93      CommandLine parse(Options options, String[] arguments, Properties properties, boolean stopAtNonOption)
94              throws ParseException;
95       */
96  }