<?xml version="1.0"?>
<!--
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.
-->
<document>
 <properties>
  <title>Release notes for CLI 1.3</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>
<body>

<section name="Release notes">

  <p>These are the release notes for Commons CLI 1.3.</p>

<source>
INTRODUCTION:

This document contains the release notes for this version of the Commons CLI
package. Commons CLI provides a simple API for working with the command line
arguments and options.

Commons CLI 1.3 is a bugfix and feature release and binary compatible with the
previous versions, except for the OptionValidator class that is no longer public
(change introduced in v1.2). Commons CLI 1.3 at least requires Java 5.0.

More information can be found on the project site at
http://commons.apache.org/cli.

NOTES
=====

A new parser is available: DefaultParser. It combines the features of the
GnuParser and the PosixParser. It also provides additional features like
partial matching for the long options, and long options without
separator (i.e like the JVM memory settings: -Xmx512m). This new parser
deprecates the previous ones.

DEPRECATIONS
============

o org.apache.commons.cli.BasicParser
    replaced by org.apache.commons.cli.DefaultParser

o org.apache.commons.cli.GnuParser
    replaced by org.apache.commons.cli.DefaultParser

o org.apache.commons.cli.OptionBuilder
    replaced by org.apache.commons.cli.Option.builder()
                org.apache.commons.cli.Option.builder(String)
                org.apache.commons.cli.Option.Builder

o org.apache.commons.cli.Parser
    replaced by org.apache.commons.cli.DefaultParser

o org.apache.commons.cli.PosixParser
    replaced by org.apache.commons.cli.DefaultParser


NEW FEATURES
============

o CLI-161: PosixParser doesn't stop the parsing on "--" tokens following an
           option with an argument
o CLI-167: Support options like Java memory settings (-Xmx512M)
o CLI-181: Unified Parser
o CLI-224: Added new fluent API to create Option instances via builder class
           Option.Builder. This replaces the now deprecated OptionBuilder.
           Thanks to Duncan Jones, Brian Blount.
o CLI-160: PosixParser now supports partial long options (--ver instead of
           --version).
o CLI-169: HelpFormatter now supports setting the displayed separator of long
           options. Thanks to J. Lewis Muir.
o CLI-214: Added new method Options.addOption(String, String). Thanks to
           Alexandru Mocanu.


BUG FIXES
=========

o CLI-248: Dead links on doc page.
o CLI-234: Fixed code example in javadoc of
           "Option#Builder#valueSeparator(char)". Thanks to Greg Thomas.
o CLI-241: Clarified behavior of "OptionValidator#validateOption(String)"
           in case of null input. Thanks to Beluga Behr.
o CLI-202: Default options will now work correctly with required options that
           are missing.
o CLI-203: Default options will now work correctly together with option groups.
o CLI-205: HelpFormatter.setArgName(String) now correctly sets the argument
           name.
o CLI-204: Passing default values for not defined options to a parser will now
           trigger a ParseException instead of a NullPointerException.
o CLI-201: Default properties provided as input to the Parser.parse() methods
           are now correctly processed.
o CLI-215: CommandLine.getParsedOptionValue() now returns a String object if no
           option type has been explicitly set. Thanks to Manuel Müller.
o CLI-212: HelpFormatter now prints command-line options in the same order as
           they have been added. Thanks to Per Cederberg.
o CLI-186: Standard help text now shows mandatory arguments also for the first
           option. Thanks to Kristoff Kiefer.
o CLI-207: HelpFormatter does not strip anymore leading whitespace in the
           footer text. Thanks to Uri Moszkowicz.
o CLI-185: Strip quotes contained in argument values only if there is exactly
           one at the beginning and one at the end. Thanks to
           Einar M. R. Rosenvinge.
o CLI-184: Negative numerical arguments take precedence over numerical options.
o CLI-193: Fix possible StringIndexOutOfBoundsException in HelpFormatter.
           Thanks to Travis McLeskey.
o CLI-183: OptionGroups no longer throw an AlreadySelectedException when reused
           for several parsings.
o CLI-182: OptionGroup now selects properly an option with no short name.


CHANGES
=======

o CLI-240: Small cleanup of Option class. Thanks to Beluga Behr.
o CLI-230: Options.getRequiredOptions() now returns an unmodifiable list.
o CLI-218: Clarify javadoc for CommandLine.getOptionValue() that the first
           specified argument will be returned. Thanks to Sven.
o CLI-227: Changed unit tests to junit 4 annotation style. Thanks to
           Duncan Jones.
o CLI-209: The javadoc of OptionBuilder now states that the class is not
           thread-safe. Thanks to Thomas Herre.
o CLI-200: Fixed typo in javadoc of class CommandLine. Thanks to
           Gerard Weatherby.
o CLI-223: Source code now uses generic types instead of raw types where
           possible. Thanks to Gerard Weatherby.
o CLI-220  Corrected javadoc for return type of
           MissingOptionException.getMissingOptions(). Thanks to Joe Casadonte.
o CLI-197: Improve description of parameter "stopAtNonOption" in method
           CommandLine.parse(Options, String[], boolean). Thanks to
           Anders Larsson.
o CLI-231: Removed DoubleCheckedLocking test from checkstyle configuration.
           Thanks to Duncan Jones.
</source>

</section>

</body>
</document>