Any global configuration defined more than once will produce an excep…

…tion; javadoc updated to clarify parsing rules, new test files added and tests updated accordingly.

src/main/java/org/apache/commons/cli/config/GlobalConfiguration.java

@@ -26,8 +26,8 @@
  * least one {@link OptionConfiguration}.
  *
  * <p>
- * Lines beginning with &#35; are ignored.
- *
+ * Lines beginning with &#35; are ignored. Each global configuration can only be
+ * declared once; redeclaring a global option will produce an error.
  * <p>
  * Global configuration items are as follows - the global options beginning with
  * {@code HELP_} enable callers to print help linked to an option without any
@@ -370,20 +370,40 @@ else if (OptionsTypeEnum.LONG.getType().equals(data))
     private void parseHelp(final String line) throws ConfigurationException
     {
         String[] data = line.split("=");
-        if (GlobalConfiguration.HELP_COMMAND_NAME.equals(data[0].trim()))
+        if (HELP_COMMAND_NAME.equals(data[0].trim()))
         {
+            if (helpCommandName != null)
+            {
+                throw new ConfigurationException(HELP_COMMAND_NAME
+                        + " has already been defined.");
+            }
             helpCommandName = data[1].trim();
         }
         else if (GlobalConfiguration.HELP_COMMAND_HEADER.equals(data[0].trim()))
         {
+            if (helpCommandHeader != null)
+            {
+                throw new ConfigurationException(HELP_COMMAND_HEADER
+                        + " has already been defined.");
+            }
             helpCommandHeader = data[1].trim();
         }
-        else if (GlobalConfiguration.HELP_COMMAND_FOOTER.equals(data[0].trim()))
+        else if (HELP_COMMAND_FOOTER.equals(data[0].trim()))
         {
+            if (helpCommandFooter != null)
+            {
+                throw new ConfigurationException(HELP_COMMAND_FOOTER
+                        + " has already been defined.");
+            }
             helpCommandFooter = data[1].trim();
         }
-        else if (GlobalConfiguration.HELP_OPTION_NAME.equals(data[0].trim()))
+        else if (HELP_OPTION_NAME.equals(data[0].trim()))
         {
+            if (helpOptionName != null)
+            {
+                throw new ConfigurationException(HELP_OPTION_NAME
+                        + " has already been defined.");
+            }
             helpOptionName = data[1].trim();
         }
         else

src/main/java/org/apache/commons/cli/config/OptionConfiguration.java

@@ -59,6 +59,30 @@
  * Lines beginning with # are ignored.
  *
  * <p>
+ * In all cases, lines may be escaped; escaped lines must end in a trailing
+ * backslash character; lines to be appended must be indented using white space
+ * (space character and/or tab characters). This is especially useful when
+ * defining help descriptions. For example:
+ *
+ * <pre>
+ * option.file.description=Supply the output file to write results to. If the \
+ *      file doesn't exist, it is created. If the file does exist, it is
+ *      appended to.
+ * </pre>
+ *
+ * Note in the above example the spaces before the backslashes - this is so
+ * sentences are not 'glued' together and provide spacing that is easy on the
+ * eye to readers of the output.
+ * 
+ * <p>
+ * Options must be defined in groups - that is, once an option has been defined,
+ * it cannot have other values set on it (like description, argument name etc.)
+ * after another option has been defined. Options cannot have a value set on it
+ * more than once - so you cannot define the description twice, for example. In
+ * either case an exception will be thrown with the offending line and its line
+ * number.
+ *
+ * <p>
  * For example, a configuration file named {@code opt.config} could be created
  * with the following option configuration (note that typically, creators of
  * configurations will likely have the {@code name} and the long option text
@@ -94,22 +118,6 @@
  * {@link OptionListener#option(java.lang.String, java.lang.Object)} and would
  * receive an update with the option {@code file} given a value of
  * {@code datafile.txt}.
- *
- * <p>
- * In all cases, lines may be escaped; escaped lines must end in a trailing
- * backslash character; lines to be appended must be indented using white space
- * (space character and/or tab characters). This is especially useful when
- * defining help descriptions. For example:
- *
- * <pre>
- * option.file.description=Supply the output file to write results to. If the \
- *      file doesn't exist, it is created. If the file does exist, it is
- *      appended to.
- * </pre>
- *
- * Note in the above example the spaces before the backslashes - this is so
- * sentences are not 'glued' together and provide spacing that is easy on the
- * eye to readers of the output.
  */
 public class OptionConfiguration
 {

src/test/java/org/apache/commons/cli/config/ConfigurationParserTest.java

@@ -20,6 +20,7 @@
 import java.util.Map;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import static org.apache.commons.cli.config.GlobalConfiguration.HELP_COMMAND_NAME;
 import static org.apache.commons.cli.config.GlobalConfiguration.OPTION_TYPE;
 import org.junit.After;
 import org.junit.AfterClass;
@@ -605,6 +606,102 @@ public void testParseInputStreamOptionsBadOrdering() throws Exception
         }
     }
 
+    /**
+     * Test that an option that is redefined later in the file throws an
+     * exception.
+     */
+    @Test
+    public void testParseInputStreamHelpCommandDefinedTwice() throws Exception
+    {
+        ConfigurationParser configParser = new ConfigurationParser();
+        InputStream is = ConfigurationParserTest.class.getResourceAsStream(
+                "/config/config_027_help_command_defined_twice.conf");
+        try
+        {
+            configParser.parse(is, "UTF-8");
+            fail("Expected exception.");
+        }
+        catch (ConfigurationException ex)
+        {
+            System.out.println(ex.getMessage());
+            assertTrue(ex.getMessage().contains(
+                    GlobalConfiguration.HELP_COMMAND_NAME 
+                        + " has already been defined."));
+        }
+    }
+
+    /**
+     * Test that an option that is redefined later in the file throws an
+     * exception.
+     */
+    @Test
+    public void testParseInputStreamHelpOptionNameDefinedTwice() throws Exception
+    {
+        ConfigurationParser configParser = new ConfigurationParser();
+        InputStream is = ConfigurationParserTest.class.getResourceAsStream(
+                "/config/config_028_help_option_defined_twice.conf");
+        try
+        {
+            configParser.parse(is, "UTF-8");
+            fail("Expected exception.");
+        }
+        catch (ConfigurationException ex)
+        {
+            System.out.println(ex.getMessage());
+            assertTrue(ex.getMessage().contains(
+                    GlobalConfiguration.HELP_OPTION_NAME
+                        + " has already been defined."));
+        }
+    }
+
+    /**
+     * Test that an option that is redefined later in the file throws an
+     * exception.
+     */
+    @Test
+    public void testParseInputStreamHelpFooterDefinedTwice() throws Exception
+    {
+        ConfigurationParser configParser = new ConfigurationParser();
+        InputStream is = ConfigurationParserTest.class.getResourceAsStream(
+                "/config/config_029_help_footer_defined_twice.conf");
+        try
+        {
+            configParser.parse(is, "UTF-8");
+            fail("Expected exception.");
+        }
+        catch (ConfigurationException ex)
+        {
+            System.out.println(ex.getMessage());
+            assertTrue(ex.getMessage().contains(
+                    GlobalConfiguration.HELP_COMMAND_FOOTER
+                        + " has already been defined."));
+        }
+    }
+
+    /**
+     * Test that an option that is redefined later in the file throws an
+     * exception.
+     */
+    @Test
+    public void testParseInputStreamHelpHeaderDefinedTwice() throws Exception
+    {
+        ConfigurationParser configParser = new ConfigurationParser();
+        InputStream is = ConfigurationParserTest.class.getResourceAsStream(
+                "/config/config_030_help_header_defined_twice.conf");
+        try
+        {
+            configParser.parse(is, "UTF-8");
+            fail("Expected exception.");
+        }
+        catch (ConfigurationException ex)
+        {
+            System.out.println(ex.getMessage());
+            assertTrue(ex.getMessage().contains(
+                    GlobalConfiguration.HELP_COMMAND_HEADER
+                        + " has already been defined."));
+        }
+    }
+
     /**
      * Test of addOptionListener method, of class ConfigurationParser.
      */

src/test/resources/config/config_027_help_command_defined_twice.conf

@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+# Error, command name defined twice:
+HELP_COMMAND_NAME=foo_command
+HELP_COMMAND_NAME=foo_command

src/test/resources/config/config_028_help_option_defined_twice.conf

@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+# Error, command name defined twice:
+HELP_OPTION_NAME=showHelp
+HELP_OPTION_NAME=showHelp

src/test/resources/config/config_029_help_footer_defined_twice.conf

@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+# Error, command name defined twice:
+HELP_COMMAND_FOOTER=Help footer
+HELP_COMMAND_FOOTER=Help footer

src/test/resources/config/config_030_help_header_defined_twice.conf

@@ -0,0 +1,20 @@
+#
+# 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.
+#
+
+# Error, command name defined twice:
+HELP_COMMAND_HEADER=Help header
+HELP_COMMAND_HEADER=Help header